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)
  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 (
  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 and "CONFIG_ANDROID_SWITCH" is
 118 disabled, /sys/class/switch/* are created as symbolic links to
 119 /sys/class/extcon/*. Because CONFIG_ANDROID_SWITCH creates
 120 /sys/class/switch directory, we disable symboling linking if
 121 CONFIG_ANDROID_SWITCH is enabled.
 122
 123   The two files of switch class, name and state, are provided with
 124 extcon, too. When the multistate support (STEP 2 of CHAPTER 1.) is
 125 not enabled or print_state callback is supplied, the output of
 126 state ABI is same with switch class.