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 Original line Diff line number Diff line
@@ -7,6 +7,7 @@ Designs and Implementations 
   control-names

   control-names

   channel-mapping-api

   channel-mapping-api

   compress-offload

   compress-offload

   timestamping

   procfile

   procfile

   powersave

   powersave

   oss-emulation

   oss-emulation

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

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

ALSA PCM Timestamping

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



The ALSA API can provide two different system timestamps:

The ALSA API can provide two different system timestamps:





- Trigger_tstamp is the system time snapshot taken when the .trigger

- 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 use of these different pointers and time information depends on

the application needs:

the application needs:





- 'avail' reports how much can be written in the ring buffer

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

- ``delay`` reports the time it will take to hear a new sample after all

  queued samples have been played out.

  queued samples have been played out.





When timestamps are enabled, the avail/delay information is reported

When timestamps are enabled, the avail/delay information is reported

along with a snapshot of system time. Applications can select from

along with a snapshot of system time. Applications can select from

CLOCK_REALTIME (NTP corrections including going backwards),

``CLOCK_REALTIME`` (NTP corrections including going backwards),

CLOCK_MONOTONIC (NTP corrections but never going backwards),

``CLOCK_MONOTONIC`` (NTP corrections but never going backwards),

CLOCK_MONOTIC_RAW (without NTP corrections) and change the mode

``CLOCK_MONOTIC_RAW`` (without NTP corrections) and change the mode

dynamically with sw_params

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

of time as measured by different components of audio hardware.  In

ascii-art, this could be represented as follows (for the playback

ascii-art, this could be represented as follows (for the playback

case):

case):



::





  --------------------------------------------------------------> time

  --------------------------------------------------------------> time

    ^               ^              ^                ^           ^

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

    |<----------------- delay---------------------->|           |

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

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







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

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

as possible to the actual transducer

as possible to the actual transducer
@@ -113,11 +118,11 @@ audio applications... 




Due to the varied nature of timestamping needs, even for a single

Due to the varied nature of timestamping needs, even for a single

application, the audio_tstamp_config can be changed dynamically. In

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

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

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

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

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

information. To make sure applications are not confused, a

driver_timestamp field is added in the snd_pcm_status structure; this

driver_timestamp field is added in the snd_pcm_status structure; this

timestamp shows when the information is put together by the driver

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.

this driver_timestamp will be identical to the regular system tstamp.





Examples of typestamping with HDaudio:

Examples of typestamping with HDaudio:





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

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

::



  $ ./audio_time  -p --ts_type=1

  $ ./audio_time  -p --ts_type=1

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

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

  playback: systime: 426236663 nsec, audio time 427187500 nsec, 	systime delta -950837

  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

  playback: systime: 937903344 nsec, audio time 938854166 nsec, 	systime delta -950822





2. DMA timestamp, compensation for DMA+analog delay

2. DMA timestamp, compensation for DMA+analog delay

::



  $ ./audio_time  -p --ts_type=1 -d

  $ ./audio_time  -p --ts_type=1 -d

  playback: systime: 341053347 nsec, audio time 341062500 nsec, 	systime delta -9153

  playback: systime: 341053347 nsec, audio time 341062500 nsec, 	systime delta -9153

  playback: systime: 426072447 nsec, audio time 426062500 nsec, 	systime delta 9947

  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

  playback: systime: 852741306 nsec, audio time 852750000 nsec, 	systime delta -8694





3. link timestamp, compensation for DMA+analog delay

3. link timestamp, compensation for DMA+analog delay

::



  $ ./audio_time  -p --ts_type=2 -d

  $ ./audio_time  -p --ts_type=2 -d

  playback: systime: 341060004 nsec, audio time 341062791 nsec, 	systime delta -2787

  playback: systime: 341060004 nsec, audio time 341062791 nsec, 	systime delta -2787

  playback: systime: 426242074 nsec, audio time 426244875 nsec, 	systime delta -2801

  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)

the use of the frame counter by the driver)





Example 3: DMA timestamp, no compensation for delay, delta of ~5ms

Example 3: DMA timestamp, no compensation for delay, delta of ~5ms

::



  $ ./audio_time -p -Dhw:1 -t1

  $ ./audio_time -p -Dhw:1 -t1

  playback: systime: 120174019 nsec, audio time 125000000 nsec, 	systime delta -4825981

  playback: systime: 120174019 nsec, audio time 125000000 nsec, 	systime delta -4825981

  playback: systime: 245041136 nsec, audio time 250000000 nsec, 	systime delta -4958864

  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

  playback: systime: 870037336 nsec, audio time 875000000 nsec, 	systime delta -4962664





Example 4: DMA timestamp, compensation for delay, delay of ~1ms

Example 4: DMA timestamp, compensation for delay, delay of ~1ms

::



  $ ./audio_time -p -Dhw:1 -t1 -d

  $ ./audio_time -p -Dhw:1 -t1 -d

  playback: systime: 120190520 nsec, audio time 120000000 nsec, 	systime delta 190520

  playback: systime: 120190520 nsec, audio time 120000000 nsec, 	systime delta 190520

  playback: systime: 245036740 nsec, audio time 244000000 nsec, 	systime delta 1036740

  playback: systime: 245036740 nsec, audio time 244000000 nsec, 	systime delta 1036740