1/* SPDX-License-Identifier: GPL-2.0-only */ 2/* 3 * Linux WiMAX 4 * Kernel space API for accessing WiMAX devices 5 * 6 * Copyright (C) 2007-2008 Intel Corporation <linux-wimax@intel.com> 7 * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com> 8 * 9 * The WiMAX stack provides an API for controlling and managing the 10 * system's WiMAX devices. This API affects the control plane; the 11 * data plane is accessed via the network stack (netdev). 12 * 13 * Parts of the WiMAX stack API and notifications are exported to 14 * user space via Generic Netlink. In user space, libwimax (part of 15 * the wimax-tools package) provides a shim layer for accessing those 16 * calls. 17 * 18 * The API is standarized for all WiMAX devices and different drivers 19 * implement the backend support for it. However, device-specific 20 * messaging pipes are provided that can be used to issue commands and 21 * receive notifications in free form. 22 * 23 * Currently the messaging pipes are the only means of control as it 24 * is not known (due to the lack of more devices in the market) what 25 * will be a good abstraction layer. Expect this to change as more 26 * devices show in the market. This API is designed to be growable in 27 * order to address this problem. 28 * 29 * USAGE 30 * 31 * Embed a `struct wimax_dev` at the beginning of the the device's 32 * private structure, initialize and register it. For details, see 33 * `struct wimax_dev`s documentation. 34 * 35 * Once this is done, wimax-tools's libwimaxll can be used to 36 * communicate with the driver from user space. You user space 37 * application does not have to forcibily use libwimaxll and can talk 38 * the generic netlink protocol directly if desired. 39 * 40 * Remember this is a very low level API that will to provide all of 41 * WiMAX features. Other daemons and services running in user space 42 * are the expected clients of it. They offer a higher level API that 43 * applications should use (an example of this is the Intel's WiMAX 44 * Network Service for the i2400m). 45 * 46 * DESIGN 47 * 48 * Although not set on final stone, this very basic interface is 49 * mostly completed. Remember this is meant to grow as new common 50 * operations are decided upon. New operations will be added to the 51 * interface, intent being on keeping backwards compatibility as much 52 * as possible. 53 * 54 * This layer implements a set of calls to control a WiMAX device, 55 * exposing a frontend to the rest of the kernel and user space (via 56 * generic netlink) and a backend implementation in the driver through 57 * function pointers. 58 * 59 * WiMAX devices have a state, and a kernel-only API allows the 60 * drivers to manipulate that state. State transitions are atomic, and 61 * only some of them are allowed (see `enum wimax_st`). 62 * 63 * Most API calls will set the state automatically; in most cases 64 * drivers have to only report state changes due to external 65 * conditions. 66 * 67 * All API operations are 'atomic', serialized through a mutex in the 68 * `struct wimax_dev`. 69 * 70 * EXPORTING TO USER SPACE THROUGH GENERIC NETLINK 71 * 72 * The API is exported to user space using generic netlink (other 73 * methods can be added as needed). 74 * 75 * There is a Generic Netlink Family named "WiMAX", where interfaces 76 * supporting the WiMAX interface receive commands and broadcast their 77 * signals over a multicast group named "msg". 78 * 79 * Mapping to the source/destination interface is done by an interface 80 * index attribute. 81 * 82 * For user-to-kernel traffic (commands) we use a function call 83 * marshalling mechanism, where a message X with attributes A, B, C 84 * sent from user space to kernel space means executing the WiMAX API 85 * call wimax_X(A, B, C), sending the results back as a message. 86 * 87 * Kernel-to-user (notifications or signals) communication is sent 88 * over multicast groups. This allows to have multiple applications 89 * monitoring them. 90 * 91 * Each command/signal gets assigned it's own attribute policy. This 92 * way the validator will verify that all the attributes in there are 93 * only the ones that should be for each command/signal. Thing of an 94 * attribute mapping to a type+argumentname for each command/signal. 95 * 96 * If we had a single policy for *all* commands/signals, after running 97 * the validator we'd have to check "does this attribute belong in 98 * here"? for each one. It can be done manually, but it's just easier 99 * to have the validator do that job with multiple policies. As well, 100 * it makes it easier to later expand each command/signal signature 101 * without affecting others and keeping the namespace more or less 102 * sane. Not that it is too complicated, but it makes it even easier. 103 * 104 * No state information is maintained in the kernel for each user 105 * space connection (the connection is stateless). 106 * 107 * TESTING FOR THE INTERFACE AND VERSIONING 108 * 109 * If network interface X is a WiMAX device, there will be a Generic 110 * Netlink family named "WiMAX X" and the device will present a 111 * "wimax" directory in it's network sysfs directory 112 * (/sys/class/net/DEVICE/wimax) [used by HAL]. 113 * 114 * The inexistence of any of these means the device does not support 115 * this WiMAX API. 116 * 117 * By querying the generic netlink controller, versioning information 118 * and the multicast groups available can be found. Applications using 119 * the interface can either rely on that or use the generic netlink 120 * controller to figure out which generic netlink commands/signals are 121 * supported. 122 * 123 * NOTE: this versioning is a last resort to avoid hard 124 * incompatibilities. It is the intention of the design of this 125 * stack not to introduce backward incompatible changes. 126 * 127 * The version code has to fit in one byte (restrictions imposed by 128 * generic netlink); we use `version / 10` for the major version and 129 * `version % 10` for the minor. This gives 9 minors for each major 130 * and 25 majors. 131 * 132 * The version change protocol is as follow: 133 * 134 * - Major versions: needs to be increased if an existing message/API 135 * call is changed or removed. Doesn't need to be changed if a new 136 * message is added. 137 * 138 * - Minor version: needs to be increased if new messages/API calls are 139 * being added or some other consideration that doesn't impact the 140 * user-kernel interface too much (like some kind of bug fix) and 141 * that is kind of left up in the air to common sense. 142 * 143 * User space code should not try to work if the major version it was 144 * compiled for differs from what the kernel offers. As well, if the 145 * minor version of the kernel interface is lower than the one user 146 * space is expecting (the one it was compiled for), the kernel 147 * might be missing API calls; user space shall be ready to handle 148 * said condition. Use the generic netlink controller operations to 149 * find which ones are supported and which not. 150 * 151 * libwimaxll:wimaxll_open() takes care of checking versions. 152 * 153 * THE OPERATIONS: 154 * 155 * Each operation is defined in its on file (drivers/net/wimax/op-*.c) 156 * for clarity. The parts needed for an operation are: 157 * 158 * - a function pointer in `struct wimax_dev`: optional, as the 159 * operation might be implemented by the stack and not by the 160 * driver. 161 * 162 * All function pointers are named wimax_dev->op_*(), and drivers 163 * must implement them except where noted otherwise. 164 * 165 * - When exported to user space, a `struct nla_policy` to define the 166 * attributes of the generic netlink command and a `struct genl_ops` 167 * to define the operation. 168 * 169 * All the declarations for the operation codes (WIMAX_GNL_OP_<NAME>) 170 * and generic netlink attributes (WIMAX_GNL_<NAME>_*) are declared in 171 * include/linux/wimax.h; this file is intended to be cloned by user 172 * space to gain access to those declarations. 173 * 174 * A few caveats to remember: 175 * 176 * - Need to define attribute numbers starting in 1; otherwise it 177 * fails. 178 * 179 * - the `struct genl_family` requires a maximum attribute id; when 180 * defining the `struct nla_policy` for each message, it has to have 181 * an array size of WIMAX_GNL_ATTR_MAX+1. 182 * 183 * The op_*() function pointers will not be called if the wimax_dev is 184 * in a state <= %WIMAX_ST_UNINITIALIZED. The exception is: 185 * 186 * - op_reset: can be called at any time after wimax_dev_add() has 187 * been called. 188 * 189 * THE PIPE INTERFACE: 190 * 191 * This interface is kept intentionally simple. The driver can send 192 * and receive free-form messages to/from user space through a 193 * pipe. See drivers/net/wimax/op-msg.c for details. 194 * 195 * The kernel-to-user messages are sent with 196 * wimax_msg(). user-to-kernel messages are delivered via 197 * wimax_dev->op_msg_from_user(). 198 * 199 * RFKILL: 200 * 201 * RFKILL support is built into the wimax_dev layer; the driver just 202 * needs to call wimax_report_rfkill_{hw,sw}() to inform of changes in 203 * the hardware or software RF kill switches. When the stack wants to 204 * turn the radio off, it will call wimax_dev->op_rfkill_sw_toggle(), 205 * which the driver implements. 206 * 207 * User space can set the software RF Kill switch by calling 208 * wimax_rfkill(). 209 * 210 * The code for now only supports devices that don't require polling; 211 * If the device needs to be polled, create a self-rearming delayed 212 * work struct for polling or look into adding polled support to the 213 * WiMAX stack. 214 * 215 * When initializing the hardware (_probe), after calling 216 * wimax_dev_add(), query the device for it's RF Kill switches status 217 * and feed it back to the WiMAX stack using 218 * wimax_report_rfkill_{hw,sw}(). If any switch is missing, always 219 * report it as ON. 220 * 221 * NOTE: the wimax stack uses an inverted terminology to that of the 222 * RFKILL subsystem: 223 * 224 * - ON: radio is ON, RFKILL is DISABLED or OFF. 225 * - OFF: radio is OFF, RFKILL is ENABLED or ON. 226 * 227 * MISCELLANEOUS OPS: 228 * 229 * wimax_reset() can be used to reset the device to power on state; by 230 * default it issues a warm reset that maintains the same device 231 * node. If that is not possible, it falls back to a cold reset 232 * (device reconnect). The driver implements the backend to this 233 * through wimax_dev->op_reset(). 234 */ 235 236#ifndef __NET__WIMAX_H__ 237#define __NET__WIMAX_H__ 238 239#include <linux/wimax.h> 240#include <net/genetlink.h> 241#include <linux/netdevice.h> 242 243struct net_device; 244struct genl_info; 245struct wimax_dev; 246 247/** 248 * struct wimax_dev - Generic WiMAX device 249 * 250 * @net_dev: [fill] Pointer to the &struct net_device this WiMAX 251 * device implements. 252 * 253 * @op_msg_from_user: [fill] Driver-specific operation to 254 * handle a raw message from user space to the driver. The 255 * driver can send messages to user space using with 256 * wimax_msg_to_user(). 257 * 258 * @op_rfkill_sw_toggle: [fill] Driver-specific operation to act on 259 * userspace (or any other agent) requesting the WiMAX device to 260 * change the RF Kill software switch (WIMAX_RF_ON or 261 * WIMAX_RF_OFF). 262 * If such hardware support is not present, it is assumed the 263 * radio cannot be switched off and it is always on (and the stack 264 * will error out when trying to switch it off). In such case, 265 * this function pointer can be left as NULL. 266 * 267 * @op_reset: [fill] Driver specific operation to reset the 268 * device. 269 * This operation should always attempt first a warm reset that 270 * does not disconnect the device from the bus and return 0. 271 * If that fails, it should resort to some sort of cold or bus 272 * reset (even if it implies a bus disconnection and device 273 * disappearance). In that case, -ENODEV should be returned to 274 * indicate the device is gone. 275 * This operation has to be synchronous, and return only when the 276 * reset is complete. In case of having had to resort to bus/cold 277 * reset implying a device disconnection, the call is allowed to 278 * return immediately. 279 * NOTE: wimax_dev->mutex is NOT locked when this op is being 280 * called; however, wimax_dev->mutex_reset IS locked to ensure 281 * serialization of calls to wimax_reset(). 282 * See wimax_reset()'s documentation. 283 * 284 * @name: [fill] A way to identify this device. We need to register a 285 * name with many subsystems (rfkill, workqueue creation, etc). 286 * We can't use the network device name as that 287 * might change and in some instances we don't know it yet (until 288 * we don't call register_netdev()). So we generate an unique one 289 * using the driver name and device bus id, place it here and use 290 * it across the board. Recommended naming: 291 * DRIVERNAME-BUSNAME:BUSID (dev->bus->name, dev->bus_id). 292 * 293 * @id_table_node: [private] link to the list of wimax devices kept by 294 * id-table.c. Protected by it's own spinlock. 295 * 296 * @mutex: [private] Serializes all concurrent access and execution of 297 * operations. 298 * 299 * @mutex_reset: [private] Serializes reset operations. Needs to be a 300 * different mutex because as part of the reset operation, the 301 * driver has to call back into the stack to do things such as 302 * state change, that require wimax_dev->mutex. 303 * 304 * @state: [private] Current state of the WiMAX device. 305 * 306 * @rfkill: [private] integration into the RF-Kill infrastructure. 307 * 308 * @rf_sw: [private] State of the software radio switch (OFF/ON) 309 * 310 * @rf_hw: [private] State of the hardware radio switch (OFF/ON) 311 * 312 * @debugfs_dentry: [private] Used to hook up a debugfs entry. This 313 * shows up in the debugfs root as wimax\:DEVICENAME. 314 * 315 * Description: 316 * This structure defines a common interface to access all WiMAX 317 * devices from different vendors and provides a common API as well as 318 * a free-form device-specific messaging channel. 319 * 320 * Usage: 321 * 1. Embed a &struct wimax_dev at *the beginning* the network 322 * device structure so that netdev_priv() points to it. 323 * 324 * 2. memset() it to zero 325 * 326 * 3. Initialize with wimax_dev_init(). This will leave the WiMAX 327 * device in the %__WIMAX_ST_NULL state. 328 * 329 * 4. Fill all the fields marked with [fill]; once called 330 * wimax_dev_add(), those fields CANNOT be modified. 331 * 332 * 5. Call wimax_dev_add() *after* registering the network 333 * device. This will leave the WiMAX device in the %WIMAX_ST_DOWN 334 * state. 335 * Protect the driver's net_device->open() against succeeding if 336 * the wimax device state is lower than %WIMAX_ST_DOWN. 337 * 338 * 6. Select when the device is going to be turned on/initialized; 339 * for example, it could be initialized on 'ifconfig up' (when the 340 * netdev op 'open()' is called on the driver). 341 * 342 * When the device is initialized (at `ifconfig up` time, or right 343 * after calling wimax_dev_add() from _probe(), make sure the 344 * following steps are taken 345 * 346 * a. Move the device to %WIMAX_ST_UNINITIALIZED. This is needed so 347 * some API calls that shouldn't work until the device is ready 348 * can be blocked. 349 * 350 * b. Initialize the device. Make sure to turn the SW radio switch 351 * off and move the device to state %WIMAX_ST_RADIO_OFF when 352 * done. When just initialized, a device should be left in RADIO 353 * OFF state until user space devices to turn it on. 354 * 355 * c. Query the device for the state of the hardware rfkill switch 356 * and call wimax_rfkill_report_hw() and wimax_rfkill_report_sw() 357 * as needed. See below. 358 * 359 * wimax_dev_rm() undoes before unregistering the network device. Once 360 * wimax_dev_add() is called, the driver can get called on the 361 * wimax_dev->op_* function pointers 362 * 363 * CONCURRENCY: 364 * 365 * The stack provides a mutex for each device that will disallow API 366 * calls happening concurrently; thus, op calls into the driver 367 * through the wimax_dev->op*() function pointers will always be 368 * serialized and *never* concurrent. 369 * 370 * For locking, take wimax_dev->mutex is taken; (most) operations in 371 * the API have to check for wimax_dev_is_ready() to return 0 before 372 * continuing (this is done internally). 373 * 374 * REFERENCE COUNTING: 375 * 376 * The WiMAX device is reference counted by the associated network 377 * device. The only operation that can be used to reference the device 378 * is wimax_dev_get_by_genl_info(), and the reference it acquires has 379 * to be released with dev_put(wimax_dev->net_dev). 380 * 381 * RFKILL: 382 * 383 * At startup, both HW and SW radio switchess are assumed to be off. 384 * 385 * At initialization time [after calling wimax_dev_add()], have the 386 * driver query the device for the status of the software and hardware 387 * RF kill switches and call wimax_report_rfkill_hw() and 388 * wimax_rfkill_report_sw() to indicate their state. If any is 389 * missing, just call it to indicate it is ON (radio always on). 390 * 391 * Whenever the driver detects a change in the state of the RF kill 392 * switches, it should call wimax_report_rfkill_hw() or 393 * wimax_report_rfkill_sw() to report it to the stack. 394 */ 395struct wimax_dev { 396 struct net_device *net_dev; 397 struct list_head id_table_node; 398 struct mutex mutex; /* Protects all members and API calls */ 399 struct mutex mutex_reset; 400 enum wimax_st state; 401 402 int (*op_msg_from_user)(struct wimax_dev *wimax_dev, 403 const char *, 404 const void *, size_t, 405 const struct genl_info *info); 406 int (*op_rfkill_sw_toggle)(struct wimax_dev *wimax_dev, 407 enum wimax_rf_state); 408 int (*op_reset)(struct wimax_dev *wimax_dev); 409 410 struct rfkill *rfkill; 411 unsigned int rf_hw; 412 unsigned int rf_sw; 413 char name[32]; 414 415 struct dentry *debugfs_dentry; 416}; 417 418 419 420/* 421 * WiMAX stack public API for device drivers 422 * ----------------------------------------- 423 * 424 * These functions are not exported to user space. 425 */ 426void wimax_dev_init(struct wimax_dev *); 427int wimax_dev_add(struct wimax_dev *, struct net_device *); 428void wimax_dev_rm(struct wimax_dev *); 429 430static inline 431struct wimax_dev *net_dev_to_wimax(struct net_device *net_dev) 432{ 433 return netdev_priv(net_dev); 434} 435 436static inline 437struct device *wimax_dev_to_dev(struct wimax_dev *wimax_dev) 438{ 439 return wimax_dev->net_dev->dev.parent; 440} 441 442void wimax_state_change(struct wimax_dev *, enum wimax_st); 443enum wimax_st wimax_state_get(struct wimax_dev *); 444 445/* 446 * Radio Switch state reporting. 447 * 448 * enum wimax_rf_state is declared in linux/wimax.h so the exports 449 * to user space can use it. 450 */ 451void wimax_report_rfkill_hw(struct wimax_dev *, enum wimax_rf_state); 452void wimax_report_rfkill_sw(struct wimax_dev *, enum wimax_rf_state); 453 454 455/* 456 * Free-form messaging to/from user space 457 * 458 * Sending a message: 459 * 460 * wimax_msg(wimax_dev, pipe_name, buf, buf_size, GFP_KERNEL); 461 * 462 * Broken up: 463 * 464 * skb = wimax_msg_alloc(wimax_dev, pipe_name, buf_size, GFP_KERNEL); 465 * ...fill up skb... 466 * wimax_msg_send(wimax_dev, pipe_name, skb); 467 * 468 * Be sure not to modify skb->data in the middle (ie: don't use 469 * skb_push()/skb_pull()/skb_reserve() on the skb). 470 * 471 * "pipe_name" is any string, that can be interpreted as the name of 472 * the pipe or recipient; the interpretation of it is driver 473 * specific, so the recipient can multiplex it as wished. It can be 474 * NULL, it won't be used - an example is using a "diagnostics" tag to 475 * send diagnostics information that a device-specific diagnostics 476 * tool would be interested in. 477 */ 478struct sk_buff *wimax_msg_alloc(struct wimax_dev *, const char *, const void *, 479 size_t, gfp_t); 480int wimax_msg_send(struct wimax_dev *, struct sk_buff *); 481int wimax_msg(struct wimax_dev *, const char *, const void *, size_t, gfp_t); 482 483const void *wimax_msg_data_len(struct sk_buff *, size_t *); 484const void *wimax_msg_data(struct sk_buff *); 485ssize_t wimax_msg_len(struct sk_buff *); 486 487 488/* 489 * WiMAX stack user space API 490 * -------------------------- 491 * 492 * This API is what gets exported to user space for general 493 * operations. As well, they can be called from within the kernel, 494 * (with a properly referenced `struct wimax_dev`). 495 * 496 * Properly referenced means: the 'struct net_device' that embeds the 497 * device's control structure and (as such) the 'struct wimax_dev' is 498 * referenced by the caller. 499 */ 500int wimax_rfkill(struct wimax_dev *, enum wimax_rf_state); 501int wimax_reset(struct wimax_dev *); 502 503#endif /* #ifndef __NET__WIMAX_H__ */ 504