~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/include/net/wimax.h

Version: ~ [ linux-5.11-rc3 ] ~ [ linux-5.10.7 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.89 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.167 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.215 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.251 ] ~ [ linux-4.8.17 ] ~ [ linux-4.7.10 ] ~ [ linux-4.6.7 ] ~ [ linux-4.5.7 ] ~ [ linux-4.4.251 ] ~ [ linux-4.3.6 ] ~ [ linux-4.2.8 ] ~ [ linux-4.1.52 ] ~ [ linux-4.0.9 ] ~ [ linux-3.19.8 ] ~ [ linux-3.18.140 ] ~ [ linux-3.17.8 ] ~ [ linux-3.16.85 ] ~ [ linux-3.15.10 ] ~ [ linux-3.14.79 ] ~ [ linux-3.13.11 ] ~ [ linux-3.12.74 ] ~ [ linux-3.11.10 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.5 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

  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 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 
243 struct net_device;
244 struct genl_info;
245 struct 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  */
395 struct 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  */
426 void wimax_dev_init(struct wimax_dev *);
427 int wimax_dev_add(struct wimax_dev *, struct net_device *);
428 void wimax_dev_rm(struct wimax_dev *);
429 
430 static inline
431 struct wimax_dev *net_dev_to_wimax(struct net_device *net_dev)
432 {
433         return netdev_priv(net_dev);
434 }
435 
436 static inline
437 struct device *wimax_dev_to_dev(struct wimax_dev *wimax_dev)
438 {
439         return wimax_dev->net_dev->dev.parent;
440 }
441 
442 void wimax_state_change(struct wimax_dev *, enum wimax_st);
443 enum 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  */
451 void wimax_report_rfkill_hw(struct wimax_dev *, enum wimax_rf_state);
452 void 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  */
478 struct sk_buff *wimax_msg_alloc(struct wimax_dev *, const char *, const void *,
479                                 size_t, gfp_t);
480 int wimax_msg_send(struct wimax_dev *, struct sk_buff *);
481 int wimax_msg(struct wimax_dev *, const char *, const void *, size_t, gfp_t);
482 
483 const void *wimax_msg_data_len(struct sk_buff *, size_t *);
484 const void *wimax_msg_data(struct sk_buff *);
485 ssize_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  */
500 int wimax_rfkill(struct wimax_dev *, enum wimax_rf_state);
501 int wimax_reset(struct wimax_dev *);
502 
503 #endif /* #ifndef __NET__WIMAX_H__ */
504 

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | Wiki (Japanese) | Wiki (English) | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

osdn.jp