linux/include/linux/wimax.h
<<
>>
Prefs
   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
  56enum {
  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 */
  75enum {
  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 */
  86enum {
  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 */
  99enum 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 */
 106enum {
 107        WIMAX_GNL_RFKILL_IFIDX = 1,
 108        WIMAX_GNL_RFKILL_STATE,
 109};
 110
 111
 112/* Attributes for wimax_reset() */
 113enum {
 114        WIMAX_GNL_RESET_IFIDX = 1,
 115};
 116
 117/* Attributes for wimax_state_get() */
 118enum {
 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 */
 128enum {
 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
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.