1STRUCT WIMAX_DEV(9)            Linux Networking            STRUCT WIMAX_DEV(9)
2
3
4

NAME

6       struct_wimax_dev - Generic WiMAX device
7

SYNOPSIS

9       struct wimax_dev {
10         struct net_device * net_dev;
11         struct list_head id_table_node;
12         struct mutex mutex;
13         struct mutex mutex_reset;
14         enum wimax_st state;
15         int (* op_msg_from_user) (struct wimax_dev *wimax_dev,const char *,const void *, size_t,const struct genl_info *info);
16         int (* op_rfkill_sw_toggle) (struct wimax_dev *wimax_dev,enum wimax_rf_state);
17         int (* op_reset) (struct wimax_dev *wimax_dev);
18         struct rfkill * rfkill;
19         unsigned int rf_hw;
20         unsigned int rf_sw;
21         char name[32];
22         struct dentry * debugfs_dentry;
23       };
24

MEMBERS

26       net_dev
27           [fill] Pointer to the struct net_device this WiMAX device
28           implements.
29
30       id_table_node
31           [private] link to the list of wimax devices kept by id-table.c.
32           Protected by it's own spinlock.
33
34       mutex
35           [private] Serializes all concurrent access and execution of
36           operations.
37
38       mutex_reset
39           [private] Serializes reset operations. Needs to be a different
40           mutex because as part of the reset operation, the driver has to
41           call back into the stack to do things such as state change, that
42           require wimax_dev->mutex.
43
44       state
45           [private] Current state of the WiMAX device.
46
47       op_msg_from_user
48           [fill] Driver-specific operation to handle a raw message from user
49           space to the driver. The driver can send messages to user space
50           using with wimax_msg_to_user.
51
52       op_rfkill_sw_toggle
53           [fill] Driver-specific operation to act on userspace (or any other
54           agent) requesting the WiMAX device to change the RF Kill software
55           switch (WIMAX_RF_ON or WIMAX_RF_OFF). If such hardware support is
56           not present, it is assumed the radio cannot be switched off and it
57           is always on (and the stack will error out when trying to switch it
58           off). In such case, this function pointer can be left as NULL.
59
60       op_reset
61           [fill] Driver specific operation to reset the device. This
62           operation should always attempt first a warm reset that does not
63           disconnect the device from the bus and return 0. If that fails, it
64           should resort to some sort of cold or bus reset (even if it implies
65           a bus disconnection and device disappearance). In that case,
66           -ENODEV should be returned to indicate the device is gone. This
67           operation has to be synchronous, and return only when the reset is
68           complete. In case of having had to resort to bus/cold reset
69           implying a device disconnection, the call is allowed to return
70           inmediately.
71
72       rfkill
73           [private] integration into the RF-Kill infrastructure.
74
75       rf_hw
76           [private] State of the hardware radio switch (OFF/ON)
77
78       rf_sw
79           [private] State of the software radio switch (OFF/ON)
80
81       name[32]
82           [fill] A way to identify this device. We need to register a name
83           with many subsystems (rfkill, workqueue creation, etc). We can't
84           use the network device name as that might change and in some
85           instances we don't know it yet (until we don't call
86           register_netdev). So we generate an unique one using the driver
87           name and device bus id, place it here and use it across the board.
88           Recommended naming: DRIVERNAME-BUSNAME:BUSID (dev->bus->name,
89           dev->bus_id).
90
91       debugfs_dentry
92           [private] Used to hook up a debugfs entry. This shows up in the
93           debugfs root as wimax\:DEVICENAME.
94

NOTE

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

DESCRIPTION

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

USAGE

106       1. Embed a struct wimax_dev at *the beginning* the network device
107       structure so that netdev_priv points to it.
108
109       2.  memset it to zero
110
111       3. Initialize with wimax_dev_init. This will leave the WiMAX device in
112       the __WIMAX_ST_NULL state.
113
114       4. Fill all the fields marked with [fill]; once called wimax_dev_add,
115       those fields CANNOT be modified.
116
117       5. Call wimax_dev_add *after* registering the network device. This will
118       leave the WiMAX device in the WIMAX_ST_DOWN state. Protect the driver's
119       net_device->open against succeeding if the wimax device state is lower
120       than WIMAX_ST_DOWN.
121
122       6. Select when the device is going to be turned on/initialized; for
123       example, it could be initialized on 'ifconfig up' (when the netdev op
124       'open' is called on the driver).
125
126       When the device is initialized (at `ifconfig up` time, or right after
127       calling wimax_dev_add from _probe, make sure the following steps are
128       taken
129
130       a. Move the device to WIMAX_ST_UNINITIALIZED. This is needed so some
131       API calls that shouldn't work until the device is ready can be blocked.
132
133       b. Initialize the device. Make sure to turn the SW radio switch off and
134       move the device to state WIMAX_ST_RADIO_OFF when done. When just
135       initialized, a device should be left in RADIO OFF state until user
136       space devices to turn it on.
137
138       c. Query the device for the state of the hardware rfkill switch and
139       call wimax_rfkill_report_hw and wimax_rfkill_report_sw as needed. See
140       below.
141
142       wimax_dev_rm undoes before unregistering the network device. Once
143       wimax_dev_add is called, the driver can get called on the
144       wimax_dev->op_* function pointers
145

CONCURRENCY

147       The stack provides a mutex for each device that will disallow API calls
148       happening concurrently; thus, op calls into the driver through the
149       wimax_dev->op*() function pointers will always be serialized and
150       *never* concurrent.
151
152       For locking, take wimax_dev->mutex is taken; (most) operations in the
153       API have to check for wimax_dev_is_ready to return 0 before continuing
154       (this is done internally).
155

REFERENCE COUNTING

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

RFKILL

163       At startup, both HW and SW radio switchess are assumed to be off.
164
165       At initialization time [after calling wimax_dev_add], have the driver
166       query the device for the status of the software and hardware RF kill
167       switches and call wimax_report_rfkill_hw and wimax_rfkill_report_sw to
168       indicate their state. If any is missing, just call it to indicate it is
169       ON (radio always on).
170
171       Whenever the driver detects a change in the state of the RF kill
172       switches, it should call wimax_report_rfkill_hw or
173       wimax_report_rfkill_sw to report it to the stack.
174
176Kernel Hackers Manual 3.10         June 2019               STRUCT WIMAX_DEV(9)
Impressum