1
  2	Staging/Android Switch Class Porting Guide
  3	(linux/drivers/staging/android/switch)
  4	(c) Copyright 2012 Samsung Electronics
  5
  6AUTHORS
  7MyungJoo 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
 40With this changes, the ex-switch extcon class device works as it once
 41worked as switch class device. However, it will now have additional
 42interfaces (both ABI and in-kernel API) and different ABI locations.
 43However, if CONFIG_ANDROID is enabled without CONFIG_ANDROID_SWITCH,
 44/sys/class/switch/* will be symbolically linked to /sys/class/extcon/
 45so 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
 63Example: 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
 79notifier chains.
 80
 81  At the side of other device drivers (the extcon device itself
 82does not need to get notified of its own events), there are two
 83methods 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),
 99the 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
104for an extcon device. When cables A and B are declared to be mutually
105exclusive, 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
116disabled, /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
119CONFIG_ANDROID_SWITCH is enabled.
120
121  The two files of switch class, name and state, are provided with
122extcon, too. When the multistate support (STEP 2 of CHAPTER 1.) is
123not enabled or print_state callback is supplied, the output of
124state ABI is same with switch class.