---

---

---

001: /*
002:  * Linux WiMax
003:  * API for user space
004:  *
005:  *
006:  * Copyright (C) 2007-2008 Intel Corporation. All rights reserved.
007:  *
008:  * Redistribution and use in source and binary forms, with or without
009:  * modification, are permitted provided that the following conditions
010:  * are met:
011:  *
012:  *   * Redistributions of source code must retain the above copyright
013:  *     notice, this list of conditions and the following disclaimer.
014:  *   * Redistributions in binary form must reproduce the above copyright
015:  *     notice, this list of conditions and the following disclaimer in
016:  *     the documentation and/or other materials provided with the
017:  *     distribution.
018:  *   * Neither the name of Intel Corporation nor the names of its
019:  *     contributors may be used to endorse or promote products derived
020:  *     from this software without specific prior written permission.
021:  *
022:  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
023:  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
024:  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
025:  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
026:  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
027:  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
028:  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
029:  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
030:  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
031:  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
032:  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
033:  *
034:  *
035:  * Intel Corporation <linux-wimax@intel.com>
036:  * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
037:  *  - Initial implementation
038:  *
039:  *
040:  * This file declares the user/kernel protocol that is spoken over
041:  * Generic Netlink, as well as any type declaration that is to be used
042:  * by kernel and user space.
043:  *
044:  * It is intended for user space to clone it verbatim to use it as a
045:  * primary reference for definitions.
046:  *
047:  * Stuff intended for kernel usage as well as full protocol and stack
048:  * documentation is rooted in include/net/wimax.h.
049:  */
050: 
051: #ifndef __LINUX__WIMAX_H__
052: #define __LINUX__WIMAX_H__
053: 
054: #include <linux/types.h>
055: 
056: enum {
057:         /**
058:          * Version of the interface (unsigned decimal, MMm, max 25.5)
059:          * M - Major: change if removing or modifying an existing call.
060:          * m - minor: change when adding a new call
061:          */
062:         WIMAX_GNL_VERSION = 01,
063:         /* Generic NetLink attributes */
064:         WIMAX_GNL_ATTR_INVALID = 0x00,
065:         WIMAX_GNL_ATTR_MAX = 10,
066: };
067: 
068: 
069: /*
070:  * Generic NetLink operations
071:  *
072:  * Most of these map to an API call; _OP_ stands for operation, _RP_
073:  * for reply and _RE_ for report (aka: signal).
074:  */
075: enum {
076:         WIMAX_GNL_OP_MSG_FROM_USER,     /* User to kernel message */
077:         WIMAX_GNL_OP_MSG_TO_USER,       /* Kernel to user message */
078:         WIMAX_GNL_OP_RFKILL,    /* Run wimax_rfkill() */
079:         WIMAX_GNL_OP_RESET,     /* Run wimax_rfkill() */
080:         WIMAX_GNL_RE_STATE_CHANGE,      /* Report: status change */
081:         WIMAX_GNL_OP_STATE_GET,         /* Request for current state */
082: };
083: 
084: 
085: /* Message from user / to user */
086: enum {
087:         WIMAX_GNL_MSG_IFIDX = 1,
088:         WIMAX_GNL_MSG_PIPE_NAME,
089:         WIMAX_GNL_MSG_DATA,
090: };
091: 
092: 
093: /*
094:  * wimax_rfkill()
095:  *
096:  * The state of the radio (ON/OFF) is mapped to the rfkill subsystem's
097:  * switch state (DISABLED/ENABLED).
098:  */
099: 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: 

---

---

---