NAME¶

struct_wimax_dev - Generic WiMAX device

SYNOPSIS¶

struct wimax_dev {


  struct net_device * net_dev;


  struct list_head id_table_node;


  struct mutex mutex;


  struct mutex mutex_reset;


  enum wimax_st state;


  int (* op_msg_from_user) (struct wimax_dev *wimax_dev,const char *,const void *, size_t,const struct genl_info *info);


  int (* op_rfkill_sw_toggle) (struct wimax_dev *wimax_dev,enum wimax_rf_state);


  int (* op_reset) (struct wimax_dev *wimax_dev);


  struct rfkill * rfkill;


  unsigned rf_hw;


  unsigned rf_sw;


  char name[32];


  struct dentry * debugfs_dentry;
};  

MEMBERS¶

net_dev

id_table_node

mutex

mutex_reset

state

op_msg_from_user

op_rfkill_sw_toggle

op_reset

rfkill

rf_hw

rf_sw

name[32]

debugfs_dentry

NOTE¶

wimax_dev->mutex is NOT locked when this op is being called; however, wimax_dev->mutex_reset IS locked to ensure serialization of calls to wimax_reset. See wimax_reset´s documentation.

DESCRIPTION¶

This structure defines a common interface to access all WiMAX devices from different vendors and provides a common API as well as a free-form device-specific messaging channel.

USAGE¶

1. Embed a struct wimax_dev at *the beginning* the network device structure so that netdev_priv points to it.

2. memset it to zero

3. Initialize with wimax_dev_init. This will leave the WiMAX device in the __WIMAX_ST_NULL state.

4. Fill all the fields marked with [fill]; once called wimax_dev_add, those fields CANNOT be modified.

5. Call wimax_dev_add *after* registering the network device. This will leave the WiMAX device in the WIMAX_ST_DOWN state. Protect the driver´s net_device->open against succeeding if the wimax device state is lower than WIMAX_ST_DOWN.

6. Select when the device is going to be turned on/initialized; for example, it could be initialized on ´ifconfig up´ (when the netdev op ´open´ is called on the driver).

When the device is initialized (at `ifconfig up` time, or right after calling wimax_dev_add from _probe, make sure the following steps are taken

a. Move the device to WIMAX_ST_UNINITIALIZED. This is needed so some API calls that shouldn´t work until the device is ready can be blocked.

b. Initialize the device. Make sure to turn the SW radio switch off and move the device to state WIMAX_ST_RADIO_OFF when done. When just initialized, a device should be left in RADIO OFF state until user space devices to turn it on.

c. Query the device for the state of the hardware rfkill switch and call wimax_rfkill_report_hw and wimax_rfkill_report_sw as needed. See below.

wimax_dev_rm undoes before unregistering the network device. Once wimax_dev_add is called, the driver can get called on the wimax_dev->op_* function pointers

CONCURRENCY¶

The stack provides a mutex for each device that will disallow API calls happening concurrently; thus, op calls into the driver through the wimax_dev->op*() function pointers will always be serialized and *never* concurrent.

For locking, take wimax_dev->mutex is taken; (most) operations in the API have to check for wimax_dev_is_ready to return 0 before continuing (this is done internally).

REFERENCE COUNTING¶

The WiMAX device is reference counted by the associated network device. The only operation that can be used to reference the device is wimax_dev_get_by_genl_info, and the reference it acquires has to be released with dev_put(wimax_dev->net_dev).

RFKILL¶

At startup, both HW and SW radio switchess are assumed to be off.

At initialization time [after calling wimax_dev_add], have the driver query the device for the status of the software and hardware RF kill switches and call wimax_report_rfkill_hw and wimax_rfkill_report_sw to indicate their state. If any is missing, just call it to indicate it is ON (radio always on).

Whenever the driver detects a change in the state of the RF kill switches, it should call wimax_report_rfkill_hw or wimax_report_rfkill_sw to report it to the stack.

COPYRIGHT¶