summaryrefslogtreecommitdiffstats
path: root/Documentation/sound/designs
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/sound/designs')
-rw-r--r--Documentation/sound/designs/channel-mapping-api.rst164
-rw-r--r--Documentation/sound/designs/compress-offload.rst329
-rw-r--r--Documentation/sound/designs/control-names.rst142
-rw-r--r--Documentation/sound/designs/index.rst18
-rw-r--r--Documentation/sound/designs/jack-controls.rst48
-rw-r--r--Documentation/sound/designs/jack-injection.rst166
-rw-r--r--Documentation/sound/designs/midi-2.0.rst566
-rw-r--r--Documentation/sound/designs/oss-emulation.rst336
-rw-r--r--Documentation/sound/designs/powersave.rst43
-rw-r--r--Documentation/sound/designs/procfile.rst238
-rw-r--r--Documentation/sound/designs/seq-oss.rst371
-rw-r--r--Documentation/sound/designs/timestamping.rst215
-rw-r--r--Documentation/sound/designs/tracepoints.rst172
13 files changed, 2808 insertions, 0 deletions
diff --git a/Documentation/sound/designs/channel-mapping-api.rst b/Documentation/sound/designs/channel-mapping-api.rst
new file mode 100644
index 0000000000..58e6312a43
--- /dev/null
+++ b/Documentation/sound/designs/channel-mapping-api.rst
@@ -0,0 +1,164 @@
+============================
+ALSA PCM channel-mapping API
+============================
+
+Takashi Iwai <tiwai@suse.de>
+
+General
+=======
+
+The channel mapping API allows user to query the possible channel maps
+and the current channel map, also optionally to modify the channel map
+of the current stream.
+
+A channel map is an array of position for each PCM channel.
+Typically, a stereo PCM stream has a channel map of
+``{ front_left, front_right }``
+while a 4.0 surround PCM stream has a channel map of
+``{ front left, front right, rear left, rear right }.``
+
+The problem, so far, was that we had no standard channel map
+explicitly, and applications had no way to know which channel
+corresponds to which (speaker) position. Thus, applications applied
+wrong channels for 5.1 outputs, and you hear suddenly strange sound
+from rear. Or, some devices secretly assume that center/LFE is the
+third/fourth channels while others that C/LFE as 5th/6th channels.
+
+Also, some devices such as HDMI are configurable for different speaker
+positions even with the same number of total channels. However, there
+was no way to specify this because of lack of channel map
+specification. These are the main motivations for the new channel
+mapping API.
+
+
+Design
+======
+
+Actually, "the channel mapping API" doesn't introduce anything new in
+the kernel/user-space ABI perspective. It uses only the existing
+control element features.
+
+As a ground design, each PCM substream may contain a control element
+providing the channel mapping information and configuration. This
+element is specified by:
+
+* iface = SNDRV_CTL_ELEM_IFACE_PCM
+* name = "Playback Channel Map" or "Capture Channel Map"
+* device = the same device number for the assigned PCM substream
+* index = the same index number for the assigned PCM substream
+
+Note the name is different depending on the PCM substream direction.
+
+Each control element provides at least the TLV read operation and the
+read operation. Optionally, the write operation can be provided to
+allow user to change the channel map dynamically.
+
+TLV
+---
+
+The TLV operation gives the list of available channel
+maps. A list item of a channel map is usually a TLV of
+``type data-bytes ch0 ch1 ch2...``
+where type is the TLV type value, the second argument is the total
+bytes (not the numbers) of channel values, and the rest are the
+position value for each channel.
+
+As a TLV type, either ``SNDRV_CTL_TLVT_CHMAP_FIXED``,
+``SNDRV_CTL_TLV_CHMAP_VAR`` or ``SNDRV_CTL_TLVT_CHMAP_PAIRED`` can be used.
+The ``_FIXED`` type is for a channel map with the fixed channel position
+while the latter two are for flexible channel positions. ``_VAR`` type is
+for a channel map where all channels are freely swappable and ``_PAIRED``
+type is where pair-wise channels are swappable. For example, when you
+have {FL/FR/RL/RR} channel map, ``_PAIRED`` type would allow you to swap
+only {RL/RR/FL/FR} while ``_VAR`` type would allow even swapping FL and
+RR.
+
+These new TLV types are defined in ``sound/tlv.h``.
+
+The available channel position values are defined in ``sound/asound.h``,
+here is a cut:
+
+::
+
+ /* channel positions */
+ enum {
+ SNDRV_CHMAP_UNKNOWN = 0,
+ SNDRV_CHMAP_NA, /* N/A, silent */
+ SNDRV_CHMAP_MONO, /* mono stream */
+ /* this follows the alsa-lib mixer channel value + 3 */
+ SNDRV_CHMAP_FL, /* front left */
+ SNDRV_CHMAP_FR, /* front right */
+ SNDRV_CHMAP_RL, /* rear left */
+ SNDRV_CHMAP_RR, /* rear right */
+ SNDRV_CHMAP_FC, /* front center */
+ SNDRV_CHMAP_LFE, /* LFE */
+ SNDRV_CHMAP_SL, /* side left */
+ SNDRV_CHMAP_SR, /* side right */
+ SNDRV_CHMAP_RC, /* rear center */
+ /* new definitions */
+ SNDRV_CHMAP_FLC, /* front left center */
+ SNDRV_CHMAP_FRC, /* front right center */
+ SNDRV_CHMAP_RLC, /* rear left center */
+ SNDRV_CHMAP_RRC, /* rear right center */
+ SNDRV_CHMAP_FLW, /* front left wide */
+ SNDRV_CHMAP_FRW, /* front right wide */
+ SNDRV_CHMAP_FLH, /* front left high */
+ SNDRV_CHMAP_FCH, /* front center high */
+ SNDRV_CHMAP_FRH, /* front right high */
+ SNDRV_CHMAP_TC, /* top center */
+ SNDRV_CHMAP_TFL, /* top front left */
+ SNDRV_CHMAP_TFR, /* top front right */
+ SNDRV_CHMAP_TFC, /* top front center */
+ SNDRV_CHMAP_TRL, /* top rear left */
+ SNDRV_CHMAP_TRR, /* top rear right */
+ SNDRV_CHMAP_TRC, /* top rear center */
+ SNDRV_CHMAP_LAST = SNDRV_CHMAP_TRC,
+ };
+
+When a PCM stream can provide more than one channel map, you can
+provide multiple channel maps in a TLV container type. The TLV data
+to be returned will contain such as:
+::
+
+ SNDRV_CTL_TLVT_CONTAINER 96
+ SNDRV_CTL_TLVT_CHMAP_FIXED 4 SNDRV_CHMAP_FC
+ SNDRV_CTL_TLVT_CHMAP_FIXED 8 SNDRV_CHMAP_FL SNDRV_CHMAP_FR
+ SNDRV_CTL_TLVT_CHMAP_FIXED 16 NDRV_CHMAP_FL SNDRV_CHMAP_FR \
+ SNDRV_CHMAP_RL SNDRV_CHMAP_RR
+
+The channel position is provided in LSB 16bits. The upper bits are
+used for bit flags.
+::
+
+ #define SNDRV_CHMAP_POSITION_MASK 0xffff
+ #define SNDRV_CHMAP_PHASE_INVERSE (0x01 << 16)
+ #define SNDRV_CHMAP_DRIVER_SPEC (0x02 << 16)
+
+``SNDRV_CHMAP_PHASE_INVERSE`` indicates the channel is phase inverted,
+(thus summing left and right channels would result in almost silence).
+Some digital mic devices have this.
+
+When ``SNDRV_CHMAP_DRIVER_SPEC`` is set, all the channel position values
+don't follow the standard definition above but driver-specific.
+
+Read Operation
+--------------
+
+The control read operation is for providing the current channel map of
+the given stream. The control element returns an integer array
+containing the position of each channel.
+
+When this is performed before the number of the channel is specified
+(i.e. hw_params is set), it should return all channels set to
+``UNKNOWN``.
+
+Write Operation
+---------------
+
+The control write operation is optional, and only for devices that can
+change the channel configuration on the fly, such as HDMI. User needs
+to pass an integer value containing the valid channel positions for
+all channels of the assigned PCM substream.
+
+This operation is allowed only at PCM PREPARED state. When called in
+other states, it shall return an error.
diff --git a/Documentation/sound/designs/compress-offload.rst b/Documentation/sound/designs/compress-offload.rst
new file mode 100644
index 0000000000..655624f770
--- /dev/null
+++ b/Documentation/sound/designs/compress-offload.rst
@@ -0,0 +1,329 @@
+=========================
+ALSA Compress-Offload API
+=========================
+
+Pierre-Louis.Bossart <pierre-louis.bossart@linux.intel.com>
+
+Vinod Koul <vinod.koul@linux.intel.com>
+
+
+Overview
+========
+Since its early days, the ALSA API was defined with PCM support or
+constant bitrates payloads such as IEC61937 in mind. Arguments and
+returned values in frames are the norm, making it a challenge to
+extend the existing API to compressed data streams.
+
+In recent years, audio digital signal processors (DSP) were integrated
+in system-on-chip designs, and DSPs are also integrated in audio
+codecs. Processing compressed data on such DSPs results in a dramatic
+reduction of power consumption compared to host-based
+processing. Support for such hardware has not been very good in Linux,
+mostly because of a lack of a generic API available in the mainline
+kernel.
+
+Rather than requiring a compatibility break with an API change of the
+ALSA PCM interface, a new 'Compressed Data' API is introduced to
+provide a control and data-streaming interface for audio DSPs.
+
+The design of this API was inspired by the 2-year experience with the
+Intel Moorestown SOC, with many corrections required to upstream the
+API in the mainline kernel instead of the staging tree and make it
+usable by others.
+
+
+Requirements
+============
+The main requirements are:
+
+- separation between byte counts and time. Compressed formats may have
+ a header per file, per frame, or no header at all. The payload size
+ may vary from frame-to-frame. As a result, it is not possible to
+ estimate reliably the duration of audio buffers when handling
+ compressed data. Dedicated mechanisms are required to allow for
+ reliable audio-video synchronization, which requires precise
+ reporting of the number of samples rendered at any given time.
+
+- Handling of multiple formats. PCM data only requires a specification
+ of the sampling rate, number of channels and bits per sample. In
+ contrast, compressed data comes in a variety of formats. Audio DSPs
+ may also provide support for a limited number of audio encoders and
+ decoders embedded in firmware, or may support more choices through
+ dynamic download of libraries.
+
+- Focus on main formats. This API provides support for the most
+ popular formats used for audio and video capture and playback. It is
+ likely that as audio compression technology advances, new formats
+ will be added.
+
+- Handling of multiple configurations. Even for a given format like
+ AAC, some implementations may support AAC multichannel but HE-AAC
+ stereo. Likewise WMA10 level M3 may require too much memory and cpu
+ cycles. The new API needs to provide a generic way of listing these
+ formats.
+
+- Rendering/Grabbing only. This API does not provide any means of
+ hardware acceleration, where PCM samples are provided back to
+ user-space for additional processing. This API focuses instead on
+ streaming compressed data to a DSP, with the assumption that the
+ decoded samples are routed to a physical output or logical back-end.
+
+- Complexity hiding. Existing user-space multimedia frameworks all
+ have existing enums/structures for each compressed format. This new
+ API assumes the existence of a platform-specific compatibility layer
+ to expose, translate and make use of the capabilities of the audio
+ DSP, eg. Android HAL or PulseAudio sinks. By construction, regular
+ applications are not supposed to make use of this API.
+
+
+Design
+======
+The new API shares a number of concepts with the PCM API for flow
+control. Start, pause, resume, drain and stop commands have the same
+semantics no matter what the content is.
+
+The concept of memory ring buffer divided in a set of fragments is
+borrowed from the ALSA PCM API. However, only sizes in bytes can be
+specified.
+
+Seeks/trick modes are assumed to be handled by the host.
+
+The notion of rewinds/forwards is not supported. Data committed to the
+ring buffer cannot be invalidated, except when dropping all buffers.
+
+The Compressed Data API does not make any assumptions on how the data
+is transmitted to the audio DSP. DMA transfers from main memory to an
+embedded audio cluster or to a SPI interface for external DSPs are
+possible. As in the ALSA PCM case, a core set of routines is exposed;
+each driver implementer will have to write support for a set of
+mandatory routines and possibly make use of optional ones.
+
+The main additions are
+
+get_caps
+ This routine returns the list of audio formats supported. Querying the
+ codecs on a capture stream will return encoders, decoders will be
+ listed for playback streams.
+
+get_codec_caps
+ For each codec, this routine returns a list of
+ capabilities. The intent is to make sure all the capabilities
+ correspond to valid settings, and to minimize the risks of
+ configuration failures. For example, for a complex codec such as AAC,
+ the number of channels supported may depend on a specific profile. If
+ the capabilities were exposed with a single descriptor, it may happen
+ that a specific combination of profiles/channels/formats may not be
+ supported. Likewise, embedded DSPs have limited memory and cpu cycles,
+ it is likely that some implementations make the list of capabilities
+ dynamic and dependent on existing workloads. In addition to codec
+ settings, this routine returns the minimum buffer size handled by the
+ implementation. This information can be a function of the DMA buffer
+ sizes, the number of bytes required to synchronize, etc, and can be
+ used by userspace to define how much needs to be written in the ring
+ buffer before playback can start.
+
+set_params
+ This routine sets the configuration chosen for a specific codec. The
+ most important field in the parameters is the codec type; in most
+ cases decoders will ignore other fields, while encoders will strictly
+ comply to the settings
+
+get_params
+ This routines returns the actual settings used by the DSP. Changes to
+ the settings should remain the exception.
+
+get_timestamp
+ The timestamp becomes a multiple field structure. It lists the number
+ of bytes transferred, the number of samples processed and the number
+ of samples rendered/grabbed. All these values can be used to determine
+ the average bitrate, figure out if the ring buffer needs to be
+ refilled or the delay due to decoding/encoding/io on the DSP.
+
+Note that the list of codecs/profiles/modes was derived from the
+OpenMAX AL specification instead of reinventing the wheel.
+Modifications include:
+- Addition of FLAC and IEC formats
+- Merge of encoder/decoder capabilities
+- Profiles/modes listed as bitmasks to make descriptors more compact
+- Addition of set_params for decoders (missing in OpenMAX AL)
+- Addition of AMR/AMR-WB encoding modes (missing in OpenMAX AL)
+- Addition of format information for WMA
+- Addition of encoding options when required (derived from OpenMAX IL)
+- Addition of rateControlSupported (missing in OpenMAX AL)
+
+State Machine
+=============
+
+The compressed audio stream state machine is described below ::
+
+ +----------+
+ | |
+ | OPEN |
+ | |
+ +----------+
+ |
+ |
+ | compr_set_params()
+ |
+ v
+ compr_free() +----------+
+ +------------------------------------| |
+ | | SETUP |
+ | +-------------------------| |<-------------------------+
+ | | compr_write() +----------+ |
+ | | ^ |
+ | | | compr_drain_notify() |
+ | | | or |
+ | | | compr_stop() |
+ | | | |
+ | | +----------+ |
+ | | | | |
+ | | | DRAIN | |
+ | | | | |
+ | | +----------+ |
+ | | ^ |
+ | | | |
+ | | | compr_drain() |
+ | | | |
+ | v | |
+ | +----------+ +----------+ |
+ | | | compr_start() | | compr_stop() |
+ | | PREPARE |------------------->| RUNNING |--------------------------+
+ | | | | | |
+ | +----------+ +----------+ |
+ | | | ^ |
+ | |compr_free() | | |
+ | | compr_pause() | | compr_resume() |
+ | | | | |
+ | v v | |
+ | +----------+ +----------+ |
+ | | | | | compr_stop() |
+ +--->| FREE | | PAUSE |---------------------------+
+ | | | |
+ +----------+ +----------+
+
+
+Gapless Playback
+================
+When playing thru an album, the decoders have the ability to skip the encoder
+delay and padding and directly move from one track content to another. The end
+user can perceive this as gapless playback as we don't have silence while
+switching from one track to another
+
+Also, there might be low-intensity noises due to encoding. Perfect gapless is
+difficult to reach with all types of compressed data, but works fine with most
+music content. The decoder needs to know the encoder delay and encoder padding.
+So we need to pass this to DSP. This metadata is extracted from ID3/MP4 headers
+and are not present by default in the bitstream, hence the need for a new
+interface to pass this information to the DSP. Also DSP and userspace needs to
+switch from one track to another and start using data for second track.
+
+The main additions are:
+
+set_metadata
+ This routine sets the encoder delay and encoder padding. This can be used by
+ decoder to strip the silence. This needs to be set before the data in the track
+ is written.
+
+set_next_track
+ This routine tells DSP that metadata and write operation sent after this would
+ correspond to subsequent track
+
+partial drain
+ This is called when end of file is reached. The userspace can inform DSP that
+ EOF is reached and now DSP can start skipping padding delay. Also next write
+ data would belong to next track
+
+Sequence flow for gapless would be:
+- Open
+- Get caps / codec caps
+- Set params
+- Set metadata of the first track
+- Fill data of the first track
+- Trigger start
+- User-space finished sending all,
+- Indicate next track data by sending set_next_track
+- Set metadata of the next track
+- then call partial_drain to flush most of buffer in DSP
+- Fill data of the next track
+- DSP switches to second track
+
+(note: order for partial_drain and write for next track can be reversed as well)
+
+Gapless Playback SM
+===================
+
+For Gapless, we move from running state to partial drain and back, along
+with setting of meta_data and signalling for next track ::
+
+
+ +----------+
+ compr_drain_notify() | |
+ +------------------------>| RUNNING |
+ | | |
+ | +----------+
+ | |
+ | |
+ | | compr_next_track()
+ | |
+ | V
+ | +----------+
+ | compr_set_params() | |
+ | +-----------|NEXT_TRACK|
+ | | | |
+ | | +--+-------+
+ | | | |
+ | +--------------+ |
+ | |
+ | | compr_partial_drain()
+ | |
+ | V
+ | +----------+
+ | | |
+ +------------------------ | PARTIAL_ |
+ | DRAIN |
+ +----------+
+
+Not supported
+=============
+- Support for VoIP/circuit-switched calls is not the target of this
+ API. Support for dynamic bit-rate changes would require a tight
+ coupling between the DSP and the host stack, limiting power savings.
+
+- Packet-loss concealment is not supported. This would require an
+ additional interface to let the decoder synthesize data when frames
+ are lost during transmission. This may be added in the future.
+
+- Volume control/routing is not handled by this API. Devices exposing a
+ compressed data interface will be considered as regular ALSA devices;
+ volume changes and routing information will be provided with regular
+ ALSA kcontrols.
+
+- Embedded audio effects. Such effects should be enabled in the same
+ manner, no matter if the input was PCM or compressed.
+
+- multichannel IEC encoding. Unclear if this is required.
+
+- Encoding/decoding acceleration is not supported as mentioned
+ above. It is possible to route the output of a decoder to a capture
+ stream, or even implement transcoding capabilities. This routing
+ would be enabled with ALSA kcontrols.
+
+- Audio policy/resource management. This API does not provide any
+ hooks to query the utilization of the audio DSP, nor any preemption
+ mechanisms.
+
+- No notion of underrun/overrun. Since the bytes written are compressed
+ in nature and data written/read doesn't translate directly to
+ rendered output in time, this does not deal with underrun/overrun and
+ maybe dealt in user-library
+
+
+Credits
+=======
+- Mark Brown and Liam Girdwood for discussions on the need for this API
+- Harsha Priya for her work on intel_sst compressed API
+- Rakesh Ughreja for valuable feedback
+- Sing Nallasellan, Sikkandar Madar and Prasanna Samaga for
+ demonstrating and quantifying the benefits of audio offload on a
+ real platform.
diff --git a/Documentation/sound/designs/control-names.rst b/Documentation/sound/designs/control-names.rst
new file mode 100644
index 0000000000..765ff9b5b7
--- /dev/null
+++ b/Documentation/sound/designs/control-names.rst
@@ -0,0 +1,142 @@
+===========================
+Standard ALSA Control Names
+===========================
+
+This document describes standard names of mixer controls.
+
+Standard Syntax
+---------------
+Syntax: [LOCATION] SOURCE [CHANNEL] [DIRECTION] FUNCTION
+
+
+DIRECTION
+~~~~~~~~~
+================ ===============
+<nothing> both directions
+Playback one direction
+Capture one direction
+Bypass Playback one direction
+Bypass Capture one direction
+================ ===============
+
+FUNCTION
+~~~~~~~~
+======== =================================
+Switch on/off switch
+Volume amplifier
+Route route control, hardware specific
+======== =================================
+
+CHANNEL
+~~~~~~~
+============ ==================================================
+<nothing> channel independent, or applies to all channels
+Front front left/right channels
+Surround rear left/right in 4.0/5.1 surround
+CLFE C/LFE channels
+Center center channel
+LFE LFE channel
+Side side left/right for 7.1 surround
+============ ==================================================
+
+LOCATION (Physical location of source)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============ =====================
+Front front position
+Rear rear position
+Dock on docking station
+Internal internal
+============ =====================
+
+SOURCE
+~~~~~~
+=================== =================================================
+Master
+Master Mono
+Hardware Master
+Speaker internal speaker
+Bass Speaker internal LFE speaker
+Headphone
+Line Out
+Beep beep generator
+Phone
+Phone Input
+Phone Output
+Synth
+FM
+Mic
+Headset Mic mic part of combined headset jack - 4-pin
+ headphone + mic
+Headphone Mic mic part of either/or - 3-pin headphone or mic
+Line input only, use "Line Out" for output
+CD
+Video
+Zoom Video
+Aux
+PCM
+PCM Pan
+Loopback
+Analog Loopback D/A -> A/D loopback
+Digital Loopback playback -> capture loopback -
+ without analog path
+Mono
+Mono Output
+Multi
+ADC
+Wave
+Music
+I2S
+IEC958
+HDMI
+SPDIF output only
+SPDIF In
+Digital In
+HDMI/DP either HDMI or DisplayPort
+=================== =================================================
+
+Exceptions (deprecated)
+-----------------------
+
+===================================== =======================
+[Analogue|Digital] Capture Source
+[Analogue|Digital] Capture Switch aka input gain switch
+[Analogue|Digital] Capture Volume aka input gain volume
+[Analogue|Digital] Playback Switch aka output gain switch
+[Analogue|Digital] Playback Volume aka output gain volume
+Tone Control - Switch
+Tone Control - Bass
+Tone Control - Treble
+3D Control - Switch
+3D Control - Center
+3D Control - Depth
+3D Control - Wide
+3D Control - Space
+3D Control - Level
+Mic Boost [(?dB)]
+===================================== =======================
+
+PCM interface
+-------------
+
+=================== ========================================
+Sample Clock Source { "Word", "Internal", "AutoSync" }
+Clock Sync Status { "Lock", "Sync", "No Lock" }
+External Rate external capture rate
+Capture Rate capture rate taken from external source
+=================== ========================================
+
+IEC958 (S/PDIF) interface
+-------------------------
+
+============================================ ======================================
+IEC958 [...] [Playback|Capture] Switch turn on/off the IEC958 interface
+IEC958 [...] [Playback|Capture] Volume digital volume control
+IEC958 [...] [Playback|Capture] Default default or global value - read/write
+IEC958 [...] [Playback|Capture] Mask consumer and professional mask
+IEC958 [...] [Playback|Capture] Con Mask consumer mask
+IEC958 [...] [Playback|Capture] Pro Mask professional mask
+IEC958 [...] [Playback|Capture] PCM Stream the settings assigned to a PCM stream
+IEC958 Q-subcode [Playback|Capture] Default Q-subcode bits
+
+IEC958 Preamble [Playback|Capture] Default burst preamble words (4*16bits)
+============================================ ======================================
diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst
new file mode 100644
index 0000000000..b79db9ad87
--- /dev/null
+++ b/Documentation/sound/designs/index.rst
@@ -0,0 +1,18 @@
+Designs and Implementations
+===========================
+
+.. toctree::
+ :maxdepth: 2
+
+ control-names
+ channel-mapping-api
+ compress-offload
+ timestamping
+ jack-controls
+ tracepoints
+ procfile
+ powersave
+ oss-emulation
+ seq-oss
+ jack-injection
+ midi-2.0
diff --git a/Documentation/sound/designs/jack-controls.rst b/Documentation/sound/designs/jack-controls.rst
new file mode 100644
index 0000000000..e8a18f126a
--- /dev/null
+++ b/Documentation/sound/designs/jack-controls.rst
@@ -0,0 +1,48 @@
+==================
+ALSA Jack Controls
+==================
+
+Why we need Jack kcontrols
+==========================
+
+ALSA uses kcontrols to export audio controls(switch, volume, Mux, ...)
+to user space. This means userspace applications like pulseaudio can
+switch off headphones and switch on speakers when no headphones are
+plugged in.
+
+The old ALSA jack code only created input devices for each registered
+jack. These jack input devices are not readable by userspace devices
+that run as non root.
+
+The new jack code creates embedded jack kcontrols for each jack that
+can be read by any process.
+
+This can be combined with UCM to allow userspace to route audio more
+intelligently based on jack insertion or removal events.
+
+Jack Kcontrol Internals
+=======================
+
+Each jack will have a kcontrol list, so that we can create a kcontrol
+and attach it to the jack, at jack creation stage. We can also add a
+kcontrol to an existing jack, at anytime when required.
+
+Those kcontrols will be freed automatically when the Jack is freed.
+
+How to use jack kcontrols
+=========================
+
+In order to keep compatibility, snd_jack_new() has been modified by
+adding two params:
+
+initial_kctl
+ if true, create a kcontrol and add it to the jack list.
+phantom_jack
+ Don't create a input device for phantom jacks.
+
+HDA jacks can set phantom_jack to true in order to create a phantom
+jack and set initial_kctl to true to create an initial kcontrol with
+the correct id.
+
+ASoC jacks should set initial_kctl as false. The pin name will be
+assigned as the jack kcontrol name.
diff --git a/Documentation/sound/designs/jack-injection.rst b/Documentation/sound/designs/jack-injection.rst
new file mode 100644
index 0000000000..f979052152
--- /dev/null
+++ b/Documentation/sound/designs/jack-injection.rst
@@ -0,0 +1,166 @@
+============================
+ALSA Jack Software Injection
+============================
+
+Simple Introduction On Jack Injection
+=====================================
+
+Here jack injection means users could inject plugin or plugout events
+to the audio jacks through debugfs interface, it is helpful to
+validate ALSA userspace changes. For example, we change the audio
+profile switching code in the pulseaudio, and we want to verify if the
+change works as expected and if the change introduce the regression,
+in this case, we could inject plugin or plugout events to an audio
+jack or to some audio jacks, we don't need to physically access the
+machine and plug/unplug physical devices to the audio jack.
+
+In this design, an audio jack doesn't equal to a physical audio jack.
+Sometimes a physical audio jack contains multi functions, and the
+ALSA driver creates multi ``jack_kctl`` for a ``snd_jack``, here the
+``snd_jack`` represents a physical audio jack and the ``jack_kctl``
+represents a function, for example a physical jack has two functions:
+headphone and mic_in, the ALSA ASoC driver will build 2 ``jack_kctl``
+for this jack. The jack injection is implemented based on the
+``jack_kctl`` instead of ``snd_jack``.
+
+To inject events to audio jacks, we need to enable the jack injection
+via ``sw_inject_enable`` first, once it is enabled, this jack will not
+change the state by hardware events anymore, we could inject plugin or
+plugout events via ``jackin_inject`` and check the jack state via
+``status``, after we finish our test, we need to disable the jack
+injection via ``sw_inject_enable`` too, once it is disabled, the jack
+state will be restored according to the last reported hardware events
+and will change by future hardware events.
+
+The Layout of Jack Injection Interface
+======================================
+
+If users enable the SND_JACK_INJECTION_DEBUG in the kernel, the audio
+jack injection interface will be created as below:
+::
+
+ $debugfs_mount_dir/sound
+ |-- card0
+ |-- |-- HDMI_DP_pcm_10_Jack
+ |-- |-- |-- jackin_inject
+ |-- |-- |-- kctl_id
+ |-- |-- |-- mask_bits
+ |-- |-- |-- status
+ |-- |-- |-- sw_inject_enable
+ |-- |-- |-- type
+ ...
+ |-- |-- HDMI_DP_pcm_9_Jack
+ |-- |-- jackin_inject
+ |-- |-- kctl_id
+ |-- |-- mask_bits
+ |-- |-- status
+ |-- |-- sw_inject_enable
+ |-- |-- type
+ |-- card1
+ |-- HDMI_DP_pcm_5_Jack
+ |-- |-- jackin_inject
+ |-- |-- kctl_id
+ |-- |-- mask_bits
+ |-- |-- status
+ |-- |-- sw_inject_enable
+ |-- |-- type
+ ...
+ |-- Headphone_Jack
+ |-- |-- jackin_inject
+ |-- |-- kctl_id
+ |-- |-- mask_bits
+ |-- |-- status
+ |-- |-- sw_inject_enable
+ |-- |-- type
+ |-- Headset_Mic_Jack
+ |-- jackin_inject
+ |-- kctl_id
+ |-- mask_bits
+ |-- status
+ |-- sw_inject_enable
+ |-- type
+
+The Explanation Of The Nodes
+======================================
+
+kctl_id
+ read-only, get jack_kctl->kctl's id
+ ::
+
+ sound/card1/Headphone_Jack# cat kctl_id
+ Headphone Jack
+
+mask_bits
+ read-only, get jack_kctl's supported events mask_bits
+ ::
+
+ sound/card1/Headphone_Jack# cat mask_bits
+ 0x0001 HEADPHONE(0x0001)
+
+status
+ read-only, get jack_kctl's current status
+
+- headphone unplugged:
+
+ ::
+
+ sound/card1/Headphone_Jack# cat status
+ Unplugged
+
+- headphone plugged:
+
+ ::
+
+ sound/card1/Headphone_Jack# cat status
+ Plugged
+
+type
+ read-only, get snd_jack's supported events from type (all supported events on the physical audio jack)
+ ::
+
+ sound/card1/Headphone_Jack# cat type
+ 0x7803 HEADPHONE(0x0001) MICROPHONE(0x0002) BTN_3(0x0800) BTN_2(0x1000) BTN_1(0x2000) BTN_0(0x4000)
+
+sw_inject_enable
+ read-write, enable or disable injection
+
+- injection disabled:
+
+ ::
+
+ sound/card1/Headphone_Jack# cat sw_inject_enable
+ Jack: Headphone Jack Inject Enabled: 0
+
+- injection enabled:
+
+ ::
+
+ sound/card1/Headphone_Jack# cat sw_inject_enable
+ Jack: Headphone Jack Inject Enabled: 1
+
+- to enable jack injection:
+
+ ::
+
+ sound/card1/Headphone_Jack# echo 1 > sw_inject_enable
+
+- to disable jack injection:
+
+ ::
+
+ sound/card1/Headphone_Jack# echo 0 > sw_inject_enable
+
+jackin_inject
+ write-only, inject plugin or plugout
+
+- to inject plugin:
+
+ ::
+
+ sound/card1/Headphone_Jack# echo 1 > jackin_inject
+
+- to inject plugout:
+
+ ::
+
+ sound/card1/Headphone_Jack# echo 0 > jackin_inject
diff --git a/Documentation/sound/designs/midi-2.0.rst b/Documentation/sound/designs/midi-2.0.rst
new file mode 100644
index 0000000000..086487ca7a
--- /dev/null
+++ b/Documentation/sound/designs/midi-2.0.rst
@@ -0,0 +1,566 @@
+=================
+MIDI 2.0 on Linux
+=================
+
+General
+=======
+
+MIDI 2.0 is an extended protocol for providing higher resolutions and
+more fine controls over the legacy MIDI 1.0. The fundamental changes
+introduced for supporting MIDI 2.0 are:
+
+- Support of Universal MIDI Packet (UMP)
+- Support of MIDI 2.0 protocol messages
+- Transparent conversions between UMP and legacy MIDI 1.0 byte stream
+- MIDI-CI for property and profile configurations
+
+UMP is a new container format to hold all MIDI protocol 1.0 and MIDI
+2.0 protocol messages. Unlike the former byte stream, it's 32bit
+aligned, and each message can be put in a single packet. UMP can send
+the events up to 16 "UMP Groups", where each UMP Group contain up to
+16 MIDI channels.
+
+MIDI 2.0 protocol is an extended protocol to achieve the higher
+resolution and more controls over the old MIDI 1.0 protocol.
+
+MIDI-CI is a high-level protocol that can talk with the MIDI device
+for the flexible profiles and configurations. It's represented in the
+form of special SysEx.
+
+For Linux implementations, the kernel supports the UMP transport and
+the encoding/decoding of MIDI protocols on UMP, while MIDI-CI is
+supported in user-space over the standard SysEx.
+
+As of this writing, only USB MIDI device supports the UMP and Linux
+2.0 natively. The UMP support itself is pretty generic, hence it
+could be used by other transport layers, although it could be
+implemented differently (e.g. as a ALSA sequencer client), too.
+
+The access to UMP devices are provided in two ways: the access via
+rawmidi device and the access via ALSA sequencer API.
+
+ALSA sequencer API was extended to allow the payload of UMP packets.
+It's allowed to connect freely between MIDI 1.0 and MIDI 2.0 sequencer
+clients, and the events are converted transparently.
+
+
+Kernel Configuration
+====================
+
+The following new configs are added for supporting MIDI 2.0:
+`CONFIG_SND_UMP`, `CONFIG_SND_UMP_LEGACY_RAWMIDI`,
+`CONFIG_SND_SEQ_UMP`, `CONFIG_SND_SEQ_UMP_CLIENT`, and
+`CONFIG_SND_USB_AUDIO_MIDI_V2`. The first visible one is
+`CONFIG_SND_USB_AUDIO_MIDI_V2`, and when you choose it (to set `=y`),
+the core support for UMP (`CONFIG_SND_UMP`) and the sequencer binding
+(`CONFIG_SND_SEQ_UMP_CLIENT`) will be automatically selected.
+
+Additionally, `CONFIG_SND_UMP_LEGACY_RAWMIDI=y` will enable the
+support for the legacy raw MIDI device for UMP Endpoints.
+
+
+Rawmidi Device with USB MIDI 2.0
+================================
+
+When a device supports MIDI 2.0, the USB-audio driver probes and uses
+the MIDI 2.0 interface (that is found always at the altset 1) as
+default instead of the MIDI 1.0 interface (at altset 0). You can
+switch back to the binding with the old MIDI 1.0 interface by passing
+`midi2_enable=0` option to snd-usb-audio driver module, too.
+
+The USB audio driver tries to query the UMP Endpoint and UMP Function
+Block information that are provided since UMP v1.1, and builds up the
+topology based on those information. When the device is older and
+doesn't respond to the new UMP inquiries, the driver falls back and
+builds the topology based on Group Terminal Block (GTB) information
+from the USB descriptor. Some device might be screwed up by the
+unexpected UMP command; in such a case, pass `midi2_ump_probe=0`
+option to snd-usb-audio driver for skipping the UMP v1.1 inquiries.
+
+When the MIDI 2.0 device is probed, the kernel creates a rawmidi
+device for each UMP Endpoint of the device. Its device name is
+`/dev/snd/umpC*D*` and different from the standard rawmidi device name
+`/dev/snd/midiC*D*` for MIDI 1.0, in order to avoid confusing the
+legacy applications accessing mistakenly to UMP devices.
+
+You can read and write UMP packet data directly from/to this UMP
+rawmidi device. For example, reading via `hexdump` like below will
+show the incoming UMP packets of the card 0 device 0 in the hex
+format::
+
+ % hexdump -C /dev/snd/umpC0D0
+ 00000000 01 07 b0 20 00 07 b0 20 64 3c 90 20 64 3c 80 20 |... ... d<. d<. |
+
+Unlike the MIDI 1.0 byte stream, UMP is a 32bit packet, and the size
+for reading or writing the device is also aligned to 32bit (which is 4
+bytes).
+
+The 32-bit words in the UMP packet payload are always in CPU native
+endianness. Transport drivers are responsible to convert UMP words
+from / to system endianness to required transport endianness / byte
+order.
+
+When `CONFIG_SND_UMP_LEGACY_RAWMIDI` is set, the driver creates
+another standard raw MIDI device additionally as `/dev/snd/midiC*D*`.
+This contains 16 substreams, and each substream corresponds to a
+(0-based) UMP Group. Legacy applications can access to the specified
+group via each substream in MIDI 1.0 byte stream format. With the
+ALSA rawmidi API, you can open the arbitrary substream, while just
+opening `/dev/snd/midiC*D*` will end up with opening the first
+substream.
+
+Each UMP Endpoint can provide the additional information, constructed
+from the information inquired via UMP 1.1 Stream messages or USB MIDI
+2.0 descriptors. And a UMP Endpoint may contain one or more UMP
+Blocks, where UMP Block is an abstraction introduced in the ALSA UMP
+implementations to represent the associations among UMP Groups. UMP
+Block corresponds to Function Block in UMP 1.1 specification. When
+UMP 1.1 Function Block information isn't available, it's filled
+partially from Group Terminal Block (GTB) as defined in USB MIDI 2.0
+specifications.
+
+The information of UMP Endpoints and UMP Blocks are found in the proc
+file `/proc/asound/card*/midi*`. For example::
+
+ % cat /proc/asound/card1/midi0
+ ProtoZOA MIDI
+
+ Type: UMP
+ EP Name: ProtoZOA
+ EP Product ID: ABCD12345678
+ UMP Version: 0x0000
+ Protocol Caps: 0x00000100
+ Protocol: 0x00000100
+ Num Blocks: 3
+
+ Block 0 (ProtoZOA Main)
+ Direction: bidirection
+ Active: Yes
+ Groups: 1-1
+ Is MIDI1: No
+
+ Block 1 (ProtoZOA Ext IN)
+ Direction: output
+ Active: Yes
+ Groups: 2-2
+ Is MIDI1: Yes (Low Speed)
+ ....
+
+Note that `Groups` field shown in the proc file above indicates the
+1-based UMP Group numbers (from-to).
+
+Those additional UMP Endpoint and UMP Block information can be
+obtained via the new ioctls `SNDRV_UMP_IOCTL_ENDPOINT_INFO` and
+`SNDRV_UMP_IOCTL_BLOCK_INFO`, respectively.
+
+The rawmidi name and the UMP Endpoint name are usually identical, and
+in the case of USB MIDI, it's taken from `iInterface` of the
+corresponding USB MIDI interface descriptor. If it's not provided,
+it's copied from `iProduct` of the USB device descriptor as a
+fallback.
+
+The Endpoint Product ID is a string field and supposed to be unique.
+It's copied from `iSerialNumber` of the device for USB MIDI.
+
+The protocol capabilities and the actual protocol bits are defined in
+`asound.h`.
+
+
+ALSA Sequencer with USB MIDI 2.0
+================================
+
+In addition to the rawmidi interfaces, ALSA sequencer interface
+supports the new UMP MIDI 2.0 device, too. Now, each ALSA sequencer
+client may set its MIDI version (0, 1 or 2) to declare itself being
+either the legacy, UMP MIDI 1.0 or UMP MIDI 2.0 device, respectively.
+The first, legacy client is the one that sends/receives the old
+sequencer event as was. Meanwhile, UMP MIDI 1.0 and 2.0 clients send
+and receive in the extended event record for UMP. The MIDI version is
+seen in the new `midi_version` field of `snd_seq_client_info`.
+
+A UMP packet can be sent/received in a sequencer event embedded by
+specifying the new event flag bit `SNDRV_SEQ_EVENT_UMP`. When this
+flag is set, the event has 16 byte (128 bit) data payload for holding
+the UMP packet. Without the `SNDRV_SEQ_EVENT_UMP` bit flag, the event
+is treated as a legacy event as it was (with max 12 byte data
+payload).
+
+With `SNDRV_SEQ_EVENT_UMP` flag set, the type field of a UMP sequencer
+event is ignored (but it should be set to 0 as default).
+
+The type of each client can be seen in `/proc/asound/seq/clients`.
+For example::
+
+ % cat /proc/asound/seq/clients
+ Client info
+ cur clients : 3
+ ....
+ Client 14 : "Midi Through" [Kernel Legacy]
+ Port 0 : "Midi Through Port-0" (RWe-)
+ Client 20 : "ProtoZOA" [Kernel UMP MIDI1]
+ UMP Endpoint: ProtoZOA
+ UMP Block 0: ProtoZOA Main [Active]
+ Groups: 1-1
+ UMP Block 1: ProtoZOA Ext IN [Active]
+ Groups: 2-2
+ UMP Block 2: ProtoZOA Ext OUT [Active]
+ Groups: 3-3
+ Port 0 : "MIDI 2.0" (RWeX) [In/Out]
+ Port 1 : "ProtoZOA Main" (RWeX) [In/Out]
+ Port 2 : "ProtoZOA Ext IN" (-We-) [Out]
+ Port 3 : "ProtoZOA Ext OUT" (R-e-) [In]
+
+Here you can find two types of kernel clients, "Legacy" for client 14,
+and "UMP MIDI1" for client 20, which is a USB MIDI 2.0 device.
+A USB MIDI 2.0 client gives always the port 0 as "MIDI 2.0" and the
+rest ports from 1 for each UMP Group (e.g. port 1 for Group 1).
+In this example, the device has three active groups (Main, Ext IN and
+Ext OUT), and those are exposed as sequencer ports from 1 to 3.
+The "MIDI 2.0" port is for a UMP Endpoint, and its difference from
+other UMP Group ports is that UMP Endpoint port sends the events from
+the all ports on the device ("catch-all"), while each UMP Group port
+sends only the events from the given UMP Group.
+Also, UMP groupless messages (such as the UMP message type 0x0f) are
+sent only to the UMP Endpoint port.
+
+Note that, although each UMP sequencer client usually creates 16
+ports, those ports that don't belong to any UMP Blocks (or belonging
+to inactive UMP Blocks) are marked as inactive, and they don't appear
+in the proc outputs. In the example above, the sequencer ports from 4
+to 16 are present but not shown there.
+
+The proc file above shows the UMP Block information, too. The same
+entry (but with more detailed information) is found in the rawmidi
+proc output.
+
+When clients are connected between different MIDI versions, the events
+are translated automatically depending on the client's version, not
+only between the legacy and the UMP MIDI 1.0/2.0 types, but also
+between UMP MIDI 1.0 and 2.0 types, too. For example, running
+`aseqdump` program on the ProtoZOA Main port in the legacy mode will
+give you the output like::
+
+ % aseqdump -p 20:1
+ Waiting for data. Press Ctrl+C to end.
+ Source Event Ch Data
+ 20:1 Note on 0, note 60, velocity 100
+ 20:1 Note off 0, note 60, velocity 100
+ 20:1 Control change 0, controller 11, value 4
+
+When you run `aseqdump` in MIDI 2.0 mode, it'll receive the high
+precision data like::
+
+ % aseqdump -u 2 -p 20:1
+ Waiting for data. Press Ctrl+C to end.
+ Source Event Ch Data
+ 20:1 Note on 0, note 60, velocity 0xc924, attr type = 0, data = 0x0
+ 20:1 Note off 0, note 60, velocity 0xc924, attr type = 0, data = 0x0
+ 20:1 Control change 0, controller 11, value 0x2000000
+
+while the data is automatically converted by ALSA sequencer core.
+
+
+Rawmidi API Extensions
+======================
+
+* The additional UMP Endpoint information can be obtained via the new
+ ioctl `SNDRV_UMP_IOCTL_ENDPOINT_INFO`. It contains the associated
+ card and device numbers, the bit flags, the protocols, the number of
+ UMP Blocks, the name string of the endpoint, etc.
+
+ The protocols are specified in two field, the protocol capabilities
+ and the current protocol. Both contain the bit flags specifying the
+ MIDI protocol version (`SNDRV_UMP_EP_INFO_PROTO_MIDI1` or
+ `SNDRV_UMP_EP_INFO_PROTO_MIDI2`) in the upper byte and the jitter
+ reduction timestamp (`SNDRV_UMP_EP_INFO_PROTO_JRTS_TX` and
+ `SNDRV_UMP_EP_INFO_PROTO_JRTS_RX`) in the lower byte.
+
+ A UMP Endpoint may contain up to 32 UMP Blocks, and the number of
+ the currently assigned blocks are shown in the Endpoint information.
+
+* Each UMP Block information can be obtained via another new ioctl
+ `SNDRV_UMP_IOCTL_BLOCK_INFO`. The block ID number (0-based) has to
+ be passed for the block to query. The received data contains the
+ associated the direction of the block, the first associated group ID
+ (0-based) and the number of groups, the name string of the block,
+ etc.
+
+ The direction is either `SNDRV_UMP_DIR_INPUT`,
+ `SNDRV_UMP_DIR_OUTPUT` or `SNDRV_UMP_DIR_BIDIRECTION`.
+
+* For the device supports UMP v1.1, the UMP MIDI protocol can be
+ switched via "Stream Configuration Request" message (UMP type 0x0f,
+ status 0x05). When UMP core receives such a message, it updates the
+ UMP EP info and the corresponding sequencer clients as well.
+
+
+Control API Extensions
+======================
+
+* The new ioctl `SNDRV_CTL_IOCTL_UMP_NEXT_DEVICE` is introduced for
+ querying the next UMP rawmidi device, while the existing ioctl
+ `SNDRV_CTL_IOCTL_RAWMIDI_NEXT_DEVICE` queries only the legacy
+ rawmidi devices.
+
+ For setting the subdevice (substream number) to be opened, use the
+ ioctl `SNDRV_CTL_IOCTL_RAWMIDI_PREFER_SUBDEVICE` like the normal
+ rawmidi.
+
+* Two new ioctls `SNDRV_CTL_IOCTL_UMP_ENDPOINT_INFO` and
+ `SNDRV_CTL_IOCTL_UMP_BLOCK_INFO` provide the UMP Endpoint and UMP
+ Block information of the specified UMP device via ALSA control API
+ without opening the actual (UMP) rawmidi device.
+ The `card` field is ignored upon inquiry, always tied with the card
+ of the control interface.
+
+
+Sequencer API Extensions
+========================
+
+* `midi_version` field is added to `snd_seq_client_info` to indicate
+ the current MIDI version (either 0, 1 or 2) of each client.
+ When `midi_version` is 1 or 2, the alignment of read from a UMP
+ sequencer client is also changed from the former 28 bytes to 32
+ bytes for the extended payload. The alignment size for the write
+ isn't changed, but each event size may differ depending on the new
+ bit flag below.
+
+* `SNDRV_SEQ_EVENT_UMP` flag bit is added for each sequencer event
+ flags. When this bit flag is set, the sequencer event is extended
+ to have a larger payload of 16 bytes instead of the legacy 12
+ bytes, and the event contains the UMP packet in the payload.
+
+* The new sequencer port type bit (`SNDRV_SEQ_PORT_TYPE_MIDI_UMP`)
+ indicates the port being UMP-capable.
+
+* The sequencer ports have new capability bits to indicate the
+ inactive ports (`SNDRV_SEQ_PORT_CAP_INACTIVE`) and the UMP Endpoint
+ port (`SNDRV_SEQ_PORT_CAP_UMP_ENDPOINT`).
+
+* The event conversion of ALSA sequencer clients can be suppressed the
+ new filter bit `SNDRV_SEQ_FILTER_NO_CONVERT` set to the client info.
+ For example, the kernel pass-through client (`snd-seq-dummy`) sets
+ this flag internally.
+
+* The port information gained the new field `direction` to indicate
+ the direction of the port (either `SNDRV_SEQ_PORT_DIR_INPUT`,
+ `SNDRV_SEQ_PORT_DIR_OUTPUT` or `SNDRV_SEQ_PORT_DIR_BIDIRECTION`).
+
+* Another additional field for the port information is `ump_group`
+ which specifies the associated UMP Group Number (1-based).
+ When it's non-zero, the UMP group field in the UMP packet updated
+ upon delivery to the specified group (corrected to be 0-based).
+ Each sequencer port is supposed to set this field if it's a port to
+ specific to a certain UMP group.
+
+* Each client may set the additional event filter for UMP Groups in
+ `group_filter` bitmap. The filter consists of bitmap from 1-based
+ Group numbers. For example, when the bit 1 is set, messages from
+ Group 1 (i.e. the very first group) are filtered and not delivered.
+ The bit 0 is used for filtering UMP groupless messages.
+
+* Two new ioctls are added for UMP-capable clients:
+ `SNDRV_SEQ_IOCTL_GET_CLIENT_UMP_INFO` and
+ `SNDRV_SEQ_IOCTL_SET_CLIENT_UMP_INFO`. They are used to get and set
+ either `snd_ump_endpoint_info` or `snd_ump_block_info` data
+ associated with the sequencer client. The USB MIDI driver provides
+ those information from the underlying UMP rawmidi, while a
+ user-space client may provide its own data via `*_SET` ioctl.
+ For an Endpoint data, pass 0 to the `type` field, while for a Block
+ data, pass the block number + 1 to the `type` field.
+ Setting the data for a kernel client shall result in an error.
+
+* With UMP 1.1, Function Block information may be changed
+ dynamically. When the update of Function Block is received from the
+ device, ALSA sequencer core changes the corresponding sequencer port
+ name and attributes accordingly, and notifies the changes via the
+ announcement to the ALSA sequencer system port, similarly like the
+ normal port change notification.
+
+
+MIDI2 USB Gadget Function Driver
+================================
+
+The latest kernel contains the support for USB MIDI 2.0 gadget
+function driver, which can be used for prototyping and debugging MIDI
+2.0 features.
+
+`CONFIG_USB_GADGET`, `CONFIG_USB_CONFIGFS` and
+`CONFIG_USB_CONFIGFS_F_MIDI2` need to be enabled for the MIDI2 gadget
+driver.
+
+In addition, for using a gadget driver, you need a working UDC driver.
+In the example below, we use `dummy_hcd` driver (enabled via
+`CONFIG_USB_DUMMY_HCD`) that is available on PC and VM for debugging
+purpose. There are other UDC drivers depending on the platform, and
+those can be used for a real device, instead, too.
+
+At first, on a system to run the gadget, load `libcomposite` module::
+
+ % modprobe libcomposite
+
+and you'll have `usb_gadget` subdirectory under configfs space
+(typically `/sys/kernel/config` on modern OS). Then create a gadget
+instance and add configurations there, for example::
+
+ % cd /sys/kernel/config
+ % mkdir usb_gadget/g1
+
+ % cd usb_gadget/g1
+ % mkdir configs/c.1
+ % mkdir functions/midi2.usb0
+
+ % echo 0x0004 > idProduct
+ % echo 0x17b3 > idVendor
+ % mkdir strings/0x409
+ % echo "ACME Enterprises" > strings/0x409/manufacturer
+ % echo "ACMESynth" > strings/0x409/product
+ % echo "ABCD12345" > strings/0x409/serialnumber
+
+ % mkdir configs/c.1/strings/0x409
+ % echo "Monosynth" > configs/c.1/strings/0x409/configuration
+ % echo 120 > configs/c.1/MaxPower
+
+At this point, there must be a subdirectory `ep.0`, and that is the
+configuration for a UMP Endpoint. You can fill the Endpoint
+information like::
+
+ % echo "ACMESynth" > functions/midi2.usb0/iface_name
+ % echo "ACMESynth" > functions/midi2.usb0/ep.0/ep_name
+ % echo "ABCD12345" > functions/midi2.usb0/ep.0/product_id
+ % echo 0x0123 > functions/midi2.usb0/ep.0/family
+ % echo 0x4567 > functions/midi2.usb0/ep.0/model
+ % echo 0x123456 > functions/midi2.usb0/ep.0/manufacturer
+ % echo 0x12345678 > functions/midi2.usb0/ep.0/sw_revision
+
+The default MIDI protocol can be set either 1 or 2::
+
+ % echo 2 > functions/midi2.usb0/ep.0/protocol
+
+And, you can find a subdirectory `block.0` under this Endpoint
+subdirectory. This defines the Function Block information::
+
+ % echo "Monosynth" > functions/midi2.usb0/ep.0/block.0/name
+ % echo 0 > functions/midi2.usb0/ep.0/block.0/first_group
+ % echo 1 > functions/midi2.usb0/ep.0/block.0/num_groups
+
+Finally, link the configuration and enable it::
+
+ % ln -s functions/midi2.usb0 configs/c.1
+ % echo dummy_udc.0 > UDC
+
+where `dummy_udc.0` is an example case and it differs depending on the
+system. You can find the UDC instances in `/sys/class/udc` and pass
+the found name instead::
+
+ % ls /sys/class/udc
+ dummy_udc.0
+
+Now, the MIDI 2.0 gadget device is enabled, and the gadget host
+creates a new sound card instance containing a UMP rawmidi device by
+`f_midi2` driver::
+
+ % cat /proc/asound/cards
+ ....
+ 1 [Gadget ]: f_midi2 - MIDI 2.0 Gadget
+ MIDI 2.0 Gadget
+
+And on the connected host, a similar card should appear, too, but with
+the card and device names given in the configfs above::
+
+ % cat /proc/asound/cards
+ ....
+ 2 [ACMESynth ]: USB-Audio - ACMESynth
+ ACME Enterprises ACMESynth at usb-dummy_hcd.0-1, high speed
+
+You can play a MIDI file on the gadget side::
+
+ % aplaymidi -p 20:1 to_host.mid
+
+and this will appear as an input from a MIDI device on the connected
+host::
+
+ % aseqdump -p 20:0 -u 2
+
+Vice versa, a playback on the connected host will work as an input on
+the gadget, too.
+
+Each Function Block may have different direction and UI-hint,
+specified via `direction` and `ui_hint` attributes.
+Passing `1` is for input-only, `2` for out-only and `3` for
+bidirectional (the default value). For example::
+
+ % echo 2 > functions/midi2.usb0/ep.0/block.0/direction
+ % echo 2 > functions/midi2.usb0/ep.0/block.0/ui_hint
+
+When you need more than one Function Blocks, you can create
+subdirectories `block.1`, `block.2`, etc dynamically, and configure
+them in the configuration procedure above before linking.
+For example, to create a second Function Block for a keyboard::
+
+ % mkdir functions/midi2.usb0/ep.0/block.1
+ % echo "Keyboard" > functions/midi2.usb0/ep.0/block.1/name
+ % echo 1 > functions/midi2.usb0/ep.0/block.1/first_group
+ % echo 1 > functions/midi2.usb0/ep.0/block.1/num_groups
+ % echo 1 > functions/midi2.usb0/ep.0/block.1/direction
+ % echo 1 > functions/midi2.usb0/ep.0/block.1/ui_hint
+
+The `block.*` subdirectories can be removed dynamically, too (except
+for `block.0` which is persistent).
+
+For assigning a Function Block for MIDI 1.0 I/O, set up in `is_midi1`
+attribute. 1 is for MIDI 1.0, and 2 is for MIDI 1.0 with low speed
+connection::
+
+ % echo 2 > functions/midi2.usb0/ep.0/block.1/is_midi1
+
+For disabling the processing of UMP Stream messages in the gadget
+driver, pass `0` to `process_ump` attribute in the top-level config::
+
+ % echo 0 > functions/midi2.usb0/process_ump
+
+The MIDI 1.0 interface at altset 0 is supported by the gadget driver,
+too. When MIDI 1.0 interface is selected by the connected host, the
+UMP I/O on the gadget is translated from/to USB MIDI 1.0 packets
+accordingly while the gadget driver keeps communicating with the
+user-space over UMP rawmidi.
+
+MIDI 1.0 ports are set up from the config in each Function Block.
+For example::
+
+ % echo 0 > functions/midi2.usb0/ep.0/block.0/midi1_first_group
+ % echo 1 > functions/midi2.usb0/ep.0/block.0/midi1_num_groups
+
+The configuration above will enable the Group 1 (the index 0) for MIDI
+1.0 interface. Note that those groups must be in the groups defined
+for the Function Block itself.
+
+The gadget driver supports more than one UMP Endpoints, too.
+Similarly like the Function Blocks, you can create a new subdirectory
+`ep.1` (but under the card top-level config) to enable a new Endpoint::
+
+ % mkdir functions/midi2.usb0/ep.1
+
+and create a new Function Block there. For example, to create 4
+Groups for the Function Block of this new Endpoint::
+
+ % mkdir functions/midi2.usb0/ep.1/block.0
+ % echo 4 > functions/midi2.usb0/ep.1/block.0/num_groups
+
+Now, you'll have 4 rawmidi devices in total: the first two are UMP
+rawmidi devices for Endpoint 0 and Endpoint 1, and other two for the
+legacy MIDI 1.0 rawmidi devices corresponding to both EP 0 and EP 1.
+
+The current altsetting on the gadget can be informed via a control
+element "Operation Mode" with `RAWMIDI` iface. e.g. you can read it
+via `amixer` program running on the gadget host like::
+
+ % amixer -c1 cget iface=RAWMIDI,name='Operation Mode'
+ ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0
+ : values=2
+
+The value (shown in the second returned line with `: values=`)
+indicates 1 for MIDI 1.0 (altset 0), 2 for MIDI 2.0 (altset 1) and 0
+for unset.
+
+As of now, the configurations can't be changed after binding.
diff --git a/Documentation/sound/designs/oss-emulation.rst b/Documentation/sound/designs/oss-emulation.rst
new file mode 100644
index 0000000000..e8dcb9633e
--- /dev/null
+++ b/Documentation/sound/designs/oss-emulation.rst
@@ -0,0 +1,336 @@
+=============================
+Notes on Kernel OSS-Emulation
+=============================
+
+Jan. 22, 2004 Takashi Iwai <tiwai@suse.de>
+
+
+Modules
+=======
+
+ALSA provides a powerful OSS emulation on the kernel.
+The OSS emulation for PCM, mixer and sequencer devices is implemented
+as add-on kernel modules, snd-pcm-oss, snd-mixer-oss and snd-seq-oss.
+When you need to access the OSS PCM, mixer or sequencer devices, the
+corresponding module has to be loaded.
+
+These modules are loaded automatically when the corresponding service
+is called. The alias is defined ``sound-service-x-y``, where x and y are
+the card number and the minor unit number. Usually you don't have to
+define these aliases by yourself.
+
+Only necessary step for auto-loading of OSS modules is to define the
+card alias in ``/etc/modprobe.d/alsa.conf``, such as::
+
+ alias sound-slot-0 snd-emu10k1
+
+As the second card, define ``sound-slot-1`` as well.
+Note that you can't use the aliased name as the target name (i.e.
+``alias sound-slot-0 snd-card-0`` doesn't work any more like the old
+modutils).
+
+The currently available OSS configuration is shown in
+/proc/asound/oss/sndstat. This shows in the same syntax of
+/dev/sndstat, which is available on the commercial OSS driver.
+On ALSA, you can symlink /dev/sndstat to this proc file.
+
+Please note that the devices listed in this proc file appear only
+after the corresponding OSS-emulation module is loaded. Don't worry
+even if "NOT ENABLED IN CONFIG" is shown in it.
+
+
+Device Mapping
+==============
+
+ALSA supports the following OSS device files:
+::
+
+ PCM:
+ /dev/dspX
+ /dev/adspX
+
+ Mixer:
+ /dev/mixerX
+
+ MIDI:
+ /dev/midi0X
+ /dev/amidi0X
+
+ Sequencer:
+ /dev/sequencer
+ /dev/sequencer2 (aka /dev/music)
+
+where X is the card number from 0 to 7.
+
+(NOTE: Some distributions have the device files like /dev/midi0 and
+/dev/midi1. They are NOT for OSS but for tclmidi, which is
+a totally different thing.)
+
+Unlike the real OSS, ALSA cannot use the device files more than the
+assigned ones. For example, the first card cannot use /dev/dsp1 or
+/dev/dsp2, but only /dev/dsp0 and /dev/adsp0.
+
+As seen above, PCM and MIDI may have two devices. Usually, the first
+PCM device (``hw:0,0`` in ALSA) is mapped to /dev/dsp and the secondary
+device (``hw:0,1``) to /dev/adsp (if available). For MIDI, /dev/midi and
+/dev/amidi, respectively.
+
+You can change this device mapping via the module options of
+snd-pcm-oss and snd-rawmidi. In the case of PCM, the following
+options are available for snd-pcm-oss:
+
+dsp_map
+ PCM device number assigned to /dev/dspX
+ (default = 0)
+adsp_map
+ PCM device number assigned to /dev/adspX
+ (default = 1)
+
+For example, to map the third PCM device (``hw:0,2``) to /dev/adsp0,
+define like this:
+::
+
+ options snd-pcm-oss adsp_map=2
+
+The options take arrays. For configuring the second card, specify
+two entries separated by comma. For example, to map the third PCM
+device on the second card to /dev/adsp1, define like below:
+::
+
+ options snd-pcm-oss adsp_map=0,2
+
+To change the mapping of MIDI devices, the following options are
+available for snd-rawmidi:
+
+midi_map
+ MIDI device number assigned to /dev/midi0X
+ (default = 0)
+amidi_map
+ MIDI device number assigned to /dev/amidi0X
+ (default = 1)
+
+For example, to assign the third MIDI device on the first card to
+/dev/midi00, define as follows:
+::
+
+ options snd-rawmidi midi_map=2
+
+
+PCM Mode
+========
+
+As default, ALSA emulates the OSS PCM with so-called plugin layer,
+i.e. tries to convert the sample format, rate or channels
+automatically when the card doesn't support it natively.
+This will lead to some problems for some applications like quake or
+wine, especially if they use the card only in the MMAP mode.
+
+In such a case, you can change the behavior of PCM per application by
+writing a command to the proc file. There is a proc file for each PCM
+stream, ``/proc/asound/cardX/pcmY[cp]/oss``, where X is the card number
+(zero-based), Y the PCM device number (zero-based), and ``p`` is for
+playback and ``c`` for capture, respectively. Note that this proc file
+exists only after snd-pcm-oss module is loaded.
+
+The command sequence has the following syntax:
+::
+
+ app_name fragments fragment_size [options]
+
+``app_name`` is the name of application with (higher priority) or without
+path.
+``fragments`` specifies the number of fragments or zero if no specific
+number is given.
+``fragment_size`` is the size of fragment in bytes or zero if not given.
+``options`` is the optional parameters. The following options are
+available:
+
+disable
+ the application tries to open a pcm device for
+ this channel but does not want to use it.
+direct
+ don't use plugins
+block
+ force block open mode
+non-block
+ force non-block open mode
+partial-frag
+ write also partial fragments (affects playback only)
+no-silence
+ do not fill silence ahead to avoid clicks
+
+The ``disable`` option is useful when one stream direction (playback or
+capture) is not handled correctly by the application although the
+hardware itself does support both directions.
+The ``direct`` option is used, as mentioned above, to bypass the automatic
+conversion and useful for MMAP-applications.
+For example, to playback the first PCM device without plugins for
+quake, send a command via echo like the following:
+::
+
+ % echo "quake 0 0 direct" > /proc/asound/card0/pcm0p/oss
+
+While quake wants only playback, you may append the second command
+to notify driver that only this direction is about to be allocated:
+::
+
+ % echo "quake 0 0 disable" > /proc/asound/card0/pcm0c/oss
+
+The permission of proc files depend on the module options of snd.
+As default it's set as root, so you'll likely need to be superuser for
+sending the command above.
+
+The block and non-block options are used to change the behavior of
+opening the device file.
+
+As default, ALSA behaves as original OSS drivers, i.e. does not block
+the file when it's busy. The -EBUSY error is returned in this case.
+
+This blocking behavior can be changed globally via nonblock_open
+module option of snd-pcm-oss. For using the blocking mode as default
+for OSS devices, define like the following:
+::
+
+ options snd-pcm-oss nonblock_open=0
+
+The ``partial-frag`` and ``no-silence`` commands have been added recently.
+Both commands are for optimization use only. The former command
+specifies to invoke the write transfer only when the whole fragment is
+filled. The latter stops writing the silence data ahead
+automatically. Both are disabled as default.
+
+You can check the currently defined configuration by reading the proc
+file. The read image can be sent to the proc file again, hence you
+can save the current configuration
+::
+
+ % cat /proc/asound/card0/pcm0p/oss > /somewhere/oss-cfg
+
+and restore it like
+::
+
+ % cat /somewhere/oss-cfg > /proc/asound/card0/pcm0p/oss
+
+Also, for clearing all the current configuration, send ``erase`` command
+as below:
+::
+
+ % echo "erase" > /proc/asound/card0/pcm0p/oss
+
+
+Mixer Elements
+==============
+
+Since ALSA has completely different mixer interface, the emulation of
+OSS mixer is relatively complicated. ALSA builds up a mixer element
+from several different ALSA (mixer) controls based on the name
+string. For example, the volume element SOUND_MIXER_PCM is composed
+from "PCM Playback Volume" and "PCM Playback Switch" controls for the
+playback direction and from "PCM Capture Volume" and "PCM Capture
+Switch" for the capture directory (if exists). When the PCM volume of
+OSS is changed, all the volume and switch controls above are adjusted
+automatically.
+
+As default, ALSA uses the following control for OSS volumes:
+
+==================== ===================== =====
+OSS volume ALSA control Index
+==================== ===================== =====
+SOUND_MIXER_VOLUME Master 0
+SOUND_MIXER_BASS Tone Control - Bass 0
+SOUND_MIXER_TREBLE Tone Control - Treble 0
+SOUND_MIXER_SYNTH Synth 0
+SOUND_MIXER_PCM PCM 0
+SOUND_MIXER_SPEAKER PC Speaker 0
+SOUND_MIXER_LINE Line 0
+SOUND_MIXER_MIC Mic 0
+SOUND_MIXER_CD CD 0
+SOUND_MIXER_IMIX Monitor Mix 0
+SOUND_MIXER_ALTPCM PCM 1
+SOUND_MIXER_RECLEV (not assigned)
+SOUND_MIXER_IGAIN Capture 0
+SOUND_MIXER_OGAIN Playback 0
+SOUND_MIXER_LINE1 Aux 0
+SOUND_MIXER_LINE2 Aux 1
+SOUND_MIXER_LINE3 Aux 2
+SOUND_MIXER_DIGITAL1 Digital 0
+SOUND_MIXER_DIGITAL2 Digital 1
+SOUND_MIXER_DIGITAL3 Digital 2
+SOUND_MIXER_PHONEIN Phone 0
+SOUND_MIXER_PHONEOUT Phone 1
+SOUND_MIXER_VIDEO Video 0
+SOUND_MIXER_RADIO Radio 0
+SOUND_MIXER_MONITOR Monitor 0
+==================== ===================== =====
+
+The second column is the base-string of the corresponding ALSA
+control. In fact, the controls with ``XXX [Playback|Capture]
+[Volume|Switch]`` will be checked in addition.
+
+The current assignment of these mixer elements is listed in the proc
+file, /proc/asound/cardX/oss_mixer, which will be like the following
+::
+
+ VOLUME "Master" 0
+ BASS "" 0
+ TREBLE "" 0
+ SYNTH "" 0
+ PCM "PCM" 0
+ ...
+
+where the first column is the OSS volume element, the second column
+the base-string of the corresponding ALSA control, and the third the
+control index. When the string is empty, it means that the
+corresponding OSS control is not available.
+
+For changing the assignment, you can write the configuration to this
+proc file. For example, to map "Wave Playback" to the PCM volume,
+send the command like the following:
+::
+
+ % echo 'VOLUME "Wave Playback" 0' > /proc/asound/card0/oss_mixer
+
+The command is exactly as same as listed in the proc file. You can
+change one or more elements, one volume per line. In the last
+example, both "Wave Playback Volume" and "Wave Playback Switch" will
+be affected when PCM volume is changed.
+
+Like the case of PCM proc file, the permission of proc files depend on
+the module options of snd. you'll likely need to be superuser for
+sending the command above.
+
+As well as in the case of PCM proc file, you can save and restore the
+current mixer configuration by reading and writing the whole file
+image.
+
+
+Duplex Streams
+==============
+
+Note that when attempting to use a single device file for playback and
+capture, the OSS API provides no way to set the format, sample rate or
+number of channels different in each direction. Thus
+::
+
+ io_handle = open("device", O_RDWR)
+
+will only function correctly if the values are the same in each direction.
+
+To use different values in the two directions, use both
+::
+
+ input_handle = open("device", O_RDONLY)
+ output_handle = open("device", O_WRONLY)
+
+and set the values for the corresponding handle.
+
+
+Unsupported Features
+====================
+
+MMAP on ICE1712 driver
+----------------------
+ICE1712 supports only the unconventional format, interleaved
+10-channels 24bit (packed in 32bit) format. Therefore you cannot mmap
+the buffer as the conventional (mono or 2-channels, 8 or 16bit) format
+on OSS.
diff --git a/Documentation/sound/designs/powersave.rst b/Documentation/sound/designs/powersave.rst
new file mode 100644
index 0000000000..138157452e
--- /dev/null
+++ b/Documentation/sound/designs/powersave.rst
@@ -0,0 +1,43 @@
+==========================
+Notes on Power-Saving Mode
+==========================
+
+AC97 and HD-audio drivers have the automatic power-saving mode.
+This feature is enabled via Kconfig ``CONFIG_SND_AC97_POWER_SAVE``
+and ``CONFIG_SND_HDA_POWER_SAVE`` options, respectively.
+
+With the automatic power-saving, the driver turns off the codec power
+appropriately when no operation is required. When no applications use
+the device and/or no analog loopback is set, the power disablement is
+done fully or partially. It'll save a certain power consumption, thus
+good for laptops (even for desktops).
+
+The time-out for automatic power-off can be specified via ``power_save``
+module option of snd-ac97-codec and snd-hda-intel modules. Specify
+the time-out value in seconds. 0 means to disable the automatic
+power-saving. The default value of timeout is given via
+``CONFIG_SND_AC97_POWER_SAVE_DEFAULT`` and
+``CONFIG_SND_HDA_POWER_SAVE_DEFAULT`` Kconfig options. Setting this to 1
+(the minimum value) isn't recommended because many applications try to
+reopen the device frequently. 10 would be a good choice for normal
+operations.
+
+The ``power_save`` option is exported as writable. This means you can
+adjust the value via sysfs on the fly. For example, to turn on the
+automatic power-save mode with 10 seconds, write to
+``/sys/modules/snd_ac97_codec/parameters/power_save`` (usually as root):
+::
+
+ # echo 10 > /sys/modules/snd_ac97_codec/parameters/power_save
+
+
+Note that you might hear click noise/pop when changing the power
+state. Also, it often takes certain time to wake up from the
+power-down to the active state. These are often hardly to fix, so
+don't report extra bug reports unless you have a fix patch ;-)
+
+For HD-audio interface, there is another module option,
+power_save_controller. This enables/disables the power-save mode of
+the controller side. Setting this on may reduce a bit more power
+consumption, but might result in longer wake-up time and click noise.
+Try to turn it off when you experience such a thing too often.
diff --git a/Documentation/sound/designs/procfile.rst b/Documentation/sound/designs/procfile.rst
new file mode 100644
index 0000000000..e9f7e0cbdc
--- /dev/null
+++ b/Documentation/sound/designs/procfile.rst
@@ -0,0 +1,238 @@
+==========================
+Proc Files of ALSA Drivers
+==========================
+
+Takashi Iwai <tiwai@suse.de>
+
+General
+=======
+
+ALSA has its own proc tree, /proc/asound. Many useful information are
+found in this tree. When you encounter a problem and need debugging,
+check the files listed in the following sections.
+
+Each card has its subtree cardX, where X is from 0 to 7. The
+card-specific files are stored in the ``card*`` subdirectories.
+
+
+Global Information
+==================
+
+cards
+ Shows the list of currently configured ALSA drivers,
+ index, the id string, short and long descriptions.
+
+version
+ Shows the version string and compile date.
+
+modules
+ Lists the module of each card
+
+devices
+ Lists the ALSA native device mappings.
+
+meminfo
+ Shows the status of allocated pages via ALSA drivers.
+ Appears only when ``CONFIG_SND_DEBUG=y``.
+
+hwdep
+ Lists the currently available hwdep devices in format of
+ ``<card>-<device>: <name>``
+
+pcm
+ Lists the currently available PCM devices in format of
+ ``<card>-<device>: <id>: <name> : <sub-streams>``
+
+timer
+ Lists the currently available timer devices
+
+
+oss/devices
+ Lists the OSS device mappings.
+
+oss/sndstat
+ Provides the output compatible with /dev/sndstat.
+ You can symlink this to /dev/sndstat.
+
+
+Card Specific Files
+===================
+
+The card-specific files are found in ``/proc/asound/card*`` directories.
+Some drivers (e.g. cmipci) have their own proc entries for the
+register dump, etc (e.g. ``/proc/asound/card*/cmipci`` shows the register
+dump). These files would be really helpful for debugging.
+
+When PCM devices are available on this card, you can see directories
+like pcm0p or pcm1c. They hold the PCM information for each PCM
+stream. The number after ``pcm`` is the PCM device number from 0, and
+the last ``p`` or ``c`` means playback or capture direction. The files in
+this subtree is described later.
+
+The status of MIDI I/O is found in ``midi*`` files. It shows the device
+name and the received/transmitted bytes through the MIDI device.
+
+When the card is equipped with AC97 codecs, there are ``codec97#*``
+subdirectories (described later).
+
+When the OSS mixer emulation is enabled (and the module is loaded),
+oss_mixer file appears here, too. This shows the current mapping of
+OSS mixer elements to the ALSA control elements. You can change the
+mapping by writing to this device. Read OSS-Emulation.txt for
+details.
+
+
+PCM Proc Files
+==============
+
+``card*/pcm*/info``
+ The general information of this PCM device: card #, device #,
+ substreams, etc.
+
+``card*/pcm*/xrun_debug``
+ This file appears when ``CONFIG_SND_DEBUG=y`` and
+ ``CONFIG_SND_PCM_XRUN_DEBUG=y``.
+ This shows the status of xrun (= buffer overrun/xrun) and
+ invalid PCM position debug/check of ALSA PCM middle layer.
+ It takes an integer value, can be changed by writing to this
+ file, such as::
+
+ # echo 5 > /proc/asound/card0/pcm0p/xrun_debug
+
+ The value consists of the following bit flags:
+
+ * bit 0 = Enable XRUN/jiffies debug messages
+ * bit 1 = Show stack trace at XRUN / jiffies check
+ * bit 2 = Enable additional jiffies check
+
+ When the bit 0 is set, the driver will show the messages to
+ kernel log when an xrun is detected. The debug message is
+ shown also when the invalid H/W pointer is detected at the
+ update of periods (usually called from the interrupt
+ handler).
+
+ When the bit 1 is set, the driver will show the stack trace
+ additionally. This may help the debugging.
+
+ Since 2.6.30, this option can enable the hwptr check using
+ jiffies. This detects spontaneous invalid pointer callback
+ values, but can be lead to too much corrections for a (mostly
+ buggy) hardware that doesn't give smooth pointer updates.
+ This feature is enabled via the bit 2.
+
+``card*/pcm*/sub*/info``
+ The general information of this PCM sub-stream.
+
+``card*/pcm*/sub*/status``
+ The current status of this PCM sub-stream, elapsed time,
+ H/W position, etc.
+
+``card*/pcm*/sub*/hw_params``
+ The hardware parameters set for this sub-stream.
+
+``card*/pcm*/sub*/sw_params``
+ The soft parameters set for this sub-stream.
+
+``card*/pcm*/sub*/prealloc``
+ The buffer pre-allocation information.
+
+``card*/pcm*/sub*/xrun_injection``
+ Triggers an XRUN to the running stream when any value is
+ written to this proc file. Used for fault injection.
+ This entry is write-only.
+
+AC97 Codec Information
+======================
+
+``card*/codec97#*/ac97#?-?``
+ Shows the general information of this AC97 codec chip, such as
+ name, capabilities, set up.
+
+``card*/codec97#0/ac97#?-?+regs``
+ Shows the AC97 register dump. Useful for debugging.
+
+ When CONFIG_SND_DEBUG is enabled, you can write to this file for
+ changing an AC97 register directly. Pass two hex numbers.
+ For example,
+
+::
+
+ # echo 02 9f1f > /proc/asound/card0/codec97#0/ac97#0-0+regs
+
+
+USB Audio Streams
+=================
+
+``card*/stream*``
+ Shows the assignment and the current status of each audio stream
+ of the given card. This information is very useful for debugging.
+
+
+HD-Audio Codecs
+===============
+
+``card*/codec#*``
+ Shows the general codec information and the attribute of each
+ widget node.
+
+``card*/eld#*``
+ Available for HDMI or DisplayPort interfaces.
+ Shows ELD(EDID Like Data) info retrieved from the attached HDMI sink,
+ and describes its audio capabilities and configurations.
+
+ Some ELD fields may be modified by doing ``echo name hex_value > eld#*``.
+ Only do this if you are sure the HDMI sink provided value is wrong.
+ And if that makes your HDMI audio work, please report to us so that we
+ can fix it in future kernel releases.
+
+
+Sequencer Information
+=====================
+
+seq/drivers
+ Lists the currently available ALSA sequencer drivers.
+
+seq/clients
+ Shows the list of currently available sequencer clients and
+ ports. The connection status and the running status are shown
+ in this file, too.
+
+seq/queues
+ Lists the currently allocated/running sequencer queues.
+
+seq/timer
+ Lists the currently allocated/running sequencer timers.
+
+seq/oss
+ Lists the OSS-compatible sequencer stuffs.
+
+
+Help For Debugging?
+===================
+
+When the problem is related with PCM, first try to turn on xrun_debug
+mode. This will give you the kernel messages when and where xrun
+happened.
+
+If it's really a bug, report it with the following information:
+
+- the name of the driver/card, show in ``/proc/asound/cards``
+- the register dump, if available (e.g. ``card*/cmipci``)
+
+when it's a PCM problem,
+
+- set-up of PCM, shown in hw_parms, sw_params, and status in the PCM
+ sub-stream directory
+
+when it's a mixer problem,
+
+- AC97 proc files, ``codec97#*/*`` files
+
+for USB audio/midi,
+
+- output of ``lsusb -v``
+- ``stream*`` files in card directory
+
+
+The ALSA bug-tracking system is found at:
+https://bugtrack.alsa-project.org/alsa-bug/
diff --git a/Documentation/sound/designs/seq-oss.rst b/Documentation/sound/designs/seq-oss.rst
new file mode 100644
index 0000000000..ec6304a074
--- /dev/null
+++ b/Documentation/sound/designs/seq-oss.rst
@@ -0,0 +1,371 @@
+===============================
+OSS Sequencer Emulation on ALSA
+===============================
+
+Copyright (c) 1998,1999 by Takashi Iwai
+
+ver.0.1.8; Nov. 16, 1999
+
+Description
+===========
+
+This directory contains the OSS sequencer emulation driver on ALSA. Note
+that this program is still in the development state.
+
+What this does - it provides the emulation of the OSS sequencer, access
+via ``/dev/sequencer`` and ``/dev/music`` devices.
+The most of applications using OSS can run if the appropriate ALSA
+sequencer is prepared.
+
+The following features are emulated by this driver:
+
+* Normal sequencer and MIDI events:
+
+ They are converted to the ALSA sequencer events, and sent to the
+ corresponding port.
+
+* Timer events:
+
+ The timer is not selectable by ioctl. The control rate is fixed to
+ 100 regardless of HZ. That is, even on Alpha system, a tick is always
+ 1/100 second. The base rate and tempo can be changed in ``/dev/music``.
+
+* Patch loading:
+
+ It purely depends on the synth drivers whether it's supported since
+ the patch loading is realized by callback to the synth driver.
+
+* I/O controls:
+
+ Most of controls are accepted. Some controls
+ are dependent on the synth driver, as well as even on original OSS.
+
+Furthermore, you can find the following advanced features:
+
+* Better queue mechanism:
+
+ The events are queued before processing them.
+
+* Multiple applications:
+
+ You can run two or more applications simultaneously (even for OSS
+ sequencer)!
+ However, each MIDI device is exclusive - that is, if a MIDI device
+ is opened once by some application, other applications can't use
+ it. No such a restriction in synth devices.
+
+* Real-time event processing:
+
+ The events can be processed in real time without using out of bound
+ ioctl. To switch to real-time mode, send ABSTIME 0 event. The followed
+ events will be processed in real-time without queued. To switch off the
+ real-time mode, send RELTIME 0 event.
+
+* ``/proc`` interface:
+
+ The status of applications and devices can be shown via
+ ``/proc/asound/seq/oss`` at any time. In the later version,
+ configuration will be changed via ``/proc`` interface, too.
+
+
+Installation
+============
+
+Run configure script with both sequencer support (``--with-sequencer=yes``)
+and OSS emulation (``--with-oss=yes``) options. A module ``snd-seq-oss.o``
+will be created. If the synth module of your sound card supports for OSS
+emulation (so far, only Emu8000 driver), this module will be loaded
+automatically.
+Otherwise, you need to load this module manually.
+
+At beginning, this module probes all the MIDI ports which have been
+already connected to the sequencer. Once after that, the creation and deletion
+of ports are watched by announcement mechanism of ALSA sequencer.
+
+The available synth and MIDI devices can be found in proc interface.
+Run ``cat /proc/asound/seq/oss``, and check the devices. For example,
+if you use an AWE64 card, you'll see like the following:
+::
+
+ OSS sequencer emulation version 0.1.8
+ ALSA client number 63
+ ALSA receiver port 0
+
+ Number of applications: 0
+
+ Number of synth devices: 1
+ synth 0: [EMU8000]
+ type 0x1 : subtype 0x20 : voices 32
+ capabilities : ioctl enabled / load_patch enabled
+
+ Number of MIDI devices: 3
+ midi 0: [Emu8000 Port-0] ALSA port 65:0
+ capability write / opened none
+
+ midi 1: [Emu8000 Port-1] ALSA port 65:1
+ capability write / opened none
+
+ midi 2: [0: MPU-401 (UART)] ALSA port 64:0
+ capability read/write / opened none
+
+Note that the device number may be different from the information of
+``/proc/asound/oss-devices`` or ones of the original OSS driver.
+Use the device number listed in ``/proc/asound/seq/oss``
+to play via OSS sequencer emulation.
+
+Using Synthesizer Devices
+=========================
+
+Run your favorite program. I've tested playmidi-2.4, awemidi-0.4.3, gmod-3.1
+and xmp-1.1.5. You can load samples via ``/dev/sequencer`` like sfxload,
+too.
+
+If the lowlevel driver supports multiple access to synth devices (like
+Emu8000 driver), two or more applications are allowed to run at the same
+time.
+
+Using MIDI Devices
+==================
+
+So far, only MIDI output was tested. MIDI input was not checked at all,
+but hopefully it will work. Use the device number listed in
+``/proc/asound/seq/oss``.
+Be aware that these numbers are mostly different from the list in
+``/proc/asound/oss-devices``.
+
+Module Options
+==============
+
+The following module options are available:
+
+maxqlen
+ specifies the maximum read/write queue length. This queue is private
+ for OSS sequencer, so that it is independent from the queue length of ALSA
+ sequencer. Default value is 1024.
+
+seq_oss_debug
+ specifies the debug level and accepts zero (= no debug message) or
+ positive integer. Default value is 0.
+
+Queue Mechanism
+===============
+
+OSS sequencer emulation uses an ALSA priority queue. The
+events from ``/dev/sequencer`` are processed and put onto the queue
+specified by module option.
+
+All the events from ``/dev/sequencer`` are parsed at beginning.
+The timing events are also parsed at this moment, so that the events may
+be processed in real-time. Sending an event ABSTIME 0 switches the operation
+mode to real-time mode, and sending an event RELTIME 0 switches it off.
+In the real-time mode, all events are dispatched immediately.
+
+The queued events are dispatched to the corresponding ALSA sequencer
+ports after scheduled time by ALSA sequencer dispatcher.
+
+If the write-queue is full, the application sleeps until a certain amount
+(as default one half) becomes empty in blocking mode. The synchronization
+to write timing was implemented, too.
+
+The input from MIDI devices or echo-back events are stored on read FIFO
+queue. If application reads ``/dev/sequencer`` in blocking mode, the
+process will be awaked.
+
+Interface to Synthesizer Device
+===============================
+
+Registration
+------------
+
+To register an OSS synthesizer device, use snd_seq_oss_synth_register()
+function:
+::
+
+ int snd_seq_oss_synth_register(char *name, int type, int subtype, int nvoices,
+ snd_seq_oss_callback_t *oper, void *private_data)
+
+The arguments ``name``, ``type``, ``subtype`` and ``nvoices``
+are used for making the appropriate synth_info structure for ioctl. The
+return value is an index number of this device. This index must be remembered
+for unregister. If registration is failed, -errno will be returned.
+
+To release this device, call snd_seq_oss_synth_unregister() function:
+::
+
+ int snd_seq_oss_synth_unregister(int index)
+
+where the ``index`` is the index number returned by register function.
+
+Callbacks
+---------
+
+OSS synthesizer devices have capability for sample downloading and ioctls
+like sample reset. In OSS emulation, these special features are realized
+by using callbacks. The registration argument oper is used to specify these
+callbacks. The following callback functions must be defined:
+::
+
+ snd_seq_oss_callback_t:
+ int (*open)(snd_seq_oss_arg_t *p, void *closure);
+ int (*close)(snd_seq_oss_arg_t *p);
+ int (*ioctl)(snd_seq_oss_arg_t *p, unsigned int cmd, unsigned long arg);
+ int (*load_patch)(snd_seq_oss_arg_t *p, int format, const char *buf, int offs, int count);
+ int (*reset)(snd_seq_oss_arg_t *p);
+
+Except for ``open`` and ``close`` callbacks, they are allowed to be NULL.
+
+Each callback function takes the argument type ``snd_seq_oss_arg_t`` as the
+first argument.
+::
+
+ struct snd_seq_oss_arg_t {
+ int app_index;
+ int file_mode;
+ int seq_mode;
+ snd_seq_addr_t addr;
+ void *private_data;
+ int event_passing;
+ };
+
+The first three fields, ``app_index``, ``file_mode`` and ``seq_mode``
+are initialized by OSS sequencer. The ``app_index`` is the application
+index which is unique to each application opening OSS sequencer. The
+``file_mode`` is bit-flags indicating the file operation mode. See
+``seq_oss.h`` for its meaning. The ``seq_mode`` is sequencer operation
+mode. In the current version, only ``SND_OSSSEQ_MODE_SYNTH`` is used.
+
+The next two fields, ``addr`` and ``private_data``, must be
+filled by the synth driver at open callback. The ``addr`` contains
+the address of ALSA sequencer port which is assigned to this device. If
+the driver allocates memory for ``private_data``, it must be released
+in close callback by itself.
+
+The last field, ``event_passing``, indicates how to translate note-on
+/ off events. In ``PROCESS_EVENTS`` mode, the note 255 is regarded
+as velocity change, and key pressure event is passed to the port. In
+``PASS_EVENTS`` mode, all note on/off events are passed to the port
+without modified. ``PROCESS_KEYPRESS`` mode checks the note above 128
+and regards it as key pressure event (mainly for Emu8000 driver).
+
+Open Callback
+-------------
+
+The ``open`` is called at each time this device is opened by an application
+using OSS sequencer. This must not be NULL. Typically, the open callback
+does the following procedure:
+
+#. Allocate private data record.
+#. Create an ALSA sequencer port.
+#. Set the new port address on ``arg->addr``.
+#. Set the private data record pointer on ``arg->private_data``.
+
+Note that the type bit-flags in port_info of this synth port must NOT contain
+``TYPE_MIDI_GENERIC``
+bit. Instead, ``TYPE_SPECIFIC`` should be used. Also, ``CAP_SUBSCRIPTION``
+bit should NOT be included, too. This is necessary to tell it from other
+normal MIDI devices. If the open procedure succeeded, return zero. Otherwise,
+return -errno.
+
+Ioctl Callback
+--------------
+
+The ``ioctl`` callback is called when the sequencer receives device-specific
+ioctls. The following two ioctls should be processed by this callback:
+
+IOCTL_SEQ_RESET_SAMPLES
+ reset all samples on memory -- return 0
+
+IOCTL_SYNTH_MEMAVL
+ return the available memory size
+
+FM_4OP_ENABLE
+ can be ignored usually
+
+The other ioctls are processed inside the sequencer without passing to
+the lowlevel driver.
+
+Load_Patch Callback
+-------------------
+
+The ``load_patch`` callback is used for sample-downloading. This callback
+must read the data on user-space and transfer to each device. Return 0
+if succeeded, and -errno if failed. The format argument is the patch key
+in patch_info record. The buf is user-space pointer where patch_info record
+is stored. The offs can be ignored. The count is total data size of this
+sample data.
+
+Close Callback
+--------------
+
+The ``close`` callback is called when this device is closed by the
+application. If any private data was allocated in open callback, it must
+be released in the close callback. The deletion of ALSA port should be
+done here, too. This callback must not be NULL.
+
+Reset Callback
+--------------
+
+The ``reset`` callback is called when sequencer device is reset or
+closed by applications. The callback should turn off the sounds on the
+relevant port immediately, and initialize the status of the port. If this
+callback is undefined, OSS seq sends a ``HEARTBEAT`` event to the
+port.
+
+Events
+======
+
+Most of the events are processed by sequencer and translated to the adequate
+ALSA sequencer events, so that each synth device can receive by input_event
+callback of ALSA sequencer port. The following ALSA events should be
+implemented by the driver:
+
+============= ===================
+ALSA event Original OSS events
+============= ===================
+NOTEON SEQ_NOTEON, MIDI_NOTEON
+NOTE SEQ_NOTEOFF, MIDI_NOTEOFF
+KEYPRESS MIDI_KEY_PRESSURE
+CHANPRESS SEQ_AFTERTOUCH, MIDI_CHN_PRESSURE
+PGMCHANGE SEQ_PGMCHANGE, MIDI_PGM_CHANGE
+PITCHBEND SEQ_CONTROLLER(CTRL_PITCH_BENDER),
+ MIDI_PITCH_BEND
+CONTROLLER MIDI_CTL_CHANGE,
+ SEQ_BALANCE (with CTL_PAN)
+CONTROL14 SEQ_CONTROLLER
+REGPARAM SEQ_CONTROLLER(CTRL_PITCH_BENDER_RANGE)
+SYSEX SEQ_SYSEX
+============= ===================
+
+The most of these behavior can be realized by MIDI emulation driver
+included in the Emu8000 lowlevel driver. In the future release, this module
+will be independent.
+
+Some OSS events (``SEQ_PRIVATE`` and ``SEQ_VOLUME`` events) are passed as event
+type SND_SEQ_OSS_PRIVATE. The OSS sequencer passes these event 8 byte
+packets without any modification. The lowlevel driver should process these
+events appropriately.
+
+Interface to MIDI Device
+========================
+
+Since the OSS emulation probes the creation and deletion of ALSA MIDI
+sequencer ports automatically by receiving announcement from ALSA
+sequencer, the MIDI devices don't need to be registered explicitly
+like synth devices.
+However, the MIDI port_info registered to ALSA sequencer must include
+a group name ``SND_SEQ_GROUP_DEVICE`` and a capability-bit
+``CAP_READ`` or ``CAP_WRITE``. Also, subscription capabilities,
+``CAP_SUBS_READ`` or ``CAP_SUBS_WRITE``, must be defined, too. If
+these conditions are not satisfied, the port is not registered as OSS
+sequencer MIDI device.
+
+The events via MIDI devices are parsed in OSS sequencer and converted
+to the corresponding ALSA sequencer events. The input from MIDI sequencer
+is also converted to MIDI byte events by OSS sequencer. This works just
+a reverse way of seq_midi module.
+
+Known Problems / TODO's
+=======================
+
+* Patch loading via ALSA instrument layer is not implemented yet.
+
diff --git a/Documentation/sound/designs/timestamping.rst b/Documentation/sound/designs/timestamping.rst
new file mode 100644
index 0000000000..7c7ecf5dbc
--- /dev/null
+++ b/Documentation/sound/designs/timestamping.rst
@@ -0,0 +1,215 @@
+=====================
+ALSA PCM Timestamping
+=====================
+
+The ALSA API can provide two different system timestamps:
+
+- Trigger_tstamp is the system time snapshot taken when the .trigger
+ callback is invoked. This snapshot is taken by the ALSA core in the
+ general case, but specific hardware may have synchronization
+ capabilities or conversely may only be able to provide a correct
+ estimate with a delay. In the latter two cases, the low-level driver
+ is responsible for updating the trigger_tstamp at the most appropriate
+ and precise moment. Applications should not rely solely on the first
+ trigger_tstamp but update their internal calculations if the driver
+ provides a refined estimate with a delay.
+
+- tstamp is the current system timestamp updated during the last
+ event or application query.
+ The difference (tstamp - trigger_tstamp) defines the elapsed time.
+
+The ALSA API provides two basic pieces of information, avail
+and delay, which combined with the trigger and current system
+timestamps allow for applications to keep track of the 'fullness' of
+the ring buffer and the amount of queued samples.
+
+The use of these different pointers and time information depends on
+the application needs:
+
+- ``avail`` reports how much can be written in the ring buffer
+- ``delay`` reports the time it will take to hear a new sample after all
+ queued samples have been played out.
+
+When timestamps are enabled, the avail/delay information is reported
+along with a snapshot of system time. Applications can select from
+``CLOCK_REALTIME`` (NTP corrections including going backwards),
+``CLOCK_MONOTONIC`` (NTP corrections but never going backwards),
+``CLOCK_MONOTIC_RAW`` (without NTP corrections) and change the mode
+dynamically with sw_params
+
+
+The ALSA API also provide an audio_tstamp which reflects the passage
+of time as measured by different components of audio hardware. In
+ascii-art, this could be represented as follows (for the playback
+case):
+::
+
+ --------------------------------------------------------------> time
+ ^ ^ ^ ^ ^
+ | | | | |
+ analog link dma app FullBuffer
+ time time time time time
+ | | | | |
+ |< codec delay >|<--hw delay-->|<queued samples>|<---avail->|
+ |<----------------- delay---------------------->| |
+ |<----ring buffer length---->|
+
+
+The analog time is taken at the last stage of the playback, as close
+as possible to the actual transducer
+
+The link time is taken at the output of the SoC/chipset as the samples
+are pushed on a link. The link time can be directly measured if
+supported in hardware by sample counters or wallclocks (e.g. with
+HDAudio 24MHz or PTP clock for networked solutions) or indirectly
+estimated (e.g. with the frame counter in USB).
+
+The DMA time is measured using counters - typically the least reliable
+of all measurements due to the bursty nature of DMA transfers.
+
+The app time corresponds to the time tracked by an application after
+writing in the ring buffer.
+
+The application can query the hardware capabilities, define which
+audio time it wants reported by selecting the relevant settings in
+audio_tstamp_config fields, thus get an estimate of the timestamp
+accuracy. It can also request the delay-to-analog be included in the
+measurement. Direct access to the link time is very interesting on
+platforms that provide an embedded DSP; measuring directly the link
+time with dedicated hardware, possibly synchronized with system time,
+removes the need to keep track of internal DSP processing times and
+latency.
+
+In case the application requests an audio tstamp that is not supported
+in hardware/low-level driver, the type is overridden as DEFAULT and the
+timestamp will report the DMA time based on the hw_pointer value.
+
+For backwards compatibility with previous implementations that did not
+provide timestamp selection, with a zero-valued COMPAT timestamp type
+the results will default to the HDAudio wall clock for playback
+streams and to the DMA time (hw_ptr) in all other cases.
+
+The audio timestamp accuracy can be returned to user-space, so that
+appropriate decisions are made:
+
+- for dma time (default), the granularity of the transfers can be
+ inferred from the steps between updates and in turn provide
+ information on how much the application pointer can be rewound
+ safely.
+
+- the link time can be used to track long-term drifts between audio
+ and system time using the (tstamp-trigger_tstamp)/audio_tstamp
+ ratio, the precision helps define how much smoothing/low-pass
+ filtering is required. The link time can be either reset on startup
+ or reported as is (the latter being useful to compare progress of
+ different streams - but may require the wallclock to be always
+ running and not wrap-around during idle periods). If supported in
+ hardware, the absolute link time could also be used to define a
+ precise start time (patches WIP)
+
+- including the delay in the audio timestamp may
+ counter-intuitively not increase the precision of timestamps, e.g. if a
+ codec includes variable-latency DSP processing or a chain of
+ hardware components the delay is typically not known with precision.
+
+The accuracy is reported in nanosecond units (using an unsigned 32-bit
+word), which gives a max precision of 4.29s, more than enough for
+audio applications...
+
+Due to the varied nature of timestamping needs, even for a single
+application, the audio_tstamp_config can be changed dynamically. In
+the ``STATUS`` ioctl, the parameters are read-only and do not allow for
+any application selection. To work around this limitation without
+impacting legacy applications, a new ``STATUS_EXT`` ioctl is introduced
+with read/write parameters. ALSA-lib will be modified to make use of
+``STATUS_EXT`` and effectively deprecate ``STATUS``.
+
+The ALSA API only allows for a single audio timestamp to be reported
+at a time. This is a conscious design decision, reading the audio
+timestamps from hardware registers or from IPC takes time, the more
+timestamps are read the more imprecise the combined measurements
+are. To avoid any interpretation issues, a single (system, audio)
+timestamp is reported. Applications that need different timestamps
+will be required to issue multiple queries and perform an
+interpolation of the results
+
+In some hardware-specific configuration, the system timestamp is
+latched by a low-level audio subsystem, and the information provided
+back to the driver. Due to potential delays in the communication with
+the hardware, there is a risk of misalignment with the avail and delay
+information. To make sure applications are not confused, a
+driver_timestamp field is added in the snd_pcm_status structure; this
+timestamp shows when the information is put together by the driver
+before returning from the ``STATUS`` and ``STATUS_EXT`` ioctl. in most cases
+this driver_timestamp will be identical to the regular system tstamp.
+
+Examples of timestamping with HDAudio:
+
+1. DMA timestamp, no compensation for DMA+analog delay
+::
+
+ $ ./audio_time -p --ts_type=1
+ playback: systime: 341121338 nsec, audio time 342000000 nsec, systime delta -878662
+ playback: systime: 426236663 nsec, audio time 427187500 nsec, systime delta -950837
+ playback: systime: 597080580 nsec, audio time 598000000 nsec, systime delta -919420
+ playback: systime: 682059782 nsec, audio time 683020833 nsec, systime delta -961051
+ playback: systime: 852896415 nsec, audio time 853854166 nsec, systime delta -957751
+ playback: systime: 937903344 nsec, audio time 938854166 nsec, systime delta -950822
+
+2. DMA timestamp, compensation for DMA+analog delay
+::
+
+ $ ./audio_time -p --ts_type=1 -d
+ playback: systime: 341053347 nsec, audio time 341062500 nsec, systime delta -9153
+ playback: systime: 426072447 nsec, audio time 426062500 nsec, systime delta 9947
+ playback: systime: 596899518 nsec, audio time 596895833 nsec, systime delta 3685
+ playback: systime: 681915317 nsec, audio time 681916666 nsec, systime delta -1349
+ playback: systime: 852741306 nsec, audio time 852750000 nsec, systime delta -8694
+
+3. link timestamp, compensation for DMA+analog delay
+::
+
+ $ ./audio_time -p --ts_type=2 -d
+ playback: systime: 341060004 nsec, audio time 341062791 nsec, systime delta -2787
+ playback: systime: 426242074 nsec, audio time 426244875 nsec, systime delta -2801
+ playback: systime: 597080992 nsec, audio time 597084583 nsec, systime delta -3591
+ playback: systime: 682084512 nsec, audio time 682088291 nsec, systime delta -3779
+ playback: systime: 852936229 nsec, audio time 852940916 nsec, systime delta -4687
+ playback: systime: 938107562 nsec, audio time 938112708 nsec, systime delta -5146
+
+Example 1 shows that the timestamp at the DMA level is close to 1ms
+ahead of the actual playback time (as a side time this sort of
+measurement can help define rewind safeguards). Compensating for the
+DMA-link delay in example 2 helps remove the hardware buffering but
+the information is still very jittery, with up to one sample of
+error. In example 3 where the timestamps are measured with the link
+wallclock, the timestamps show a monotonic behavior and a lower
+dispersion.
+
+Example 3 and 4 are with USB audio class. Example 3 shows a high
+offset between audio time and system time due to buffering. Example 4
+shows how compensating for the delay exposes a 1ms accuracy (due to
+the use of the frame counter by the driver)
+
+Example 3: DMA timestamp, no compensation for delay, delta of ~5ms
+::
+
+ $ ./audio_time -p -Dhw:1 -t1
+ playback: systime: 120174019 nsec, audio time 125000000 nsec, systime delta -4825981
+ playback: systime: 245041136 nsec, audio time 250000000 nsec, systime delta -4958864
+ playback: systime: 370106088 nsec, audio time 375000000 nsec, systime delta -4893912
+ playback: systime: 495040065 nsec, audio time 500000000 nsec, systime delta -4959935
+ playback: systime: 620038179 nsec, audio time 625000000 nsec, systime delta -4961821
+ playback: systime: 745087741 nsec, audio time 750000000 nsec, systime delta -4912259
+ playback: systime: 870037336 nsec, audio time 875000000 nsec, systime delta -4962664
+
+Example 4: DMA timestamp, compensation for delay, delay of ~1ms
+::
+
+ $ ./audio_time -p -Dhw:1 -t1 -d
+ playback: systime: 120190520 nsec, audio time 120000000 nsec, systime delta 190520
+ playback: systime: 245036740 nsec, audio time 244000000 nsec, systime delta 1036740
+ playback: systime: 370034081 nsec, audio time 369000000 nsec, systime delta 1034081
+ playback: systime: 495159907 nsec, audio time 494000000 nsec, systime delta 1159907
+ playback: systime: 620098824 nsec, audio time 619000000 nsec, systime delta 1098824
+ playback: systime: 745031847 nsec, audio time 744000000 nsec, systime delta 1031847
diff --git a/Documentation/sound/designs/tracepoints.rst b/Documentation/sound/designs/tracepoints.rst
new file mode 100644
index 0000000000..b0a7e30101
--- /dev/null
+++ b/Documentation/sound/designs/tracepoints.rst
@@ -0,0 +1,172 @@
+===================
+Tracepoints in ALSA
+===================
+
+2017/07/02
+Takasahi Sakamoto
+
+Tracepoints in ALSA PCM core
+============================
+
+ALSA PCM core registers ``snd_pcm`` subsystem to kernel tracepoint system.
+This subsystem includes two categories of tracepoints; for state of PCM buffer
+and for processing of PCM hardware parameters. These tracepoints are available
+when corresponding kernel configurations are enabled. When ``CONFIG_SND_DEBUG``
+is enabled, the latter tracepoints are available. When additional
+``SND_PCM_XRUN_DEBUG`` is enabled too, the former trace points are enabled.
+
+Tracepoints for state of PCM buffer
+------------------------------------
+
+This category includes four tracepoints; ``hwptr``, ``applptr``, ``xrun`` and
+``hw_ptr_error``.
+
+Tracepoints for processing of PCM hardware parameters
+-----------------------------------------------------
+
+This category includes two tracepoints; ``hw_mask_param`` and
+``hw_interval_param``.
+
+In a design of ALSA PCM core, data transmission is abstracted as PCM substream.
+Applications manage PCM substream to maintain data transmission for PCM frames.
+Before starting the data transmission, applications need to configure PCM
+substream. In this procedure, PCM hardware parameters are decided by
+interaction between applications and ALSA PCM core. Once decided, runtime of
+the PCM substream keeps the parameters.
+
+The parameters are described in struct snd_pcm_hw_params. This
+structure includes several types of parameters. Applications set preferable
+value to these parameters, then execute ioctl(2) with SNDRV_PCM_IOCTL_HW_REFINE
+or SNDRV_PCM_IOCTL_HW_PARAMS. The former is used just for refining available
+set of parameters. The latter is used for an actual decision of the parameters.
+
+The struct snd_pcm_hw_params structure has below members:
+
+``flags``
+ Configurable. ALSA PCM core and some drivers handle this flag to select
+ convenient parameters or change their behaviour.
+``masks``
+ Configurable. This type of parameter is described in
+ struct snd_mask and represent mask values. As of PCM protocol
+ v2.0.13, three types are defined.
+
+ - SNDRV_PCM_HW_PARAM_ACCESS
+ - SNDRV_PCM_HW_PARAM_FORMAT
+ - SNDRV_PCM_HW_PARAM_SUBFORMAT
+``intervals``
+ Configurable. This type of parameter is described in
+ struct snd_interval and represent values with a range. As of
+ PCM protocol v2.0.13, twelve types are defined.
+
+ - SNDRV_PCM_HW_PARAM_SAMPLE_BITS
+ - SNDRV_PCM_HW_PARAM_FRAME_BITS
+ - SNDRV_PCM_HW_PARAM_CHANNELS
+ - SNDRV_PCM_HW_PARAM_RATE
+ - SNDRV_PCM_HW_PARAM_PERIOD_TIME
+ - SNDRV_PCM_HW_PARAM_PERIOD_SIZE
+ - SNDRV_PCM_HW_PARAM_PERIOD_BYTES
+ - SNDRV_PCM_HW_PARAM_PERIODS
+ - SNDRV_PCM_HW_PARAM_BUFFER_TIME
+ - SNDRV_PCM_HW_PARAM_BUFFER_SIZE
+ - SNDRV_PCM_HW_PARAM_BUFFER_BYTES
+ - SNDRV_PCM_HW_PARAM_TICK_TIME
+``rmask``
+ Configurable. This is evaluated at ioctl(2) with
+ SNDRV_PCM_IOCTL_HW_REFINE only. Applications can select which
+ mask/interval parameter can be changed by ALSA PCM core. For
+ SNDRV_PCM_IOCTL_HW_PARAMS, this mask is ignored and all of parameters
+ are going to be changed.
+``cmask``
+ Read-only. After returning from ioctl(2), buffer in user space for
+ struct snd_pcm_hw_params includes result of each operation.
+ This mask represents which mask/interval parameter is actually changed.
+``info``
+ Read-only. This represents hardware/driver capabilities as bit flags
+ with SNDRV_PCM_INFO_XXX. Typically, applications execute ioctl(2) with
+ SNDRV_PCM_IOCTL_HW_REFINE to retrieve this flag, then decide candidates
+ of parameters and execute ioctl(2) with SNDRV_PCM_IOCTL_HW_PARAMS to
+ configure PCM substream.
+``msbits``
+ Read-only. This value represents available bit width in MSB side of
+ a PCM sample. When a parameter of SNDRV_PCM_HW_PARAM_SAMPLE_BITS was
+ decided as a fixed number, this value is also calculated according to
+ it. Else, zero. But this behaviour depends on implementations in driver
+ side.
+``rate_num``
+ Read-only. This value represents numerator of sampling rate in fraction
+ notation. Basically, when a parameter of SNDRV_PCM_HW_PARAM_RATE was
+ decided as a single value, this value is also calculated according to
+ it. Else, zero. But this behaviour depends on implementations in driver
+ side.
+``rate_den``
+ Read-only. This value represents denominator of sampling rate in
+ fraction notation. Basically, when a parameter of
+ SNDRV_PCM_HW_PARAM_RATE was decided as a single value, this value is
+ also calculated according to it. Else, zero. But this behaviour depends
+ on implementations in driver side.
+``fifo_size``
+ Read-only. This value represents the size of FIFO in serial sound
+ interface of hardware. Basically, each driver can assigns a proper
+ value to this parameter but some drivers intentionally set zero with
+ a care of hardware design or data transmission protocol.
+
+ALSA PCM core handles buffer of struct snd_pcm_hw_params when
+applications execute ioctl(2) with SNDRV_PCM_HW_REFINE or SNDRV_PCM_HW_PARAMS.
+Parameters in the buffer are changed according to
+struct snd_pcm_hardware and rules of constraints in the runtime. The
+structure describes capabilities of handled hardware. The rules describes
+dependencies on which a parameter is decided according to several parameters.
+A rule has a callback function, and drivers can register arbitrary functions
+to compute the target parameter. ALSA PCM core registers some rules to the
+runtime as a default.
+
+Each driver can join in the interaction as long as it prepared for two stuffs
+in a callback of struct snd_pcm_ops.open.
+
+1. In the callback, drivers are expected to change a member of
+ struct snd_pcm_hardware type in the runtime, according to
+ capacities of corresponding hardware.
+2. In the same callback, drivers are also expected to register additional rules
+ of constraints into the runtime when several parameters have dependencies
+ due to hardware design.
+
+The driver can refers to result of the interaction in a callback of
+struct snd_pcm_ops.hw_params, however it should not change the
+content.
+
+Tracepoints in this category are designed to trace changes of the
+mask/interval parameters. When ALSA PCM core changes them, ``hw_mask_param`` or
+``hw_interval_param`` event is probed according to type of the changed parameter.
+
+ALSA PCM core also has a pretty print format for each of the tracepoints. Below
+is an example for ``hw_mask_param``.
+
+::
+
+ hw_mask_param: pcmC0D0p 001/023 FORMAT 00000000000000000000001000000044 00000000000000000000001000000044
+
+
+Below is an example for ``hw_interval_param``.
+
+::
+
+ hw_interval_param: pcmC0D0p 000/023 BUFFER_SIZE 0 0 [0 4294967295] 0 1 [0 4294967295]
+
+The first three fields are common. They represent name of ALSA PCM character
+device, rules of constraint and name of the changed parameter, in order. The
+field for rules of constraint consists of two sub-fields; index of applied rule
+and total number of rules added to the runtime. As an exception, the index 000
+means that the parameter is changed by ALSA PCM core, regardless of the rules.
+
+The rest of field represent state of the parameter before/after changing. These
+fields are different according to type of the parameter. For parameters of mask
+type, the fields represent hexadecimal dump of content of the parameter. For
+parameters of interval type, the fields represent values of each member of
+``empty``, ``integer``, ``openmin``, ``min``, ``max``, ``openmax`` in
+struct snd_interval in this order.
+
+Tracepoints in drivers
+======================
+
+Some drivers have tracepoints for developers' convenience. For them, please
+refer to each documentation or implementation.