include/uapi/linux/rfkill.h

   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  * Userspace using &struct rfkill_event_ext must adhere to the following
 163  * rules
 164  *
 165  * 1. accept short writes, optionally using them to detect that it's
 166  *    running on an older kernel;
 167  * 2. accept short reads, knowing that this means it's running on an
 168  *    older kernel;
 169  * 3. treat reads that are as long as requested as acceptable, not
 170  *    checking against RFKILL_EVENT_SIZE_V1 or such.
 171  */
 172 #define RFKILL_EVENT_SIZE_V1    sizeof(struct rfkill_event)
 173
 174 /* ioctl for turning off rfkill-input (if present) */
 175 #define RFKILL_IOC_MAGIC        'R'
 176 #define RFKILL_IOC_NOINPUT      1
 177 #define RFKILL_IOCTL_NOINPUT    _IO(RFKILL_IOC_MAGIC, RFKILL_IOC_NOINPUT)
 178
 179 /* and that's all userspace gets */
 180
 181 #endif /* _UAPI__RFKILL_H */