tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation/extcon: porting guide for Android kernel switch driver.
Signed-off-by: MyungJoo Ham <myungjoo.ham@samsung.com>
Signed-off-by: Kyungmin Park <kyungmin.park@samsung.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
authored by
MyungJoo Ham
and committed by
Greg Kroah-Hartman
3e971dbc
bde68e60
+124
+124
Documentation/extcon/porting-android-switch-class
+124
Documentation/extcon/porting-android-switch-class
···
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.