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