Commit | Line | Data |
---|---|---|
ace22f08 IPG |
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__ */ |