diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2009-06-15 12:40:05 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2009-06-15 12:40:05 -0400 |
commit | 2ed0e21b30b53d3a94e204196e523e6c8f732b56 (patch) | |
tree | de2635426477d86338a9469ce09ba0626052288f /Documentation | |
parent | 0fa213310cd8fa7a51071cdcf130e26fa56e9549 (diff) | |
parent | 9cbc1cb8cd46ce1f7645b9de249b2ce8460129bb (diff) |
Merge git://git.kernel.org/pub/scm/linux/kernel/git/davem/net-next-2.6
* git://git.kernel.org/pub/scm/linux/kernel/git/davem/net-next-2.6: (1244 commits)
pkt_sched: Rename PSCHED_US2NS and PSCHED_NS2US
ipv4: Fix fib_trie rebalancing
Bluetooth: Fix issue with uninitialized nsh.type in DTL-1 driver
Bluetooth: Fix Kconfig issue with RFKILL integration
PIM-SM: namespace changes
ipv4: update ARPD help text
net: use a deferred timer in rt_check_expire
ieee802154: fix kconfig bool/tristate muckup
bonding: initialization rework
bonding: use is_zero_ether_addr
bonding: network device names are case sensative
bonding: elminate bad refcount code
bonding: fix style issues
bonding: fix destructor
bonding: remove bonding read/write semaphore
bonding: initialize before registration
bonding: bond_create always called with default parameters
x_tables: Convert printk to pr_err
netfilter: conntrack: optional reliable conntrack event delivery
list_nulls: add hlist_nulls_add_head and hlist_nulls_del
...
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/DocBook/mac80211.tmpl | 1 | ||||
-rw-r--r-- | Documentation/feature-removal-schedule.txt | 7 | ||||
-rw-r--r-- | Documentation/isdn/00-INDEX | 29 | ||||
-rw-r--r-- | Documentation/isdn/INTERFACE.CAPI | 94 | ||||
-rw-r--r-- | Documentation/isdn/README.gigaset | 42 | ||||
-rw-r--r-- | Documentation/networking/can.txt | 235 | ||||
-rw-r--r-- | Documentation/networking/ieee802154.txt | 76 | ||||
-rw-r--r-- | Documentation/networking/ip-sysctl.txt | 18 | ||||
-rw-r--r-- | Documentation/networking/ipv6.txt | 37 | ||||
-rw-r--r-- | Documentation/networking/mac80211-injection.txt | 28 | ||||
-rw-r--r-- | Documentation/networking/operstates.txt | 3 | ||||
-rw-r--r-- | Documentation/networking/packet_mmap.txt | 140 | ||||
-rw-r--r-- | Documentation/powerpc/dts-bindings/can/sja1000.txt | 53 | ||||
-rw-r--r-- | Documentation/rfkill.txt | 607 |
14 files changed, 729 insertions, 641 deletions
diff --git a/Documentation/DocBook/mac80211.tmpl b/Documentation/DocBook/mac80211.tmpl index fbeaffc1dcc3..e36986663570 100644 --- a/Documentation/DocBook/mac80211.tmpl +++ b/Documentation/DocBook/mac80211.tmpl | |||
@@ -145,7 +145,6 @@ usage should require reading the full document. | |||
145 | interface in STA mode at first! | 145 | interface in STA mode at first! |
146 | </para> | 146 | </para> |
147 | !Finclude/net/mac80211.h ieee80211_if_init_conf | 147 | !Finclude/net/mac80211.h ieee80211_if_init_conf |
148 | !Finclude/net/mac80211.h ieee80211_if_conf | ||
149 | </chapter> | 148 | </chapter> |
150 | 149 | ||
151 | <chapter id="rx-tx"> | 150 | <chapter id="rx-tx"> |
diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index ec9ef5d0d7b3..7129846a2785 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt | |||
@@ -438,6 +438,13 @@ Why: Superseded by tdfxfb. I2C/DDC support used to live in a separate | |||
438 | Who: Jean Delvare <khali@linux-fr.org> | 438 | Who: Jean Delvare <khali@linux-fr.org> |
439 | Krzysztof Helt <krzysztof.h1@wp.pl> | 439 | Krzysztof Helt <krzysztof.h1@wp.pl> |
440 | 440 | ||
441 | --------------------------- | ||
442 | |||
443 | What: CONFIG_RFKILL_INPUT | ||
444 | When: 2.6.33 | ||
445 | Why: Should be implemented in userspace, policy daemon. | ||
446 | Who: Johannes Berg <johannes@sipsolutions.net> | ||
447 | |||
441 | ---------------------------- | 448 | ---------------------------- |
442 | 449 | ||
443 | What: CONFIG_X86_OLD_MCE | 450 | What: CONFIG_X86_OLD_MCE |
diff --git a/Documentation/isdn/00-INDEX b/Documentation/isdn/00-INDEX index 5a2d69989a8c..f6010a536590 100644 --- a/Documentation/isdn/00-INDEX +++ b/Documentation/isdn/00-INDEX | |||
@@ -22,16 +22,11 @@ README.gigaset | |||
22 | - info on the drivers for Siemens Gigaset ISDN adapters. | 22 | - info on the drivers for Siemens Gigaset ISDN adapters. |
23 | README.icn | 23 | README.icn |
24 | - info on the ICN-ISDN-card and its driver. | 24 | - info on the ICN-ISDN-card and its driver. |
25 | >>>>>>> 93af7aca44f0e82e67bda10a0fb73d383edcc8bd:Documentation/isdn/00-INDEX | ||
25 | README.HiSax | 26 | README.HiSax |
26 | - info on the HiSax driver which replaces the old teles. | 27 | - info on the HiSax driver which replaces the old teles. |
27 | README.hfc-pci | 28 | README.audio |
28 | - info on hfc-pci based cards. | 29 | - info for running audio over ISDN. |
29 | README.pcbit | ||
30 | - info on the PCBIT-D ISDN adapter and driver. | ||
31 | README.syncppp | ||
32 | - info on running Sync PPP over ISDN. | ||
33 | syncPPP.FAQ | ||
34 | - frequently asked questions about running PPP over ISDN. | ||
35 | README.avmb1 | 30 | README.avmb1 |
36 | - info on driver for AVM-B1 ISDN card. | 31 | - info on driver for AVM-B1 ISDN card. |
37 | README.act2000 | 32 | README.act2000 |
@@ -42,10 +37,28 @@ README.concap | |||
42 | - info on "CONCAP" encapsulation protocol interface used for X.25. | 37 | - info on "CONCAP" encapsulation protocol interface used for X.25. |
43 | README.diversion | 38 | README.diversion |
44 | - info on module for isdn diversion services. | 39 | - info on module for isdn diversion services. |
40 | README.fax | ||
41 | - info for using Fax over ISDN. | ||
42 | README.gigaset | ||
43 | - info on the drivers for Siemens Gigaset ISDN adapters | ||
44 | README.hfc-pci | ||
45 | - info on hfc-pci based cards. | ||
46 | README.hysdn | ||
47 | - info on driver for Hypercope active HYSDN cards | ||
48 | README.icn | ||
49 | - info on the ICN-ISDN-card and its driver. | ||
50 | README.mISDN | ||
51 | - info on the Modular ISDN subsystem (mISDN) | ||
52 | README.pcbit | ||
53 | - info on the PCBIT-D ISDN adapter and driver. | ||
45 | README.sc | 54 | README.sc |
46 | - info on driver for Spellcaster cards. | 55 | - info on driver for Spellcaster cards. |
56 | README.syncppp | ||
57 | - info on running Sync PPP over ISDN. | ||
47 | README.x25 | 58 | README.x25 |
48 | - info for running X.25 over ISDN. | 59 | - info for running X.25 over ISDN. |
60 | syncPPP.FAQ | ||
61 | - frequently asked questions about running PPP over ISDN. | ||
49 | README.hysdn | 62 | README.hysdn |
50 | - info on driver for Hypercope active HYSDN cards | 63 | - info on driver for Hypercope active HYSDN cards |
51 | README.mISDN | 64 | README.mISDN |
diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/INTERFACE.CAPI index 786d619b36e5..686e107923ec 100644 --- a/Documentation/isdn/INTERFACE.CAPI +++ b/Documentation/isdn/INTERFACE.CAPI | |||
@@ -45,7 +45,7 @@ From then on, Kernel CAPI may call the registered callback functions for the | |||
45 | device. | 45 | device. |
46 | 46 | ||
47 | If the device becomes unusable for any reason (shutdown, disconnect ...), the | 47 | If the device becomes unusable for any reason (shutdown, disconnect ...), the |
48 | driver has to call capi_ctr_reseted(). This will prevent further calls to the | 48 | driver has to call capi_ctr_down(). This will prevent further calls to the |
49 | callback functions by Kernel CAPI. | 49 | callback functions by Kernel CAPI. |
50 | 50 | ||
51 | 51 | ||
@@ -114,20 +114,36 @@ char *driver_name | |||
114 | int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata) | 114 | int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata) |
115 | (optional) pointer to a callback function for sending firmware and | 115 | (optional) pointer to a callback function for sending firmware and |
116 | configuration data to the device | 116 | configuration data to the device |
117 | Return value: 0 on success, error code on error | ||
118 | Called in process context. | ||
117 | 119 | ||
118 | void (*reset_ctr)(struct capi_ctr *ctrlr) | 120 | void (*reset_ctr)(struct capi_ctr *ctrlr) |
119 | pointer to a callback function for performing a reset on the device, | 121 | (optional) pointer to a callback function for performing a reset on |
120 | releasing all registered applications | 122 | the device, releasing all registered applications |
123 | Called in process context. | ||
121 | 124 | ||
122 | void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, | 125 | void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, |
123 | capi_register_params *rparam) | 126 | capi_register_params *rparam) |
124 | void (*release_appl)(struct capi_ctr *ctrlr, u16 applid) | 127 | void (*release_appl)(struct capi_ctr *ctrlr, u16 applid) |
125 | pointers to callback functions for registration and deregistration of | 128 | pointers to callback functions for registration and deregistration of |
126 | applications with the device | 129 | applications with the device |
130 | Calls to these functions are serialized by Kernel CAPI so that only | ||
131 | one call to any of them is active at any time. | ||
127 | 132 | ||
128 | u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb) | 133 | u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb) |
129 | pointer to a callback function for sending a CAPI message to the | 134 | pointer to a callback function for sending a CAPI message to the |
130 | device | 135 | device |
136 | Return value: CAPI error code | ||
137 | If the method returns 0 (CAPI_NOERROR) the driver has taken ownership | ||
138 | of the skb and the caller may no longer access it. If it returns a | ||
139 | non-zero (error) value then ownership of the skb returns to the caller | ||
140 | who may reuse or free it. | ||
141 | The return value should only be used to signal problems with respect | ||
142 | to accepting or queueing the message. Errors occurring during the | ||
143 | actual processing of the message should be signaled with an | ||
144 | appropriate reply message. | ||
145 | Calls to this function are not serialized by Kernel CAPI, ie. it must | ||
146 | be prepared to be re-entered. | ||
131 | 147 | ||
132 | char *(*procinfo)(struct capi_ctr *ctrlr) | 148 | char *(*procinfo)(struct capi_ctr *ctrlr) |
133 | pointer to a callback function returning the entry for the device in | 149 | pointer to a callback function returning the entry for the device in |
@@ -138,6 +154,8 @@ read_proc_t *ctr_read_proc | |||
138 | system entry, /proc/capi/controllers/<n>; will be called with a | 154 | system entry, /proc/capi/controllers/<n>; will be called with a |
139 | pointer to the device's capi_ctr structure as the last (data) argument | 155 | pointer to the device's capi_ctr structure as the last (data) argument |
140 | 156 | ||
157 | Note: Callback functions are never called in interrupt context. | ||
158 | |||
141 | - to be filled in before calling capi_ctr_ready(): | 159 | - to be filled in before calling capi_ctr_ready(): |
142 | 160 | ||
143 | u8 manu[CAPI_MANUFACTURER_LEN] | 161 | u8 manu[CAPI_MANUFACTURER_LEN] |
@@ -153,6 +171,45 @@ u8 serial[CAPI_SERIAL_LEN] | |||
153 | value to return for CAPI_GET_SERIAL | 171 | value to return for CAPI_GET_SERIAL |
154 | 172 | ||
155 | 173 | ||
174 | 4.3 The _cmsg Structure | ||
175 | |||
176 | (declared in <linux/isdn/capiutil.h>) | ||
177 | |||
178 | The _cmsg structure stores the contents of a CAPI 2.0 message in an easily | ||
179 | accessible form. It contains members for all possible CAPI 2.0 parameters, of | ||
180 | which only those appearing in the message type currently being processed are | ||
181 | actually used. Unused members should be set to zero. | ||
182 | |||
183 | Members are named after the CAPI 2.0 standard names of the parameters they | ||
184 | represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data | ||
185 | types are: | ||
186 | |||
187 | u8 for CAPI parameters of type 'byte' | ||
188 | |||
189 | u16 for CAPI parameters of type 'word' | ||
190 | |||
191 | u32 for CAPI parameters of type 'dword' | ||
192 | |||
193 | _cstruct for CAPI parameters of type 'struct' not containing any | ||
194 | variably-sized (struct) subparameters (eg. 'Called Party Number') | ||
195 | The member is a pointer to a buffer containing the parameter in | ||
196 | CAPI encoding (length + content). It may also be NULL, which will | ||
197 | be taken to represent an empty (zero length) parameter. | ||
198 | |||
199 | _cmstruct for CAPI parameters of type 'struct' containing 'struct' | ||
200 | subparameters ('Additional Info' and 'B Protocol') | ||
201 | The representation is a single byte containing one of the values: | ||
202 | CAPI_DEFAULT: the parameter is empty | ||
203 | CAPI_COMPOSE: the values of the subparameters are stored | ||
204 | individually in the corresponding _cmsg structure members | ||
205 | |||
206 | Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert | ||
207 | messages between their transport encoding described in the CAPI 2.0 standard | ||
208 | and their _cmsg structure representation. Note that capi_cmsg2message() does | ||
209 | not know or check the size of its destination buffer. The caller must make | ||
210 | sure it is big enough to accomodate the resulting CAPI message. | ||
211 | |||
212 | |||
156 | 5. Lower Layer Interface Functions | 213 | 5. Lower Layer Interface Functions |
157 | 214 | ||
158 | (declared in <linux/isdn/capilli.h>) | 215 | (declared in <linux/isdn/capilli.h>) |
@@ -166,7 +223,7 @@ int detach_capi_ctr(struct capi_ctr *ctrlr) | |||
166 | register/unregister a device (controller) with Kernel CAPI | 223 | register/unregister a device (controller) with Kernel CAPI |
167 | 224 | ||
168 | void capi_ctr_ready(struct capi_ctr *ctrlr) | 225 | void capi_ctr_ready(struct capi_ctr *ctrlr) |
169 | void capi_ctr_reseted(struct capi_ctr *ctrlr) | 226 | void capi_ctr_down(struct capi_ctr *ctrlr) |
170 | signal controller ready/not ready | 227 | signal controller ready/not ready |
171 | 228 | ||
172 | void capi_ctr_suspend_output(struct capi_ctr *ctrlr) | 229 | void capi_ctr_suspend_output(struct capi_ctr *ctrlr) |
@@ -211,3 +268,32 @@ CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI | |||
211 | (u32) | 268 | (u32) |
212 | CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16) | 269 | CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16) |
213 | 270 | ||
271 | |||
272 | Library functions for working with _cmsg structures | ||
273 | (from <linux/isdn/capiutil.h>): | ||
274 | |||
275 | unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg) | ||
276 | Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the | ||
277 | result in *msg. | ||
278 | |||
279 | unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg) | ||
280 | Disassembles the CAPI 2.0 message in *msg, storing the parameters in | ||
281 | *cmsg. | ||
282 | |||
283 | unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, | ||
284 | u16 Messagenumber, u32 Controller) | ||
285 | Fills the header part and address field of the _cmsg structure *cmsg | ||
286 | with the given values, zeroing the remainder of the structure so only | ||
287 | parameters with non-default values need to be changed before sending | ||
288 | the message. | ||
289 | |||
290 | void capi_cmsg_answer(_cmsg *cmsg) | ||
291 | Sets the low bit of the Subcommand field in *cmsg, thereby converting | ||
292 | _REQ to _CONF and _IND to _RESP. | ||
293 | |||
294 | char *capi_cmd2str(u8 Command, u8 Subcommand) | ||
295 | Returns the CAPI 2.0 message name corresponding to the given command | ||
296 | and subcommand values, as a static ASCII string. The return value may | ||
297 | be NULL if the command/subcommand is not one of those defined in the | ||
298 | CAPI 2.0 standard. | ||
299 | |||
diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/README.gigaset index 02c0e9341dd8..f9963103ae3d 100644 --- a/Documentation/isdn/README.gigaset +++ b/Documentation/isdn/README.gigaset | |||
@@ -149,10 +149,8 @@ GigaSet 307x Device Driver | |||
149 | configuration files and chat scripts in the gigaset-VERSION/ppp directory | 149 | configuration files and chat scripts in the gigaset-VERSION/ppp directory |
150 | in the driver packages from http://sourceforge.net/projects/gigaset307x/. | 150 | in the driver packages from http://sourceforge.net/projects/gigaset307x/. |
151 | Please note that the USB drivers are not able to change the state of the | 151 | Please note that the USB drivers are not able to change the state of the |
152 | control lines (the M105 driver can be configured to use some undocumented | 152 | control lines. This means you must use "Stupid Mode" if you are using |
153 | control requests, if you really need the control lines, though). This means | 153 | wvdial or you should use the nocrtscts option of pppd. |
154 | you must use "Stupid Mode" if you are using wvdial or you should use the | ||
155 | nocrtscts option of pppd. | ||
156 | You must also assure that the ppp_async module is loaded with the parameter | 154 | You must also assure that the ppp_async module is loaded with the parameter |
157 | flag_time=0. You can do this e.g. by adding a line like | 155 | flag_time=0. You can do this e.g. by adding a line like |
158 | 156 | ||
@@ -190,20 +188,19 @@ GigaSet 307x Device Driver | |||
190 | You can also use /sys/class/tty/ttyGxy/cidmode for changing the CID mode | 188 | You can also use /sys/class/tty/ttyGxy/cidmode for changing the CID mode |
191 | setting (ttyGxy is ttyGU0 or ttyGB0). | 189 | setting (ttyGxy is ttyGU0 or ttyGB0). |
192 | 190 | ||
193 | 2.6. M105 Undocumented USB Requests | 191 | 2.6. Unregistered Wireless Devices (M101/M105) |
194 | ------------------------------ | 192 | ----------------------------------------- |
195 | 193 | The main purpose of the ser_gigaset and usb_gigaset drivers is to allow | |
196 | The Gigaset M105 USB data box understands a couple of useful, but | 194 | the M101 and M105 wireless devices to be used as ISDN devices for ISDN |
197 | undocumented USB commands. These requests are not used in normal | 195 | connections through a Gigaset base. Therefore they assume that the device |
198 | operation (for wireless access to the base), but are needed for access | 196 | is registered to a DECT base. |
199 | to the M105's own configuration mode (registration to the base, baudrate | 197 | |
200 | and line format settings, device status queries) via the gigacontr | 198 | If the M101/M105 device is not registered to a base, initialization of |
201 | utility. Their use is controlled by the kernel configuration option | 199 | the device fails, and a corresponding error message is logged by the |
202 | "Support for undocumented USB requests" (CONFIG_GIGASET_UNDOCREQ). If you | 200 | driver. In that situation, a restricted set of functions is available |
203 | encounter error code -ENOTTY when trying to use some features of the | 201 | which includes, in particular, those necessary for registering the device |
204 | M105, try setting that option to "y" via 'make {x,menu}config' and | 202 | to a base or for switching it between Fixed Part and Portable Part |
205 | recompiling the driver. | 203 | modes. |
206 | |||
207 | 204 | ||
208 | 3. Troubleshooting | 205 | 3. Troubleshooting |
209 | --------------- | 206 | --------------- |
@@ -234,11 +231,12 @@ GigaSet 307x Device Driver | |||
234 | Select Unimodem mode for all DECT data adapters. (see section 2.4.) | 231 | Select Unimodem mode for all DECT data adapters. (see section 2.4.) |
235 | 232 | ||
236 | Problem: | 233 | Problem: |
237 | You want to configure your USB DECT data adapter (M105) but gigacontr | 234 | Messages like this: |
238 | reports an error: "/dev/ttyGU0: Inappropriate ioctl for device". | 235 | usb_gigaset 3-2:1.0: Could not initialize the device. |
236 | appear in your syslog. | ||
239 | Solution: | 237 | Solution: |
240 | Recompile the usb_gigaset driver with the kernel configuration option | 238 | Check whether your M10x wireless device is correctly registered to the |
241 | CONFIG_GIGASET_UNDOCREQ set to 'y'. (see section 2.6.) | 239 | Gigaset base. (see section 2.6.) |
242 | 240 | ||
243 | 3.2. Telling the driver to provide more information | 241 | 3.2. Telling the driver to provide more information |
244 | ---------------------------------------------- | 242 | ---------------------------------------------- |
diff --git a/Documentation/networking/can.txt b/Documentation/networking/can.txt index 463d9e029ef3..cd79735013f9 100644 --- a/Documentation/networking/can.txt +++ b/Documentation/networking/can.txt | |||
@@ -36,10 +36,15 @@ This file contains | |||
36 | 6.2 local loopback of sent frames | 36 | 6.2 local loopback of sent frames |
37 | 6.3 CAN controller hardware filters | 37 | 6.3 CAN controller hardware filters |
38 | 6.4 The virtual CAN driver (vcan) | 38 | 6.4 The virtual CAN driver (vcan) |
39 | 6.5 currently supported CAN hardware | 39 | 6.5 The CAN network device driver interface |
40 | 6.6 todo | 40 | 6.5.1 Netlink interface to set/get devices properties |
41 | 6.5.2 Setting the CAN bit-timing | ||
42 | 6.5.3 Starting and stopping the CAN network device | ||
43 | 6.6 supported CAN hardware | ||
41 | 44 | ||
42 | 7 Credits | 45 | 7 Socket CAN resources |
46 | |||
47 | 8 Credits | ||
43 | 48 | ||
44 | ============================================================================ | 49 | ============================================================================ |
45 | 50 | ||
@@ -234,6 +239,8 @@ solution for a couple of reasons: | |||
234 | the user application using the common CAN filter mechanisms. Inside | 239 | the user application using the common CAN filter mechanisms. Inside |
235 | this filter definition the (interested) type of errors may be | 240 | this filter definition the (interested) type of errors may be |
236 | selected. The reception of error frames is disabled by default. | 241 | selected. The reception of error frames is disabled by default. |
242 | The format of the CAN error frame is briefly decribed in the Linux | ||
243 | header file "include/linux/can/error.h". | ||
237 | 244 | ||
238 | 4. How to use Socket CAN | 245 | 4. How to use Socket CAN |
239 | ------------------------ | 246 | ------------------------ |
@@ -605,61 +612,213 @@ solution for a couple of reasons: | |||
605 | removal of vcan network devices can be managed with the ip(8) tool: | 612 | removal of vcan network devices can be managed with the ip(8) tool: |
606 | 613 | ||
607 | - Create a virtual CAN network interface: | 614 | - Create a virtual CAN network interface: |
608 | ip link add type vcan | 615 | $ ip link add type vcan |
609 | 616 | ||
610 | - Create a virtual CAN network interface with a specific name 'vcan42': | 617 | - Create a virtual CAN network interface with a specific name 'vcan42': |
611 | ip link add dev vcan42 type vcan | 618 | $ ip link add dev vcan42 type vcan |
612 | 619 | ||
613 | - Remove a (virtual CAN) network interface 'vcan42': | 620 | - Remove a (virtual CAN) network interface 'vcan42': |
614 | ip link del vcan42 | 621 | $ ip link del vcan42 |
615 | 622 | ||
616 | The tool 'vcan' from the SocketCAN SVN repository on BerliOS is obsolete. | 623 | 6.5 The CAN network device driver interface |
617 | 624 | ||
618 | Virtual CAN network device creation in older Kernels: | 625 | The CAN network device driver interface provides a generic interface |
619 | In Linux Kernel versions < 2.6.24 the vcan driver creates 4 vcan | 626 | to setup, configure and monitor CAN network devices. The user can then |
620 | netdevices at module load time by default. This value can be changed | 627 | configure the CAN device, like setting the bit-timing parameters, via |
621 | with the module parameter 'numdev'. E.g. 'modprobe vcan numdev=8' | 628 | the netlink interface using the program "ip" from the "IPROUTE2" |
622 | 629 | utility suite. The following chapter describes briefly how to use it. | |
623 | 6.5 currently supported CAN hardware | 630 | Furthermore, the interface uses a common data structure and exports a |
631 | set of common functions, which all real CAN network device drivers | ||
632 | should use. Please have a look to the SJA1000 or MSCAN driver to | ||
633 | understand how to use them. The name of the module is can-dev.ko. | ||
634 | |||
635 | 6.5.1 Netlink interface to set/get devices properties | ||
636 | |||
637 | The CAN device must be configured via netlink interface. The supported | ||
638 | netlink message types are defined and briefly described in | ||
639 | "include/linux/can/netlink.h". CAN link support for the program "ip" | ||
640 | of the IPROUTE2 utility suite is avaiable and it can be used as shown | ||
641 | below: | ||
642 | |||
643 | - Setting CAN device properties: | ||
644 | |||
645 | $ ip link set can0 type can help | ||
646 | Usage: ip link set DEVICE type can | ||
647 | [ bitrate BITRATE [ sample-point SAMPLE-POINT] ] | | ||
648 | [ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1 | ||
649 | phase-seg2 PHASE-SEG2 [ sjw SJW ] ] | ||
650 | |||
651 | [ loopback { on | off } ] | ||
652 | [ listen-only { on | off } ] | ||
653 | [ triple-sampling { on | off } ] | ||
654 | |||
655 | [ restart-ms TIME-MS ] | ||
656 | [ restart ] | ||
657 | |||
658 | Where: BITRATE := { 1..1000000 } | ||
659 | SAMPLE-POINT := { 0.000..0.999 } | ||
660 | TQ := { NUMBER } | ||
661 | PROP-SEG := { 1..8 } | ||
662 | PHASE-SEG1 := { 1..8 } | ||
663 | PHASE-SEG2 := { 1..8 } | ||
664 | SJW := { 1..4 } | ||
665 | RESTART-MS := { 0 | NUMBER } | ||
666 | |||
667 | - Display CAN device details and statistics: | ||
668 | |||
669 | $ ip -details -statistics link show can0 | ||
670 | 2: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc pfifo_fast state UP qlen 10 | ||
671 | link/can | ||
672 | can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100 | ||
673 | bitrate 125000 sample_point 0.875 | ||
674 | tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1 | ||
675 | sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 | ||
676 | clock 8000000 | ||
677 | re-started bus-errors arbit-lost error-warn error-pass bus-off | ||
678 | 41 17457 0 41 42 41 | ||
679 | RX: bytes packets errors dropped overrun mcast | ||
680 | 140859 17608 17457 0 0 0 | ||
681 | TX: bytes packets errors dropped carrier collsns | ||
682 | 861 112 0 41 0 0 | ||
683 | |||
684 | More info to the above output: | ||
685 | |||
686 | "<TRIPLE-SAMPLING>" | ||
687 | Shows the list of selected CAN controller modes: LOOPBACK, | ||
688 | LISTEN-ONLY, or TRIPLE-SAMPLING. | ||
689 | |||
690 | "state ERROR-ACTIVE" | ||
691 | The current state of the CAN controller: "ERROR-ACTIVE", | ||
692 | "ERROR-WARNING", "ERROR-PASSIVE", "BUS-OFF" or "STOPPED" | ||
693 | |||
694 | "restart-ms 100" | ||
695 | Automatic restart delay time. If set to a non-zero value, a | ||
696 | restart of the CAN controller will be triggered automatically | ||
697 | in case of a bus-off condition after the specified delay time | ||
698 | in milliseconds. By default it's off. | ||
699 | |||
700 | "bitrate 125000 sample_point 0.875" | ||
701 | Shows the real bit-rate in bits/sec and the sample-point in the | ||
702 | range 0.000..0.999. If the calculation of bit-timing parameters | ||
703 | is enabled in the kernel (CONFIG_CAN_CALC_BITTIMING=y), the | ||
704 | bit-timing can be defined by setting the "bitrate" argument. | ||
705 | Optionally the "sample-point" can be specified. By default it's | ||
706 | 0.000 assuming CIA-recommended sample-points. | ||
707 | |||
708 | "tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1" | ||
709 | Shows the time quanta in ns, propagation segment, phase buffer | ||
710 | segment 1 and 2 and the synchronisation jump width in units of | ||
711 | tq. They allow to define the CAN bit-timing in a hardware | ||
712 | independent format as proposed by the Bosch CAN 2.0 spec (see | ||
713 | chapter 8 of http://www.semiconductors.bosch.de/pdf/can2spec.pdf). | ||
714 | |||
715 | "sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 | ||
716 | clock 8000000" | ||
717 | Shows the bit-timing constants of the CAN controller, here the | ||
718 | "sja1000". The minimum and maximum values of the time segment 1 | ||
719 | and 2, the synchronisation jump width in units of tq, the | ||
720 | bitrate pre-scaler and the CAN system clock frequency in Hz. | ||
721 | These constants could be used for user-defined (non-standard) | ||
722 | bit-timing calculation algorithms in user-space. | ||
723 | |||
724 | "re-started bus-errors arbit-lost error-warn error-pass bus-off" | ||
725 | Shows the number of restarts, bus and arbitration lost errors, | ||
726 | and the state changes to the error-warning, error-passive and | ||
727 | bus-off state. RX overrun errors are listed in the "overrun" | ||
728 | field of the standard network statistics. | ||
729 | |||
730 | 6.5.2 Setting the CAN bit-timing | ||
731 | |||
732 | The CAN bit-timing parameters can always be defined in a hardware | ||
733 | independent format as proposed in the Bosch CAN 2.0 specification | ||
734 | specifying the arguments "tq", "prop_seg", "phase_seg1", "phase_seg2" | ||
735 | and "sjw": | ||
736 | |||
737 | $ ip link set canX type can tq 125 prop-seg 6 \ | ||
738 | phase-seg1 7 phase-seg2 2 sjw 1 | ||
739 | |||
740 | If the kernel option CONFIG_CAN_CALC_BITTIMING is enabled, CIA | ||
741 | recommended CAN bit-timing parameters will be calculated if the bit- | ||
742 | rate is specified with the argument "bitrate": | ||
743 | |||
744 | $ ip link set canX type can bitrate 125000 | ||
745 | |||
746 | Note that this works fine for the most common CAN controllers with | ||
747 | standard bit-rates but may *fail* for exotic bit-rates or CAN system | ||
748 | clock frequencies. Disabling CONFIG_CAN_CALC_BITTIMING saves some | ||
749 | space and allows user-space tools to solely determine and set the | ||
750 | bit-timing parameters. The CAN controller specific bit-timing | ||
751 | constants can be used for that purpose. They are listed by the | ||
752 | following command: | ||
753 | |||
754 | $ ip -details link show can0 | ||
755 | ... | ||
756 | sja1000: clock 8000000 tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 | ||
757 | |||
758 | 6.5.3 Starting and stopping the CAN network device | ||
759 | |||
760 | A CAN network device is started or stopped as usual with the command | ||
761 | "ifconfig canX up/down" or "ip link set canX up/down". Be aware that | ||
762 | you *must* define proper bit-timing parameters for real CAN devices | ||
763 | before you can start it to avoid error-prone default settings: | ||
764 | |||
765 | $ ip link set canX up type can bitrate 125000 | ||
766 | |||
767 | A device may enter the "bus-off" state if too much errors occurred on | ||
768 | the CAN bus. Then no more messages are received or sent. An automatic | ||
769 | bus-off recovery can be enabled by setting the "restart-ms" to a | ||
770 | non-zero value, e.g.: | ||
771 | |||
772 | $ ip link set canX type can restart-ms 100 | ||
773 | |||
774 | Alternatively, the application may realize the "bus-off" condition | ||
775 | by monitoring CAN error frames and do a restart when appropriate with | ||
776 | the command: | ||
777 | |||
778 | $ ip link set canX type can restart | ||
779 | |||
780 | Note that a restart will also create a CAN error frame (see also | ||
781 | chapter 3.4). | ||
624 | 782 | ||
625 | On the project website http://developer.berlios.de/projects/socketcan | 783 | 6.6 Supported CAN hardware |
626 | there are different drivers available: | ||
627 | 784 | ||
628 | vcan: Virtual CAN interface driver (if no real hardware is available) | 785 | Please check the "Kconfig" file in "drivers/net/can" to get an actual |
629 | sja1000: Philips SJA1000 CAN controller (recommended) | 786 | list of the support CAN hardware. On the Socket CAN project website |
630 | i82527: Intel i82527 CAN controller | 787 | (see chapter 7) there might be further drivers available, also for |
631 | mscan: Motorola/Freescale CAN controller (e.g. inside SOC MPC5200) | 788 | older kernel versions. |
632 | ccan: CCAN controller core (e.g. inside SOC h7202) | ||
633 | slcan: For a bunch of CAN adaptors that are attached via a | ||
634 | serial line ASCII protocol (for serial / USB adaptors) | ||
635 | 789 | ||
636 | Additionally the different CAN adaptors (ISA/PCI/PCMCIA/USB/Parport) | 790 | 7. Socket CAN resources |
637 | from PEAK Systemtechnik support the CAN netdevice driver model | 791 | ----------------------- |
638 | since Linux driver v6.0: http://www.peak-system.com/linux/index.htm | ||
639 | 792 | ||
640 | Please check the Mailing Lists on the berlios OSS project website. | 793 | You can find further resources for Socket CAN like user space tools, |
794 | support for old kernel versions, more drivers, mailing lists, etc. | ||
795 | at the BerliOS OSS project website for Socket CAN: | ||
641 | 796 | ||
642 | 6.6 todo | 797 | http://developer.berlios.de/projects/socketcan |
643 | 798 | ||
644 | The configuration interface for CAN network drivers is still an open | 799 | If you have questions, bug fixes, etc., don't hesitate to post them to |
645 | issue that has not been finalized in the socketcan project. Also the | 800 | the Socketcan-Users mailing list. But please search the archives first. |
646 | idea of having a library module (candev.ko) that holds functions | ||
647 | that are needed by all CAN netdevices is not ready to ship. | ||
648 | Your contribution is welcome. | ||
649 | 801 | ||
650 | 7. Credits | 802 | 8. Credits |
651 | ---------- | 803 | ---------- |
652 | 804 | ||
653 | Oliver Hartkopp (PF_CAN core, filters, drivers, bcm) | 805 | Oliver Hartkopp (PF_CAN core, filters, drivers, bcm, SJA1000 driver) |
654 | Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan) | 806 | Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan) |
655 | Jan Kizka (RT-SocketCAN core, Socket-API reconciliation) | 807 | Jan Kizka (RT-SocketCAN core, Socket-API reconciliation) |
656 | Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews) | 808 | Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews, |
809 | CAN device driver interface, MSCAN driver) | ||
657 | Robert Schwebel (design reviews, PTXdist integration) | 810 | Robert Schwebel (design reviews, PTXdist integration) |
658 | Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers) | 811 | Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers) |
659 | Benedikt Spranger (reviews) | 812 | Benedikt Spranger (reviews) |
660 | Thomas Gleixner (LKML reviews, coding style, posting hints) | 813 | Thomas Gleixner (LKML reviews, coding style, posting hints) |
661 | Andrey Volkov (kernel subtree structure, ioctls, mscan driver) | 814 | Andrey Volkov (kernel subtree structure, ioctls, MSCAN driver) |
662 | Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003) | 815 | Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003) |
663 | Klaus Hitschler (PEAK driver integration) | 816 | Klaus Hitschler (PEAK driver integration) |
664 | Uwe Koppe (CAN netdevices with PF_PACKET approach) | 817 | Uwe Koppe (CAN netdevices with PF_PACKET approach) |
665 | Michael Schulze (driver layer loopback requirement, RT CAN drivers review) | 818 | Michael Schulze (driver layer loopback requirement, RT CAN drivers review) |
819 | Pavel Pisa (Bit-timing calculation) | ||
820 | Sascha Hauer (SJA1000 platform driver) | ||
821 | Sebastian Haas (SJA1000 EMS PCI driver) | ||
822 | Markus Plessing (SJA1000 EMS PCI driver) | ||
823 | Per Dalen (SJA1000 Kvaser PCI driver) | ||
824 | Sam Ravnborg (reviews, coding style, kbuild help) | ||
diff --git a/Documentation/networking/ieee802154.txt b/Documentation/networking/ieee802154.txt new file mode 100644 index 000000000000..a0280ad2edc9 --- /dev/null +++ b/Documentation/networking/ieee802154.txt | |||
@@ -0,0 +1,76 @@ | |||
1 | |||
2 | Linux IEEE 802.15.4 implementation | ||
3 | |||
4 | |||
5 | Introduction | ||
6 | ============ | ||
7 | |||
8 | The Linux-ZigBee project goal is to provide complete implementation | ||
9 | of IEEE 802.15.4 / ZigBee / 6LoWPAN protocols. IEEE 802.15.4 is a stack | ||
10 | of protocols for organizing Low-Rate Wireless Personal Area Networks. | ||
11 | |||
12 | Currently only IEEE 802.15.4 layer is implemented. We have choosen | ||
13 | to use plain Berkeley socket API, the generic Linux networking stack | ||
14 | to transfer IEEE 802.15.4 messages and a special protocol over genetlink | ||
15 | for configuration/management | ||
16 | |||
17 | |||
18 | Socket API | ||
19 | ========== | ||
20 | |||
21 | int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0); | ||
22 | ..... | ||
23 | |||
24 | The address family, socket addresses etc. are defined in the | ||
25 | include/net/ieee802154/af_ieee802154.h header or in the special header | ||
26 | in our userspace package (see either linux-zigbee sourceforge download page | ||
27 | or git tree at git://linux-zigbee.git.sourceforge.net/gitroot/linux-zigbee). | ||
28 | |||
29 | One can use SOCK_RAW for passing raw data towards device xmit function. YMMV. | ||
30 | |||
31 | |||
32 | MLME - MAC Level Management | ||
33 | ============================ | ||
34 | |||
35 | Most of IEEE 802.15.4 MLME interfaces are directly mapped on netlink commands. | ||
36 | See the include/net/ieee802154/nl802154.h header. Our userspace tools package | ||
37 | (see above) provides CLI configuration utility for radio interfaces and simple | ||
38 | coordinator for IEEE 802.15.4 networks as an example users of MLME protocol. | ||
39 | |||
40 | |||
41 | Kernel side | ||
42 | ============= | ||
43 | |||
44 | Like with WiFi, there are several types of devices implementing IEEE 802.15.4. | ||
45 | 1) 'HardMAC'. The MAC layer is implemented in the device itself, the device | ||
46 | exports MLME and data API. | ||
47 | 2) 'SoftMAC' or just radio. These types of devices are just radio transceivers | ||
48 | possibly with some kinds of acceleration like automatic CRC computation and | ||
49 | comparation, automagic ACK handling, address matching, etc. | ||
50 | |||
51 | Those types of devices require different approach to be hooked into Linux kernel. | ||
52 | |||
53 | |||
54 | HardMAC | ||
55 | ======= | ||
56 | |||
57 | See the header include/net/ieee802154/netdevice.h. You have to implement Linux | ||
58 | net_device, with .type = ARPHRD_IEEE802154. Data is exchanged with socket family | ||
59 | code via plain sk_buffs. The control block of sk_buffs will contain additional | ||
60 | info as described in the struct ieee802154_mac_cb. | ||
61 | |||
62 | To hook the MLME interface you have to populate the ml_priv field of your | ||
63 | net_device with a pointer to struct ieee802154_mlme_ops instance. All fields are | ||
64 | required. | ||
65 | |||
66 | We provide an example of simple HardMAC driver at drivers/ieee802154/fakehard.c | ||
67 | |||
68 | |||
69 | SoftMAC | ||
70 | ======= | ||
71 | |||
72 | We are going to provide intermediate layer impelementing IEEE 802.15.4 MAC | ||
73 | in software. This is currently WIP. | ||
74 | |||
75 | See header include/net/ieee802154/mac802154.h and several drivers in | ||
76 | drivers/ieee802154/ | ||
diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index b121c5db707f..8be76235fe67 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt | |||
@@ -168,7 +168,16 @@ tcp_dsack - BOOLEAN | |||
168 | Allows TCP to send "duplicate" SACKs. | 168 | Allows TCP to send "duplicate" SACKs. |
169 | 169 | ||
170 | tcp_ecn - BOOLEAN | 170 | tcp_ecn - BOOLEAN |
171 | Enable Explicit Congestion Notification in TCP. | 171 | Enable Explicit Congestion Notification (ECN) in TCP. ECN is only |
172 | used when both ends of the TCP flow support it. It is useful to | ||
173 | avoid losses due to congestion (when the bottleneck router supports | ||
174 | ECN). | ||
175 | Possible values are: | ||
176 | 0 disable ECN | ||
177 | 1 ECN enabled | ||
178 | 2 Only server-side ECN enabled. If the other end does | ||
179 | not support ECN, behavior is like with ECN disabled. | ||
180 | Default: 2 | ||
172 | 181 | ||
173 | tcp_fack - BOOLEAN | 182 | tcp_fack - BOOLEAN |
174 | Enable FACK congestion avoidance and fast retransmission. | 183 | Enable FACK congestion avoidance and fast retransmission. |
@@ -1048,6 +1057,13 @@ disable_ipv6 - BOOLEAN | |||
1048 | address. | 1057 | address. |
1049 | Default: FALSE (enable IPv6 operation) | 1058 | Default: FALSE (enable IPv6 operation) |
1050 | 1059 | ||
1060 | When this value is changed from 1 to 0 (IPv6 is being enabled), | ||
1061 | it will dynamically create a link-local address on the given | ||
1062 | interface and start Duplicate Address Detection, if necessary. | ||
1063 | |||
1064 | When this value is changed from 0 to 1 (IPv6 is being disabled), | ||
1065 | it will dynamically delete all address on the given interface. | ||
1066 | |||
1051 | accept_dad - INTEGER | 1067 | accept_dad - INTEGER |
1052 | Whether to accept DAD (Duplicate Address Detection). | 1068 | Whether to accept DAD (Duplicate Address Detection). |
1053 | 0: Disable DAD | 1069 | 0: Disable DAD |
diff --git a/Documentation/networking/ipv6.txt b/Documentation/networking/ipv6.txt index 268e5c103dd8..9fd7e21296c8 100644 --- a/Documentation/networking/ipv6.txt +++ b/Documentation/networking/ipv6.txt | |||
@@ -33,3 +33,40 @@ disable | |||
33 | 33 | ||
34 | A reboot is required to enable IPv6. | 34 | A reboot is required to enable IPv6. |
35 | 35 | ||
36 | autoconf | ||
37 | |||
38 | Specifies whether to enable IPv6 address autoconfiguration | ||
39 | on all interfaces. This might be used when one does not wish | ||
40 | for addresses to be automatically generated from prefixes | ||
41 | received in Router Advertisements. | ||
42 | |||
43 | The possible values and their effects are: | ||
44 | |||
45 | 0 | ||
46 | IPv6 address autoconfiguration is disabled on all interfaces. | ||
47 | |||
48 | Only the IPv6 loopback address (::1) and link-local addresses | ||
49 | will be added to interfaces. | ||
50 | |||
51 | 1 | ||
52 | IPv6 address autoconfiguration is enabled on all interfaces. | ||
53 | |||
54 | This is the default value. | ||
55 | |||
56 | disable_ipv6 | ||
57 | |||
58 | Specifies whether to disable IPv6 on all interfaces. | ||
59 | This might be used when no IPv6 addresses are desired. | ||
60 | |||
61 | The possible values and their effects are: | ||
62 | |||
63 | 0 | ||
64 | IPv6 is enabled on all interfaces. | ||
65 | |||
66 | This is the default value. | ||
67 | |||
68 | 1 | ||
69 | IPv6 is disabled on all interfaces. | ||
70 | |||
71 | No IPv6 addresses will be added to interfaces. | ||
72 | |||
diff --git a/Documentation/networking/mac80211-injection.txt b/Documentation/networking/mac80211-injection.txt index 84906ef3ed6e..b30e81ad5307 100644 --- a/Documentation/networking/mac80211-injection.txt +++ b/Documentation/networking/mac80211-injection.txt | |||
@@ -12,38 +12,22 @@ following format: | |||
12 | The radiotap format is discussed in | 12 | The radiotap format is discussed in |
13 | ./Documentation/networking/radiotap-headers.txt. | 13 | ./Documentation/networking/radiotap-headers.txt. |
14 | 14 | ||
15 | Despite 13 radiotap argument types are currently defined, most only make sense | 15 | Despite many radiotap parameters being currently defined, most only make sense |
16 | to appear on received packets. The following information is parsed from the | 16 | to appear on received packets. The following information is parsed from the |
17 | radiotap headers and used to control injection: | 17 | radiotap headers and used to control injection: |
18 | 18 | ||
19 | * IEEE80211_RADIOTAP_RATE | ||
20 | |||
21 | rate in 500kbps units, automatic if invalid or not present | ||
22 | |||
23 | |||
24 | * IEEE80211_RADIOTAP_ANTENNA | ||
25 | |||
26 | antenna to use, automatic if not present | ||
27 | |||
28 | |||
29 | * IEEE80211_RADIOTAP_DBM_TX_POWER | ||
30 | |||
31 | transmit power in dBm, automatic if not present | ||
32 | |||
33 | |||
34 | * IEEE80211_RADIOTAP_FLAGS | 19 | * IEEE80211_RADIOTAP_FLAGS |
35 | 20 | ||
36 | IEEE80211_RADIOTAP_F_FCS: FCS will be removed and recalculated | 21 | IEEE80211_RADIOTAP_F_FCS: FCS will be removed and recalculated |
37 | IEEE80211_RADIOTAP_F_WEP: frame will be encrypted if key available | 22 | IEEE80211_RADIOTAP_F_WEP: frame will be encrypted if key available |
38 | IEEE80211_RADIOTAP_F_FRAG: frame will be fragmented if longer than the | 23 | IEEE80211_RADIOTAP_F_FRAG: frame will be fragmented if longer than the |
39 | current fragmentation threshold. Note that | 24 | current fragmentation threshold. |
40 | this flag is only reliable when software | 25 | |
41 | fragmentation is enabled) | ||
42 | 26 | ||
43 | The injection code can also skip all other currently defined radiotap fields | 27 | The injection code can also skip all other currently defined radiotap fields |
44 | facilitating replay of captured radiotap headers directly. | 28 | facilitating replay of captured radiotap headers directly. |
45 | 29 | ||
46 | Here is an example valid radiotap header defining these three parameters | 30 | Here is an example valid radiotap header defining some parameters |
47 | 31 | ||
48 | 0x00, 0x00, // <-- radiotap version | 32 | 0x00, 0x00, // <-- radiotap version |
49 | 0x0b, 0x00, // <- radiotap header length | 33 | 0x0b, 0x00, // <- radiotap header length |
@@ -72,8 +56,8 @@ interface), along the following lines: | |||
72 | ... | 56 | ... |
73 | r = pcap_inject(ppcap, u8aSendBuffer, nLength); | 57 | r = pcap_inject(ppcap, u8aSendBuffer, nLength); |
74 | 58 | ||
75 | You can also find sources for a complete inject test applet here: | 59 | You can also find a link to a complete inject application here: |
76 | 60 | ||
77 | http://penumbra.warmcat.com/_twk/tiki-index.php?page=packetspammer | 61 | http://wireless.kernel.org/en/users/Documentation/packetspammer |
78 | 62 | ||
79 | Andy Green <andy@warmcat.com> | 63 | Andy Green <andy@warmcat.com> |
diff --git a/Documentation/networking/operstates.txt b/Documentation/networking/operstates.txt index c9074f9b78bb..1a77a3cfae54 100644 --- a/Documentation/networking/operstates.txt +++ b/Documentation/networking/operstates.txt | |||
@@ -38,9 +38,6 @@ ifinfomsg::if_flags & IFF_LOWER_UP: | |||
38 | ifinfomsg::if_flags & IFF_DORMANT: | 38 | ifinfomsg::if_flags & IFF_DORMANT: |
39 | Driver has signaled netif_dormant_on() | 39 | Driver has signaled netif_dormant_on() |
40 | 40 | ||
41 | These interface flags can also be queried without netlink using the | ||
42 | SIOCGIFFLAGS ioctl. | ||
43 | |||
44 | TLV IFLA_OPERSTATE | 41 | TLV IFLA_OPERSTATE |
45 | 42 | ||
46 | contains RFC2863 state of the interface in numeric representation: | 43 | contains RFC2863 state of the interface in numeric representation: |
diff --git a/Documentation/networking/packet_mmap.txt b/Documentation/networking/packet_mmap.txt index 07c53d596035..a22fd85e3796 100644 --- a/Documentation/networking/packet_mmap.txt +++ b/Documentation/networking/packet_mmap.txt | |||
@@ -4,16 +4,18 @@ | |||
4 | 4 | ||
5 | This file documents the CONFIG_PACKET_MMAP option available with the PACKET | 5 | This file documents the CONFIG_PACKET_MMAP option available with the PACKET |
6 | socket interface on 2.4 and 2.6 kernels. This type of sockets is used for | 6 | socket interface on 2.4 and 2.6 kernels. This type of sockets is used for |
7 | capture network traffic with utilities like tcpdump or any other that uses | 7 | capture network traffic with utilities like tcpdump or any other that needs |
8 | the libpcap library. | 8 | raw access to network interface. |
9 | |||
10 | You can find the latest version of this document at | ||
11 | 9 | ||
10 | You can find the latest version of this document at: | ||
12 | http://pusa.uv.es/~ulisses/packet_mmap/ | 11 | http://pusa.uv.es/~ulisses/packet_mmap/ |
13 | 12 | ||
14 | Please send me your comments to | 13 | Howto can be found at: |
14 | http://wiki.gnu-log.net (packet_mmap) | ||
15 | 15 | ||
16 | Please send your comments to | ||
16 | Ulisses Alonso Camaró <uaca@i.hate.spam.alumni.uv.es> | 17 | Ulisses Alonso Camaró <uaca@i.hate.spam.alumni.uv.es> |
18 | Johann Baudy <johann.baudy@gnu-log.net> | ||
17 | 19 | ||
18 | ------------------------------------------------------------------------------- | 20 | ------------------------------------------------------------------------------- |
19 | + Why use PACKET_MMAP | 21 | + Why use PACKET_MMAP |
@@ -25,19 +27,24 @@ to capture each packet, it requires two if you want to get packet's | |||
25 | timestamp (like libpcap always does). | 27 | timestamp (like libpcap always does). |
26 | 28 | ||
27 | In the other hand PACKET_MMAP is very efficient. PACKET_MMAP provides a size | 29 | In the other hand PACKET_MMAP is very efficient. PACKET_MMAP provides a size |
28 | configurable circular buffer mapped in user space. This way reading packets just | 30 | configurable circular buffer mapped in user space that can be used to either |
29 | needs to wait for them, most of the time there is no need to issue a single | 31 | send or receive packets. This way reading packets just needs to wait for them, |
30 | system call. By using a shared buffer between the kernel and the user | 32 | most of the time there is no need to issue a single system call. Concerning |
31 | also has the benefit of minimizing packet copies. | 33 | transmission, multiple packets can be sent through one system call to get the |
32 | 34 | highest bandwidth. | |
33 | It's fine to use PACKET_MMAP to improve the performance of the capture process, | 35 | By using a shared buffer between the kernel and the user also has the benefit |
34 | but it isn't everything. At least, if you are capturing at high speeds (this | 36 | of minimizing packet copies. |
35 | is relative to the cpu speed), you should check if the device driver of your | 37 | |
36 | network interface card supports some sort of interrupt load mitigation or | 38 | It's fine to use PACKET_MMAP to improve the performance of the capture and |
37 | (even better) if it supports NAPI, also make sure it is enabled. | 39 | transmission process, but it isn't everything. At least, if you are capturing |
40 | at high speeds (this is relative to the cpu speed), you should check if the | ||
41 | device driver of your network interface card supports some sort of interrupt | ||
42 | load mitigation or (even better) if it supports NAPI, also make sure it is | ||
43 | enabled. For transmission, check the MTU (Maximum Transmission Unit) used and | ||
44 | supported by devices of your network. | ||
38 | 45 | ||
39 | -------------------------------------------------------------------------------- | 46 | -------------------------------------------------------------------------------- |
40 | + How to use CONFIG_PACKET_MMAP | 47 | + How to use CONFIG_PACKET_MMAP to improve capture process |
41 | -------------------------------------------------------------------------------- | 48 | -------------------------------------------------------------------------------- |
42 | 49 | ||
43 | From the user standpoint, you should use the higher level libpcap library, which | 50 | From the user standpoint, you should use the higher level libpcap library, which |
@@ -57,7 +64,7 @@ the low level details or want to improve libpcap by including PACKET_MMAP | |||
57 | support. | 64 | support. |
58 | 65 | ||
59 | -------------------------------------------------------------------------------- | 66 | -------------------------------------------------------------------------------- |
60 | + How to use CONFIG_PACKET_MMAP directly | 67 | + How to use CONFIG_PACKET_MMAP directly to improve capture process |
61 | -------------------------------------------------------------------------------- | 68 | -------------------------------------------------------------------------------- |
62 | 69 | ||
63 | From the system calls stand point, the use of PACKET_MMAP involves | 70 | From the system calls stand point, the use of PACKET_MMAP involves |
@@ -66,6 +73,7 @@ the following process: | |||
66 | 73 | ||
67 | [setup] socket() -------> creation of the capture socket | 74 | [setup] socket() -------> creation of the capture socket |
68 | setsockopt() ---> allocation of the circular buffer (ring) | 75 | setsockopt() ---> allocation of the circular buffer (ring) |
76 | option: PACKET_RX_RING | ||
69 | mmap() ---------> mapping of the allocated buffer to the | 77 | mmap() ---------> mapping of the allocated buffer to the |
70 | user process | 78 | user process |
71 | 79 | ||
@@ -97,13 +105,75 @@ also the mapping of the circular buffer in the user process and | |||
97 | the use of this buffer. | 105 | the use of this buffer. |
98 | 106 | ||
99 | -------------------------------------------------------------------------------- | 107 | -------------------------------------------------------------------------------- |
108 | + How to use CONFIG_PACKET_MMAP directly to improve transmission process | ||
109 | -------------------------------------------------------------------------------- | ||
110 | Transmission process is similar to capture as shown below. | ||
111 | |||
112 | [setup] socket() -------> creation of the transmission socket | ||
113 | setsockopt() ---> allocation of the circular buffer (ring) | ||
114 | option: PACKET_TX_RING | ||
115 | bind() ---------> bind transmission socket with a network interface | ||
116 | mmap() ---------> mapping of the allocated buffer to the | ||
117 | user process | ||
118 | |||
119 | [transmission] poll() ---------> wait for free packets (optional) | ||
120 | send() ---------> send all packets that are set as ready in | ||
121 | the ring | ||
122 | The flag MSG_DONTWAIT can be used to return | ||
123 | before end of transfer. | ||
124 | |||
125 | [shutdown] close() --------> destruction of the transmission socket and | ||
126 | deallocation of all associated resources. | ||
127 | |||
128 | Binding the socket to your network interface is mandatory (with zero copy) to | ||
129 | know the header size of frames used in the circular buffer. | ||
130 | |||
131 | As capture, each frame contains two parts: | ||
132 | |||
133 | -------------------- | ||
134 | | struct tpacket_hdr | Header. It contains the status of | ||
135 | | | of this frame | ||
136 | |--------------------| | ||
137 | | data buffer | | ||
138 | . . Data that will be sent over the network interface. | ||
139 | . . | ||
140 | -------------------- | ||
141 | |||
142 | bind() associates the socket to your network interface thanks to | ||
143 | sll_ifindex parameter of struct sockaddr_ll. | ||
144 | |||
145 | Initialization example: | ||
146 | |||
147 | struct sockaddr_ll my_addr; | ||
148 | struct ifreq s_ifr; | ||
149 | ... | ||
150 | |||
151 | strncpy (s_ifr.ifr_name, "eth0", sizeof(s_ifr.ifr_name)); | ||
152 | |||
153 | /* get interface index of eth0 */ | ||
154 | ioctl(this->socket, SIOCGIFINDEX, &s_ifr); | ||
155 | |||
156 | /* fill sockaddr_ll struct to prepare binding */ | ||
157 | my_addr.sll_family = AF_PACKET; | ||
158 | my_addr.sll_protocol = ETH_P_ALL; | ||
159 | my_addr.sll_ifindex = s_ifr.ifr_ifindex; | ||
160 | |||
161 | /* bind socket to eth0 */ | ||
162 | bind(this->socket, (struct sockaddr *)&my_addr, sizeof(struct sockaddr_ll)); | ||
163 | |||
164 | A complete tutorial is available at: http://wiki.gnu-log.net/ | ||
165 | |||
166 | -------------------------------------------------------------------------------- | ||
100 | + PACKET_MMAP settings | 167 | + PACKET_MMAP settings |
101 | -------------------------------------------------------------------------------- | 168 | -------------------------------------------------------------------------------- |
102 | 169 | ||
103 | 170 | ||
104 | To setup PACKET_MMAP from user level code is done with a call like | 171 | To setup PACKET_MMAP from user level code is done with a call like |
105 | 172 | ||
173 | - Capture process | ||
106 | setsockopt(fd, SOL_PACKET, PACKET_RX_RING, (void *) &req, sizeof(req)) | 174 | setsockopt(fd, SOL_PACKET, PACKET_RX_RING, (void *) &req, sizeof(req)) |
175 | - Transmission process | ||
176 | setsockopt(fd, SOL_PACKET, PACKET_TX_RING, (void *) &req, sizeof(req)) | ||
107 | 177 | ||
108 | The most significant argument in the previous call is the req parameter, | 178 | The most significant argument in the previous call is the req parameter, |
109 | this parameter must to have the following structure: | 179 | this parameter must to have the following structure: |
@@ -117,11 +187,11 @@ this parameter must to have the following structure: | |||
117 | }; | 187 | }; |
118 | 188 | ||
119 | This structure is defined in /usr/include/linux/if_packet.h and establishes a | 189 | This structure is defined in /usr/include/linux/if_packet.h and establishes a |
120 | circular buffer (ring) of unswappable memory mapped in the capture process. | 190 | circular buffer (ring) of unswappable memory. |
121 | Being mapped in the capture process allows reading the captured frames and | 191 | Being mapped in the capture process allows reading the captured frames and |
122 | related meta-information like timestamps without requiring a system call. | 192 | related meta-information like timestamps without requiring a system call. |
123 | 193 | ||
124 | Captured frames are grouped in blocks. Each block is a physically contiguous | 194 | Frames are grouped in blocks. Each block is a physically contiguous |
125 | region of memory and holds tp_block_size/tp_frame_size frames. The total number | 195 | region of memory and holds tp_block_size/tp_frame_size frames. The total number |
126 | of blocks is tp_block_nr. Note that tp_frame_nr is a redundant parameter because | 196 | of blocks is tp_block_nr. Note that tp_frame_nr is a redundant parameter because |
127 | 197 | ||
@@ -336,6 +406,7 @@ struct tpacket_hdr). If this field is 0 means that the frame is ready | |||
336 | to be used for the kernel, If not, there is a frame the user can read | 406 | to be used for the kernel, If not, there is a frame the user can read |
337 | and the following flags apply: | 407 | and the following flags apply: |
338 | 408 | ||
409 | +++ Capture process: | ||
339 | from include/linux/if_packet.h | 410 | from include/linux/if_packet.h |
340 | 411 | ||
341 | #define TP_STATUS_COPY 2 | 412 | #define TP_STATUS_COPY 2 |
@@ -391,6 +462,37 @@ packets are in the ring: | |||
391 | It doesn't incur in a race condition to first check the status value and | 462 | It doesn't incur in a race condition to first check the status value and |
392 | then poll for frames. | 463 | then poll for frames. |
393 | 464 | ||
465 | |||
466 | ++ Transmission process | ||
467 | Those defines are also used for transmission: | ||
468 | |||
469 | #define TP_STATUS_AVAILABLE 0 // Frame is available | ||
470 | #define TP_STATUS_SEND_REQUEST 1 // Frame will be sent on next send() | ||
471 | #define TP_STATUS_SENDING 2 // Frame is currently in transmission | ||
472 | #define TP_STATUS_WRONG_FORMAT 4 // Frame format is not correct | ||
473 | |||
474 | First, the kernel initializes all frames to TP_STATUS_AVAILABLE. To send a | ||
475 | packet, the user fills a data buffer of an available frame, sets tp_len to | ||
476 | current data buffer size and sets its status field to TP_STATUS_SEND_REQUEST. | ||
477 | This can be done on multiple frames. Once the user is ready to transmit, it | ||
478 | calls send(). Then all buffers with status equal to TP_STATUS_SEND_REQUEST are | ||
479 | forwarded to the network device. The kernel updates each status of sent | ||
480 | frames with TP_STATUS_SENDING until the end of transfer. | ||
481 | At the end of each transfer, buffer status returns to TP_STATUS_AVAILABLE. | ||
482 | |||
483 | header->tp_len = in_i_size; | ||
484 | header->tp_status = TP_STATUS_SEND_REQUEST; | ||
485 | retval = send(this->socket, NULL, 0, 0); | ||
486 | |||
487 | The user can also use poll() to check if a buffer is available: | ||
488 | (status == TP_STATUS_SENDING) | ||
489 | |||
490 | struct pollfd pfd; | ||
491 | pfd.fd = fd; | ||
492 | pfd.revents = 0; | ||
493 | pfd.events = POLLOUT; | ||
494 | retval = poll(&pfd, 1, timeout); | ||
495 | |||
394 | -------------------------------------------------------------------------------- | 496 | -------------------------------------------------------------------------------- |
395 | + THANKS | 497 | + THANKS |
396 | -------------------------------------------------------------------------------- | 498 | -------------------------------------------------------------------------------- |
diff --git a/Documentation/powerpc/dts-bindings/can/sja1000.txt b/Documentation/powerpc/dts-bindings/can/sja1000.txt new file mode 100644 index 000000000000..d6d209ded937 --- /dev/null +++ b/Documentation/powerpc/dts-bindings/can/sja1000.txt | |||
@@ -0,0 +1,53 @@ | |||
1 | Memory mapped SJA1000 CAN controller from NXP (formerly Philips) | ||
2 | |||
3 | Required properties: | ||
4 | |||
5 | - compatible : should be "nxp,sja1000". | ||
6 | |||
7 | - reg : should specify the chip select, address offset and size required | ||
8 | to map the registers of the SJA1000. The size is usually 0x80. | ||
9 | |||
10 | - interrupts: property with a value describing the interrupt source | ||
11 | (number and sensitivity) required for the SJA1000. | ||
12 | |||
13 | Optional properties: | ||
14 | |||
15 | - nxp,external-clock-frequency : Frequency of the external oscillator | ||
16 | clock in Hz. Note that the internal clock frequency used by the | ||
17 | SJA1000 is half of that value. If not specified, a default value | ||
18 | of 16000000 (16 MHz) is used. | ||
19 | |||
20 | - nxp,tx-output-mode : operation mode of the TX output control logic: | ||
21 | <0x0> : bi-phase output mode | ||
22 | <0x1> : normal output mode (default) | ||
23 | <0x2> : test output mode | ||
24 | <0x3> : clock output mode | ||
25 | |||
26 | - nxp,tx-output-config : TX output pin configuration: | ||
27 | <0x01> : TX0 invert | ||
28 | <0x02> : TX0 pull-down (default) | ||
29 | <0x04> : TX0 pull-up | ||
30 | <0x06> : TX0 push-pull | ||
31 | <0x08> : TX1 invert | ||
32 | <0x10> : TX1 pull-down | ||
33 | <0x20> : TX1 pull-up | ||
34 | <0x30> : TX1 push-pull | ||
35 | |||
36 | - nxp,clock-out-frequency : clock frequency in Hz on the CLKOUT pin. | ||
37 | If not specified or if the specified value is 0, the CLKOUT pin | ||
38 | will be disabled. | ||
39 | |||
40 | - nxp,no-comparator-bypass : Allows to disable the CAN input comperator. | ||
41 | |||
42 | For futher information, please have a look to the SJA1000 data sheet. | ||
43 | |||
44 | Examples: | ||
45 | |||
46 | can@3,100 { | ||
47 | compatible = "nxp,sja1000"; | ||
48 | reg = <3 0x100 0x80>; | ||
49 | interrupts = <2 0>; | ||
50 | interrupt-parent = <&mpic>; | ||
51 | nxp,external-clock-frequency = <16000000>; | ||
52 | }; | ||
53 | |||
diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt index 4d3ee317a4a3..1b74b5f30af4 100644 --- a/Documentation/rfkill.txt +++ b/Documentation/rfkill.txt | |||
@@ -1,575 +1,136 @@ | |||
1 | rfkill - RF switch subsystem support | 1 | rfkill - RF kill switch support |
2 | ==================================== | 2 | =============================== |
3 | 3 | ||
4 | 1 Introduction | 4 | 1. Introduction |
5 | 2 Implementation details | 5 | 2. Implementation details |
6 | 3 Kernel driver guidelines | 6 | 3. Kernel driver guidelines |
7 | 3.1 wireless device drivers | 7 | 4. Kernel API |
8 | 3.2 platform/switch drivers | 8 | 5. Userspace support |
9 | 3.3 input device drivers | ||
10 | 4 Kernel API | ||
11 | 5 Userspace support | ||
12 | 9 | ||
13 | 10 | ||
14 | 1. Introduction: | 11 | 1. Introduction |
15 | 12 | ||
16 | The rfkill switch subsystem exists to add a generic interface to circuitry that | 13 | The rfkill subsystem provides a generic interface to disabling any radio |
17 | can enable or disable the signal output of a wireless *transmitter* of any | 14 | transmitter in the system. When a transmitter is blocked, it shall not |
18 | type. By far, the most common use is to disable radio-frequency transmitters. | 15 | radiate any power. |
19 | 16 | ||
20 | Note that disabling the signal output means that the the transmitter is to be | 17 | The subsystem also provides the ability to react on button presses and |
21 | made to not emit any energy when "blocked". rfkill is not about blocking data | 18 | disable all transmitters of a certain type (or all). This is intended for |
22 | transmissions, it is about blocking energy emission. | 19 | situations where transmitters need to be turned off, for example on |
20 | aircraft. | ||
23 | 21 | ||
24 | The rfkill subsystem offers support for keys and switches often found on | ||
25 | laptops to enable wireless devices like WiFi and Bluetooth, so that these keys | ||
26 | and switches actually perform an action in all wireless devices of a given type | ||
27 | attached to the system. | ||
28 | 22 | ||
29 | The buttons to enable and disable the wireless transmitters are important in | ||
30 | situations where the user is for example using his laptop on a location where | ||
31 | radio-frequency transmitters _must_ be disabled (e.g. airplanes). | ||
32 | 23 | ||
33 | Because of this requirement, userspace support for the keys should not be made | 24 | 2. Implementation details |
34 | mandatory. Because userspace might want to perform some additional smarter | ||
35 | tasks when the key is pressed, rfkill provides userspace the possibility to | ||
36 | take over the task to handle the key events. | ||
37 | |||
38 | =============================================================================== | ||
39 | 2: Implementation details | ||
40 | 25 | ||
41 | The rfkill subsystem is composed of various components: the rfkill class, the | 26 | The rfkill subsystem is composed of various components: the rfkill class, the |
42 | rfkill-input module (an input layer handler), and some specific input layer | 27 | rfkill-input module (an input layer handler), and some specific input layer |
43 | events. | 28 | events. |
44 | 29 | ||
45 | The rfkill class provides kernel drivers with an interface that allows them to | 30 | The rfkill class is provided for kernel drivers to register their radio |
46 | know when they should enable or disable a wireless network device transmitter. | 31 | transmitter with the kernel, provide methods for turning it on and off and, |
47 | This is enabled by the CONFIG_RFKILL Kconfig option. | 32 | optionally, letting the system know about hardware-disabled states that may |
48 | 33 | be implemented on the device. This code is enabled with the CONFIG_RFKILL | |
49 | The rfkill class support makes sure userspace will be notified of all state | 34 | Kconfig option, which drivers can "select". |
50 | changes on rfkill devices through uevents. It provides a notification chain | ||
51 | for interested parties in the kernel to also get notified of rfkill state | ||
52 | changes in other drivers. It creates several sysfs entries which can be used | ||
53 | by userspace. See section "Userspace support". | ||
54 | |||
55 | The rfkill-input module provides the kernel with the ability to implement a | ||
56 | basic response when the user presses a key or button (or toggles a switch) | ||
57 | related to rfkill functionality. It is an in-kernel implementation of default | ||
58 | policy of reacting to rfkill-related input events and neither mandatory nor | ||
59 | required for wireless drivers to operate. It is enabled by the | ||
60 | CONFIG_RFKILL_INPUT Kconfig option. | ||
61 | |||
62 | rfkill-input is a rfkill-related events input layer handler. This handler will | ||
63 | listen to all rfkill key events and will change the rfkill state of the | ||
64 | wireless devices accordingly. With this option enabled userspace could either | ||
65 | do nothing or simply perform monitoring tasks. | ||
66 | |||
67 | The rfkill-input module also provides EPO (emergency power-off) functionality | ||
68 | for all wireless transmitters. This function cannot be overridden, and it is | ||
69 | always active. rfkill EPO is related to *_RFKILL_ALL input layer events. | ||
70 | |||
71 | |||
72 | Important terms for the rfkill subsystem: | ||
73 | |||
74 | In order to avoid confusion, we avoid the term "switch" in rfkill when it is | ||
75 | referring to an electronic control circuit that enables or disables a | ||
76 | transmitter. We reserve it for the physical device a human manipulates | ||
77 | (which is an input device, by the way): | ||
78 | |||
79 | rfkill switch: | ||
80 | |||
81 | A physical device a human manipulates. Its state can be perceived by | ||
82 | the kernel either directly (through a GPIO pin, ACPI GPE) or by its | ||
83 | effect on a rfkill line of a wireless device. | ||
84 | |||
85 | rfkill controller: | ||
86 | |||
87 | A hardware circuit that controls the state of a rfkill line, which a | ||
88 | kernel driver can interact with *to modify* that state (i.e. it has | ||
89 | either write-only or read/write access). | ||
90 | |||
91 | rfkill line: | ||
92 | |||
93 | An input channel (hardware or software) of a wireless device, which | ||
94 | causes a wireless transmitter to stop emitting energy (BLOCK) when it | ||
95 | is active. Point of view is extremely important here: rfkill lines are | ||
96 | always seen from the PoV of a wireless device (and its driver). | ||
97 | |||
98 | soft rfkill line/software rfkill line: | ||
99 | |||
100 | A rfkill line the wireless device driver can directly change the state | ||
101 | of. Related to rfkill_state RFKILL_STATE_SOFT_BLOCKED. | ||
102 | |||
103 | hard rfkill line/hardware rfkill line: | ||
104 | |||
105 | A rfkill line that works fully in hardware or firmware, and that cannot | ||
106 | be overridden by the kernel driver. The hardware device or the | ||
107 | firmware just exports its status to the driver, but it is read-only. | ||
108 | Related to rfkill_state RFKILL_STATE_HARD_BLOCKED. | ||
109 | |||
110 | The enum rfkill_state describes the rfkill state of a transmitter: | ||
111 | |||
112 | When a rfkill line or rfkill controller is in the RFKILL_STATE_UNBLOCKED state, | ||
113 | the wireless transmitter (radio TX circuit for example) is *enabled*. When the | ||
114 | it is in the RFKILL_STATE_SOFT_BLOCKED or RFKILL_STATE_HARD_BLOCKED, the | ||
115 | wireless transmitter is to be *blocked* from operating. | ||
116 | |||
117 | RFKILL_STATE_SOFT_BLOCKED indicates that a call to toggle_radio() can change | ||
118 | that state. RFKILL_STATE_HARD_BLOCKED indicates that a call to toggle_radio() | ||
119 | will not be able to change the state and will return with a suitable error if | ||
120 | attempts are made to set the state to RFKILL_STATE_UNBLOCKED. | ||
121 | |||
122 | RFKILL_STATE_HARD_BLOCKED is used by drivers to signal that the device is | ||
123 | locked in the BLOCKED state by a hardwire rfkill line (typically an input pin | ||
124 | that, when active, forces the transmitter to be disabled) which the driver | ||
125 | CANNOT override. | ||
126 | |||
127 | Full rfkill functionality requires two different subsystems to cooperate: the | ||
128 | input layer and the rfkill class. The input layer issues *commands* to the | ||
129 | entire system requesting that devices registered to the rfkill class change | ||
130 | state. The way this interaction happens is not complex, but it is not obvious | ||
131 | either: | ||
132 | |||
133 | Kernel Input layer: | ||
134 | |||
135 | * Generates KEY_WWAN, KEY_WLAN, KEY_BLUETOOTH, SW_RFKILL_ALL, and | ||
136 | other such events when the user presses certain keys, buttons, or | ||
137 | toggles certain physical switches. | ||
138 | |||
139 | THE INPUT LAYER IS NEVER USED TO PROPAGATE STATUS, NOTIFICATIONS OR THE | ||
140 | KIND OF STUFF AN ON-SCREEN-DISPLAY APPLICATION WOULD REPORT. It is | ||
141 | used to issue *commands* for the system to change behaviour, and these | ||
142 | commands may or may not be carried out by some kernel driver or | ||
143 | userspace application. It follows that doing user feedback based only | ||
144 | on input events is broken, as there is no guarantee that an input event | ||
145 | will be acted upon. | ||
146 | |||
147 | Most wireless communication device drivers implementing rfkill | ||
148 | functionality MUST NOT generate these events, and have no reason to | ||
149 | register themselves with the input layer. Doing otherwise is a common | ||
150 | misconception. There is an API to propagate rfkill status change | ||
151 | information, and it is NOT the input layer. | ||
152 | |||
153 | rfkill class: | ||
154 | |||
155 | * Calls a hook in a driver to effectively change the wireless | ||
156 | transmitter state; | ||
157 | * Keeps track of the wireless transmitter state (with help from | ||
158 | the driver); | ||
159 | * Generates userspace notifications (uevents) and a call to a | ||
160 | notification chain (kernel) when there is a wireless transmitter | ||
161 | state change; | ||
162 | * Connects a wireless communications driver with the common rfkill | ||
163 | control system, which, for example, allows actions such as | ||
164 | "switch all bluetooth devices offline" to be carried out by | ||
165 | userspace or by rfkill-input. | ||
166 | |||
167 | THE RFKILL CLASS NEVER ISSUES INPUT EVENTS. THE RFKILL CLASS DOES | ||
168 | NOT LISTEN TO INPUT EVENTS. NO DRIVER USING THE RFKILL CLASS SHALL | ||
169 | EVER LISTEN TO, OR ACT ON RFKILL INPUT EVENTS. Doing otherwise is | ||
170 | a layering violation. | ||
171 | |||
172 | Most wireless data communication drivers in the kernel have just to | ||
173 | implement the rfkill class API to work properly. Interfacing to the | ||
174 | input layer is not often required (and is very often a *bug*) on | ||
175 | wireless drivers. | ||
176 | |||
177 | Platform drivers often have to attach to the input layer to *issue* | ||
178 | (but never to listen to) rfkill events for rfkill switches, and also to | ||
179 | the rfkill class to export a control interface for the platform rfkill | ||
180 | controllers to the rfkill subsystem. This does NOT mean the rfkill | ||
181 | switch is attached to a rfkill class (doing so is almost always wrong). | ||
182 | It just means the same kernel module is the driver for different | ||
183 | devices (rfkill switches and rfkill controllers). | ||
184 | |||
185 | |||
186 | Userspace input handlers (uevents) or kernel input handlers (rfkill-input): | ||
187 | |||
188 | * Implements the policy of what should happen when one of the input | ||
189 | layer events related to rfkill operation is received. | ||
190 | * Uses the sysfs interface (userspace) or private rfkill API calls | ||
191 | to tell the devices registered with the rfkill class to change | ||
192 | their state (i.e. translates the input layer event into real | ||
193 | action). | ||
194 | |||
195 | * rfkill-input implements EPO by handling EV_SW SW_RFKILL_ALL 0 | ||
196 | (power off all transmitters) in a special way: it ignores any | ||
197 | overrides and local state cache and forces all transmitters to the | ||
198 | RFKILL_STATE_SOFT_BLOCKED state (including those which are already | ||
199 | supposed to be BLOCKED). | ||
200 | * rfkill EPO will remain active until rfkill-input receives an | ||
201 | EV_SW SW_RFKILL_ALL 1 event. While the EPO is active, transmitters | ||
202 | are locked in the blocked state (rfkill will refuse to unblock them). | ||
203 | * rfkill-input implements different policies that the user can | ||
204 | select for handling EV_SW SW_RFKILL_ALL 1. It will unlock rfkill, | ||
205 | and either do nothing (leave transmitters blocked, but now unlocked), | ||
206 | restore the transmitters to their state before the EPO, or unblock | ||
207 | them all. | ||
208 | |||
209 | Userspace uevent handler or kernel platform-specific drivers hooked to the | ||
210 | rfkill notifier chain: | ||
211 | |||
212 | * Taps into the rfkill notifier chain or to KOBJ_CHANGE uevents, | ||
213 | in order to know when a device that is registered with the rfkill | ||
214 | class changes state; | ||
215 | * Issues feedback notifications to the user; | ||
216 | * In the rare platforms where this is required, synthesizes an input | ||
217 | event to command all *OTHER* rfkill devices to also change their | ||
218 | statues when a specific rfkill device changes state. | ||
219 | |||
220 | |||
221 | =============================================================================== | ||
222 | 3: Kernel driver guidelines | ||
223 | |||
224 | Remember: point-of-view is everything for a driver that connects to the rfkill | ||
225 | subsystem. All the details below must be measured/perceived from the point of | ||
226 | view of the specific driver being modified. | ||
227 | |||
228 | The first thing one needs to know is whether his driver should be talking to | ||
229 | the rfkill class or to the input layer. In rare cases (platform drivers), it | ||
230 | could happen that you need to do both, as platform drivers often handle a | ||
231 | variety of devices in the same driver. | ||
232 | |||
233 | Do not mistake input devices for rfkill controllers. The only type of "rfkill | ||
234 | switch" device that is to be registered with the rfkill class are those | ||
235 | directly controlling the circuits that cause a wireless transmitter to stop | ||
236 | working (or the software equivalent of them), i.e. what we call a rfkill | ||
237 | controller. Every other kind of "rfkill switch" is just an input device and | ||
238 | MUST NOT be registered with the rfkill class. | ||
239 | |||
240 | A driver should register a device with the rfkill class when ALL of the | ||
241 | following conditions are met (they define a rfkill controller): | ||
242 | |||
243 | 1. The device is/controls a data communications wireless transmitter; | ||
244 | |||
245 | 2. The kernel can interact with the hardware/firmware to CHANGE the wireless | ||
246 | transmitter state (block/unblock TX operation); | ||
247 | |||
248 | 3. The transmitter can be made to not emit any energy when "blocked": | ||
249 | rfkill is not about blocking data transmissions, it is about blocking | ||
250 | energy emission; | ||
251 | |||
252 | A driver should register a device with the input subsystem to issue | ||
253 | rfkill-related events (KEY_WLAN, KEY_BLUETOOTH, KEY_WWAN, KEY_WIMAX, | ||
254 | SW_RFKILL_ALL, etc) when ALL of the folowing conditions are met: | ||
255 | |||
256 | 1. It is directly related to some physical device the user interacts with, to | ||
257 | command the O.S./firmware/hardware to enable/disable a data communications | ||
258 | wireless transmitter. | ||
259 | |||
260 | Examples of the physical device are: buttons, keys and switches the user | ||
261 | will press/touch/slide/switch to enable or disable the wireless | ||
262 | communication device. | ||
263 | |||
264 | 2. It is NOT slaved to another device, i.e. there is no other device that | ||
265 | issues rfkill-related input events in preference to this one. | ||
266 | |||
267 | Please refer to the corner cases and examples section for more details. | ||
268 | |||
269 | When in doubt, do not issue input events. For drivers that should generate | ||
270 | input events in some platforms, but not in others (e.g. b43), the best solution | ||
271 | is to NEVER generate input events in the first place. That work should be | ||
272 | deferred to a platform-specific kernel module (which will know when to generate | ||
273 | events through the rfkill notifier chain) or to userspace. This avoids the | ||
274 | usual maintenance problems with DMI whitelisting. | ||
275 | |||
276 | |||
277 | Corner cases and examples: | ||
278 | ==================================== | ||
279 | |||
280 | 1. If the device is an input device that, because of hardware or firmware, | ||
281 | causes wireless transmitters to be blocked regardless of the kernel's will, it | ||
282 | is still just an input device, and NOT to be registered with the rfkill class. | ||
283 | |||
284 | 2. If the wireless transmitter switch control is read-only, it is an input | ||
285 | device and not to be registered with the rfkill class (and maybe not to be made | ||
286 | an input layer event source either, see below). | ||
287 | |||
288 | 3. If there is some other device driver *closer* to the actual hardware the | ||
289 | user interacted with (the button/switch/key) to issue an input event, THAT is | ||
290 | the device driver that should be issuing input events. | ||
291 | |||
292 | E.g: | ||
293 | [RFKILL slider switch] -- [GPIO hardware] -- [WLAN card rf-kill input] | ||
294 | (platform driver) (wireless card driver) | ||
295 | |||
296 | The user is closer to the RFKILL slide switch plaform driver, so the driver | ||
297 | which must issue input events is the platform driver looking at the GPIO | ||
298 | hardware, and NEVER the wireless card driver (which is just a slave). It is | ||
299 | very likely that there are other leaves than just the WLAN card rf-kill input | ||
300 | (e.g. a bluetooth card, etc)... | ||
301 | |||
302 | On the other hand, some embedded devices do this: | ||
303 | |||
304 | [RFKILL slider switch] -- [WLAN card rf-kill input] | ||
305 | (wireless card driver) | ||
306 | |||
307 | In this situation, the wireless card driver *could* register itself as an input | ||
308 | device and issue rf-kill related input events... but in order to AVOID the need | ||
309 | for DMI whitelisting, the wireless card driver does NOT do it. Userspace (HAL) | ||
310 | or a platform driver (that exists only on these embedded devices) will do the | ||
311 | dirty job of issuing the input events. | ||
312 | |||
313 | |||
314 | COMMON MISTAKES in kernel drivers, related to rfkill: | ||
315 | ==================================== | ||
316 | |||
317 | 1. NEVER confuse input device keys and buttons with input device switches. | ||
318 | |||
319 | 1a. Switches are always set or reset. They report the current state | ||
320 | (on position or off position). | ||
321 | |||
322 | 1b. Keys and buttons are either in the pressed or not-pressed state, and | ||
323 | that's it. A "button" that latches down when you press it, and | ||
324 | unlatches when you press it again is in fact a switch as far as input | ||
325 | devices go. | ||
326 | |||
327 | Add the SW_* events you need for switches, do NOT try to emulate a button using | ||
328 | KEY_* events just because there is no such SW_* event yet. Do NOT try to use, | ||
329 | for example, KEY_BLUETOOTH when you should be using SW_BLUETOOTH instead. | ||
330 | |||
331 | 2. Input device switches (sources of EV_SW events) DO store their current state | ||
332 | (so you *must* initialize it by issuing a gratuitous input layer event on | ||
333 | driver start-up and also when resuming from sleep), and that state CAN be | ||
334 | queried from userspace through IOCTLs. There is no sysfs interface for this, | ||
335 | but that doesn't mean you should break things trying to hook it to the rfkill | ||
336 | class to get a sysfs interface :-) | ||
337 | |||
338 | 3. Do not issue *_RFKILL_ALL events by default, unless you are sure it is the | ||
339 | correct event for your switch/button. These events are emergency power-off | ||
340 | events when they are trying to turn the transmitters off. An example of an | ||
341 | input device which SHOULD generate *_RFKILL_ALL events is the wireless-kill | ||
342 | switch in a laptop which is NOT a hotkey, but a real sliding/rocker switch. | ||
343 | An example of an input device which SHOULD NOT generate *_RFKILL_ALL events by | ||
344 | default, is any sort of hot key that is type-specific (e.g. the one for WLAN). | ||
345 | |||
346 | |||
347 | 3.1 Guidelines for wireless device drivers | ||
348 | ------------------------------------------ | ||
349 | |||
350 | (in this text, rfkill->foo means the foo field of struct rfkill). | ||
351 | |||
352 | 1. Each independent transmitter in a wireless device (usually there is only one | ||
353 | transmitter per device) should have a SINGLE rfkill class attached to it. | ||
354 | |||
355 | 2. If the device does not have any sort of hardware assistance to allow the | ||
356 | driver to rfkill the device, the driver should emulate it by taking all actions | ||
357 | required to silence the transmitter. | ||
358 | |||
359 | 3. If it is impossible to silence the transmitter (i.e. it still emits energy, | ||
360 | even if it is just in brief pulses, when there is no data to transmit and there | ||
361 | is no hardware support to turn it off) do NOT lie to the users. Do not attach | ||
362 | it to a rfkill class. The rfkill subsystem does not deal with data | ||
363 | transmission, it deals with energy emission. If the transmitter is emitting | ||
364 | energy, it is not blocked in rfkill terms. | ||
365 | |||
366 | 4. It doesn't matter if the device has multiple rfkill input lines affecting | ||
367 | the same transmitter, their combined state is to be exported as a single state | ||
368 | per transmitter (see rule 1). | ||
369 | |||
370 | This rule exists because users of the rfkill subsystem expect to get (and set, | ||
371 | when possible) the overall transmitter rfkill state, not of a particular rfkill | ||
372 | line. | ||
373 | |||
374 | 5. The wireless device driver MUST NOT leave the transmitter enabled during | ||
375 | suspend and hibernation unless: | ||
376 | 35 | ||
377 | 5.1. The transmitter has to be enabled for some sort of functionality | 36 | The rfkill class code also notifies userspace of state changes, this is |
378 | like wake-on-wireless-packet or autonomous packed forwarding in a mesh | 37 | achieved via uevents. It also provides some sysfs files for userspace to |
379 | network, and that functionality is enabled for this suspend/hibernation | 38 | check the status of radio transmitters. See the "Userspace support" section |
380 | cycle. | 39 | below. |
381 | 40 | ||
382 | AND | ||
383 | 41 | ||
384 | 5.2. The device was not on a user-requested BLOCKED state before | 42 | The rfkill-input code implements a basic response to rfkill buttons -- it |
385 | the suspend (i.e. the driver must NOT unblock a device, not even | 43 | implements turning on/off all devices of a certain class (or all). |
386 | to support wake-on-wireless-packet or remain in the mesh). | ||
387 | 44 | ||
388 | In other words, there is absolutely no allowed scenario where a driver can | 45 | When the device is hard-blocked (either by a call to rfkill_set_hw_state() |
389 | automatically take action to unblock a rfkill controller (obviously, this deals | 46 | or from query_hw_block) set_block() will be invoked but drivers can well |
390 | with scenarios where soft-blocking or both soft and hard blocking is happening. | 47 | ignore the method call since they can use the return value of the function |
391 | Scenarios where hardware rfkill lines are the only ones blocking the | 48 | rfkill_set_hw_state() to sync the software state instead of keeping track |
392 | transmitter are outside of this rule, since the wireless device driver does not | 49 | of calls to set_block(). |
393 | control its input hardware rfkill lines in the first place). | ||
394 | 50 | ||
395 | 6. During resume, rfkill will try to restore its previous state. | ||
396 | 51 | ||
397 | 7. After a rfkill class is suspended, it will *not* call rfkill->toggle_radio | 52 | The entire functionality is spread over more than one subsystem: |
398 | until it is resumed. | ||
399 | 53 | ||
54 | * The kernel input layer generates KEY_WWAN, KEY_WLAN etc. and | ||
55 | SW_RFKILL_ALL -- when the user presses a button. Drivers for radio | ||
56 | transmitters generally do not register to the input layer, unless the | ||
57 | device really provides an input device (i.e. a button that has no | ||
58 | effect other than generating a button press event) | ||
400 | 59 | ||
401 | Example of a WLAN wireless driver connected to the rfkill subsystem: | 60 | * The rfkill-input code hooks up to these events and switches the soft-block |
402 | -------------------------------------------------------------------- | 61 | of the various radio transmitters, depending on the button type. |
403 | 62 | ||
404 | A certain WLAN card has one input pin that causes it to block the transmitter | 63 | * The rfkill drivers turn off/on their transmitters as requested. |
405 | and makes the status of that input pin available (only for reading!) to the | ||
406 | kernel driver. This is a hard rfkill input line (it cannot be overridden by | ||
407 | the kernel driver). | ||
408 | 64 | ||
409 | The card also has one PCI register that, if manipulated by the driver, causes | 65 | * The rfkill class will generate userspace notifications (uevents) to tell |
410 | it to block the transmitter. This is a soft rfkill input line. | 66 | userspace what the current state is. |
411 | 67 | ||
412 | It has also a thermal protection circuitry that shuts down its transmitter if | ||
413 | the card overheats, and makes the status of that protection available (only for | ||
414 | reading!) to the kernel driver. This is also a hard rfkill input line. | ||
415 | 68 | ||
416 | If either one of these rfkill lines are active, the transmitter is blocked by | ||
417 | the hardware and forced offline. | ||
418 | 69 | ||
419 | The driver should allocate and attach to its struct device *ONE* instance of | 70 | 3. Kernel driver guidelines |
420 | the rfkill class (there is only one transmitter). | ||
421 | 71 | ||
422 | It can implement the get_state() hook, and return RFKILL_STATE_HARD_BLOCKED if | ||
423 | either one of its two hard rfkill input lines are active. If the two hard | ||
424 | rfkill lines are inactive, it must return RFKILL_STATE_SOFT_BLOCKED if its soft | ||
425 | rfkill input line is active. Only if none of the rfkill input lines are | ||
426 | active, will it return RFKILL_STATE_UNBLOCKED. | ||
427 | 72 | ||
428 | Since the device has a hardware rfkill line, it IS subject to state changes | 73 | Drivers for radio transmitters normally implement only the rfkill class. |
429 | external to rfkill. Therefore, the driver must make sure that it calls | 74 | These drivers may not unblock the transmitter based on own decisions, they |
430 | rfkill_force_state() to keep the status always up-to-date, and it must do a | 75 | should act on information provided by the rfkill class only. |
431 | rfkill_force_state() on resume from sleep. | ||
432 | 76 | ||
433 | Every time the driver gets a notification from the card that one of its rfkill | 77 | Platform drivers might implement input devices if the rfkill button is just |
434 | lines changed state (polling might be needed on badly designed cards that don't | 78 | that, a button. If that button influences the hardware then you need to |
435 | generate interrupts for such events), it recomputes the rfkill state as per | 79 | implement an rfkill class instead. This also applies if the platform provides |
436 | above, and calls rfkill_force_state() to update it. | 80 | a way to turn on/off the transmitter(s). |
437 | 81 | ||
438 | The driver should implement the toggle_radio() hook, that: | 82 | During suspend/hibernation, transmitters should only be left enabled when |
83 | wake-on wlan or similar functionality requires it and the device wasn't | ||
84 | blocked before suspend/hibernate. Note that it may be necessary to update | ||
85 | the rfkill subsystem's idea of what the current state is at resume time if | ||
86 | the state may have changed over suspend. | ||
439 | 87 | ||
440 | 1. Returns an error if one of the hardware rfkill lines are active, and the | ||
441 | caller asked for RFKILL_STATE_UNBLOCKED. | ||
442 | 88 | ||
443 | 2. Activates the soft rfkill line if the caller asked for state | ||
444 | RFKILL_STATE_SOFT_BLOCKED. It should do this even if one of the hard rfkill | ||
445 | lines are active, effectively double-blocking the transmitter. | ||
446 | 89 | ||
447 | 3. Deactivates the soft rfkill line if none of the hardware rfkill lines are | 90 | 4. Kernel API |
448 | active and the caller asked for RFKILL_STATE_UNBLOCKED. | ||
449 | |||
450 | =============================================================================== | ||
451 | 4: Kernel API | ||
452 | 91 | ||
453 | To build a driver with rfkill subsystem support, the driver should depend on | 92 | To build a driver with rfkill subsystem support, the driver should depend on |
454 | (or select) the Kconfig symbol RFKILL; it should _not_ depend on RKFILL_INPUT. | 93 | (or select) the Kconfig symbol RFKILL. |
455 | 94 | ||
456 | The hardware the driver talks to may be write-only (where the current state | 95 | The hardware the driver talks to may be write-only (where the current state |
457 | of the hardware is unknown), or read-write (where the hardware can be queried | 96 | of the hardware is unknown), or read-write (where the hardware can be queried |
458 | about its current state). | 97 | about its current state). |
459 | 98 | ||
460 | The rfkill class will call the get_state hook of a device every time it needs | 99 | Calling rfkill_set_hw_state() when a state change happens is required from |
461 | to know the *real* current state of the hardware. This can happen often, but | 100 | rfkill drivers that control devices that can be hard-blocked unless they also |
462 | it does not do any polling, so it is not enough on hardware that is subject | 101 | assign the poll_hw_block() callback (then the rfkill core will poll the |
463 | to state changes outside of the rfkill subsystem. | 102 | device). Don't do this unless you cannot get the event in any other way. |
464 | |||
465 | Therefore, calling rfkill_force_state() when a state change happens is | ||
466 | mandatory when the device has a hardware rfkill line, or when something else | ||
467 | like the firmware could cause its state to be changed without going through the | ||
468 | rfkill class. | ||
469 | |||
470 | Some hardware provides events when its status changes. In these cases, it is | ||
471 | best for the driver to not provide a get_state hook, and instead register the | ||
472 | rfkill class *already* with the correct status, and keep it updated using | ||
473 | rfkill_force_state() when it gets an event from the hardware. | ||
474 | |||
475 | rfkill_force_state() must be used on the device resume handlers to update the | ||
476 | rfkill status, should there be any chance of the device status changing during | ||
477 | the sleep. | ||
478 | |||
479 | There is no provision for a statically-allocated rfkill struct. You must | ||
480 | use rfkill_allocate() to allocate one. | ||
481 | |||
482 | You should: | ||
483 | - rfkill_allocate() | ||
484 | - modify rfkill fields (flags, name) | ||
485 | - modify state to the current hardware state (THIS IS THE ONLY TIME | ||
486 | YOU CAN ACCESS state DIRECTLY) | ||
487 | - rfkill_register() | ||
488 | |||
489 | The only way to set a device to the RFKILL_STATE_HARD_BLOCKED state is through | ||
490 | a suitable return of get_state() or through rfkill_force_state(). | ||
491 | 103 | ||
492 | When a device is in the RFKILL_STATE_HARD_BLOCKED state, the only way to switch | ||
493 | it to a different state is through a suitable return of get_state() or through | ||
494 | rfkill_force_state(). | ||
495 | 104 | ||
496 | If toggle_radio() is called to set a device to state RFKILL_STATE_SOFT_BLOCKED | ||
497 | when that device is already at the RFKILL_STATE_HARD_BLOCKED state, it should | ||
498 | not return an error. Instead, it should try to double-block the transmitter, | ||
499 | so that its state will change from RFKILL_STATE_HARD_BLOCKED to | ||
500 | RFKILL_STATE_SOFT_BLOCKED should the hardware blocking cease. | ||
501 | |||
502 | Please refer to the source for more documentation. | ||
503 | |||
504 | =============================================================================== | ||
505 | 5: Userspace support | ||
506 | |||
507 | rfkill devices issue uevents (with an action of "change"), with the following | ||
508 | environment variables set: | ||
509 | |||
510 | RFKILL_NAME | ||
511 | RFKILL_STATE | ||
512 | RFKILL_TYPE | ||
513 | 105 | ||
514 | The ABI for these variables is defined by the sysfs attributes. It is best | 106 | 5. Userspace support |
515 | to take a quick look at the source to make sure of the possible values. | ||
516 | 107 | ||
517 | It is expected that HAL will trap those, and bridge them to DBUS, etc. These | 108 | The following sysfs entries exist for every rfkill device: |
518 | events CAN and SHOULD be used to give feedback to the user about the rfkill | ||
519 | status of the system. | ||
520 | |||
521 | Input devices may issue events that are related to rfkill. These are the | ||
522 | various KEY_* events and SW_* events supported by rfkill-input.c. | ||
523 | |||
524 | ******IMPORTANT****** | ||
525 | When rfkill-input is ACTIVE, userspace is NOT TO CHANGE THE STATE OF AN RFKILL | ||
526 | SWITCH IN RESPONSE TO AN INPUT EVENT also handled by rfkill-input, unless it | ||
527 | has set to true the user_claim attribute for that particular switch. This rule | ||
528 | is *absolute*; do NOT violate it. | ||
529 | ******IMPORTANT****** | ||
530 | |||
531 | Userspace must not assume it is the only source of control for rfkill switches. | ||
532 | Their state CAN and WILL change due to firmware actions, direct user actions, | ||
533 | and the rfkill-input EPO override for *_RFKILL_ALL. | ||
534 | |||
535 | When rfkill-input is not active, userspace must initiate a rfkill status | ||
536 | change by writing to the "state" attribute in order for anything to happen. | ||
537 | |||
538 | Take particular care to implement EV_SW SW_RFKILL_ALL properly. When that | ||
539 | switch is set to OFF, *every* rfkill device *MUST* be immediately put into the | ||
540 | RFKILL_STATE_SOFT_BLOCKED state, no questions asked. | ||
541 | |||
542 | The following sysfs entries will be created: | ||
543 | 109 | ||
544 | name: Name assigned by driver to this key (interface or driver name). | 110 | name: Name assigned by driver to this key (interface or driver name). |
545 | type: Name of the key type ("wlan", "bluetooth", etc). | 111 | type: Name of the key type ("wlan", "bluetooth", etc). |
546 | state: Current state of the transmitter | 112 | state: Current state of the transmitter |
547 | 0: RFKILL_STATE_SOFT_BLOCKED | 113 | 0: RFKILL_STATE_SOFT_BLOCKED |
548 | transmitter is forced off, but one can override it | 114 | transmitter is turned off by software |
549 | by a write to the state attribute; | ||
550 | 1: RFKILL_STATE_UNBLOCKED | 115 | 1: RFKILL_STATE_UNBLOCKED |
551 | transmiter is NOT forced off, and may operate if | 116 | transmitter is (potentially) active |
552 | all other conditions for such operation are met | ||
553 | (such as interface is up and configured, etc); | ||
554 | 2: RFKILL_STATE_HARD_BLOCKED | 117 | 2: RFKILL_STATE_HARD_BLOCKED |
555 | transmitter is forced off by something outside of | 118 | transmitter is forced off by something outside of |
556 | the driver's control. One cannot set a device to | 119 | the driver's control. |
557 | this state through writes to the state attribute; | 120 | claim: 0: Kernel handles events (currently always reads that value) |
558 | claim: 1: Userspace handles events, 0: Kernel handles events | 121 | |
559 | 122 | rfkill devices also issue uevents (with an action of "change"), with the | |
560 | Both the "state" and "claim" entries are also writable. For the "state" entry | 123 | following environment variables set: |
561 | this means that when 1 or 0 is written, the device rfkill state (if not yet in | 124 | |
562 | the requested state), will be will be toggled accordingly. | 125 | RFKILL_NAME |
563 | 126 | RFKILL_STATE | |
564 | For the "claim" entry writing 1 to it means that the kernel no longer handles | 127 | RFKILL_TYPE |
565 | key events even though RFKILL_INPUT input was enabled. When "claim" has been | 128 | |
566 | set to 0, userspace should make sure that it listens for the input events or | 129 | The contents of these variables corresponds to the "name", "state" and |
567 | check the sysfs "state" entry regularly to correctly perform the required tasks | 130 | "type" sysfs files explained above. |
568 | when the rkfill key is pressed. | 131 | |
569 | 132 | An alternative userspace interface exists as a misc device /dev/rfkill, | |
570 | A note about input devices and EV_SW events: | 133 | which allows userspace to obtain and set the state of rfkill devices and |
571 | 134 | sets of devices. It also notifies userspace about device addition and | |
572 | In order to know the current state of an input device switch (like | 135 | removal. The API is a simple read/write API that is defined in |
573 | SW_RFKILL_ALL), you will need to use an IOCTL. That information is not | 136 | linux/rfkill.h. |
574 | available through sysfs in a generic way at this time, and it is not available | ||
575 | through the rfkill class AT ALL. | ||