UbiquitousOS
/
OpenCloudOS-Kernel
mirror of https://gitee.com/OpenCloudOS/OpenCloudOS-Kernel.git
11
0
Fork 0
Code Issues Projects Releases Wiki Activity

ALSA: doc: ReSTize timestamping document 

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

Signed-off-by: Takashi Iwai <tiwai@suse.de>
This commit is contained in:
Takashi Iwai 2016-11-10 11:06:55 +01:00
parent e9df12c3ba
commit 20a1d0f44d
2 changed files with 80 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Documentation/sound/designs/index.rst
View File

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

143
Documentation/sound/alsa/timestamping.txt → Documentation/sound/designs/timestamping.rst
View File

@ -1,18 +1,22 @@
=====================
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
callback is invoked. This snapshot is taken by the ALSA core in the callback is invoked. This snapshot is taken by the ALSA core in the
general case, but specific hardware may have synchronization general case, but specific hardware may have synchronization
capabilities or conversely may only be able to provide a correct capabilities or conversely may only be able to provide a correct
estimate with a delay. In the latter two cases, the low-level driver estimate with a delay. In the latter two cases, the low-level driver
is responsible for updating the trigger_tstamp at the most appropriate is responsible for updating the trigger_tstamp at the most appropriate
and precise moment. Applications should not rely solely on the first and precise moment. Applications should not rely solely on the first
trigger_tstamp but update their internal calculations if the driver trigger_tstamp but update their internal calculations if the driver
provides a refined estimate with a delay. provides a refined estimate with a delay.
- tstamp is the current system timestamp updated during the last - tstamp is the current system timestamp updated during the last
event or application query. event or application query.
The difference (tstamp - trigger_tstamp) defines the elapsed time. The difference (tstamp - trigger_tstamp) defines the elapsed time.
The ALSA API provides two basic pieces of information, avail The ALSA API provides two basic pieces of information, avail
and delay, which combined with the trigger and current system and delay, which combined with the trigger and current system
@ -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,17 +42,18 @@ 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
^ ^ ^ ^ ^
| | | | |
analog link dma app FullBuffer
time time time time time
| | | | |
|< codec delay >|<--hw delay-->|<queued samples>|<---avail->|
|<----------------- delay---------------------->| |
|<----ring buffer length---->|
--------------------------------------------------------------> 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 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,36 +140,42 @@ 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 ::
playback: systime: 341121338 nsec, audio time 342000000 nsec, systime delta -878662
playback: systime: 426236663 nsec, audio time 427187500 nsec, systime delta -950837 $ ./audio_time -p --ts_type=1
playback: systime: 597080580 nsec, audio time 598000000 nsec, systime delta -919420 playback: systime: 341121338 nsec, audio time 342000000 nsec, systime delta -878662
playback: systime: 682059782 nsec, audio time 683020833 nsec, systime delta -961051 playback: systime: 426236663 nsec, audio time 427187500 nsec, systime delta -950837
playback: systime: 852896415 nsec, audio time 853854166 nsec, systime delta -957751 playback: systime: 597080580 nsec, audio time 598000000 nsec, systime delta -919420
playback: systime: 937903344 nsec, audio time 938854166 nsec, systime delta -950822 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 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 $ ./audio_time -p --ts_type=1 -d
playback: systime: 596899518 nsec, audio time 596895833 nsec, systime delta 3685 playback: systime: 341053347 nsec, audio time 341062500 nsec, systime delta -9153
playback: systime: 681915317 nsec, audio time 681916666 nsec, systime delta -1349 playback: systime: 426072447 nsec, audio time 426062500 nsec, systime delta 9947
playback: systime: 852741306 nsec, audio time 852750000 nsec, systime delta -8694 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 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 $ ./audio_time -p --ts_type=2 -d
playback: systime: 597080992 nsec, audio time 597084583 nsec, systime delta -3591 playback: systime: 341060004 nsec, audio time 341062791 nsec, systime delta -2787
playback: systime: 682084512 nsec, audio time 682088291 nsec, systime delta -3779 playback: systime: 426242074 nsec, audio time 426244875 nsec, systime delta -2801
playback: systime: 852936229 nsec, audio time 852940916 nsec, systime delta -4687 playback: systime: 597080992 nsec, audio time 597084583 nsec, systime delta -3591
playback: systime: 938107562 nsec, audio time 938112708 nsec, systime delta -5146 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 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 ahead of the actual playback time (as a side time this sort of
@ -181,20 +192,24 @@ 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 ::
playback: systime: 120174019 nsec, audio time 125000000 nsec, systime delta -4825981
playback: systime: 245041136 nsec, audio time 250000000 nsec, systime delta -4958864 $ ./audio_time -p -Dhw:1 -t1
playback: systime: 370106088 nsec, audio time 375000000 nsec, systime delta -4893912 playback: systime: 120174019 nsec, audio time 125000000 nsec, systime delta -4825981
playback: systime: 495040065 nsec, audio time 500000000 nsec, systime delta -4959935 playback: systime: 245041136 nsec, audio time 250000000 nsec, systime delta -4958864
playback: systime: 620038179 nsec, audio time 625000000 nsec, systime delta -4961821 playback: systime: 370106088 nsec, audio time 375000000 nsec, systime delta -4893912
playback: systime: 745087741 nsec, audio time 750000000 nsec, systime delta -4912259 playback: systime: 495040065 nsec, audio time 500000000 nsec, systime delta -4959935
playback: systime: 870037336 nsec, audio time 875000000 nsec, systime delta -4962664 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 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 $ ./audio_time -p -Dhw:1 -t1 -d
playback: systime: 370034081 nsec, audio time 369000000 nsec, systime delta 1034081 playback: systime: 120190520 nsec, audio time 120000000 nsec, systime delta 190520
playback: systime: 495159907 nsec, audio time 494000000 nsec, systime delta 1159907 playback: systime: 245036740 nsec, audio time 244000000 nsec, systime delta 1036740
playback: systime: 620098824 nsec, audio time 619000000 nsec, systime delta 1098824 playback: systime: 370034081 nsec, audio time 369000000 nsec, systime delta 1034081
playback: systime: 745031847 nsec, audio time 744000000 nsec, systime delta 1031847 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