|
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__ */ |