About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / extcon / porting-android-switch-class




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:39 EST.

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)
29		: type change (sdev->edev)
30		: remove second param('dev'). if edev has parent device, should store
31		  'dev' to 'edev.dev.parent' before registering extcon device
32	- switch_dev_unregister(sdev)
33		=> extcon_dev_unregister(edev)
34		: no change but type change (sdev->edev)
35	- switch_get_state(sdev)
36		=> extcon_get_state(edev)
37		: no change but type change (sdev->edev) and (return: int->u32)
38	- switch_set_state(sdev, state)
39		=> extcon_set_state(edev, state)
40		: no change but type change (sdev->edev) and (state: int->u32)
41	
42	With this changes, the ex-switch extcon class device works as it once
43	worked as switch class device. However, it will now have additional
44	interfaces (both ABI and in-kernel API) and different ABI locations.
45	However, if CONFIG_ANDROID is enabled without CONFIG_ANDROID_SWITCH,
46	/sys/class/switch/* will be symbolically linked to /sys/class/extcon/
47	so that they are still compatible with legacy userspace processes.
48	
49	****** STEP 2. Multistate (no more magic numbers in state value)
50		Extcon's extended features for switch device drivers with
51		complex features usually required magic numbers in state
52		value of switch_dev. With extcon, such magic numbers that
53		support multiple cables are no more required or supported.
54	
55	  1. Define cable names at edev->supported_cable.
56	  2. (Recommended) remove print_state callback.
57	  3. Use extcon_get_cable_state_(edev, index) or
58	   extcon_get_cable_state(edev, cable_name) instead of
59	   extcon_get_state(edev) if you intend to get a state of a specific
60	   cable. Same for set_state. This way, you can remove the usage of
61	   magic numbers in state value.
62	  4. Use extcon_update_state() if you are updating specific bits of
63	   the state value.
64	
65	Example: a switch device driver w/ magic numbers for two cables.
66		"0x00": no cables connected.
67		"0x01": cable 1 connected
68		"0x02": cable 2 connected
69		"0x03": cable 1 and 2 connected
70	  1. edev->supported_cable = {"1", "2", NULL};
71	  2. edev->print_state = NULL;
72	  3. extcon_get_cable_state_(edev, 0) shows cable 1's state.
73	     extcon_get_cable_state(edev, "1") shows cable 1's state.
74	     extcon_set_cable_state_(edev, 1) sets cable 2's state.
75	     extcon_set_cable_state(edev, "2") sets cable 2's state
76	  4. extcon_update_state(edev, 0x01, 0) sets the least bit's 0.
77	
78	****** STEP 3. Notify other device drivers
79	
80	  You can notify others of the cable attach/detach events with
81	notifier chains.
82	
83	  At the side of other device drivers (the extcon device itself
84	does not need to get notified of its own events), there are two
85	methods to register notifier_block for cable events:
86	(a) for a specific cable or (b) for every cable.
87	
88	  (a) extcon_register_interest(obj, extcon_name, cable_name, nb)
89		Example: want to get news of "MAX8997_MUIC"'s "USB" cable
90	
91		obj = kzalloc(sizeof(struct extcon_specific_cable_nb),
92			      GFP_KERNEL);
93		nb->notifier_call = the_callback_to_handle_usb;
94	
95		extcon_register_intereset(obj, "MAX8997_MUIC", "USB", nb);
96	
97	  (b) extcon_register_notifier(edev, nb)
98		Call nb for any changes in edev.
99	
100	  Please note that in order to properly behave with method (a),
101	the extcon device driver should support multistate feature (STEP 2).
102	
103	****** STEP 4. Inter-cable relation (mutually exclusive)
104	
105	  You can provide inter-cable mutually exclusiveness information
106	for an extcon device. When cables A and B are declared to be mutually
107	exclusive, the two cables cannot be in ATTACHED state simulteneously.
108	
109	
110	/*****************************************************************
111	 * CHAPTER 2.                                                    *
112	 * PORTING USERSPACE w/ SWITCH CLASS DEVICE SUPPORT              *
113	 *****************************************************************/
114	
115	****** ABI Location
116	
117	  If "CONFIG_ANDROID" is enabled, /sys/class/switch/* are created
118	as symbolic links to /sys/class/extcon/*.
119	
120	  The two files of switch class, name and state, are provided with
121	extcon, too. When the multistate support (STEP 2 of CHAPTER 1.) is
122	not enabled or print_state callback is supplied, the output of
123	state ABI is same with switch class.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.