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 = 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 /* Attributes 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