timestamping.rst 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215
  1. =====================
  2. ALSA PCM Timestamping
  3. =====================
  4. The ALSA API can provide two different system timestamps:
  5. - Trigger_tstamp is the system time snapshot taken when the .trigger
  6. callback is invoked. This snapshot is taken by the ALSA core in the
  7. general case, but specific hardware may have synchronization
  8. capabilities or conversely may only be able to provide a correct
  9. estimate with a delay. In the latter two cases, the low-level driver
  10. is responsible for updating the trigger_tstamp at the most appropriate
  11. and precise moment. Applications should not rely solely on the first
  12. trigger_tstamp but update their internal calculations if the driver
  13. provides a refined estimate with a delay.
  14. - tstamp is the current system timestamp updated during the last
  15. event or application query.
  16. The difference (tstamp - trigger_tstamp) defines the elapsed time.
  17. The ALSA API provides two basic pieces of information, avail
  18. and delay, which combined with the trigger and current system
  19. timestamps allow for applications to keep track of the 'fullness' of
  20. the ring buffer and the amount of queued samples.
  21. The use of these different pointers and time information depends on
  22. the application needs:
  23. - ``avail`` reports how much can be written in the ring buffer
  24. - ``delay`` reports the time it will take to hear a new sample after all
  25. queued samples have been played out.
  26. When timestamps are enabled, the avail/delay information is reported
  27. along with a snapshot of system time. Applications can select from
  28. ``CLOCK_REALTIME`` (NTP corrections including going backwards),
  29. ``CLOCK_MONOTONIC`` (NTP corrections but never going backwards),
  30. ``CLOCK_MONOTIC_RAW`` (without NTP corrections) and change the mode
  31. dynamically with sw_params
  32. The ALSA API also provide an audio_tstamp which reflects the passage
  33. of time as measured by different components of audio hardware. In
  34. ascii-art, this could be represented as follows (for the playback
  35. case):
  36. ::
  37. --------------------------------------------------------------> time
  38. ^ ^ ^ ^ ^
  39. | | | | |
  40. analog link dma app FullBuffer
  41. time time time time time
  42. | | | | |
  43. |< codec delay >|<--hw delay-->|<queued samples>|<---avail->|
  44. |<----------------- delay---------------------->| |
  45. |<----ring buffer length---->|
  46. The analog time is taken at the last stage of the playback, as close
  47. as possible to the actual transducer
  48. The link time is taken at the output of the SoC/chipset as the samples
  49. are pushed on a link. The link time can be directly measured if
  50. supported in hardware by sample counters or wallclocks (e.g. with
  51. HDAudio 24MHz or PTP clock for networked solutions) or indirectly
  52. estimated (e.g. with the frame counter in USB).
  53. The DMA time is measured using counters - typically the least reliable
  54. of all measurements due to the bursty nature of DMA transfers.
  55. The app time corresponds to the time tracked by an application after
  56. writing in the ring buffer.
  57. The application can query the hardware capabilities, define which
  58. audio time it wants reported by selecting the relevant settings in
  59. audio_tstamp_config fields, thus get an estimate of the timestamp
  60. accuracy. It can also request the delay-to-analog be included in the
  61. measurement. Direct access to the link time is very interesting on
  62. platforms that provide an embedded DSP; measuring directly the link
  63. time with dedicated hardware, possibly synchronized with system time,
  64. removes the need to keep track of internal DSP processing times and
  65. latency.
  66. In case the application requests an audio tstamp that is not supported
  67. in hardware/low-level driver, the type is overridden as DEFAULT and the
  68. timestamp will report the DMA time based on the hw_pointer value.
  69. For backwards compatibility with previous implementations that did not
  70. provide timestamp selection, with a zero-valued COMPAT timestamp type
  71. the results will default to the HDAudio wall clock for playback
  72. streams and to the DMA time (hw_ptr) in all other cases.
  73. The audio timestamp accuracy can be returned to user-space, so that
  74. appropriate decisions are made:
  75. - for dma time (default), the granularity of the transfers can be
  76. inferred from the steps between updates and in turn provide
  77. information on how much the application pointer can be rewound
  78. safely.
  79. - the link time can be used to track long-term drifts between audio
  80. and system time using the (tstamp-trigger_tstamp)/audio_tstamp
  81. ratio, the precision helps define how much smoothing/low-pass
  82. filtering is required. The link time can be either reset on startup
  83. or reported as is (the latter being useful to compare progress of
  84. different streams - but may require the wallclock to be always
  85. running and not wrap-around during idle periods). If supported in
  86. hardware, the absolute link time could also be used to define a
  87. precise start time (patches WIP)
  88. - including the delay in the audio timestamp may
  89. counter-intuitively not increase the precision of timestamps, e.g. if a
  90. codec includes variable-latency DSP processing or a chain of
  91. hardware components the delay is typically not known with precision.
  92. The accuracy is reported in nanosecond units (using an unsigned 32-bit
  93. word), which gives a max precision of 4.29s, more than enough for
  94. audio applications...
  95. Due to the varied nature of timestamping needs, even for a single
  96. application, the audio_tstamp_config can be changed dynamically. In
  97. the ``STATUS`` ioctl, the parameters are read-only and do not allow for
  98. any application selection. To work around this limitation without
  99. impacting legacy applications, a new ``STATUS_EXT`` ioctl is introduced
  100. with read/write parameters. ALSA-lib will be modified to make use of
  101. ``STATUS_EXT`` and effectively deprecate ``STATUS``.
  102. The ALSA API only allows for a single audio timestamp to be reported
  103. at a time. This is a conscious design decision, reading the audio
  104. timestamps from hardware registers or from IPC takes time, the more
  105. timestamps are read the more imprecise the combined measurements
  106. are. To avoid any interpretation issues, a single (system, audio)
  107. timestamp is reported. Applications that need different timestamps
  108. will be required to issue multiple queries and perform an
  109. interpolation of the results
  110. In some hardware-specific configuration, the system timestamp is
  111. latched by a low-level audio subsystem, and the information provided
  112. back to the driver. Due to potential delays in the communication with
  113. the hardware, there is a risk of misalignment with the avail and delay
  114. information. To make sure applications are not confused, a
  115. driver_timestamp field is added in the snd_pcm_status structure; this
  116. timestamp shows when the information is put together by the driver
  117. before returning from the ``STATUS`` and ``STATUS_EXT`` ioctl. in most cases
  118. this driver_timestamp will be identical to the regular system tstamp.
  119. Examples of timestamping with HDAudio:
  120. 1. DMA timestamp, no compensation for DMA+analog delay
  121. ::
  122. $ ./audio_time -p --ts_type=1
  123. playback: systime: 341121338 nsec, audio time 342000000 nsec, systime delta -878662
  124. playback: systime: 426236663 nsec, audio time 427187500 nsec, systime delta -950837
  125. playback: systime: 597080580 nsec, audio time 598000000 nsec, systime delta -919420
  126. playback: systime: 682059782 nsec, audio time 683020833 nsec, systime delta -961051
  127. playback: systime: 852896415 nsec, audio time 853854166 nsec, systime delta -957751
  128. playback: systime: 937903344 nsec, audio time 938854166 nsec, systime delta -950822
  129. 2. DMA timestamp, compensation for DMA+analog delay
  130. ::
  131. $ ./audio_time -p --ts_type=1 -d
  132. playback: systime: 341053347 nsec, audio time 341062500 nsec, systime delta -9153
  133. playback: systime: 426072447 nsec, audio time 426062500 nsec, systime delta 9947
  134. playback: systime: 596899518 nsec, audio time 596895833 nsec, systime delta 3685
  135. playback: systime: 681915317 nsec, audio time 681916666 nsec, systime delta -1349
  136. playback: systime: 852741306 nsec, audio time 852750000 nsec, systime delta -8694
  137. 3. link timestamp, compensation for DMA+analog delay
  138. ::
  139. $ ./audio_time -p --ts_type=2 -d
  140. playback: systime: 341060004 nsec, audio time 341062791 nsec, systime delta -2787
  141. playback: systime: 426242074 nsec, audio time 426244875 nsec, systime delta -2801
  142. playback: systime: 597080992 nsec, audio time 597084583 nsec, systime delta -3591
  143. playback: systime: 682084512 nsec, audio time 682088291 nsec, systime delta -3779
  144. playback: systime: 852936229 nsec, audio time 852940916 nsec, systime delta -4687
  145. playback: systime: 938107562 nsec, audio time 938112708 nsec, systime delta -5146
  146. Example 1 shows that the timestamp at the DMA level is close to 1ms
  147. ahead of the actual playback time (as a side time this sort of
  148. measurement can help define rewind safeguards). Compensating for the
  149. DMA-link delay in example 2 helps remove the hardware buffering but
  150. the information is still very jittery, with up to one sample of
  151. error. In example 3 where the timestamps are measured with the link
  152. wallclock, the timestamps show a monotonic behavior and a lower
  153. dispersion.
  154. Example 3 and 4 are with USB audio class. Example 3 shows a high
  155. offset between audio time and system time due to buffering. Example 4
  156. shows how compensating for the delay exposes a 1ms accuracy (due to
  157. the use of the frame counter by the driver)
  158. Example 3: DMA timestamp, no compensation for delay, delta of ~5ms
  159. ::
  160. $ ./audio_time -p -Dhw:1 -t1
  161. playback: systime: 120174019 nsec, audio time 125000000 nsec, systime delta -4825981
  162. playback: systime: 245041136 nsec, audio time 250000000 nsec, systime delta -4958864
  163. playback: systime: 370106088 nsec, audio time 375000000 nsec, systime delta -4893912
  164. playback: systime: 495040065 nsec, audio time 500000000 nsec, systime delta -4959935
  165. playback: systime: 620038179 nsec, audio time 625000000 nsec, systime delta -4961821
  166. playback: systime: 745087741 nsec, audio time 750000000 nsec, systime delta -4912259
  167. playback: systime: 870037336 nsec, audio time 875000000 nsec, systime delta -4962664
  168. Example 4: DMA timestamp, compensation for delay, delay of ~1ms
  169. ::
  170. $ ./audio_time -p -Dhw:1 -t1 -d
  171. playback: systime: 120190520 nsec, audio time 120000000 nsec, systime delta 190520
  172. playback: systime: 245036740 nsec, audio time 244000000 nsec, systime delta 1036740
  173. playback: systime: 370034081 nsec, audio time 369000000 nsec, systime delta 1034081
  174. playback: systime: 495159907 nsec, audio time 494000000 nsec, systime delta 1159907
  175. playback: systime: 620098824 nsec, audio time 619000000 nsec, systime delta 1098824
  176. playback: systime: 745031847 nsec, audio time 744000000 nsec, systime delta 1031847