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 __RFKILL_H
19#define __RFKILL_H
20
21#include <uapi/linux/rfkill.h>
22
23/* don't allow anyone to use these in the kernel */
24enum rfkill_user_states {
25	RFKILL_USER_STATE_SOFT_BLOCKED	= RFKILL_STATE_SOFT_BLOCKED,
26	RFKILL_USER_STATE_UNBLOCKED	= RFKILL_STATE_UNBLOCKED,
27	RFKILL_USER_STATE_HARD_BLOCKED	= RFKILL_STATE_HARD_BLOCKED,
28};
29#undef RFKILL_STATE_SOFT_BLOCKED
30#undef RFKILL_STATE_UNBLOCKED
31#undef RFKILL_STATE_HARD_BLOCKED
32
33#include <linux/kernel.h>
34#include <linux/list.h>
35#include <linux/mutex.h>
36#include <linux/leds.h>
37#include <linux/err.h>
38
39struct device;
40/* this is opaque */
41struct rfkill;
42
43/**
44 * struct rfkill_ops - rfkill driver methods
45 *
46 * @poll: poll the rfkill block state(s) -- only assign this method
47 *	when you need polling. When called, simply call one of the
48 *	rfkill_set{,_hw,_sw}_state family of functions. If the hw
49 *	is getting unblocked you need to take into account the return
50 *	value of those functions to make sure the software block is
51 *	properly used.
52 * @query: query the rfkill block state(s) and call exactly one of the
53 *	rfkill_set{,_hw,_sw}_state family of functions. Assign this
54 *	method if input events can cause hardware state changes to make
55 *	the rfkill core query your driver before setting a requested
56 *	block.
57 * @set_block: turn the transmitter on (blocked == false) or off
58 *	(blocked == true) -- ignore and return 0 when hard blocked.
59 *	This callback must be assigned.
60 */
61struct rfkill_ops {
62	void	(*poll)(struct rfkill *rfkill, void *data);
63	void	(*query)(struct rfkill *rfkill, void *data);
64	int	(*set_block)(void *data, bool blocked);
65};
66
67#if defined(CONFIG_RFKILL) || defined(CONFIG_RFKILL_MODULE)
68/**
69 * rfkill_alloc - allocate rfkill structure
70 * @name: name of the struct -- the string is not copied internally
71 * @parent: device that has rf switch on it
72 * @type: type of the switch (RFKILL_TYPE_*)
73 * @ops: rfkill methods
74 * @ops_data: data passed to each method
75 *
76 * This function should be called by the transmitter driver to allocate an
77 * rfkill structure. Returns %NULL on failure.
78 */
79struct rfkill * __must_check rfkill_alloc(const char *name,
80					  struct device *parent,
81					  const enum rfkill_type type,
82					  const struct rfkill_ops *ops,
83					  void *ops_data);
84
85/**
86 * rfkill_register - Register a rfkill structure.
87 * @rfkill: rfkill structure to be registered
88 *
89 * This function should be called by the transmitter driver to register
90 * the rfkill structure. Before calling this function the driver needs
91 * to be ready to service method calls from rfkill.
92 *
93 * If rfkill_init_sw_state() is not called before registration,
94 * set_block() will be called to initialize the software blocked state
95 * to a default value.
96 *
97 * If the hardware blocked state is not set before registration,
98 * it is assumed to be unblocked.
99 */
100int __must_check rfkill_register(struct rfkill *rfkill);
101
102/**
103 * rfkill_pause_polling(struct rfkill *rfkill)
104 *
105 * Pause polling -- say transmitter is off for other reasons.
106 * NOTE: not necessary for suspend/resume -- in that case the
107 * core stops polling anyway
108 */
109void rfkill_pause_polling(struct rfkill *rfkill);
110
111/**
112 * rfkill_resume_polling(struct rfkill *rfkill)
113 *
114 * Pause polling -- say transmitter is off for other reasons.
115 * NOTE: not necessary for suspend/resume -- in that case the
116 * core stops polling anyway
117 */
118void rfkill_resume_polling(struct rfkill *rfkill);
119
120
121/**
122 * rfkill_unregister - Unregister a rfkill structure.
123 * @rfkill: rfkill structure to be unregistered
124 *
125 * This function should be called by the network driver during device
126 * teardown to destroy rfkill structure. Until it returns, the driver
127 * needs to be able to service method calls.
128 */
129void rfkill_unregister(struct rfkill *rfkill);
130
131/**
132 * rfkill_destroy - free rfkill structure
133 * @rfkill: rfkill structure to be destroyed
134 *
135 * Destroys the rfkill structure.
136 */
137void rfkill_destroy(struct rfkill *rfkill);
138
139/**
140 * rfkill_set_hw_state - Set the internal rfkill hardware block state
141 * @rfkill: pointer to the rfkill class to modify.
142 * @state: the current hardware block state to set
143 *
144 * rfkill drivers that get events when the hard-blocked state changes
145 * use this function to notify the rfkill core (and through that also
146 * userspace) of the current state.  They should also use this after
147 * resume if the state could have changed.
148 *
149 * You need not (but may) call this function if poll_state is assigned.
150 *
151 * This function can be called in any context, even from within rfkill
152 * callbacks.
153 *
154 * The function returns the combined block state (true if transmitter
155 * should be blocked) so that drivers need not keep track of the soft
156 * block state -- which they might not be able to.
157 */
158bool rfkill_set_hw_state(struct rfkill *rfkill, bool blocked);
159
160/**
161 * rfkill_set_sw_state - Set the internal rfkill software block state
162 * @rfkill: pointer to the rfkill class to modify.
163 * @state: the current software block state to set
164 *
165 * rfkill drivers that get events when the soft-blocked state changes
166 * (yes, some platforms directly act on input but allow changing again)
167 * use this function to notify the rfkill core (and through that also
168 * userspace) of the current state.
169 *
170 * Drivers should also call this function after resume if the state has
171 * been changed by the user.  This only makes sense for "persistent"
172 * devices (see rfkill_init_sw_state()).
173 *
174 * This function can be called in any context, even from within rfkill
175 * callbacks.
176 *
177 * The function returns the combined block state (true if transmitter
178 * should be blocked).
179 */
180bool rfkill_set_sw_state(struct rfkill *rfkill, bool blocked);
181
182/**
183 * rfkill_init_sw_state - Initialize persistent software block state
184 * @rfkill: pointer to the rfkill class to modify.
185 * @state: the current software block state to set
186 *
187 * rfkill drivers that preserve their software block state over power off
188 * use this function to notify the rfkill core (and through that also
189 * userspace) of their initial state.  It should only be used before
190 * registration.
191 *
192 * In addition, it marks the device as "persistent", an attribute which
193 * can be read by userspace.  Persistent devices are expected to preserve
194 * their own state when suspended.
195 */
196void rfkill_init_sw_state(struct rfkill *rfkill, bool blocked);
197
198/**
199 * rfkill_set_states - Set the internal rfkill block states
200 * @rfkill: pointer to the rfkill class to modify.
201 * @sw: the current software block state to set
202 * @hw: the current hardware block state to set
203 *
204 * This function can be called in any context, even from within rfkill
205 * callbacks.
206 */
207void rfkill_set_states(struct rfkill *rfkill, bool sw, bool hw);
208
209/**
210 * rfkill_blocked - query rfkill block
211 *
212 * @rfkill: rfkill struct to query
213 */
214bool rfkill_blocked(struct rfkill *rfkill);
215#else /* !RFKILL */
216static inline struct rfkill * __must_check
217rfkill_alloc(const char *name,
218	     struct device *parent,
219	     const enum rfkill_type type,
220	     const struct rfkill_ops *ops,
221	     void *ops_data)
222{
223	return ERR_PTR(-ENODEV);
224}
225
226static inline int __must_check rfkill_register(struct rfkill *rfkill)
227{
228	if (rfkill == ERR_PTR(-ENODEV))
229		return 0;
230	return -EINVAL;
231}
232
233static inline void rfkill_pause_polling(struct rfkill *rfkill)
234{
235}
236
237static inline void rfkill_resume_polling(struct rfkill *rfkill)
238{
239}
240
241static inline void rfkill_unregister(struct rfkill *rfkill)
242{
243}
244
245static inline void rfkill_destroy(struct rfkill *rfkill)
246{
247}
248
249static inline bool rfkill_set_hw_state(struct rfkill *rfkill, bool blocked)
250{
251	return blocked;
252}
253
254static inline bool rfkill_set_sw_state(struct rfkill *rfkill, bool blocked)
255{
256	return blocked;
257}
258
259static inline void rfkill_init_sw_state(struct rfkill *rfkill, bool blocked)
260{
261}
262
263static inline void rfkill_set_states(struct rfkill *rfkill, bool sw, bool hw)
264{
265}
266
267static inline bool rfkill_blocked(struct rfkill *rfkill)
268{
269	return false;
270}
271#endif /* RFKILL || RFKILL_MODULE */
272
273
274#ifdef CONFIG_RFKILL_LEDS
275/**
276 * rfkill_get_led_trigger_name - Get the LED trigger name for the button's LED.
277 * This function might return a NULL pointer if registering of the
278 * LED trigger failed. Use this as "default_trigger" for the LED.
279 */
280const char *rfkill_get_led_trigger_name(struct rfkill *rfkill);
281
282/**
283 * rfkill_set_led_trigger_name -- set the LED trigger name
284 * @rfkill: rfkill struct
285 * @name: LED trigger name
286 *
287 * This function sets the LED trigger name of the radio LED
288 * trigger that rfkill creates. It is optional, but if called
289 * must be called before rfkill_register() to be effective.
290 */
291void rfkill_set_led_trigger_name(struct rfkill *rfkill, const char *name);
292#else
293static inline const char *rfkill_get_led_trigger_name(struct rfkill *rfkill)
294{
295	return NULL;
296}
297
298static inline void
299rfkill_set_led_trigger_name(struct rfkill *rfkill, const char *name)
300{
301}
302#endif
303
304#endif /* RFKILL_H */
305