Commit | Line | Data |
---|---|---|
3e971dbc MH |
1 | |
2 | Staging/Android Switch Class Porting Guide | |
3 | (linux/drivers/staging/android/switch) | |
4 | (c) Copyright 2012 Samsung Electronics | |
5 | ||
6 | AUTHORS | |
7 | MyungJoo Ham <myungjoo.ham@samsung.com> | |
8 | ||
9 | /***************************************************************** | |
10 | * CHAPTER 1. * | |
11 | * PORTING SWITCH CLASS DEVICE DRIVERS * | |
12 | *****************************************************************/ | |
13 | ||
14 | ****** STEP 1. Basic Functionality | |
15 | No extcon extended feature, but switch features only. | |
16 | ||
17 | - struct switch_dev (fed to switch_dev_register/unregister) | |
18 | @name: no change | |
19 | @dev: no change | |
20 | @index: drop (not used in switch device driver side anyway) | |
21 | @state: no change | |
22 | If you have used @state with magic numbers, keep it | |
23 | at this step. | |
24 | @print_name: no change but type change (switch_dev->extcon_dev) | |
25 | @print_state: no change but type change (switch_dev->extcon_dev) | |
26 | ||
27 | - switch_dev_register(sdev, dev) | |
28 | => extcon_dev_register(edev, dev) | |
29 | : no change but type change (sdev->edev) | |
30 | - switch_dev_unregister(sdev) | |
31 | => extcon_dev_unregister(edev) | |
32 | : no change but type change (sdev->edev) | |
33 | - switch_get_state(sdev) | |
34 | => extcon_get_state(edev) | |
35 | : no change but type change (sdev->edev) and (return: int->u32) | |
36 | - switch_set_state(sdev, state) | |
37 | => extcon_set_state(edev, state) | |
38 | : no change but type change (sdev->edev) and (state: int->u32) | |
39 | ||
40 | With this changes, the ex-switch extcon class device works as it once | |
41 | worked as switch class device. However, it will now have additional | |
42 | interfaces (both ABI and in-kernel API) and different ABI locations. | |
43 | However, if CONFIG_ANDROID is enabled without CONFIG_ANDROID_SWITCH, | |
44 | /sys/class/switch/* will be symbolically linked to /sys/class/extcon/ | |
45 | so that they are still compatible with legacy userspace processes. | |
46 | ||
47 | ****** STEP 2. Multistate (no more magic numbers in state value) | |
48 | Extcon's extended features for switch device drivers with | |
49 | complex features usually required magic numbers in state | |
50 | value of switch_dev. With extcon, such magic numbers that | |
51 | support multiple cables ( | |
52 | ||
53 | 1. Define cable names at edev->supported_cable. | |
54 | 2. (Recommended) remove print_state callback. | |
55 | 3. Use extcon_get_cable_state_(edev, index) or | |
56 | extcon_get_cable_state(edev, cable_name) instead of | |
57 | extcon_get_state(edev) if you intend to get a state of a specific | |
58 | cable. Same for set_state. This way, you can remove the usage of | |
59 | magic numbers in state value. | |
60 | 4. Use extcon_update_state() if you are updating specific bits of | |
61 | the state value. | |
62 | ||
63 | Example: a switch device driver w/ magic numbers for two cables. | |
64 | "0x00": no cables connected. | |
65 | "0x01": cable 1 connected | |
66 | "0x02": cable 2 connected | |
67 | "0x03": cable 1 and 2 connected | |
68 | 1. edev->supported_cable = {"1", "2", NULL}; | |
69 | 2. edev->print_state = NULL; | |
70 | 3. extcon_get_cable_state_(edev, 0) shows cable 1's state. | |
71 | extcon_get_cable_state(edev, "1") shows cable 1's state. | |
72 | extcon_set_cable_state_(edev, 1) sets cable 2's state. | |
73 | extcon_set_cable_state(edev, "2") sets cable 2's state | |
74 | 4. extcon_update_state(edev, 0x01, 0) sets the least bit's 0. | |
75 | ||
76 | ****** STEP 3. Notify other device drivers | |
77 | ||
78 | You can notify others of the cable attach/detach events with | |
79 | notifier chains. | |
80 | ||
81 | At the side of other device drivers (the extcon device itself | |
82 | does not need to get notified of its own events), there are two | |
83 | methods to register notifier_block for cable events: | |
84 | (a) for a specific cable or (b) for every cable. | |
85 | ||
86 | (a) extcon_register_interest(obj, extcon_name, cable_name, nb) | |
87 | Example: want to get news of "MAX8997_MUIC"'s "USB" cable | |
88 | ||
89 | obj = kzalloc(sizeof(struct extcon_specific_cable_nb), | |
90 | GFP_KERNEL); | |
91 | nb->notifier_call = the_callback_to_handle_usb; | |
92 | ||
93 | extcon_register_intereset(obj, "MAX8997_MUIC", "USB", nb); | |
94 | ||
95 | (b) extcon_register_notifier(edev, nb) | |
96 | Call nb for any changes in edev. | |
97 | ||
98 | Please note that in order to properly behave with method (a), | |
99 | the extcon device driver should support multistate feature (STEP 2). | |
100 | ||
101 | ****** STEP 4. Inter-cable relation (mutually exclusive) | |
102 | ||
103 | You can provide inter-cable mutually exclusiveness information | |
104 | for an extcon device. When cables A and B are declared to be mutually | |
105 | exclusive, the two cables cannot be in ATTACHED state simulteneously. | |
106 | ||
107 | ||
108 | /***************************************************************** | |
109 | * CHAPTER 2. * | |
110 | * PORTING USERSPACE w/ SWITCH CLASS DEVICE SUPPORT * | |
111 | *****************************************************************/ | |
112 | ||
113 | ****** ABI Location | |
114 | ||
115 | If "CONFIG_ANDROID" is enabled and "CONFIG_ANDROID_SWITCH" is | |
116 | disabled, /sys/class/switch/* are created as symbolic links to | |
117 | /sys/class/extcon/*. Because CONFIG_ANDROID_SWITCH creates | |
118 | /sys/class/switch directory, we disable symboling linking if | |
119 | CONFIG_ANDROID_SWITCH is enabled. | |
120 | ||
121 | The two files of switch class, name and state, are provided with | |
122 | extcon, too. When the multistate support (STEP 2 of CHAPTER 1.) is | |
123 | not enabled or print_state callback is supplied, the output of | |
124 | state ABI is same with switch class. |