include/linux/wimax.h

   1 /*
   2  * Linux WiMax
   3  * API for user space
   4  *
   5  *
   6  * Copyright (C) 2007-2008 Intel Corporation. All rights reserved.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions
  10  * are met:
  11  *
  12  *   * Redistributions of source code must retain the above copyright
  13  *     notice, this list of conditions and the following disclaimer.
  14  *   * Redistributions in binary form must reproduce the above copyright
  15  *     notice, this list of conditions and the following disclaimer in
  16  *     the documentation and/or other materials provided with the
  17  *     distribution.
  18  *   * Neither the name of Intel Corporation nor the names of its
  19  *     contributors may be used to endorse or promote products derived
  20  *     from this software without specific prior written permission.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  23  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  24  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  25  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  26  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  27  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  28  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  29  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  30  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  32  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  *
  34  *
  35  * Intel Corporation <linux-wimax@intel.com>
  36  * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
  37  *  - Initial implementation
  38  *
  39  *
  40  * This file declares the user/kernel protocol that is spoken over
  41  * Generic Netlink, as well as any type declaration that is to be used
  42  * by kernel and user space.
  43  *
  44  * It is intended for user space to clone it verbatim to use it as a
  45  * primary reference for definitions.
  46  *
  47  * Stuff intended for kernel usage as well as full protocol and stack
  48  * documentation is rooted in include/net/wimax.h.
  49  */
  50
  51 #ifndef __LINUX__WIMAX_H__
  52 #define __LINUX__WIMAX_H__
  53
  54 #include <linux/types.h>
  55
  56 enum {
  57         /**
  58          * Version of the interface (unsigned decimal, MMm, max 25.5)
  59          * M - Major: change if removing or modifying an existing call.
  60          * m - minor: change when adding a new call
  61          */
  62         WIMAX_GNL_VERSION = 00,
  63         /* Generic NetLink attributes */
  64         WIMAX_GNL_ATTR_INVALID = 0x00,
  65         WIMAX_GNL_ATTR_MAX = 10,
  66 };
  67
  68
  69 /*
  70  * Generic NetLink operations
  71  *
  72  * Most of these map to an API call; _OP_ stands for operation, _RP_
  73  * for reply and _RE_ for report (aka: signal).
  74  */
  75 enum {
  76         WIMAX_GNL_OP_MSG_FROM_USER,     /* User to kernel message */
  77         WIMAX_GNL_OP_MSG_TO_USER,       /* Kernel to user message */
  78         WIMAX_GNL_OP_RFKILL,    /* Run wimax_rfkill() */
  79         WIMAX_GNL_OP_RESET,     /* Run wimax_rfkill() */
  80         WIMAX_GNL_RE_STATE_CHANGE,      /* Report: status change */
  81 };
  82
  83
  84 /* Message from user / to user */
  85 enum {
  86         WIMAX_GNL_MSG_IFIDX = 1,
  87         WIMAX_GNL_MSG_PIPE_NAME,
  88         WIMAX_GNL_MSG_DATA,
  89 };
  90
  91
  92 /*
  93  * wimax_rfkill()
  94  *
  95  * The state of the radio (ON/OFF) is mapped to the rfkill subsystem's
  96  * switch state (DISABLED/ENABLED).
  97  */
  98 enum wimax_rf_state {
  99         WIMAX_RF_OFF = 0,       /* Radio is off, rfkill on/enabled */
 100         WIMAX_RF_ON = 1,        /* Radio is on, rfkill off/disabled */
 101         WIMAX_RF_QUERY = 2,
 102 };
 103
 104 /* Attributes */
 105 enum {
 106         WIMAX_GNL_RFKILL_IFIDX = 1,
 107         WIMAX_GNL_RFKILL_STATE,
 108 };
 109
 110
 111 /* Attributes for wimax_reset() */
 112 enum {
 113         WIMAX_GNL_RESET_IFIDX = 1,
 114 };
 115
 116
 117 /*
 118  * Attributes for the Report State Change
 119  *
 120  * For now we just have the old and new states; new attributes might
 121  * be added later on.
 122  */
 123 enum {
 124         WIMAX_GNL_STCH_IFIDX = 1,
 125         WIMAX_GNL_STCH_STATE_OLD,
 126         WIMAX_GNL_STCH_STATE_NEW,
 127 };
 128
 129
 130 /**
 131  * enum wimax_st - The different states of a WiMAX device
 132  * @__WIMAX_ST_NULL: The device structure has been allocated and zeroed,
 133  *     but still wimax_dev_add() hasn't been called. There is no state.
 134  *
 135  * @WIMAX_ST_DOWN: The device has been registered with the WiMAX and
 136  *     networking stacks, but it is not initialized (normally that is
 137  *     done with 'ifconfig DEV up' [or equivalent], which can upload
 138  *     firmware and enable communications with the device).
 139  *     In this state, the device is powered down and using as less
 140  *     power as possible.
 141  *     This state is the default after a call to wimax_dev_add(). It
 142  *     is ok to have drivers move directly to %WIMAX_ST_UNINITIALIZED
 143  *     or %WIMAX_ST_RADIO_OFF in _probe() after the call to
 144  *     wimax_dev_add().
 145  *     It is recommended that the driver leaves this state when
 146  *     calling 'ifconfig DEV up' and enters it back on 'ifconfig DEV
 147  *     down'.
 148  *
 149  * @__WIMAX_ST_QUIESCING: The device is being torn down, so no API
 150  *     operations are allowed to proceed except the ones needed to
 151  *     complete the device clean up process.
 152  *
 153  * @WIMAX_ST_UNINITIALIZED: [optional] Communication with the device
 154  *     is setup, but the device still requires some configuration
 155  *     before being operational.
 156  *     Some WiMAX API calls might work.
 157  *
 158  * @WIMAX_ST_RADIO_OFF: The device is fully up; radio is off (wether
 159  *     by hardware or software switches).
 160  *     It is recommended to always leave the device in this state
 161  *     after initialization.
 162  *
 163  * @WIMAX_ST_READY: The device is fully up and radio is on.
 164  *
 165  * @WIMAX_ST_SCANNING: [optional] The device has been instructed to
 166  *     scan. In this state, the device cannot be actively connected to
 167  *     a network.
 168  *
 169  * @WIMAX_ST_CONNECTING: The device is connecting to a network. This
 170  *     state exists because in some devices, the connect process can
 171  *     include a number of negotiations between user space, kernel
 172  *     space and the device. User space needs to know what the device
 173  *     is doing. If the connect sequence in a device is atomic and
 174  *     fast, the device can transition directly to CONNECTED
 175  *
 176  * @WIMAX_ST_CONNECTED: The device is connected to a network.
 177  *
 178  * @__WIMAX_ST_INVALID: This is an invalid state used to mark the
 179  *     maximum numeric value of states.
 180  *
 181  * Description:
 182  *
 183  * Transitions from one state to another one are atomic and can only
 184  * be caused in kernel space with wimax_state_change(). To read the
 185  * state, use wimax_state_get().
 186  *
 187  * States starting with __ are internal and shall not be used or
 188  * referred to by drivers or userspace. They look ugly, but that's the
 189  * point -- if any use is made non-internal to the stack, it is easier
 190  * to catch on review.
 191  *
 192  * All API operations [with well defined exceptions] will take the
 193  * device mutex before starting and then check the state. If the state
 194  * is %__WIMAX_ST_NULL, %WIMAX_ST_DOWN, %WIMAX_ST_UNINITIALIZED or
 195  * %__WIMAX_ST_QUIESCING, it will drop the lock and quit with
 196  * -%EINVAL, -%ENOMEDIUM, -%ENOTCONN or -%ESHUTDOWN.
 197  *
 198  * The order of the definitions is important, so we can do numerical
 199  * comparisons (eg: < %WIMAX_ST_RADIO_OFF means the device is not ready
 200  * to operate).
 201  */
 202 /*
 203  * The allowed state transitions are described in the table below
 204  * (states in rows can go to states in columns where there is an X):
 205  *
 206  *                                  UNINI   RADIO READY SCAN CONNEC CONNEC
 207  *             NULL DOWN QUIESCING TIALIZED  OFF        NING  TING   TED
 208  * NULL         -    x
 209  * DOWN              -      x        x       x
 210  * QUIESCING         x      -
 211  * UNINITIALIZED            x        -       x
 212  * RADIO_OFF                x                -     x
 213  * READY                    x                x     -     x     x      x
 214  * SCANNING                 x                x     x     -     x      x
 215  * CONNECTING               x                x     x     x     -      x
 216  * CONNECTED                x                x     x                  -
 217  *
 218  * This table not available in kernel-doc because the formatting messes it up.
 219  */
 220  enum wimax_st {
 221         __WIMAX_ST_NULL = 0,
 222         WIMAX_ST_DOWN,
 223         __WIMAX_ST_QUIESCING,
 224         WIMAX_ST_UNINITIALIZED,
 225         WIMAX_ST_RADIO_OFF,
 226         WIMAX_ST_READY,
 227         WIMAX_ST_SCANNING,
 228         WIMAX_ST_CONNECTING,
 229         WIMAX_ST_CONNECTED,
 230         __WIMAX_ST_INVALID                      /* Always keep last */
 231 };
 232
 233
 234 #endif /* #ifndef __LINUX__WIMAX_H__ */