Loading...
1/*
2 * Linux WiMAX
3 * Kernel space API for accessing WiMAX devices
4 *
5 *
6 * Copyright (C) 2007-2008 Intel Corporation <linux-wimax@intel.com>
7 * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
8 *
9 * This program is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU General Public License version
11 * 2 as published by the Free Software Foundation.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
17 *
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21 * 02110-1301, USA.
22 *
23 *
24 * The WiMAX stack provides an API for controlling and managing the
25 * system's WiMAX devices. This API affects the control plane; the
26 * data plane is accessed via the network stack (netdev).
27 *
28 * Parts of the WiMAX stack API and notifications are exported to
29 * user space via Generic Netlink. In user space, libwimax (part of
30 * the wimax-tools package) provides a shim layer for accessing those
31 * calls.
32 *
33 * The API is standarized for all WiMAX devices and different drivers
34 * implement the backend support for it. However, device-specific
35 * messaging pipes are provided that can be used to issue commands and
36 * receive notifications in free form.
37 *
38 * Currently the messaging pipes are the only means of control as it
39 * is not known (due to the lack of more devices in the market) what
40 * will be a good abstraction layer. Expect this to change as more
41 * devices show in the market. This API is designed to be growable in
42 * order to address this problem.
43 *
44 * USAGE
45 *
46 * Embed a `struct wimax_dev` at the beginning of the the device's
47 * private structure, initialize and register it. For details, see
48 * `struct wimax_dev`s documentation.
49 *
50 * Once this is done, wimax-tools's libwimaxll can be used to
51 * communicate with the driver from user space. You user space
52 * application does not have to forcibily use libwimaxll and can talk
53 * the generic netlink protocol directly if desired.
54 *
55 * Remember this is a very low level API that will to provide all of
56 * WiMAX features. Other daemons and services running in user space
57 * are the expected clients of it. They offer a higher level API that
58 * applications should use (an example of this is the Intel's WiMAX
59 * Network Service for the i2400m).
60 *
61 * DESIGN
62 *
63 * Although not set on final stone, this very basic interface is
64 * mostly completed. Remember this is meant to grow as new common
65 * operations are decided upon. New operations will be added to the
66 * interface, intent being on keeping backwards compatibility as much
67 * as possible.
68 *
69 * This layer implements a set of calls to control a WiMAX device,
70 * exposing a frontend to the rest of the kernel and user space (via
71 * generic netlink) and a backend implementation in the driver through
72 * function pointers.
73 *
74 * WiMAX devices have a state, and a kernel-only API allows the
75 * drivers to manipulate that state. State transitions are atomic, and
76 * only some of them are allowed (see `enum wimax_st`).
77 *
78 * Most API calls will set the state automatically; in most cases
79 * drivers have to only report state changes due to external
80 * conditions.
81 *
82 * All API operations are 'atomic', serialized through a mutex in the
83 * `struct wimax_dev`.
84 *
85 * EXPORTING TO USER SPACE THROUGH GENERIC NETLINK
86 *
87 * The API is exported to user space using generic netlink (other
88 * methods can be added as needed).
89 *
90 * There is a Generic Netlink Family named "WiMAX", where interfaces
91 * supporting the WiMAX interface receive commands and broadcast their
92 * signals over a multicast group named "msg".
93 *
94 * Mapping to the source/destination interface is done by an interface
95 * index attribute.
96 *
97 * For user-to-kernel traffic (commands) we use a function call
98 * marshalling mechanism, where a message X with attributes A, B, C
99 * sent from user space to kernel space means executing the WiMAX API
100 * call wimax_X(A, B, C), sending the results back as a message.
101 *
102 * Kernel-to-user (notifications or signals) communication is sent
103 * over multicast groups. This allows to have multiple applications
104 * monitoring them.
105 *
106 * Each command/signal gets assigned it's own attribute policy. This
107 * way the validator will verify that all the attributes in there are
108 * only the ones that should be for each command/signal. Thing of an
109 * attribute mapping to a type+argumentname for each command/signal.
110 *
111 * If we had a single policy for *all* commands/signals, after running
112 * the validator we'd have to check "does this attribute belong in
113 * here"? for each one. It can be done manually, but it's just easier
114 * to have the validator do that job with multiple policies. As well,
115 * it makes it easier to later expand each command/signal signature
116 * without affecting others and keeping the namespace more or less
117 * sane. Not that it is too complicated, but it makes it even easier.
118 *
119 * No state information is maintained in the kernel for each user
120 * space connection (the connection is stateless).
121 *
122 * TESTING FOR THE INTERFACE AND VERSIONING
123 *
124 * If network interface X is a WiMAX device, there will be a Generic
125 * Netlink family named "WiMAX X" and the device will present a
126 * "wimax" directory in it's network sysfs directory
127 * (/sys/class/net/DEVICE/wimax) [used by HAL].
128 *
129 * The inexistence of any of these means the device does not support
130 * this WiMAX API.
131 *
132 * By querying the generic netlink controller, versioning information
133 * and the multicast groups available can be found. Applications using
134 * the interface can either rely on that or use the generic netlink
135 * controller to figure out which generic netlink commands/signals are
136 * supported.
137 *
138 * NOTE: this versioning is a last resort to avoid hard
139 * incompatibilities. It is the intention of the design of this
140 * stack not to introduce backward incompatible changes.
141 *
142 * The version code has to fit in one byte (restrictions imposed by
143 * generic netlink); we use `version / 10` for the major version and
144 * `version % 10` for the minor. This gives 9 minors for each major
145 * and 25 majors.
146 *
147 * The version change protocol is as follow:
148 *
149 * - Major versions: needs to be increased if an existing message/API
150 * call is changed or removed. Doesn't need to be changed if a new
151 * message is added.
152 *
153 * - Minor version: needs to be increased if new messages/API calls are
154 * being added or some other consideration that doesn't impact the
155 * user-kernel interface too much (like some kind of bug fix) and
156 * that is kind of left up in the air to common sense.
157 *
158 * User space code should not try to work if the major version it was
159 * compiled for differs from what the kernel offers. As well, if the
160 * minor version of the kernel interface is lower than the one user
161 * space is expecting (the one it was compiled for), the kernel
162 * might be missing API calls; user space shall be ready to handle
163 * said condition. Use the generic netlink controller operations to
164 * find which ones are supported and which not.
165 *
166 * libwimaxll:wimaxll_open() takes care of checking versions.
167 *
168 * THE OPERATIONS:
169 *
170 * Each operation is defined in its on file (drivers/net/wimax/op-*.c)
171 * for clarity. The parts needed for an operation are:
172 *
173 * - a function pointer in `struct wimax_dev`: optional, as the
174 * operation might be implemented by the stack and not by the
175 * driver.
176 *
177 * All function pointers are named wimax_dev->op_*(), and drivers
178 * must implement them except where noted otherwise.
179 *
180 * - When exported to user space, a `struct nla_policy` to define the
181 * attributes of the generic netlink command and a `struct genl_ops`
182 * to define the operation.
183 *
184 * All the declarations for the operation codes (WIMAX_GNL_OP_<NAME>)
185 * and generic netlink attributes (WIMAX_GNL_<NAME>_*) are declared in
186 * include/linux/wimax.h; this file is intended to be cloned by user
187 * space to gain access to those declarations.
188 *
189 * A few caveats to remember:
190 *
191 * - Need to define attribute numbers starting in 1; otherwise it
192 * fails.
193 *
194 * - the `struct genl_family` requires a maximum attribute id; when
195 * defining the `struct nla_policy` for each message, it has to have
196 * an array size of WIMAX_GNL_ATTR_MAX+1.
197 *
198 * The op_*() function pointers will not be called if the wimax_dev is
199 * in a state <= %WIMAX_ST_UNINITIALIZED. The exception is:
200 *
201 * - op_reset: can be called at any time after wimax_dev_add() has
202 * been called.
203 *
204 * THE PIPE INTERFACE:
205 *
206 * This interface is kept intentionally simple. The driver can send
207 * and receive free-form messages to/from user space through a
208 * pipe. See drivers/net/wimax/op-msg.c for details.
209 *
210 * The kernel-to-user messages are sent with
211 * wimax_msg(). user-to-kernel messages are delivered via
212 * wimax_dev->op_msg_from_user().
213 *
214 * RFKILL:
215 *
216 * RFKILL support is built into the wimax_dev layer; the driver just
217 * needs to call wimax_report_rfkill_{hw,sw}() to inform of changes in
218 * the hardware or software RF kill switches. When the stack wants to
219 * turn the radio off, it will call wimax_dev->op_rfkill_sw_toggle(),
220 * which the driver implements.
221 *
222 * User space can set the software RF Kill switch by calling
223 * wimax_rfkill().
224 *
225 * The code for now only supports devices that don't require polling;
226 * If the device needs to be polled, create a self-rearming delayed
227 * work struct for polling or look into adding polled support to the
228 * WiMAX stack.
229 *
230 * When initializing the hardware (_probe), after calling
231 * wimax_dev_add(), query the device for it's RF Kill switches status
232 * and feed it back to the WiMAX stack using
233 * wimax_report_rfkill_{hw,sw}(). If any switch is missing, always
234 * report it as ON.
235 *
236 * NOTE: the wimax stack uses an inverted terminology to that of the
237 * RFKILL subsystem:
238 *
239 * - ON: radio is ON, RFKILL is DISABLED or OFF.
240 * - OFF: radio is OFF, RFKILL is ENABLED or ON.
241 *
242 * MISCELLANEOUS OPS:
243 *
244 * wimax_reset() can be used to reset the device to power on state; by
245 * default it issues a warm reset that maintains the same device
246 * node. If that is not possible, it falls back to a cold reset
247 * (device reconnect). The driver implements the backend to this
248 * through wimax_dev->op_reset().
249 */
250
251#ifndef __NET__WIMAX_H__
252#define __NET__WIMAX_H__
253
254#include <linux/wimax.h>
255#include <net/genetlink.h>
256#include <linux/netdevice.h>
257
258struct net_device;
259struct genl_info;
260struct wimax_dev;
261
262/**
263 * struct wimax_dev - Generic WiMAX device
264 *
265 * @net_dev: [fill] Pointer to the &struct net_device this WiMAX
266 * device implements.
267 *
268 * @op_msg_from_user: [fill] Driver-specific operation to
269 * handle a raw message from user space to the driver. The
270 * driver can send messages to user space using with
271 * wimax_msg_to_user().
272 *
273 * @op_rfkill_sw_toggle: [fill] Driver-specific operation to act on
274 * userspace (or any other agent) requesting the WiMAX device to
275 * change the RF Kill software switch (WIMAX_RF_ON or
276 * WIMAX_RF_OFF).
277 * If such hardware support is not present, it is assumed the
278 * radio cannot be switched off and it is always on (and the stack
279 * will error out when trying to switch it off). In such case,
280 * this function pointer can be left as NULL.
281 *
282 * @op_reset: [fill] Driver specific operation to reset the
283 * device.
284 * This operation should always attempt first a warm reset that
285 * does not disconnect the device from the bus and return 0.
286 * If that fails, it should resort to some sort of cold or bus
287 * reset (even if it implies a bus disconnection and device
288 * disappearance). In that case, -ENODEV should be returned to
289 * indicate the device is gone.
290 * This operation has to be synchronous, and return only when the
291 * reset is complete. In case of having had to resort to bus/cold
292 * reset implying a device disconnection, the call is allowed to
293 * return inmediately.
294 * NOTE: wimax_dev->mutex is NOT locked when this op is being
295 * called; however, wimax_dev->mutex_reset IS locked to ensure
296 * serialization of calls to wimax_reset().
297 * See wimax_reset()'s documentation.
298 *
299 * @name: [fill] A way to identify this device. We need to register a
300 * name with many subsystems (rfkill, workqueue creation, etc).
301 * We can't use the network device name as that
302 * might change and in some instances we don't know it yet (until
303 * we don't call register_netdev()). So we generate an unique one
304 * using the driver name and device bus id, place it here and use
305 * it across the board. Recommended naming:
306 * DRIVERNAME-BUSNAME:BUSID (dev->bus->name, dev->bus_id).
307 *
308 * @id_table_node: [private] link to the list of wimax devices kept by
309 * id-table.c. Protected by it's own spinlock.
310 *
311 * @mutex: [private] Serializes all concurrent access and execution of
312 * operations.
313 *
314 * @mutex_reset: [private] Serializes reset operations. Needs to be a
315 * different mutex because as part of the reset operation, the
316 * driver has to call back into the stack to do things such as
317 * state change, that require wimax_dev->mutex.
318 *
319 * @state: [private] Current state of the WiMAX device.
320 *
321 * @rfkill: [private] integration into the RF-Kill infrastructure.
322 *
323 * @rf_sw: [private] State of the software radio switch (OFF/ON)
324 *
325 * @rf_hw: [private] State of the hardware radio switch (OFF/ON)
326 *
327 * @debugfs_dentry: [private] Used to hook up a debugfs entry. This
328 * shows up in the debugfs root as wimax\:DEVICENAME.
329 *
330 * Description:
331 * This structure defines a common interface to access all WiMAX
332 * devices from different vendors and provides a common API as well as
333 * a free-form device-specific messaging channel.
334 *
335 * Usage:
336 * 1. Embed a &struct wimax_dev at *the beginning* the network
337 * device structure so that netdev_priv() points to it.
338 *
339 * 2. memset() it to zero
340 *
341 * 3. Initialize with wimax_dev_init(). This will leave the WiMAX
342 * device in the %__WIMAX_ST_NULL state.
343 *
344 * 4. Fill all the fields marked with [fill]; once called
345 * wimax_dev_add(), those fields CANNOT be modified.
346 *
347 * 5. Call wimax_dev_add() *after* registering the network
348 * device. This will leave the WiMAX device in the %WIMAX_ST_DOWN
349 * state.
350 * Protect the driver's net_device->open() against succeeding if
351 * the wimax device state is lower than %WIMAX_ST_DOWN.
352 *
353 * 6. Select when the device is going to be turned on/initialized;
354 * for example, it could be initialized on 'ifconfig up' (when the
355 * netdev op 'open()' is called on the driver).
356 *
357 * When the device is initialized (at `ifconfig up` time, or right
358 * after calling wimax_dev_add() from _probe(), make sure the
359 * following steps are taken
360 *
361 * a. Move the device to %WIMAX_ST_UNINITIALIZED. This is needed so
362 * some API calls that shouldn't work until the device is ready
363 * can be blocked.
364 *
365 * b. Initialize the device. Make sure to turn the SW radio switch
366 * off and move the device to state %WIMAX_ST_RADIO_OFF when
367 * done. When just initialized, a device should be left in RADIO
368 * OFF state until user space devices to turn it on.
369 *
370 * c. Query the device for the state of the hardware rfkill switch
371 * and call wimax_rfkill_report_hw() and wimax_rfkill_report_sw()
372 * as needed. See below.
373 *
374 * wimax_dev_rm() undoes before unregistering the network device. Once
375 * wimax_dev_add() is called, the driver can get called on the
376 * wimax_dev->op_* function pointers
377 *
378 * CONCURRENCY:
379 *
380 * The stack provides a mutex for each device that will disallow API
381 * calls happening concurrently; thus, op calls into the driver
382 * through the wimax_dev->op*() function pointers will always be
383 * serialized and *never* concurrent.
384 *
385 * For locking, take wimax_dev->mutex is taken; (most) operations in
386 * the API have to check for wimax_dev_is_ready() to return 0 before
387 * continuing (this is done internally).
388 *
389 * REFERENCE COUNTING:
390 *
391 * The WiMAX device is reference counted by the associated network
392 * device. The only operation that can be used to reference the device
393 * is wimax_dev_get_by_genl_info(), and the reference it acquires has
394 * to be released with dev_put(wimax_dev->net_dev).
395 *
396 * RFKILL:
397 *
398 * At startup, both HW and SW radio switchess are assumed to be off.
399 *
400 * At initialization time [after calling wimax_dev_add()], have the
401 * driver query the device for the status of the software and hardware
402 * RF kill switches and call wimax_report_rfkill_hw() and
403 * wimax_rfkill_report_sw() to indicate their state. If any is
404 * missing, just call it to indicate it is ON (radio always on).
405 *
406 * Whenever the driver detects a change in the state of the RF kill
407 * switches, it should call wimax_report_rfkill_hw() or
408 * wimax_report_rfkill_sw() to report it to the stack.
409 */
410struct wimax_dev {
411 struct net_device *net_dev;
412 struct list_head id_table_node;
413 struct mutex mutex; /* Protects all members and API calls */
414 struct mutex mutex_reset;
415 enum wimax_st state;
416
417 int (*op_msg_from_user)(struct wimax_dev *wimax_dev,
418 const char *,
419 const void *, size_t,
420 const struct genl_info *info);
421 int (*op_rfkill_sw_toggle)(struct wimax_dev *wimax_dev,
422 enum wimax_rf_state);
423 int (*op_reset)(struct wimax_dev *wimax_dev);
424
425 struct rfkill *rfkill;
426 unsigned rf_hw;
427 unsigned rf_sw;
428 char name[32];
429
430 struct dentry *debugfs_dentry;
431};
432
433
434
435/*
436 * WiMAX stack public API for device drivers
437 * -----------------------------------------
438 *
439 * These functions are not exported to user space.
440 */
441extern void wimax_dev_init(struct wimax_dev *);
442extern int wimax_dev_add(struct wimax_dev *, struct net_device *);
443extern void wimax_dev_rm(struct wimax_dev *);
444
445static inline
446struct wimax_dev *net_dev_to_wimax(struct net_device *net_dev)
447{
448 return netdev_priv(net_dev);
449}
450
451static inline
452struct device *wimax_dev_to_dev(struct wimax_dev *wimax_dev)
453{
454 return wimax_dev->net_dev->dev.parent;
455}
456
457extern void wimax_state_change(struct wimax_dev *, enum wimax_st);
458extern enum wimax_st wimax_state_get(struct wimax_dev *);
459
460/*
461 * Radio Switch state reporting.
462 *
463 * enum wimax_rf_state is declared in linux/wimax.h so the exports
464 * to user space can use it.
465 */
466extern void wimax_report_rfkill_hw(struct wimax_dev *, enum wimax_rf_state);
467extern void wimax_report_rfkill_sw(struct wimax_dev *, enum wimax_rf_state);
468
469
470/*
471 * Free-form messaging to/from user space
472 *
473 * Sending a message:
474 *
475 * wimax_msg(wimax_dev, pipe_name, buf, buf_size, GFP_KERNEL);
476 *
477 * Broken up:
478 *
479 * skb = wimax_msg_alloc(wimax_dev, pipe_name, buf_size, GFP_KERNEL);
480 * ...fill up skb...
481 * wimax_msg_send(wimax_dev, pipe_name, skb);
482 *
483 * Be sure not to modify skb->data in the middle (ie: don't use
484 * skb_push()/skb_pull()/skb_reserve() on the skb).
485 *
486 * "pipe_name" is any string, than can be interpreted as the name of
487 * the pipe or destinatary; the interpretation of it is driver
488 * specific, so the recipient can multiplex it as wished. It can be
489 * NULL, it won't be used - an example is using a "diagnostics" tag to
490 * send diagnostics information that a device-specific diagnostics
491 * tool would be interested in.
492 */
493extern struct sk_buff *wimax_msg_alloc(struct wimax_dev *, const char *,
494 const void *, size_t, gfp_t);
495extern int wimax_msg_send(struct wimax_dev *, struct sk_buff *);
496extern int wimax_msg(struct wimax_dev *, const char *,
497 const void *, size_t, gfp_t);
498
499extern const void *wimax_msg_data_len(struct sk_buff *, size_t *);
500extern const void *wimax_msg_data(struct sk_buff *);
501extern ssize_t wimax_msg_len(struct sk_buff *);
502
503
504/*
505 * WiMAX stack user space API
506 * --------------------------
507 *
508 * This API is what gets exported to user space for general
509 * operations. As well, they can be called from within the kernel,
510 * (with a properly referenced `struct wimax_dev`).
511 *
512 * Properly referenced means: the 'struct net_device' that embeds the
513 * device's control structure and (as such) the 'struct wimax_dev' is
514 * referenced by the caller.
515 */
516extern int wimax_rfkill(struct wimax_dev *, enum wimax_rf_state);
517extern int wimax_reset(struct wimax_dev *);
518
519#endif /* #ifndef __NET__WIMAX_H__ */
1/* SPDX-License-Identifier: GPL-2.0-only */
2/*
3 * Linux WiMAX
4 * Kernel space API for accessing WiMAX devices
5 *
6 * Copyright (C) 2007-2008 Intel Corporation <linux-wimax@intel.com>
7 * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
8 *
9 * The WiMAX stack provides an API for controlling and managing the
10 * system's WiMAX devices. This API affects the control plane; the
11 * data plane is accessed via the network stack (netdev).
12 *
13 * Parts of the WiMAX stack API and notifications are exported to
14 * user space via Generic Netlink. In user space, libwimax (part of
15 * the wimax-tools package) provides a shim layer for accessing those
16 * calls.
17 *
18 * The API is standarized for all WiMAX devices and different drivers
19 * implement the backend support for it. However, device-specific
20 * messaging pipes are provided that can be used to issue commands and
21 * receive notifications in free form.
22 *
23 * Currently the messaging pipes are the only means of control as it
24 * is not known (due to the lack of more devices in the market) what
25 * will be a good abstraction layer. Expect this to change as more
26 * devices show in the market. This API is designed to be growable in
27 * order to address this problem.
28 *
29 * USAGE
30 *
31 * Embed a `struct wimax_dev` at the beginning of the device's
32 * private structure, initialize and register it. For details, see
33 * `struct wimax_dev`s documentation.
34 *
35 * Once this is done, wimax-tools's libwimaxll can be used to
36 * communicate with the driver from user space. You user space
37 * application does not have to forcibily use libwimaxll and can talk
38 * the generic netlink protocol directly if desired.
39 *
40 * Remember this is a very low level API that will to provide all of
41 * WiMAX features. Other daemons and services running in user space
42 * are the expected clients of it. They offer a higher level API that
43 * applications should use (an example of this is the Intel's WiMAX
44 * Network Service for the i2400m).
45 *
46 * DESIGN
47 *
48 * Although not set on final stone, this very basic interface is
49 * mostly completed. Remember this is meant to grow as new common
50 * operations are decided upon. New operations will be added to the
51 * interface, intent being on keeping backwards compatibility as much
52 * as possible.
53 *
54 * This layer implements a set of calls to control a WiMAX device,
55 * exposing a frontend to the rest of the kernel and user space (via
56 * generic netlink) and a backend implementation in the driver through
57 * function pointers.
58 *
59 * WiMAX devices have a state, and a kernel-only API allows the
60 * drivers to manipulate that state. State transitions are atomic, and
61 * only some of them are allowed (see `enum wimax_st`).
62 *
63 * Most API calls will set the state automatically; in most cases
64 * drivers have to only report state changes due to external
65 * conditions.
66 *
67 * All API operations are 'atomic', serialized through a mutex in the
68 * `struct wimax_dev`.
69 *
70 * EXPORTING TO USER SPACE THROUGH GENERIC NETLINK
71 *
72 * The API is exported to user space using generic netlink (other
73 * methods can be added as needed).
74 *
75 * There is a Generic Netlink Family named "WiMAX", where interfaces
76 * supporting the WiMAX interface receive commands and broadcast their
77 * signals over a multicast group named "msg".
78 *
79 * Mapping to the source/destination interface is done by an interface
80 * index attribute.
81 *
82 * For user-to-kernel traffic (commands) we use a function call
83 * marshalling mechanism, where a message X with attributes A, B, C
84 * sent from user space to kernel space means executing the WiMAX API
85 * call wimax_X(A, B, C), sending the results back as a message.
86 *
87 * Kernel-to-user (notifications or signals) communication is sent
88 * over multicast groups. This allows to have multiple applications
89 * monitoring them.
90 *
91 * Each command/signal gets assigned it's own attribute policy. This
92 * way the validator will verify that all the attributes in there are
93 * only the ones that should be for each command/signal. Thing of an
94 * attribute mapping to a type+argumentname for each command/signal.
95 *
96 * If we had a single policy for *all* commands/signals, after running
97 * the validator we'd have to check "does this attribute belong in
98 * here"? for each one. It can be done manually, but it's just easier
99 * to have the validator do that job with multiple policies. As well,
100 * it makes it easier to later expand each command/signal signature
101 * without affecting others and keeping the namespace more or less
102 * sane. Not that it is too complicated, but it makes it even easier.
103 *
104 * No state information is maintained in the kernel for each user
105 * space connection (the connection is stateless).
106 *
107 * TESTING FOR THE INTERFACE AND VERSIONING
108 *
109 * If network interface X is a WiMAX device, there will be a Generic
110 * Netlink family named "WiMAX X" and the device will present a
111 * "wimax" directory in it's network sysfs directory
112 * (/sys/class/net/DEVICE/wimax) [used by HAL].
113 *
114 * The inexistence of any of these means the device does not support
115 * this WiMAX API.
116 *
117 * By querying the generic netlink controller, versioning information
118 * and the multicast groups available can be found. Applications using
119 * the interface can either rely on that or use the generic netlink
120 * controller to figure out which generic netlink commands/signals are
121 * supported.
122 *
123 * NOTE: this versioning is a last resort to avoid hard
124 * incompatibilities. It is the intention of the design of this
125 * stack not to introduce backward incompatible changes.
126 *
127 * The version code has to fit in one byte (restrictions imposed by
128 * generic netlink); we use `version / 10` for the major version and
129 * `version % 10` for the minor. This gives 9 minors for each major
130 * and 25 majors.
131 *
132 * The version change protocol is as follow:
133 *
134 * - Major versions: needs to be increased if an existing message/API
135 * call is changed or removed. Doesn't need to be changed if a new
136 * message is added.
137 *
138 * - Minor version: needs to be increased if new messages/API calls are
139 * being added or some other consideration that doesn't impact the
140 * user-kernel interface too much (like some kind of bug fix) and
141 * that is kind of left up in the air to common sense.
142 *
143 * User space code should not try to work if the major version it was
144 * compiled for differs from what the kernel offers. As well, if the
145 * minor version of the kernel interface is lower than the one user
146 * space is expecting (the one it was compiled for), the kernel
147 * might be missing API calls; user space shall be ready to handle
148 * said condition. Use the generic netlink controller operations to
149 * find which ones are supported and which not.
150 *
151 * libwimaxll:wimaxll_open() takes care of checking versions.
152 *
153 * THE OPERATIONS:
154 *
155 * Each operation is defined in its on file (drivers/net/wimax/op-*.c)
156 * for clarity. The parts needed for an operation are:
157 *
158 * - a function pointer in `struct wimax_dev`: optional, as the
159 * operation might be implemented by the stack and not by the
160 * driver.
161 *
162 * All function pointers are named wimax_dev->op_*(), and drivers
163 * must implement them except where noted otherwise.
164 *
165 * - When exported to user space, a `struct nla_policy` to define the
166 * attributes of the generic netlink command and a `struct genl_ops`
167 * to define the operation.
168 *
169 * All the declarations for the operation codes (WIMAX_GNL_OP_<NAME>)
170 * and generic netlink attributes (WIMAX_GNL_<NAME>_*) are declared in
171 * include/linux/wimax.h; this file is intended to be cloned by user
172 * space to gain access to those declarations.
173 *
174 * A few caveats to remember:
175 *
176 * - Need to define attribute numbers starting in 1; otherwise it
177 * fails.
178 *
179 * - the `struct genl_family` requires a maximum attribute id; when
180 * defining the `struct nla_policy` for each message, it has to have
181 * an array size of WIMAX_GNL_ATTR_MAX+1.
182 *
183 * The op_*() function pointers will not be called if the wimax_dev is
184 * in a state <= %WIMAX_ST_UNINITIALIZED. The exception is:
185 *
186 * - op_reset: can be called at any time after wimax_dev_add() has
187 * been called.
188 *
189 * THE PIPE INTERFACE:
190 *
191 * This interface is kept intentionally simple. The driver can send
192 * and receive free-form messages to/from user space through a
193 * pipe. See drivers/net/wimax/op-msg.c for details.
194 *
195 * The kernel-to-user messages are sent with
196 * wimax_msg(). user-to-kernel messages are delivered via
197 * wimax_dev->op_msg_from_user().
198 *
199 * RFKILL:
200 *
201 * RFKILL support is built into the wimax_dev layer; the driver just
202 * needs to call wimax_report_rfkill_{hw,sw}() to inform of changes in
203 * the hardware or software RF kill switches. When the stack wants to
204 * turn the radio off, it will call wimax_dev->op_rfkill_sw_toggle(),
205 * which the driver implements.
206 *
207 * User space can set the software RF Kill switch by calling
208 * wimax_rfkill().
209 *
210 * The code for now only supports devices that don't require polling;
211 * If the device needs to be polled, create a self-rearming delayed
212 * work struct for polling or look into adding polled support to the
213 * WiMAX stack.
214 *
215 * When initializing the hardware (_probe), after calling
216 * wimax_dev_add(), query the device for it's RF Kill switches status
217 * and feed it back to the WiMAX stack using
218 * wimax_report_rfkill_{hw,sw}(). If any switch is missing, always
219 * report it as ON.
220 *
221 * NOTE: the wimax stack uses an inverted terminology to that of the
222 * RFKILL subsystem:
223 *
224 * - ON: radio is ON, RFKILL is DISABLED or OFF.
225 * - OFF: radio is OFF, RFKILL is ENABLED or ON.
226 *
227 * MISCELLANEOUS OPS:
228 *
229 * wimax_reset() can be used to reset the device to power on state; by
230 * default it issues a warm reset that maintains the same device
231 * node. If that is not possible, it falls back to a cold reset
232 * (device reconnect). The driver implements the backend to this
233 * through wimax_dev->op_reset().
234 */
235
236#ifndef __NET__WIMAX_H__
237#define __NET__WIMAX_H__
238
239#include <linux/wimax.h>
240#include <net/genetlink.h>
241#include <linux/netdevice.h>
242
243struct net_device;
244struct genl_info;
245struct wimax_dev;
246
247/**
248 * struct wimax_dev - Generic WiMAX device
249 *
250 * @net_dev: [fill] Pointer to the &struct net_device this WiMAX
251 * device implements.
252 *
253 * @op_msg_from_user: [fill] Driver-specific operation to
254 * handle a raw message from user space to the driver. The
255 * driver can send messages to user space using with
256 * wimax_msg_to_user().
257 *
258 * @op_rfkill_sw_toggle: [fill] Driver-specific operation to act on
259 * userspace (or any other agent) requesting the WiMAX device to
260 * change the RF Kill software switch (WIMAX_RF_ON or
261 * WIMAX_RF_OFF).
262 * If such hardware support is not present, it is assumed the
263 * radio cannot be switched off and it is always on (and the stack
264 * will error out when trying to switch it off). In such case,
265 * this function pointer can be left as NULL.
266 *
267 * @op_reset: [fill] Driver specific operation to reset the
268 * device.
269 * This operation should always attempt first a warm reset that
270 * does not disconnect the device from the bus and return 0.
271 * If that fails, it should resort to some sort of cold or bus
272 * reset (even if it implies a bus disconnection and device
273 * disappearance). In that case, -ENODEV should be returned to
274 * indicate the device is gone.
275 * This operation has to be synchronous, and return only when the
276 * reset is complete. In case of having had to resort to bus/cold
277 * reset implying a device disconnection, the call is allowed to
278 * return immediately.
279 * NOTE: wimax_dev->mutex is NOT locked when this op is being
280 * called; however, wimax_dev->mutex_reset IS locked to ensure
281 * serialization of calls to wimax_reset().
282 * See wimax_reset()'s documentation.
283 *
284 * @name: [fill] A way to identify this device. We need to register a
285 * name with many subsystems (rfkill, workqueue creation, etc).
286 * We can't use the network device name as that
287 * might change and in some instances we don't know it yet (until
288 * we don't call register_netdev()). So we generate an unique one
289 * using the driver name and device bus id, place it here and use
290 * it across the board. Recommended naming:
291 * DRIVERNAME-BUSNAME:BUSID (dev->bus->name, dev->bus_id).
292 *
293 * @id_table_node: [private] link to the list of wimax devices kept by
294 * id-table.c. Protected by it's own spinlock.
295 *
296 * @mutex: [private] Serializes all concurrent access and execution of
297 * operations.
298 *
299 * @mutex_reset: [private] Serializes reset operations. Needs to be a
300 * different mutex because as part of the reset operation, the
301 * driver has to call back into the stack to do things such as
302 * state change, that require wimax_dev->mutex.
303 *
304 * @state: [private] Current state of the WiMAX device.
305 *
306 * @rfkill: [private] integration into the RF-Kill infrastructure.
307 *
308 * @rf_sw: [private] State of the software radio switch (OFF/ON)
309 *
310 * @rf_hw: [private] State of the hardware radio switch (OFF/ON)
311 *
312 * @debugfs_dentry: [private] Used to hook up a debugfs entry. This
313 * shows up in the debugfs root as wimax\:DEVICENAME.
314 *
315 * Description:
316 * This structure defines a common interface to access all WiMAX
317 * devices from different vendors and provides a common API as well as
318 * a free-form device-specific messaging channel.
319 *
320 * Usage:
321 * 1. Embed a &struct wimax_dev at *the beginning* the network
322 * device structure so that netdev_priv() points to it.
323 *
324 * 2. memset() it to zero
325 *
326 * 3. Initialize with wimax_dev_init(). This will leave the WiMAX
327 * device in the %__WIMAX_ST_NULL state.
328 *
329 * 4. Fill all the fields marked with [fill]; once called
330 * wimax_dev_add(), those fields CANNOT be modified.
331 *
332 * 5. Call wimax_dev_add() *after* registering the network
333 * device. This will leave the WiMAX device in the %WIMAX_ST_DOWN
334 * state.
335 * Protect the driver's net_device->open() against succeeding if
336 * the wimax device state is lower than %WIMAX_ST_DOWN.
337 *
338 * 6. Select when the device is going to be turned on/initialized;
339 * for example, it could be initialized on 'ifconfig up' (when the
340 * netdev op 'open()' is called on the driver).
341 *
342 * When the device is initialized (at `ifconfig up` time, or right
343 * after calling wimax_dev_add() from _probe(), make sure the
344 * following steps are taken
345 *
346 * a. Move the device to %WIMAX_ST_UNINITIALIZED. This is needed so
347 * some API calls that shouldn't work until the device is ready
348 * can be blocked.
349 *
350 * b. Initialize the device. Make sure to turn the SW radio switch
351 * off and move the device to state %WIMAX_ST_RADIO_OFF when
352 * done. When just initialized, a device should be left in RADIO
353 * OFF state until user space devices to turn it on.
354 *
355 * c. Query the device for the state of the hardware rfkill switch
356 * and call wimax_rfkill_report_hw() and wimax_rfkill_report_sw()
357 * as needed. See below.
358 *
359 * wimax_dev_rm() undoes before unregistering the network device. Once
360 * wimax_dev_add() is called, the driver can get called on the
361 * wimax_dev->op_* function pointers
362 *
363 * CONCURRENCY:
364 *
365 * The stack provides a mutex for each device that will disallow API
366 * calls happening concurrently; thus, op calls into the driver
367 * through the wimax_dev->op*() function pointers will always be
368 * serialized and *never* concurrent.
369 *
370 * For locking, take wimax_dev->mutex is taken; (most) operations in
371 * the API have to check for wimax_dev_is_ready() to return 0 before
372 * continuing (this is done internally).
373 *
374 * REFERENCE COUNTING:
375 *
376 * The WiMAX device is reference counted by the associated network
377 * device. The only operation that can be used to reference the device
378 * is wimax_dev_get_by_genl_info(), and the reference it acquires has
379 * to be released with dev_put(wimax_dev->net_dev).
380 *
381 * RFKILL:
382 *
383 * At startup, both HW and SW radio switchess are assumed to be off.
384 *
385 * At initialization time [after calling wimax_dev_add()], have the
386 * driver query the device for the status of the software and hardware
387 * RF kill switches and call wimax_report_rfkill_hw() and
388 * wimax_rfkill_report_sw() to indicate their state. If any is
389 * missing, just call it to indicate it is ON (radio always on).
390 *
391 * Whenever the driver detects a change in the state of the RF kill
392 * switches, it should call wimax_report_rfkill_hw() or
393 * wimax_report_rfkill_sw() to report it to the stack.
394 */
395struct wimax_dev {
396 struct net_device *net_dev;
397 struct list_head id_table_node;
398 struct mutex mutex; /* Protects all members and API calls */
399 struct mutex mutex_reset;
400 enum wimax_st state;
401
402 int (*op_msg_from_user)(struct wimax_dev *wimax_dev,
403 const char *,
404 const void *, size_t,
405 const struct genl_info *info);
406 int (*op_rfkill_sw_toggle)(struct wimax_dev *wimax_dev,
407 enum wimax_rf_state);
408 int (*op_reset)(struct wimax_dev *wimax_dev);
409
410 struct rfkill *rfkill;
411 unsigned int rf_hw;
412 unsigned int rf_sw;
413 char name[32];
414
415 struct dentry *debugfs_dentry;
416};
417
418
419
420/*
421 * WiMAX stack public API for device drivers
422 * -----------------------------------------
423 *
424 * These functions are not exported to user space.
425 */
426void wimax_dev_init(struct wimax_dev *);
427int wimax_dev_add(struct wimax_dev *, struct net_device *);
428void wimax_dev_rm(struct wimax_dev *);
429
430static inline
431struct wimax_dev *net_dev_to_wimax(struct net_device *net_dev)
432{
433 return netdev_priv(net_dev);
434}
435
436static inline
437struct device *wimax_dev_to_dev(struct wimax_dev *wimax_dev)
438{
439 return wimax_dev->net_dev->dev.parent;
440}
441
442void wimax_state_change(struct wimax_dev *, enum wimax_st);
443enum wimax_st wimax_state_get(struct wimax_dev *);
444
445/*
446 * Radio Switch state reporting.
447 *
448 * enum wimax_rf_state is declared in linux/wimax.h so the exports
449 * to user space can use it.
450 */
451void wimax_report_rfkill_hw(struct wimax_dev *, enum wimax_rf_state);
452void wimax_report_rfkill_sw(struct wimax_dev *, enum wimax_rf_state);
453
454
455/*
456 * Free-form messaging to/from user space
457 *
458 * Sending a message:
459 *
460 * wimax_msg(wimax_dev, pipe_name, buf, buf_size, GFP_KERNEL);
461 *
462 * Broken up:
463 *
464 * skb = wimax_msg_alloc(wimax_dev, pipe_name, buf_size, GFP_KERNEL);
465 * ...fill up skb...
466 * wimax_msg_send(wimax_dev, pipe_name, skb);
467 *
468 * Be sure not to modify skb->data in the middle (ie: don't use
469 * skb_push()/skb_pull()/skb_reserve() on the skb).
470 *
471 * "pipe_name" is any string, that can be interpreted as the name of
472 * the pipe or recipient; the interpretation of it is driver
473 * specific, so the recipient can multiplex it as wished. It can be
474 * NULL, it won't be used - an example is using a "diagnostics" tag to
475 * send diagnostics information that a device-specific diagnostics
476 * tool would be interested in.
477 */
478struct sk_buff *wimax_msg_alloc(struct wimax_dev *, const char *, const void *,
479 size_t, gfp_t);
480int wimax_msg_send(struct wimax_dev *, struct sk_buff *);
481int wimax_msg(struct wimax_dev *, const char *, const void *, size_t, gfp_t);
482
483const void *wimax_msg_data_len(struct sk_buff *, size_t *);
484const void *wimax_msg_data(struct sk_buff *);
485ssize_t wimax_msg_len(struct sk_buff *);
486
487
488/*
489 * WiMAX stack user space API
490 * --------------------------
491 *
492 * This API is what gets exported to user space for general
493 * operations. As well, they can be called from within the kernel,
494 * (with a properly referenced `struct wimax_dev`).
495 *
496 * Properly referenced means: the 'struct net_device' that embeds the
497 * device's control structure and (as such) the 'struct wimax_dev' is
498 * referenced by the caller.
499 */
500int wimax_rfkill(struct wimax_dev *, enum wimax_rf_state);
501int wimax_reset(struct wimax_dev *);
502
503#endif /* #ifndef __NET__WIMAX_H__ */