lastdragon/linux-kernel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Resguardo inicial

Browse Source
This commit is contained in:
lastdragon
2026-09-06 12:53:21 -06:00
parent 662efe3c2a
commit ad2088d178
94853 changed files with 43200404 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
linux-7.2.3/Documentation/sound/designs/channel-mapping-api.rst
+164
View File
@@ -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.
linux-7.2.3/Documentation/sound/designs/compress-accel.rst
+134
View File
@@ -0,0 +1,134 @@
==================================
ALSA Co-processor Acceleration API
==================================
Jaroslav Kysela <perex@perex.cz>
Overview
========
There is a requirement to expose the audio hardware that accelerates various
tasks for user space such as sample rate converters, compressed
stream decoders, etc.
This is description for the API extension for the compress ALSA API which
is able to handle "tasks" that are not bound to real-time operations
and allows for the serialization of operations.
Requirements
============
The main requirements are:
- serialization of multiple tasks for user space to allow multiple
operations without user space intervention
- separate buffers (input + output) for each operation
- expose buffers using mmap to user space
- signal user space when the task is finished (standard poll mechanism)
Design
======
A new direction SND_COMPRESS_ACCEL is introduced to identify
the passthrough API.
The API extension shares device enumeration and parameters handling from
the main compressed API. All other realtime streaming ioctls are deactivated
and a new set of task related ioctls are introduced. The standard
read/write/mmap I/O operations are not supported in the passthrough device.
Device ("stream") state handling is reduced to OPEN/SETUP. All other
states are not available for the passthrough mode.
Data I/O mechanism is using standard dma-buf interface with all advantages
like mmap, standard I/O, buffer sharing etc. One buffer is used for the
input data and second (separate) buffer is used for the output data. Each task
have separate I/O buffers.
For the buffering parameters, the fragments means a limit of allocated tasks
for given device. The fragment_size limits the input buffer size for the given
device. The output buffer size is determined by the driver (may be different
from the input buffer size).
State Machine
=============
The passthrough audio stream state machine is described below::
+----------+
| |
| OPEN |
| |
+----------+
|
|
| compr_set_params()
|
v
all passthrough task ops +----------+
+------------------------------------| |
| | SETUP |
| |
| +----------+
| |
+------------------------------------------+
Passthrough operations (ioctls)
===============================
All operations are protected using stream->device->lock (mutex).
CREATE
------
Creates a set of input/output buffers. The input buffer size is
fragment_size. Allocates unique seqno.
The hardware drivers allocate internal 'struct dma_buf' for both input and
output buffers (using 'dma_buf_export()' function). The anonymous
file descriptors for those buffers are passed to user space.
FREE
----
Free a set of input/output buffers. If a task is active, the stop
operation is executed before. If seqno is zero, operation is executed for all
tasks.
START
-----
Starts (queues) a task. There are two cases of the task start - right after
the task is created. In this case, origin_seqno must be zero.
The second case is for reusing of already finished task. The origin_seqno
must identify the task to be reused. In both cases, a new seqno value
is allocated and returned to user space.
The prerequisite is that application filled input dma buffer with
new source data and set input_size to pass the real data size to the driver.
The order of data processing is preserved (first started job must be
finished at first).
If the multiple tasks require a state handling (e.g. resampling operation),
the user space may set SND_COMPRESS_TFLG_NEW_STREAM flag to mark the
start of the new stream data. It is useful to keep the allocated buffers
for the new operation rather using open/close mechanism.
STOP
----
Stop (dequeues) a task. If seqno is zero, operation is executed for all
tasks.
STATUS
------
Obtain the task status (active, finished). Also, the driver will set
the real output data size (valid area in the output buffer).
Credits
=======
- Shengjiu Wang <shengjiu.wang@gmail.com>
- Takashi Iwai <tiwai@suse.de>
- Vinod Koul <vkoul@kernel.org>
linux-7.2.3/Documentation/sound/designs/compress-offload.rst
+329
View File
@@ -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.
linux-7.2.3/Documentation/sound/designs/control-names.rst
+142
View File
@@ -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)
============================================ ======================================
linux-7.2.3/Documentation/sound/designs/index.rst
+19
View File
@@ -0,0 +1,19 @@
Designs and Implementations
===========================
.. toctree::
:maxdepth: 2
control-names
channel-mapping-api
compress-accel
compress-offload
timestamping
jack-controls
tracepoints
procfile
powersave
oss-emulation
seq-oss
jack-injection
midi-2.0
linux-7.2.3/Documentation/sound/designs/jack-controls.rst
+48
View File
@@ -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.
linux-7.2.3/Documentation/sound/designs/jack-injection.rst
+166
View File
@@ -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
linux-7.2.3/Documentation/sound/designs/midi-2.0.rst
+584
View File
@@ -0,0 +1,584 @@
=================
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.
* The legacy rawmidi device number is found in the new `tied_device`
field of the rawmidi info.
On the other hand, the UMP rawmidi device number is found in
`tied_device` field of the legacy rawmidi info, too.
* Each substream of the legacy rawmidi may be enabled / disabled
dynamically depending on the UMP FB state.
When the selected substream is inactive, it's indicated by the bit
0x10 (`SNDRV_RAWMIDI_INFO_STREAM_INACTIVE`) in the `flags` field of
the legacy rawmidi info.
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.
* There are two extended event types for notifying the UMP Endpoint and
Function Block changes via the system announcement port:
type 68 (`SNDRV_SEQ_EVENT_UMP_EP_CHANGE`) and type 69
(`SNDRV_SEQ_EVENT_UMP_BLOCK_CHANGE`). They take the new type,
`snd_seq_ev_ump_notify` in the payload, indicating the client number
and the FB number that are changed.
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.
linux-7.2.3/Documentation/sound/designs/oss-emulation.rst
+336
View File
@@ -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.
linux-7.2.3/Documentation/sound/designs/powersave.rst
+43
View File
@@ -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/module/snd_ac97_codec/parameters/power_save`` (usually as root):
::
# echo 10 > /sys/module/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 hard 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.
linux-7.2.3/Documentation/sound/designs/procfile.rst
+238
View File
@@ -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/
linux-7.2.3/Documentation/sound/designs/seq-oss.rst
+371
View File
@@ -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.
linux-7.2.3/Documentation/sound/designs/timestamping.rst
+215
View File
@@ -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
linux-7.2.3/Documentation/sound/designs/tracepoints.rst
+172
View File
@@ -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.