summaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2009-04-07 08:53:38 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2009-04-07 08:53:38 -0700
commit81d91acf8c093565f65383ae0349b9255fbb2d0d (patch)
tree4e72f779a88ab87b76afb3fb16adf053e7044071 /Documentation
parent132ea5e9aa9ce13f62ba45db8e43ec887d1106e9 (diff)
parent0dd7b0cbb2e426553f184f5aeba40a2203f33700 (diff)
downloadlinux-81d91acf8c093565f65383ae0349b9255fbb2d0d.tar.gz
linux-81d91acf8c093565f65383ae0349b9255fbb2d0d.tar.bz2
linux-81d91acf8c093565f65383ae0349b9255fbb2d0d.zip
Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound-2.6
* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound-2.6: (36 commits) ALSA: hda - Add VREF powerdown sequence for another board ALSA: oss - volume control for CSWITCH and CROUTE ALSA: hda - add missing comma in ad1884_slave_vols sound: usb-audio: allow period sizes less than 1 ms sound: usb-audio: save data packet interval in audioformat structure sound: usb-audio: remove check_hw_params_convention() sound: usb-audio: show sample format width in proc file ASoC: fsl_dma: Pass the proper device for dma mapping routines ASoC: Fix null dereference in ak4535_remove() ALSA: hda - enable SPDIF output for Intel DX58SO board ALSA: snd-atmel-abdac: increase periods_min to 6 instead of 4 ALSA: snd-atmel-abdac: replace bus_id with dev_name() ALSA: snd-atmel-ac97c: replace bus_id with dev_name() ALSA: snd-atmel-ac97c: cleanup registers when removing driver ALSA: snd-atmel-ac97c: do a proper reset of the external codec ALSA: snd-atmel-ac97c: enable interrupts to catch events for error reporting ALSA: snd-atmel-ac97c: set correct size for buffer hardware parameter ALSA: snd-atmel-ac97c: do not overwrite OCA and ICA when assigning channels ALSA: snd-atmel-ac97c: remove dead break statements after return in switch case ALSA: snd-atmel-ac97c: cleanup register definitions ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/sound/alsa/soc/jack.txt71
1 files changed, 71 insertions, 0 deletions
diff --git a/Documentation/sound/alsa/soc/jack.txt b/Documentation/sound/alsa/soc/jack.txt
new file mode 100644
index 000000000000..fcf82a417293
--- /dev/null
+++ b/Documentation/sound/alsa/soc/jack.txt
@@ -0,0 +1,71 @@
+ASoC jack detection
+===================
+
+ALSA has a standard API for representing physical jacks to user space,
+the kernel side of which can be seen in include/sound/jack.h. ASoC
+provides a version of this API adding two additional features:
+
+ - It allows more than one jack detection method to work together on one
+ user visible jack. In embedded systems it is common for multiple
+ to be present on a single jack but handled by separate bits of
+ hardware.
+
+ - Integration with DAPM, allowing DAPM endpoints to be updated
+ automatically based on the detected jack status (eg, turning off the
+ headphone outputs if no headphones are present).
+
+This is done by splitting the jacks up into three things working
+together: the jack itself represented by a struct snd_soc_jack, sets of
+snd_soc_jack_pins representing DAPM endpoints to update and blocks of
+code providing jack reporting mechanisms.
+
+For example, a system may have a stereo headset jack with two reporting
+mechanisms, one for the headphone and one for the microphone. Some
+systems won't be able to use their speaker output while a headphone is
+connected and so will want to make sure to update both speaker and
+headphone when the headphone jack status changes.
+
+The jack - struct snd_soc_jack
+==============================
+
+This represents a physical jack on the system and is what is visible to
+user space. The jack itself is completely passive, it is set up by the
+machine driver and updated by jack detection methods.
+
+Jacks are created by the machine driver calling snd_soc_jack_new().
+
+snd_soc_jack_pin
+================
+
+These represent a DAPM pin to update depending on some of the status
+bits supported by the jack. Each snd_soc_jack has zero or more of these
+which are updated automatically. They are created by the machine driver
+and associated with the jack using snd_soc_jack_add_pins(). The status
+of the endpoint may configured to be the opposite of the jack status if
+required (eg, enabling a built in microphone if a microphone is not
+connected via a jack).
+
+Jack detection methods
+======================
+
+Actual jack detection is done by code which is able to monitor some
+input to the system and update a jack by calling snd_soc_jack_report(),
+specifying a subset of bits to update. The jack detection code should
+be set up by the machine driver, taking configuration for the jack to
+update and the set of things to report when the jack is connected.
+
+Often this is done based on the status of a GPIO - a handler for this is
+provided by the snd_soc_jack_add_gpio() function. Other methods are
+also available, for example integrated into CODECs. One example of
+CODEC integrated jack detection can be see in the WM8350 driver.
+
+Each jack may have multiple reporting mechanisms, though it will need at
+least one to be useful.
+
+Machine drivers
+===============
+
+These are all hooked together by the machine driver depending on the
+system hardware. The machine driver will set up the snd_soc_jack and
+the list of pins to update then set up one or more jack detection
+mechanisms to update that jack based on their current status.