Documentation/sound/designs/timestamping.rst

Source file repositories/reference/linux-study-clean/Documentation/sound/designs/timestamping.rst

File Facts

System
Linux kernel
Corpus path
Documentation/sound/designs/timestamping.rst
Extension
.rst
Size
10975 bytes
Lines
216
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

=====================
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

Annotation

Implementation Notes