Home | History | Annotate | Download | only in linux
      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 (at) intel.com>
     36  * Inaky Perez-Gonzalez <inaky.perez-gonzalez (at) 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 = 01,
     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 	WIMAX_GNL_OP_STATE_GET,		/* Request for current state */
     82 };
     83 
     84 
     85 /* Message from user / to user */
     86 enum {
     87 	WIMAX_GNL_MSG_IFIDX = 1,
     88 	WIMAX_GNL_MSG_PIPE_NAME,
     89 	WIMAX_GNL_MSG_DATA,
     90 };
     91 
     92 
     93 /*
     94  * wimax_rfkill()
     95  *
     96  * The state of the radio (ON/OFF) is mapped to the rfkill subsystem's
     97  * switch state (DISABLED/ENABLED).
     98  */
     99 enum wimax_rf_state {
    100 	WIMAX_RF_OFF = 0,	/* Radio is off, rfkill on/enabled */
    101 	WIMAX_RF_ON = 1,	/* Radio is on, rfkill off/disabled */
    102 	WIMAX_RF_QUERY = 2,
    103 };
    104 
    105 /* Attributes */
    106 enum {
    107 	WIMAX_GNL_RFKILL_IFIDX = 1,
    108 	WIMAX_GNL_RFKILL_STATE,
    109 };
    110 
    111 
    112 /* Attributes for wimax_reset() */
    113 enum {
    114 	WIMAX_GNL_RESET_IFIDX = 1,
    115 };
    116 
    117 /* Atributes for wimax_state_get() */
    118 enum {
    119 	WIMAX_GNL_STGET_IFIDX = 1,
    120 };
    121 
    122 /*
    123  * Attributes for the Report State Change
    124  *
    125  * For now we just have the old and new states; new attributes might
    126  * be added later on.
    127  */
    128 enum {
    129 	WIMAX_GNL_STCH_IFIDX = 1,
    130 	WIMAX_GNL_STCH_STATE_OLD,
    131 	WIMAX_GNL_STCH_STATE_NEW,
    132 };
    133 
    134 
    135 /**
    136  * enum wimax_st - The different states of a WiMAX device
    137  * @__WIMAX_ST_NULL: The device structure has been allocated and zeroed,
    138  *     but still wimax_dev_add() hasn't been called. There is no state.
    139  *
    140  * @WIMAX_ST_DOWN: The device has been registered with the WiMAX and
    141  *     networking stacks, but it is not initialized (normally that is
    142  *     done with 'ifconfig DEV up' [or equivalent], which can upload
    143  *     firmware and enable communications with the device).
    144  *     In this state, the device is powered down and using as less
    145  *     power as possible.
    146  *     This state is the default after a call to wimax_dev_add(). It
    147  *     is ok to have drivers move directly to %WIMAX_ST_UNINITIALIZED
    148  *     or %WIMAX_ST_RADIO_OFF in _probe() after the call to
    149  *     wimax_dev_add().
    150  *     It is recommended that the driver leaves this state when
    151  *     calling 'ifconfig DEV up' and enters it back on 'ifconfig DEV
    152  *     down'.
    153  *
    154  * @__WIMAX_ST_QUIESCING: The device is being torn down, so no API
    155  *     operations are allowed to proceed except the ones needed to
    156  *     complete the device clean up process.
    157  *
    158  * @WIMAX_ST_UNINITIALIZED: [optional] Communication with the device
    159  *     is setup, but the device still requires some configuration
    160  *     before being operational.
    161  *     Some WiMAX API calls might work.
    162  *
    163  * @WIMAX_ST_RADIO_OFF: The device is fully up; radio is off (wether
    164  *     by hardware or software switches).
    165  *     It is recommended to always leave the device in this state
    166  *     after initialization.
    167  *
    168  * @WIMAX_ST_READY: The device is fully up and radio is on.
    169  *
    170  * @WIMAX_ST_SCANNING: [optional] The device has been instructed to
    171  *     scan. In this state, the device cannot be actively connected to
    172  *     a network.
    173  *
    174  * @WIMAX_ST_CONNECTING: The device is connecting to a network. This
    175  *     state exists because in some devices, the connect process can
    176  *     include a number of negotiations between user space, kernel
    177  *     space and the device. User space needs to know what the device
    178  *     is doing. If the connect sequence in a device is atomic and
    179  *     fast, the device can transition directly to CONNECTED
    180  *
    181  * @WIMAX_ST_CONNECTED: The device is connected to a network.
    182  *
    183  * @__WIMAX_ST_INVALID: This is an invalid state used to mark the
    184  *     maximum numeric value of states.
    185  *
    186  * Description:
    187  *
    188  * Transitions from one state to another one are atomic and can only
    189  * be caused in kernel space with wimax_state_change(). To read the
    190  * state, use wimax_state_get().
    191  *
    192  * States starting with __ are internal and shall not be used or
    193  * referred to by drivers or userspace. They look ugly, but that's the
    194  * point -- if any use is made non-internal to the stack, it is easier
    195  * to catch on review.
    196  *
    197  * All API operations [with well defined exceptions] will take the
    198  * device mutex before starting and then check the state. If the state
    199  * is %__WIMAX_ST_NULL, %WIMAX_ST_DOWN, %WIMAX_ST_UNINITIALIZED or
    200  * %__WIMAX_ST_QUIESCING, it will drop the lock and quit with
    201  * -%EINVAL, -%ENOMEDIUM, -%ENOTCONN or -%ESHUTDOWN.
    202  *
    203  * The order of the definitions is important, so we can do numerical
    204  * comparisons (eg: < %WIMAX_ST_RADIO_OFF means the device is not ready
    205  * to operate).
    206  */
    207 /*
    208  * The allowed state transitions are described in the table below
    209  * (states in rows can go to states in columns where there is an X):
    210  *
    211  *                                  UNINI   RADIO READY SCAN CONNEC CONNEC
    212  *             NULL DOWN QUIESCING TIALIZED  OFF        NING  TING   TED
    213  * NULL         -    x
    214  * DOWN              -      x        x       x
    215  * QUIESCING         x      -
    216  * UNINITIALIZED            x        -       x
    217  * RADIO_OFF                x                -     x
    218  * READY                    x                x     -     x     x      x
    219  * SCANNING                 x                x     x     -     x      x
    220  * CONNECTING               x                x     x     x     -      x
    221  * CONNECTED                x                x     x                  -
    222  *
    223  * This table not available in kernel-doc because the formatting messes it up.
    224  */
    225  enum wimax_st {
    226 	__WIMAX_ST_NULL = 0,
    227 	WIMAX_ST_DOWN,
    228 	__WIMAX_ST_QUIESCING,
    229 	WIMAX_ST_UNINITIALIZED,
    230 	WIMAX_ST_RADIO_OFF,
    231 	WIMAX_ST_READY,
    232 	WIMAX_ST_SCANNING,
    233 	WIMAX_ST_CONNECTING,
    234 	WIMAX_ST_CONNECTED,
    235 	__WIMAX_ST_INVALID			/* Always keep last */
    236 };
    237 
    238 
    239 #endif /* #ifndef __LINUX__WIMAX_H__ */
    240