Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 20a1d0f4 authored by Takashi Iwai's avatar Takashi Iwai
Browse files

ALSA: doc: ReSTize timestamping document 



A simple conversion from a plain text file.
Put to designs subdirectory.

Signed-off-by: default avatarTakashi Iwai <tiwai@suse.de>
parent e9df12c3

Documentation/sound/designs/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -7,6 +7,7 @@ Designs and Implementations 
   control-names

   channel-mapping-api

   compress-offload

   timestamping

   procfile

   powersave

   oss-emulation

Documentation/sound/alsa/timestamping.txt→Documentation/sound/designs/timestamping.rst

+79 −64
Original line number Diff line number Diff line 
=====================

ALSA PCM Timestamping

=====================



The ALSA API can provide two different system timestamps:



- Trigger_tstamp is the system time snapshot taken when the .trigger
@@ -22,15 +26,15 @@ 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

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

``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
@@ -38,7 +42,7 @@ 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

    ^               ^              ^                ^           ^
@@ -50,6 +54,7 @@ case): 
    |<----------------- delay---------------------->|           |

                                   |<----ring buffer length---->|





The analog time is taken at the last stage of the playback, as close

as possible to the actual transducer
@@ -113,11 +118,11 @@ 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

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

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.

``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
@@ -135,12 +140,14 @@ 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

before returning from the ``STATUS`` and ``STATUS_EXT`` ioctl. in most cases

this driver_timestamp will be identical to the regular system tstamp.



Examples of typestamping with HDaudio:



1. DMA timestamp, no compensation for DMA+analog delay

::



  $ ./audio_time  -p --ts_type=1

  playback: systime: 341121338 nsec, audio time 342000000 nsec, 	systime delta -878662

  playback: systime: 426236663 nsec, audio time 427187500 nsec, 	systime delta -950837
@@ -150,6 +157,8 @@ playback: systime: 852896415 nsec, audio time 853854166 nsec, systime delta -95 
  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
@@ -158,6 +167,8 @@ playback: systime: 681915317 nsec, audio time 681916666 nsec, systime delta -13 
  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
@@ -181,6 +192,8 @@ 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
@@ -191,6 +204,8 @@ playback: systime: 745087741 nsec, audio time 750000000 nsec, systime delta -49 
  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