rfkill: yet more minor kernel-doc fixes
[linux-2.6.git] / net / rfkill / rfkill.c
1 /*
2  * Copyright (C) 2006 - 2007 Ivo van Doorn
3  * Copyright (C) 2007 Dmitry Torokhov
4  *
5  * This program is free software; you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation; either version 2 of the License, or
8  * (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  * GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with this program; if not, write to the
17  * Free Software Foundation, Inc.,
18  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
19  */
20
21 #include <linux/kernel.h>
22 #include <linux/module.h>
23 #include <linux/init.h>
24 #include <linux/workqueue.h>
25 #include <linux/capability.h>
26 #include <linux/list.h>
27 #include <linux/mutex.h>
28 #include <linux/rfkill.h>
29
30 /* Get declaration of rfkill_switch_all() to shut up sparse. */
31 #include "rfkill-input.h"
32
33
34 MODULE_AUTHOR("Ivo van Doorn <IvDoorn@gmail.com>");
35 MODULE_VERSION("1.0");
36 MODULE_DESCRIPTION("RF switch support");
37 MODULE_LICENSE("GPL");
38
39 static LIST_HEAD(rfkill_list);  /* list of registered rf switches */
40 static DEFINE_MUTEX(rfkill_mutex);
41
42 static unsigned int rfkill_default_state = RFKILL_STATE_UNBLOCKED;
43 module_param_named(default_state, rfkill_default_state, uint, 0444);
44 MODULE_PARM_DESC(default_state,
45                  "Default initial state for all radio types, 0 = radio off");
46
47 static enum rfkill_state rfkill_states[RFKILL_TYPE_MAX];
48
49 static BLOCKING_NOTIFIER_HEAD(rfkill_notifier_list);
50
51
52 /**
53  * register_rfkill_notifier - Add notifier to rfkill notifier chain
54  * @nb: pointer to the new entry to add to the chain
55  *
56  * See blocking_notifier_chain_register() for return value and further
57  * observations.
58  *
59  * Adds a notifier to the rfkill notifier chain.  The chain will be
60  * called with a pointer to the relevant rfkill structure as a parameter,
61  * refer to include/linux/rfkill.h for the possible events.
62  *
63  * Notifiers added to this chain are to always return NOTIFY_DONE.  This
64  * chain is a blocking notifier chain: notifiers can sleep.
65  *
66  * Calls to this chain may have been done through a workqueue.  One must
67  * assume unordered asynchronous behaviour, there is no way to know if
68  * actions related to the event that generated the notification have been
69  * carried out already.
70  */
71 int register_rfkill_notifier(struct notifier_block *nb)
72 {
73         return blocking_notifier_chain_register(&rfkill_notifier_list, nb);
74 }
75 EXPORT_SYMBOL_GPL(register_rfkill_notifier);
76
77 /**
78  * unregister_rfkill_notifier - remove notifier from rfkill notifier chain
79  * @nb: pointer to the entry to remove from the chain
80  *
81  * See blocking_notifier_chain_unregister() for return value and further
82  * observations.
83  *
84  * Removes a notifier from the rfkill notifier chain.
85  */
86 int unregister_rfkill_notifier(struct notifier_block *nb)
87 {
88         return blocking_notifier_chain_unregister(&rfkill_notifier_list, nb);
89 }
90 EXPORT_SYMBOL_GPL(unregister_rfkill_notifier);
91
92
93 static void rfkill_led_trigger(struct rfkill *rfkill,
94                                enum rfkill_state state)
95 {
96 #ifdef CONFIG_RFKILL_LEDS
97         struct led_trigger *led = &rfkill->led_trigger;
98
99         if (!led->name)
100                 return;
101         if (state != RFKILL_STATE_UNBLOCKED)
102                 led_trigger_event(led, LED_OFF);
103         else
104                 led_trigger_event(led, LED_FULL);
105 #endif /* CONFIG_RFKILL_LEDS */
106 }
107
108 static void notify_rfkill_state_change(struct rfkill *rfkill)
109 {
110         blocking_notifier_call_chain(&rfkill_notifier_list,
111                         RFKILL_STATE_CHANGED,
112                         rfkill);
113 }
114
115 static void update_rfkill_state(struct rfkill *rfkill)
116 {
117         enum rfkill_state newstate, oldstate;
118
119         if (rfkill->get_state) {
120                 mutex_lock(&rfkill->mutex);
121                 if (!rfkill->get_state(rfkill->data, &newstate)) {
122                         oldstate = rfkill->state;
123                         rfkill->state = newstate;
124                         if (oldstate != newstate)
125                                 notify_rfkill_state_change(rfkill);
126                 }
127                 mutex_unlock(&rfkill->mutex);
128         }
129 }
130
131 /**
132  * rfkill_toggle_radio - wrapper for toggle_radio hook
133  * @rfkill: the rfkill struct to use
134  * @force: calls toggle_radio even if cache says it is not needed,
135  *      and also makes sure notifications of the state will be
136  *      sent even if it didn't change
137  * @state: the new state to call toggle_radio() with
138  *
139  * Calls rfkill->toggle_radio, enforcing the API for toggle_radio
140  * calls and handling all the red tape such as issuing notifications
141  * if the call is successful.
142  *
143  * Note that the @force parameter cannot override a (possibly cached)
144  * state of RFKILL_STATE_HARD_BLOCKED.  Any device making use of
145  * RFKILL_STATE_HARD_BLOCKED implements either get_state() or
146  * rfkill_force_state(), so the cache either is bypassed or valid.
147  *
148  * Note that we do call toggle_radio for RFKILL_STATE_SOFT_BLOCKED
149  * even if the radio is in RFKILL_STATE_HARD_BLOCKED state, so as to
150  * give the driver a hint that it should double-BLOCK the transmitter.
151  *
152  * Caller must have acquired rfkill->mutex.
153  */
154 static int rfkill_toggle_radio(struct rfkill *rfkill,
155                                 enum rfkill_state state,
156                                 int force)
157 {
158         int retval = 0;
159         enum rfkill_state oldstate, newstate;
160
161         oldstate = rfkill->state;
162
163         if (rfkill->get_state && !force &&
164             !rfkill->get_state(rfkill->data, &newstate))
165                 rfkill->state = newstate;
166
167         switch (state) {
168         case RFKILL_STATE_HARD_BLOCKED:
169                 /* typically happens when refreshing hardware state,
170                  * such as on resume */
171                 state = RFKILL_STATE_SOFT_BLOCKED;
172                 break;
173         case RFKILL_STATE_UNBLOCKED:
174                 /* force can't override this, only rfkill_force_state() can */
175                 if (rfkill->state == RFKILL_STATE_HARD_BLOCKED)
176                         return -EPERM;
177                 break;
178         case RFKILL_STATE_SOFT_BLOCKED:
179                 /* nothing to do, we want to give drivers the hint to double
180                  * BLOCK even a transmitter that is already in state
181                  * RFKILL_STATE_HARD_BLOCKED */
182                 break;
183         }
184
185         if (force || state != rfkill->state) {
186                 retval = rfkill->toggle_radio(rfkill->data, state);
187                 /* never allow a HARD->SOFT downgrade! */
188                 if (!retval && rfkill->state != RFKILL_STATE_HARD_BLOCKED)
189                         rfkill->state = state;
190         }
191
192         if (force || rfkill->state != oldstate) {
193                 rfkill_led_trigger(rfkill, rfkill->state);
194                 notify_rfkill_state_change(rfkill);
195         }
196
197         return retval;
198 }
199
200 /**
201  * rfkill_switch_all - Toggle state of all switches of given type
202  * @type: type of interfaces to be affected
203  * @state: the new state
204  *
205  * This function toggles the state of all switches of given type,
206  * unless a specific switch is claimed by userspace (in which case,
207  * that switch is left alone).
208  */
209 void rfkill_switch_all(enum rfkill_type type, enum rfkill_state state)
210 {
211         struct rfkill *rfkill;
212
213         mutex_lock(&rfkill_mutex);
214
215         rfkill_states[type] = state;
216
217         list_for_each_entry(rfkill, &rfkill_list, node) {
218                 if ((!rfkill->user_claim) && (rfkill->type == type)) {
219                         mutex_lock(&rfkill->mutex);
220                         rfkill_toggle_radio(rfkill, state, 0);
221                         mutex_unlock(&rfkill->mutex);
222                 }
223         }
224
225         mutex_unlock(&rfkill_mutex);
226 }
227 EXPORT_SYMBOL(rfkill_switch_all);
228
229 /**
230  * rfkill_epo - emergency power off all transmitters
231  *
232  * This kicks all rfkill devices to RFKILL_STATE_SOFT_BLOCKED, ignoring
233  * everything in its path but rfkill_mutex and rfkill->mutex.
234  */
235 void rfkill_epo(void)
236 {
237         struct rfkill *rfkill;
238
239         mutex_lock(&rfkill_mutex);
240         list_for_each_entry(rfkill, &rfkill_list, node) {
241                 mutex_lock(&rfkill->mutex);
242                 rfkill_toggle_radio(rfkill, RFKILL_STATE_SOFT_BLOCKED, 1);
243                 mutex_unlock(&rfkill->mutex);
244         }
245         mutex_unlock(&rfkill_mutex);
246 }
247 EXPORT_SYMBOL_GPL(rfkill_epo);
248
249 /**
250  * rfkill_force_state - Force the internal rfkill radio state
251  * @rfkill: pointer to the rfkill class to modify.
252  * @state: the current radio state the class should be forced to.
253  *
254  * This function updates the internal state of the radio cached
255  * by the rfkill class.  It should be used when the driver gets
256  * a notification by the firmware/hardware of the current *real*
257  * state of the radio rfkill switch.
258  *
259  * Devices which are subject to external changes on their rfkill
260  * state (such as those caused by a hardware rfkill line) MUST
261  * have their driver arrange to call rfkill_force_state() as soon
262  * as possible after such a change.
263  *
264  * This function may not be called from an atomic context.
265  */
266 int rfkill_force_state(struct rfkill *rfkill, enum rfkill_state state)
267 {
268         enum rfkill_state oldstate;
269
270         if (state != RFKILL_STATE_SOFT_BLOCKED &&
271             state != RFKILL_STATE_UNBLOCKED &&
272             state != RFKILL_STATE_HARD_BLOCKED)
273                 return -EINVAL;
274
275         mutex_lock(&rfkill->mutex);
276
277         oldstate = rfkill->state;
278         rfkill->state = state;
279
280         if (state != oldstate)
281                 notify_rfkill_state_change(rfkill);
282
283         mutex_unlock(&rfkill->mutex);
284
285         return 0;
286 }
287 EXPORT_SYMBOL(rfkill_force_state);
288
289 static ssize_t rfkill_name_show(struct device *dev,
290                                 struct device_attribute *attr,
291                                 char *buf)
292 {
293         struct rfkill *rfkill = to_rfkill(dev);
294
295         return sprintf(buf, "%s\n", rfkill->name);
296 }
297
298 static const char *rfkill_get_type_str(enum rfkill_type type)
299 {
300         switch (type) {
301         case RFKILL_TYPE_WLAN:
302                 return "wlan";
303         case RFKILL_TYPE_BLUETOOTH:
304                 return "bluetooth";
305         case RFKILL_TYPE_UWB:
306                 return "ultrawideband";
307         case RFKILL_TYPE_WIMAX:
308                 return "wimax";
309         case RFKILL_TYPE_WWAN:
310                 return "wwan";
311         default:
312                 BUG();
313         }
314 }
315
316 static ssize_t rfkill_type_show(struct device *dev,
317                                 struct device_attribute *attr,
318                                 char *buf)
319 {
320         struct rfkill *rfkill = to_rfkill(dev);
321
322         return sprintf(buf, "%s\n", rfkill_get_type_str(rfkill->type));
323 }
324
325 static ssize_t rfkill_state_show(struct device *dev,
326                                  struct device_attribute *attr,
327                                  char *buf)
328 {
329         struct rfkill *rfkill = to_rfkill(dev);
330
331         update_rfkill_state(rfkill);
332         return sprintf(buf, "%d\n", rfkill->state);
333 }
334
335 static ssize_t rfkill_state_store(struct device *dev,
336                                   struct device_attribute *attr,
337                                   const char *buf, size_t count)
338 {
339         struct rfkill *rfkill = to_rfkill(dev);
340         unsigned int state = simple_strtoul(buf, NULL, 0);
341         int error;
342
343         if (!capable(CAP_NET_ADMIN))
344                 return -EPERM;
345
346         /* RFKILL_STATE_HARD_BLOCKED is illegal here... */
347         if (state != RFKILL_STATE_UNBLOCKED &&
348             state != RFKILL_STATE_SOFT_BLOCKED)
349                 return -EINVAL;
350
351         if (mutex_lock_interruptible(&rfkill->mutex))
352                 return -ERESTARTSYS;
353         error = rfkill_toggle_radio(rfkill, state, 0);
354         mutex_unlock(&rfkill->mutex);
355
356         return error ? error : count;
357 }
358
359 static ssize_t rfkill_claim_show(struct device *dev,
360                                  struct device_attribute *attr,
361                                  char *buf)
362 {
363         struct rfkill *rfkill = to_rfkill(dev);
364
365         return sprintf(buf, "%d", rfkill->user_claim);
366 }
367
368 static ssize_t rfkill_claim_store(struct device *dev,
369                                   struct device_attribute *attr,
370                                   const char *buf, size_t count)
371 {
372         struct rfkill *rfkill = to_rfkill(dev);
373         bool claim = !!simple_strtoul(buf, NULL, 0);
374         int error;
375
376         if (!capable(CAP_NET_ADMIN))
377                 return -EPERM;
378
379         if (rfkill->user_claim_unsupported)
380                 return -EOPNOTSUPP;
381
382         /*
383          * Take the global lock to make sure the kernel is not in
384          * the middle of rfkill_switch_all
385          */
386         error = mutex_lock_interruptible(&rfkill_mutex);
387         if (error)
388                 return error;
389
390         if (rfkill->user_claim != claim) {
391                 if (!claim) {
392                         mutex_lock(&rfkill->mutex);
393                         rfkill_toggle_radio(rfkill,
394                                             rfkill_states[rfkill->type],
395                                             0);
396                         mutex_unlock(&rfkill->mutex);
397                 }
398                 rfkill->user_claim = claim;
399         }
400
401         mutex_unlock(&rfkill_mutex);
402
403         return error ? error : count;
404 }
405
406 static struct device_attribute rfkill_dev_attrs[] = {
407         __ATTR(name, S_IRUGO, rfkill_name_show, NULL),
408         __ATTR(type, S_IRUGO, rfkill_type_show, NULL),
409         __ATTR(state, S_IRUGO|S_IWUSR, rfkill_state_show, rfkill_state_store),
410         __ATTR(claim, S_IRUGO|S_IWUSR, rfkill_claim_show, rfkill_claim_store),
411         __ATTR_NULL
412 };
413
414 static void rfkill_release(struct device *dev)
415 {
416         struct rfkill *rfkill = to_rfkill(dev);
417
418         kfree(rfkill);
419         module_put(THIS_MODULE);
420 }
421
422 #ifdef CONFIG_PM
423 static int rfkill_suspend(struct device *dev, pm_message_t state)
424 {
425         struct rfkill *rfkill = to_rfkill(dev);
426
427         if (dev->power.power_state.event != state.event) {
428                 if (state.event & PM_EVENT_SLEEP) {
429                         /* Stop transmitter, keep state, no notifies */
430                         update_rfkill_state(rfkill);
431
432                         mutex_lock(&rfkill->mutex);
433                         rfkill->toggle_radio(rfkill->data,
434                                                 RFKILL_STATE_SOFT_BLOCKED);
435                         mutex_unlock(&rfkill->mutex);
436                 }
437
438                 dev->power.power_state = state;
439         }
440
441         return 0;
442 }
443
444 static int rfkill_resume(struct device *dev)
445 {
446         struct rfkill *rfkill = to_rfkill(dev);
447
448         if (dev->power.power_state.event != PM_EVENT_ON) {
449                 mutex_lock(&rfkill->mutex);
450
451                 /* restore radio state AND notify everybody */
452                 rfkill_toggle_radio(rfkill, rfkill->state, 1);
453
454                 mutex_unlock(&rfkill->mutex);
455         }
456
457         dev->power.power_state = PMSG_ON;
458         return 0;
459 }
460 #else
461 #define rfkill_suspend NULL
462 #define rfkill_resume NULL
463 #endif
464
465 static int rfkill_blocking_uevent_notifier(struct notifier_block *nb,
466                                         unsigned long eventid,
467                                         void *data)
468 {
469         struct rfkill *rfkill = (struct rfkill *)data;
470
471         switch (eventid) {
472         case RFKILL_STATE_CHANGED:
473                 kobject_uevent(&rfkill->dev.kobj, KOBJ_CHANGE);
474                 break;
475         default:
476                 break;
477         }
478
479         return NOTIFY_DONE;
480 }
481
482 static struct notifier_block rfkill_blocking_uevent_nb = {
483         .notifier_call  = rfkill_blocking_uevent_notifier,
484         .priority       = 0,
485 };
486
487 static int rfkill_dev_uevent(struct device *dev, struct kobj_uevent_env *env)
488 {
489         struct rfkill *rfkill = to_rfkill(dev);
490         int error;
491
492         error = add_uevent_var(env, "RFKILL_NAME=%s", rfkill->name);
493         if (error)
494                 return error;
495         error = add_uevent_var(env, "RFKILL_TYPE=%s",
496                                 rfkill_get_type_str(rfkill->type));
497         if (error)
498                 return error;
499         error = add_uevent_var(env, "RFKILL_STATE=%d", rfkill->state);
500         return error;
501 }
502
503 static struct class rfkill_class = {
504         .name           = "rfkill",
505         .dev_release    = rfkill_release,
506         .dev_attrs      = rfkill_dev_attrs,
507         .suspend        = rfkill_suspend,
508         .resume         = rfkill_resume,
509         .dev_uevent     = rfkill_dev_uevent,
510 };
511
512 static int rfkill_add_switch(struct rfkill *rfkill)
513 {
514         mutex_lock(&rfkill_mutex);
515
516         rfkill_toggle_radio(rfkill, rfkill_states[rfkill->type], 0);
517
518         list_add_tail(&rfkill->node, &rfkill_list);
519
520         mutex_unlock(&rfkill_mutex);
521
522         return 0;
523 }
524
525 static void rfkill_remove_switch(struct rfkill *rfkill)
526 {
527         mutex_lock(&rfkill_mutex);
528         list_del_init(&rfkill->node);
529         mutex_unlock(&rfkill_mutex);
530
531         mutex_lock(&rfkill->mutex);
532         rfkill_toggle_radio(rfkill, RFKILL_STATE_SOFT_BLOCKED, 1);
533         mutex_unlock(&rfkill->mutex);
534 }
535
536 /**
537  * rfkill_allocate - allocate memory for rfkill structure.
538  * @parent: device that has rf switch on it
539  * @type: type of the switch (RFKILL_TYPE_*)
540  *
541  * This function should be called by the network driver when it needs
542  * rfkill structure.  Once the structure is allocated the driver should
543  * finish its initialization by setting the name, private data, enable_radio
544  * and disable_radio methods and then register it with rfkill_register().
545  *
546  * NOTE: If registration fails the structure shoudl be freed by calling
547  * rfkill_free() otherwise rfkill_unregister() should be used.
548  */
549 struct rfkill *rfkill_allocate(struct device *parent, enum rfkill_type type)
550 {
551         struct rfkill *rfkill;
552         struct device *dev;
553
554         rfkill = kzalloc(sizeof(struct rfkill), GFP_KERNEL);
555         if (!rfkill)
556                 return NULL;
557
558         mutex_init(&rfkill->mutex);
559         INIT_LIST_HEAD(&rfkill->node);
560         rfkill->type = type;
561
562         dev = &rfkill->dev;
563         dev->class = &rfkill_class;
564         dev->parent = parent;
565         device_initialize(dev);
566
567         __module_get(THIS_MODULE);
568
569         return rfkill;
570 }
571 EXPORT_SYMBOL(rfkill_allocate);
572
573 /**
574  * rfkill_free - Mark rfkill structure for deletion
575  * @rfkill: rfkill structure to be destroyed
576  *
577  * Decrements reference count of the rfkill structure so it is destroyed.
578  * Note that rfkill_free() should _not_ be called after rfkill_unregister().
579  */
580 void rfkill_free(struct rfkill *rfkill)
581 {
582         if (rfkill)
583                 put_device(&rfkill->dev);
584 }
585 EXPORT_SYMBOL(rfkill_free);
586
587 static void rfkill_led_trigger_register(struct rfkill *rfkill)
588 {
589 #ifdef CONFIG_RFKILL_LEDS
590         int error;
591
592         rfkill->led_trigger.name = rfkill->dev.bus_id;
593         error = led_trigger_register(&rfkill->led_trigger);
594         if (error)
595                 rfkill->led_trigger.name = NULL;
596 #endif /* CONFIG_RFKILL_LEDS */
597 }
598
599 static void rfkill_led_trigger_unregister(struct rfkill *rfkill)
600 {
601 #ifdef CONFIG_RFKILL_LEDS
602         if (rfkill->led_trigger.name) {
603                 led_trigger_unregister(&rfkill->led_trigger);
604                 rfkill->led_trigger.name = NULL;
605         }
606 #endif
607 }
608
609 /**
610  * rfkill_register - Register a rfkill structure.
611  * @rfkill: rfkill structure to be registered
612  *
613  * This function should be called by the network driver when the rfkill
614  * structure needs to be registered. Immediately from registration the
615  * switch driver should be able to service calls to toggle_radio.
616  */
617 int rfkill_register(struct rfkill *rfkill)
618 {
619         static atomic_t rfkill_no = ATOMIC_INIT(0);
620         struct device *dev = &rfkill->dev;
621         int error;
622
623         if (!rfkill->toggle_radio)
624                 return -EINVAL;
625         if (rfkill->type >= RFKILL_TYPE_MAX)
626                 return -EINVAL;
627
628         snprintf(dev->bus_id, sizeof(dev->bus_id),
629                  "rfkill%ld", (long)atomic_inc_return(&rfkill_no) - 1);
630
631         rfkill_led_trigger_register(rfkill);
632
633         error = rfkill_add_switch(rfkill);
634         if (error) {
635                 rfkill_led_trigger_unregister(rfkill);
636                 return error;
637         }
638
639         error = device_add(dev);
640         if (error) {
641                 rfkill_remove_switch(rfkill);
642                 rfkill_led_trigger_unregister(rfkill);
643                 return error;
644         }
645
646         return 0;
647 }
648 EXPORT_SYMBOL(rfkill_register);
649
650 /**
651  * rfkill_unregister - Unregister a rfkill structure.
652  * @rfkill: rfkill structure to be unregistered
653  *
654  * This function should be called by the network driver during device
655  * teardown to destroy rfkill structure. Note that rfkill_free() should
656  * _not_ be called after rfkill_unregister().
657  */
658 void rfkill_unregister(struct rfkill *rfkill)
659 {
660         device_del(&rfkill->dev);
661         rfkill_remove_switch(rfkill);
662         rfkill_led_trigger_unregister(rfkill);
663         put_device(&rfkill->dev);
664 }
665 EXPORT_SYMBOL(rfkill_unregister);
666
667 /*
668  * Rfkill module initialization/deinitialization.
669  */
670 static int __init rfkill_init(void)
671 {
672         int error;
673         int i;
674
675         /* RFKILL_STATE_HARD_BLOCKED is illegal here... */
676         if (rfkill_default_state != RFKILL_STATE_SOFT_BLOCKED &&
677             rfkill_default_state != RFKILL_STATE_UNBLOCKED)
678                 return -EINVAL;
679
680         for (i = 0; i < ARRAY_SIZE(rfkill_states); i++)
681                 rfkill_states[i] = rfkill_default_state;
682
683         error = class_register(&rfkill_class);
684         if (error) {
685                 printk(KERN_ERR "rfkill: unable to register rfkill class\n");
686                 return error;
687         }
688
689         register_rfkill_notifier(&rfkill_blocking_uevent_nb);
690
691         return 0;
692 }
693
694 static void __exit rfkill_exit(void)
695 {
696         unregister_rfkill_notifier(&rfkill_blocking_uevent_nb);
697         class_unregister(&rfkill_class);
698 }
699
700 subsys_initcall(rfkill_init);
701 module_exit(rfkill_exit);