1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>struct wimax_dev</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Linux Networking and Network Devices APIs"><link rel="up" href="ch01s06.html" title="WiMAX"><link rel="prev" href="API-wimax-dev-rm.html" title="wimax_dev_rm"><link rel="next" href="API-enum-wimax-st.html" title="enum wimax_st"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"><span class="phrase">struct wimax_dev</span></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-wimax-dev-rm.html">Prev</a> </td><th width="60%" align="center">WiMAX</th><td width="20%" align="right"> <a accesskey="n" href="API-enum-wimax-st.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="API-struct-wimax-dev"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>struct wimax_dev — 2 Generic WiMAX device 3 </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="programlisting"> 4struct wimax_dev { 5 struct net_device * net_dev; 6 struct list_head id_table_node; 7 struct mutex mutex; 8 struct mutex mutex_reset; 9 enum wimax_st state; 10 int (* op_msg_from_user) (struct wimax_dev *wimax_dev,const char *,const void *, size_t,const struct genl_info *info); 11 int (* op_rfkill_sw_toggle) (struct wimax_dev *wimax_dev,enum wimax_rf_state); 12 int (* op_reset) (struct wimax_dev *wimax_dev); 13 struct rfkill * rfkill; 14 unsigned int rf_hw; 15 unsigned int rf_sw; 16 char name[32]; 17 struct dentry * debugfs_dentry; 18}; </pre></div><div class="refsect1"><a name="idp1097687500"></a><h2>Members</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term">net_dev</span></dt><dd><p> 19[fill] Pointer to the <span class="structname">struct net_device</span> this WiMAX 20device implements. 21 </p></dd><dt><span class="term">id_table_node</span></dt><dd><p> 22[private] link to the list of wimax devices kept by 23id-table.c. Protected by it's own spinlock. 24 </p></dd><dt><span class="term">mutex</span></dt><dd><p> 25[private] Serializes all concurrent access and execution of 26operations. 27 </p></dd><dt><span class="term">mutex_reset</span></dt><dd><p> 28[private] Serializes reset operations. Needs to be a 29different mutex because as part of the reset operation, the 30driver has to call back into the stack to do things such as 31state change, that require wimax_dev->mutex. 32 </p></dd><dt><span class="term">state</span></dt><dd><p> 33[private] Current state of the WiMAX device. 34 </p></dd><dt><span class="term">op_msg_from_user</span></dt><dd><p> 35[fill] Driver-specific operation to 36handle a raw message from user space to the driver. The 37driver can send messages to user space using with 38<code class="function">wimax_msg_to_user</code>. 39 </p></dd><dt><span class="term">op_rfkill_sw_toggle</span></dt><dd><p> 40[fill] Driver-specific operation to act on 41userspace (or any other agent) requesting the WiMAX device to 42change the RF Kill software switch (WIMAX_RF_ON or 43WIMAX_RF_OFF). 44If such hardware support is not present, it is assumed the 45radio cannot be switched off and it is always on (and the stack 46will error out when trying to switch it off). In such case, 47this function pointer can be left as NULL. 48 </p></dd><dt><span class="term">op_reset</span></dt><dd><p> 49[fill] Driver specific operation to reset the 50device. 51This operation should always attempt first a warm reset that 52does not disconnect the device from the bus and return 0. 53If that fails, it should resort to some sort of cold or bus 54reset (even if it implies a bus disconnection and device 55disappearance). In that case, -ENODEV should be returned to 56indicate the device is gone. 57This operation has to be synchronous, and return only when the 58reset is complete. In case of having had to resort to bus/cold 59reset implying a device disconnection, the call is allowed to 60return immediately. 61 </p></dd><dt><span class="term">rfkill</span></dt><dd><p> 62[private] integration into the RF-Kill infrastructure. 63 </p></dd><dt><span class="term">rf_hw</span></dt><dd><p> 64[private] State of the hardware radio switch (OFF/ON) 65 </p></dd><dt><span class="term">rf_sw</span></dt><dd><p> 66[private] State of the software radio switch (OFF/ON) 67 </p></dd><dt><span class="term">name[32]</span></dt><dd><p> 68[fill] A way to identify this device. We need to register a 69name with many subsystems (rfkill, workqueue creation, etc). 70We can't use the network device name as that 71might change and in some instances we don't know it yet (until 72we don't call <code class="function">register_netdev</code>). So we generate an unique one 73using the driver name and device bus id, place it here and use 74it across the board. Recommended naming: 75DRIVERNAME-BUSNAME:BUSID (dev->bus->name, dev->bus_id). 76 </p></dd><dt><span class="term">debugfs_dentry</span></dt><dd><p> 77[private] Used to hook up a debugfs entry. This 78shows up in the debugfs root as wimax\:DEVICENAME. 79 </p></dd></dl></div></div><div class="refsect1"><a name="idp1097700460"></a><h2>NOTE</h2><p> 80 wimax_dev->mutex is NOT locked when this op is being 81 called; however, wimax_dev->mutex_reset IS locked to ensure 82 serialization of calls to <code class="function">wimax_reset</code>. 83 See <code class="function">wimax_reset</code>'s documentation. 84</p></div><div class="refsect1"><a name="idp1097701996"></a><h2>Description</h2><p> 85 This structure defines a common interface to access all WiMAX 86 devices from different vendors and provides a common API as well as 87 a free-form device-specific messaging channel. 88</p></div><div class="refsect1"><a name="idp1097702780"></a><h2>Usage</h2><p> 89 1. Embed a <span class="structname">struct wimax_dev</span> at *the beginning* the network 90 device structure so that <code class="function">netdev_priv</code> points to it. 91 </p><p> 92 93 2. <code class="function">memset</code> it to zero 94 </p><p> 95 96 3. Initialize with <code class="function">wimax_dev_init</code>. This will leave the WiMAX 97 device in the <code class="constant">__WIMAX_ST_NULL</code> state. 98 </p><p> 99 100 4. Fill all the fields marked with [fill]; once called 101 <code class="function">wimax_dev_add</code>, those fields CANNOT be modified. 102 </p><p> 103 104 5. Call <code class="function">wimax_dev_add</code> *after* registering the network 105 device. This will leave the WiMAX device in the <code class="constant">WIMAX_ST_DOWN</code> 106 state. 107 Protect the driver's net_device-><code class="function">open</code> against succeeding if 108 the wimax device state is lower than <code class="constant">WIMAX_ST_DOWN</code>. 109 </p><p> 110 111 6. Select when the device is going to be turned on/initialized; 112 for example, it could be initialized on 'ifconfig up' (when the 113 netdev op '<code class="function">open</code>' is called on the driver). 114 </p><p> 115 116 When the device is initialized (at `ifconfig up` time, or right 117 after calling <code class="function">wimax_dev_add</code> from <code class="function">_probe</code>, make sure the 118 following steps are taken 119 </p><p> 120 121 a. Move the device to <code class="constant">WIMAX_ST_UNINITIALIZED</code>. This is needed so 122 some API calls that shouldn't work until the device is ready 123 can be blocked. 124 </p><p> 125 126 b. Initialize the device. Make sure to turn the SW radio switch 127 off and move the device to state <code class="constant">WIMAX_ST_RADIO_OFF</code> when 128 done. When just initialized, a device should be left in RADIO 129 OFF state until user space devices to turn it on. 130 </p><p> 131 132 c. Query the device for the state of the hardware rfkill switch 133 and call <code class="function">wimax_rfkill_report_hw</code> and <code class="function">wimax_rfkill_report_sw</code> 134 as needed. See below. 135 </p><p> 136 137 <code class="function">wimax_dev_rm</code> undoes before unregistering the network device. Once 138 <code class="function">wimax_dev_add</code> is called, the driver can get called on the 139 wimax_dev->op_* function pointers 140</p></div><div class="refsect1"><a name="idp1097712300"></a><h2>CONCURRENCY</h2><p> 141 </p><p> 142 143 The stack provides a mutex for each device that will disallow API 144 calls happening concurrently; thus, op calls into the driver 145 through the wimax_dev->op*() function pointers will always be 146 serialized and *never* concurrent. 147 </p><p> 148 149 For locking, take wimax_dev->mutex is taken; (most) operations in 150 the API have to check for <code class="function">wimax_dev_is_ready</code> to return 0 before 151 continuing (this is done internally). 152</p></div><div class="refsect1"><a name="idp1097714180"></a><h2>REFERENCE COUNTING</h2><p> 153 </p><p> 154 155 The WiMAX device is reference counted by the associated network 156 device. The only operation that can be used to reference the device 157 is <code class="function">wimax_dev_get_by_genl_info</code>, and the reference it acquires has 158 to be released with dev_put(wimax_dev->net_dev). 159</p></div><div class="refsect1"><a name="idp1097715588"></a><h2>RFKILL</h2><p> 160 </p><p> 161 162 At startup, both HW and SW radio switchess are assumed to be off. 163 </p><p> 164 165 At initialization time [after calling <code class="function">wimax_dev_add</code>], have the 166 driver query the device for the status of the software and hardware 167 RF kill switches and call <code class="function">wimax_report_rfkill_hw</code> and 168 <code class="function">wimax_rfkill_report_sw</code> to indicate their state. If any is 169 missing, just call it to indicate it is ON (radio always on). 170 </p><p> 171 172 Whenever the driver detects a change in the state of the RF kill 173 switches, it should call <code class="function">wimax_report_rfkill_hw</code> or 174 <code class="function">wimax_report_rfkill_sw</code> to report it to the stack. 175</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-wimax-dev-rm.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch01s06.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="API-enum-wimax-st.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">wimax_dev_rm</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span class="phrase">enum wimax_st</span></td></tr></table></div></body></html> 176