Adding upstream version 4.19.249.upstream/4.19.249upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

11 files changed, 1990 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 000000000..58e6312a4
--- /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 000000000..ad4bfbdac
--- /dev/null
+++ b/Documentation/sound/designs/compress-offload.rst
@@ -0,0 +1,245 @@
+=========================
+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)
+
+
+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)
+
+
+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 000000000..7fedd0f33
--- /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 cannel
+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 000000000..f0749943c
--- /dev/null
+++ b/Documentation/sound/designs/index.rst
@@ -0,0 +1,16 @@
+Designs and Implementations
+===========================
+
+.. toctree::
+   :maxdepth: 2
+
+   control-names
+   channel-mapping-api
+   compress-offload
+   timestamping
+   jack-controls
+   tracepoints
+   procfile
+   powersave
+   oss-emulation
+   seq-oss
diff --git a/Documentation/sound/designs/jack-controls.rst b/Documentation/sound/designs/jack-controls.rst
new file mode 100644
index 000000000..ae25b1531
--- /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
+pluged 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/oss-emulation.rst b/Documentation/sound/designs/oss-emulation.rst
new file mode 100644
index 000000000..e8dcb9633
--- /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 000000000..138157452
--- /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 000000000..29a466851
--- /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_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 000000000..e82ffe0e7
--- /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
+      capabilties : 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 000000000..2b0fff503
--- /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 typestamping 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 000000000..78bc5572f
--- /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 :c:type:`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 :c:type:`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
+        :c:type:`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
+        :c:type:`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
+        :c:type:`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 :c:type:`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
+:c:type:`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 :c:type:`struct snd_pcm_ops.open`.
+
+1. In the callback, drivers are expected to change a member of
+   :c:type:`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
+:c:type:`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
+:c:type:`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.