aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/extcon/porting-android-switch-class
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2012-05-22 16:02:13 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2012-05-22 16:02:13 -0700
commit5d4e2d08e7fdf7339f84a1c670d296a77e02f881 (patch)
tree1c419660defa56191091dfdf50fdb57a72009173 /Documentation/extcon/porting-android-switch-class
parentMerge tag 'char-misc-3.5-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc (diff)
parentuio_pdrv_genirq: get irq through platform resource if not set otherwise (diff)
downloadlinux-dev-5d4e2d08e7fdf7339f84a1c670d296a77e02f881.tar.xz
linux-dev-5d4e2d08e7fdf7339f84a1c670d296a77e02f881.zip
Merge tag 'driver-core-3.5-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core
Pull driver core updates from Greg Kroah-Hartman: "Here's the driver core, and other driver subsystems, pull request for the 3.5-rc1 merge window. Outside of a few minor driver core changes, we ended up with the following different subsystem and core changes as well, due to interdependancies on the driver core: - hyperv driver updates - drivers/memory being created and some drivers moved into it - extcon driver subsystem created out of the old Android staging switch driver code - dynamic debug updates - printk rework, and /dev/kmsg changes All of this has been tested in the linux-next releases for a few weeks with no reported problems. Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>" Fix up conflicts in drivers/extcon/extcon-max8997.c where git noticed that a patch to the deleted drivers/misc/max8997-muic.c driver needs to be applied to this one. * tag 'driver-core-3.5-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core: (90 commits) uio_pdrv_genirq: get irq through platform resource if not set otherwise memory: tegra{20,30}-mc: Remove empty *_remove() printk() - isolate KERN_CONT users from ordinary complete lines sysfs: get rid of some lockdep false positives Drivers: hv: util: Properly handle version negotiations. Drivers: hv: Get rid of an unnecessary check in vmbus_prep_negotiate_resp() memory: tegra{20,30}-mc: Use dev_err_ratelimited() driver core: Add dev_*_ratelimited() family Driver Core: don't oops with unregistered driver in driver_find_device() printk() - restore prefix/timestamp printing for multi-newline strings printk: add stub for prepend_timestamp() ARM: tegra30: Make MC optional in Kconfig ARM: tegra20: Make MC optional in Kconfig ARM: tegra30: MC: Remove unnecessary BUG*() ARM: tegra20: MC: Remove unnecessary BUG*() printk: correctly align __log_buf ARM: tegra30: Add Tegra Memory Controller(MC) driver ARM: tegra20: Add Tegra Memory Controller(MC) driver printk() - restore timestamp printing at console output printk() - do not merge continuation lines of different threads ...
Diffstat (limited to 'Documentation/extcon/porting-android-switch-class')
-rw-r--r--Documentation/extcon/porting-android-switch-class124
1 files changed, 124 insertions, 0 deletions
diff --git a/Documentation/extcon/porting-android-switch-class b/Documentation/extcon/porting-android-switch-class
new file mode 100644
index 000000000000..eb0fa5f4fe88
--- /dev/null
+++ b/Documentation/extcon/porting-android-switch-class
@@ -0,0 +1,124 @@
+
+ Staging/Android Switch Class Porting Guide
+ (linux/drivers/staging/android/switch)
+ (c) Copyright 2012 Samsung Electronics
+
+AUTHORS
+MyungJoo Ham <myungjoo.ham@samsung.com>
+
+/*****************************************************************
+ * CHAPTER 1. *
+ * PORTING SWITCH CLASS DEVICE DRIVERS *
+ *****************************************************************/
+
+****** STEP 1. Basic Functionality
+ No extcon extended feature, but switch features only.
+
+- struct switch_dev (fed to switch_dev_register/unregister)
+ @name: no change
+ @dev: no change
+ @index: drop (not used in switch device driver side anyway)
+ @state: no change
+ If you have used @state with magic numbers, keep it
+ at this step.
+ @print_name: no change but type change (switch_dev->extcon_dev)
+ @print_state: no change but type change (switch_dev->extcon_dev)
+
+- switch_dev_register(sdev, dev)
+ => extcon_dev_register(edev, dev)
+ : no change but type change (sdev->edev)
+- switch_dev_unregister(sdev)
+ => extcon_dev_unregister(edev)
+ : no change but type change (sdev->edev)
+- switch_get_state(sdev)
+ => extcon_get_state(edev)
+ : no change but type change (sdev->edev) and (return: int->u32)
+- switch_set_state(sdev, state)
+ => extcon_set_state(edev, state)
+ : no change but type change (sdev->edev) and (state: int->u32)
+
+With this changes, the ex-switch extcon class device works as it once
+worked as switch class device. However, it will now have additional
+interfaces (both ABI and in-kernel API) and different ABI locations.
+However, if CONFIG_ANDROID is enabled without CONFIG_ANDROID_SWITCH,
+/sys/class/switch/* will be symbolically linked to /sys/class/extcon/
+so that they are still compatible with legacy userspace processes.
+
+****** STEP 2. Multistate (no more magic numbers in state value)
+ Extcon's extended features for switch device drivers with
+ complex features usually required magic numbers in state
+ value of switch_dev. With extcon, such magic numbers that
+ support multiple cables (
+
+ 1. Define cable names at edev->supported_cable.
+ 2. (Recommended) remove print_state callback.
+ 3. Use extcon_get_cable_state_(edev, index) or
+ extcon_get_cable_state(edev, cable_name) instead of
+ extcon_get_state(edev) if you intend to get a state of a specific
+ cable. Same for set_state. This way, you can remove the usage of
+ magic numbers in state value.
+ 4. Use extcon_update_state() if you are updating specific bits of
+ the state value.
+
+Example: a switch device driver w/ magic numbers for two cables.
+ "0x00": no cables connected.
+ "0x01": cable 1 connected
+ "0x02": cable 2 connected
+ "0x03": cable 1 and 2 connected
+ 1. edev->supported_cable = {"1", "2", NULL};
+ 2. edev->print_state = NULL;
+ 3. extcon_get_cable_state_(edev, 0) shows cable 1's state.
+ extcon_get_cable_state(edev, "1") shows cable 1's state.
+ extcon_set_cable_state_(edev, 1) sets cable 2's state.
+ extcon_set_cable_state(edev, "2") sets cable 2's state
+ 4. extcon_update_state(edev, 0x01, 0) sets the least bit's 0.
+
+****** STEP 3. Notify other device drivers
+
+ You can notify others of the cable attach/detach events with
+notifier chains.
+
+ At the side of other device drivers (the extcon device itself
+does not need to get notified of its own events), there are two
+methods to register notifier_block for cable events:
+(a) for a specific cable or (b) for every cable.
+
+ (a) extcon_register_interest(obj, extcon_name, cable_name, nb)
+ Example: want to get news of "MAX8997_MUIC"'s "USB" cable
+
+ obj = kzalloc(sizeof(struct extcon_specific_cable_nb),
+ GFP_KERNEL);
+ nb->notifier_call = the_callback_to_handle_usb;
+
+ extcon_register_intereset(obj, "MAX8997_MUIC", "USB", nb);
+
+ (b) extcon_register_notifier(edev, nb)
+ Call nb for any changes in edev.
+
+ Please note that in order to properly behave with method (a),
+the extcon device driver should support multistate feature (STEP 2).
+
+****** STEP 4. Inter-cable relation (mutually exclusive)
+
+ You can provide inter-cable mutually exclusiveness information
+for an extcon device. When cables A and B are declared to be mutually
+exclusive, the two cables cannot be in ATTACHED state simulteneously.
+
+
+/*****************************************************************
+ * CHAPTER 2. *
+ * PORTING USERSPACE w/ SWITCH CLASS DEVICE SUPPORT *
+ *****************************************************************/
+
+****** ABI Location
+
+ If "CONFIG_ANDROID" is enabled and "CONFIG_ANDROID_SWITCH" is
+disabled, /sys/class/switch/* are created as symbolic links to
+/sys/class/extcon/*. Because CONFIG_ANDROID_SWITCH creates
+/sys/class/switch directory, we disable symboling linking if
+CONFIG_ANDROID_SWITCH is enabled.
+
+ The two files of switch class, name and state, are provided with
+extcon, too. When the multistate support (STEP 2 of CHAPTER 1.) is
+not enabled or print_state callback is supplied, the output of
+state ABI is same with switch class.