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

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

Version: ~ [ linux-5.12-rc1 ] ~ [ linux-5.11.2 ] ~ [ linux-5.10.19 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.101 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.177 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.222 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.258 ] ~ [ linux-4.8.17 ] ~ [ linux-4.7.10 ] ~ [ linux-4.6.7 ] ~ [ linux-4.5.7 ] ~ [ linux-4.4.258 ] ~ [ linux-4.3.6 ] ~ [ linux-4.2.8 ] ~ [ linux-4.1.52 ] ~ [ linux-4.0.9 ] ~ [ linux-3.18.140 ] ~ [ linux-3.16.85 ] ~ [ linux-3.14.79 ] ~ [ linux-3.12.74 ] ~ [ 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 /*
  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 
258 struct net_device;
259 struct genl_info;
260 struct 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 immediately.
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  */
410 struct 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 int rf_hw;
427         unsigned int 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  */
441 void wimax_dev_init(struct wimax_dev *);
442 int wimax_dev_add(struct wimax_dev *, struct net_device *);
443 void wimax_dev_rm(struct wimax_dev *);
444 
445 static inline
446 struct wimax_dev *net_dev_to_wimax(struct net_device *net_dev)
447 {
448         return netdev_priv(net_dev);
449 }
450 
451 static inline
452 struct device *wimax_dev_to_dev(struct wimax_dev *wimax_dev)
453 {
454         return wimax_dev->net_dev->dev.parent;
455 }
456 
457 void wimax_state_change(struct wimax_dev *, enum wimax_st);
458 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  */
466 void wimax_report_rfkill_hw(struct wimax_dev *, enum wimax_rf_state);
467 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, that can be interpreted as the name of
487  * the pipe or recipient; 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  */
493 struct sk_buff *wimax_msg_alloc(struct wimax_dev *, const char *, const void *,
494                                 size_t, gfp_t);
495 int wimax_msg_send(struct wimax_dev *, struct sk_buff *);
496 int wimax_msg(struct wimax_dev *, const char *, const void *, size_t, gfp_t);
497 
498 const void *wimax_msg_data_len(struct sk_buff *, size_t *);
499 const void *wimax_msg_data(struct sk_buff *);
500 ssize_t wimax_msg_len(struct sk_buff *);
501 
502 
503 /*
504  * WiMAX stack user space API
505  * --------------------------
506  *
507  * This API is what gets exported to user space for general
508  * operations. As well, they can be called from within the kernel,
509  * (with a properly referenced `struct wimax_dev`).
510  *
511  * Properly referenced means: the 'struct net_device' that embeds the
512  * device's control structure and (as such) the 'struct wimax_dev' is
513  * referenced by the caller.
514  */
515 int wimax_rfkill(struct wimax_dev *, enum wimax_rf_state);
516 int wimax_reset(struct wimax_dev *);
517 
518 #endif /* #ifndef __NET__WIMAX_H__ */
519 

~ [ 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