xref: /openbmc/linux/include/uapi/linux/rfkill.h (revision 3d9c1d39)
1 /*
2  * Copyright (C) 2006 - 2007 Ivo van Doorn
3  * Copyright (C) 2007 Dmitry Torokhov
4  * Copyright 2009 Johannes Berg <johannes@sipsolutions.net>
5  *
6  * Permission to use, copy, modify, and/or distribute this software for any
7  * purpose with or without fee is hereby granted, provided that the above
8  * copyright notice and this permission notice appear in all copies.
9  *
10  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17  */
18 #ifndef _UAPI__RFKILL_H
19 #define _UAPI__RFKILL_H
20 
21 
22 #include <linux/types.h>
23 
24 /* define userspace visible states */
25 #define RFKILL_STATE_SOFT_BLOCKED	0
26 #define RFKILL_STATE_UNBLOCKED		1
27 #define RFKILL_STATE_HARD_BLOCKED	2
28 
29 /**
30  * enum rfkill_type - type of rfkill switch.
31  *
32  * @RFKILL_TYPE_ALL: toggles all switches (requests only - not a switch type)
33  * @RFKILL_TYPE_WLAN: switch is on a 802.11 wireless network device.
34  * @RFKILL_TYPE_BLUETOOTH: switch is on a bluetooth device.
35  * @RFKILL_TYPE_UWB: switch is on a ultra wideband device.
36  * @RFKILL_TYPE_WIMAX: switch is on a WiMAX device.
37  * @RFKILL_TYPE_WWAN: switch is on a wireless WAN device.
38  * @RFKILL_TYPE_GPS: switch is on a GPS device.
39  * @RFKILL_TYPE_FM: switch is on a FM radio device.
40  * @RFKILL_TYPE_NFC: switch is on an NFC device.
41  * @NUM_RFKILL_TYPES: number of defined rfkill types
42  */
43 enum rfkill_type {
44 	RFKILL_TYPE_ALL = 0,
45 	RFKILL_TYPE_WLAN,
46 	RFKILL_TYPE_BLUETOOTH,
47 	RFKILL_TYPE_UWB,
48 	RFKILL_TYPE_WIMAX,
49 	RFKILL_TYPE_WWAN,
50 	RFKILL_TYPE_GPS,
51 	RFKILL_TYPE_FM,
52 	RFKILL_TYPE_NFC,
53 	NUM_RFKILL_TYPES,
54 };
55 
56 /**
57  * enum rfkill_operation - operation types
58  * @RFKILL_OP_ADD: a device was added
59  * @RFKILL_OP_DEL: a device was removed
60  * @RFKILL_OP_CHANGE: a device's state changed -- userspace changes one device
61  * @RFKILL_OP_CHANGE_ALL: userspace changes all devices (of a type, or all)
62  *	into a state, also updating the default state used for devices that
63  *	are hot-plugged later.
64  */
65 enum rfkill_operation {
66 	RFKILL_OP_ADD = 0,
67 	RFKILL_OP_DEL,
68 	RFKILL_OP_CHANGE,
69 	RFKILL_OP_CHANGE_ALL,
70 };
71 
72 /**
73  * enum rfkill_hard_block_reasons - hard block reasons
74  * @RFKILL_HARD_BLOCK_SIGNAL: the hardware rfkill signal is active
75  * @RFKILL_HARD_BLOCK_NOT_OWNER: the NIC is not owned by the host
76  */
77 enum rfkill_hard_block_reasons {
78 	RFKILL_HARD_BLOCK_SIGNAL	= 1 << 0,
79 	RFKILL_HARD_BLOCK_NOT_OWNER	= 1 << 1,
80 };
81 
82 /**
83  * struct rfkill_event - events for userspace on /dev/rfkill
84  * @idx: index of dev rfkill
85  * @type: type of the rfkill struct
86  * @op: operation code
87  * @hard: hard state (0/1)
88  * @soft: soft state (0/1)
89  *
90  * Structure used for userspace communication on /dev/rfkill,
91  * used for events from the kernel and control to the kernel.
92  */
93 struct rfkill_event {
94 	__u32 idx;
95 	__u8  type;
96 	__u8  op;
97 	__u8  soft;
98 	__u8  hard;
99 } __attribute__((packed));
100 
101 /**
102  * struct rfkill_event_ext - events for userspace on /dev/rfkill
103  * @idx: index of dev rfkill
104  * @type: type of the rfkill struct
105  * @op: operation code
106  * @hard: hard state (0/1)
107  * @soft: soft state (0/1)
108  * @hard_block_reasons: valid if hard is set. One or several reasons from
109  *	&enum rfkill_hard_block_reasons.
110  *
111  * Structure used for userspace communication on /dev/rfkill,
112  * used for events from the kernel and control to the kernel.
113  *
114  * See the extensibility docs below.
115  */
116 struct rfkill_event_ext {
117 	__u32 idx;
118 	__u8  type;
119 	__u8  op;
120 	__u8  soft;
121 	__u8  hard;
122 
123 	/*
124 	 * older kernels will accept/send only up to this point,
125 	 * and if extended further up to any chunk marked below
126 	 */
127 
128 	__u8  hard_block_reasons;
129 } __attribute__((packed));
130 
131 /**
132  * DOC: Extensibility
133  *
134  * Originally, we had planned to allow backward and forward compatible
135  * changes by just adding fields at the end of the structure that are
136  * then not reported on older kernels on read(), and not written to by
137  * older kernels on write(), with the kernel reporting the size it did
138  * accept as the result.
139  *
140  * This would have allowed userspace to detect on read() and write()
141  * which kernel structure version it was dealing with, and if was just
142  * recompiled it would have gotten the new fields, but obviously not
143  * accessed them, but things should've continued to work.
144  *
145  * Unfortunately, while actually exercising this mechanism to add the
146  * hard block reasons field, we found that userspace (notably systemd)
147  * did all kinds of fun things not in line with this scheme:
148  *
149  * 1. treat the (expected) short writes as an error;
150  * 2. ask to read sizeof(struct rfkill_event) but then compare the
151  *    actual return value to RFKILL_EVENT_SIZE_V1 and treat any
152  *    mismatch as an error.
153  *
154  * As a consequence, just recompiling with a new struct version caused
155  * things to no longer work correctly on old and new kernels.
156  *
157  * Hence, we've rolled back &struct rfkill_event to the original version
158  * and added &struct rfkill_event_ext. This effectively reverts to the
159  * old behaviour for all userspace, unless it explicitly opts in to the
160  * rules outlined here by using the new &struct rfkill_event_ext.
161  *
162  * Additionally, some other userspace (bluez, g-s-d) was reading with a
163  * large size but as streaming reads rather than message-based, or with
164  * too strict checks for the returned size. So eventually, we completely
165  * reverted this, and extended messages need to be opted in to by using
166  * an ioctl:
167  *
168  *  ioctl(fd, RFKILL_IOCTL_MAX_SIZE, sizeof(struct rfkill_event_ext));
169  *
170  * Userspace using &struct rfkill_event_ext and the ioctl must adhere to
171  * the following rules:
172  *
173  * 1. accept short writes, optionally using them to detect that it's
174  *    running on an older kernel;
175  * 2. accept short reads, knowing that this means it's running on an
176  *    older kernel;
177  * 3. treat reads that are as long as requested as acceptable, not
178  *    checking against RFKILL_EVENT_SIZE_V1 or such.
179  */
180 #define RFKILL_EVENT_SIZE_V1	sizeof(struct rfkill_event)
181 
182 /* ioctl for turning off rfkill-input (if present) */
183 #define RFKILL_IOC_MAGIC	'R'
184 #define RFKILL_IOC_NOINPUT	1
185 #define RFKILL_IOCTL_NOINPUT	_IO(RFKILL_IOC_MAGIC, RFKILL_IOC_NOINPUT)
186 #define RFKILL_IOC_MAX_SIZE	2
187 #define RFKILL_IOCTL_MAX_SIZE	_IOW(RFKILL_IOC_MAGIC, RFKILL_IOC_MAX_SIZE, __u32)
188 
189 /* and that's all userspace gets */
190 
191 #endif /* _UAPI__RFKILL_H */
192