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 */
43enum 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 */
65enum 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 */
77enum 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 */
93struct 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 */
116struct 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