Documentation / extcon / porting-android-switch-class
Custom Search
Based on kernel version 3.9. Page generated on 2013-05-02 23:05 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, 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.
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.