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