216 lines · plain
1=====================2ALSA PCM Timestamping3=====================4 5The ALSA API can provide two different system timestamps:6 7- Trigger_tstamp is the system time snapshot taken when the .trigger8 callback is invoked. This snapshot is taken by the ALSA core in the9 general case, but specific hardware may have synchronization10 capabilities or conversely may only be able to provide a correct11 estimate with a delay. In the latter two cases, the low-level driver12 is responsible for updating the trigger_tstamp at the most appropriate13 and precise moment. Applications should not rely solely on the first14 trigger_tstamp but update their internal calculations if the driver15 provides a refined estimate with a delay.16 17- tstamp is the current system timestamp updated during the last18 event or application query.19 The difference (tstamp - trigger_tstamp) defines the elapsed time.20 21The ALSA API provides two basic pieces of information, avail22and delay, which combined with the trigger and current system23timestamps allow for applications to keep track of the 'fullness' of24the ring buffer and the amount of queued samples.25 26The use of these different pointers and time information depends on27the application needs:28 29- ``avail`` reports how much can be written in the ring buffer30- ``delay`` reports the time it will take to hear a new sample after all31 queued samples have been played out.32 33When timestamps are enabled, the avail/delay information is reported34along with a snapshot of system time. Applications can select from35``CLOCK_REALTIME`` (NTP corrections including going backwards),36``CLOCK_MONOTONIC`` (NTP corrections but never going backwards),37``CLOCK_MONOTIC_RAW`` (without NTP corrections) and change the mode38dynamically with sw_params39 40 41The ALSA API also provide an audio_tstamp which reflects the passage42of time as measured by different components of audio hardware. In43ascii-art, this could be represented as follows (for the playback44case):45::46 47 --------------------------------------------------------------> time48 ^ ^ ^ ^ ^49 | | | | |50 analog link dma app FullBuffer51 time time time time time52 | | | | |53 |< codec delay >|<--hw delay-->|<queued samples>|<---avail->|54 |<----------------- delay---------------------->| |55 |<----ring buffer length---->|56 57 58The analog time is taken at the last stage of the playback, as close59as possible to the actual transducer60 61The link time is taken at the output of the SoC/chipset as the samples62are pushed on a link. The link time can be directly measured if63supported in hardware by sample counters or wallclocks (e.g. with64HDAudio 24MHz or PTP clock for networked solutions) or indirectly65estimated (e.g. with the frame counter in USB).66 67The DMA time is measured using counters - typically the least reliable68of all measurements due to the bursty nature of DMA transfers.69 70The app time corresponds to the time tracked by an application after71writing in the ring buffer.72 73The application can query the hardware capabilities, define which74audio time it wants reported by selecting the relevant settings in75audio_tstamp_config fields, thus get an estimate of the timestamp76accuracy. It can also request the delay-to-analog be included in the77measurement. Direct access to the link time is very interesting on78platforms that provide an embedded DSP; measuring directly the link79time with dedicated hardware, possibly synchronized with system time,80removes the need to keep track of internal DSP processing times and81latency.82 83In case the application requests an audio tstamp that is not supported84in hardware/low-level driver, the type is overridden as DEFAULT and the85timestamp will report the DMA time based on the hw_pointer value.86 87For backwards compatibility with previous implementations that did not88provide timestamp selection, with a zero-valued COMPAT timestamp type89the results will default to the HDAudio wall clock for playback90streams and to the DMA time (hw_ptr) in all other cases.91 92The audio timestamp accuracy can be returned to user-space, so that93appropriate decisions are made:94 95- for dma time (default), the granularity of the transfers can be96 inferred from the steps between updates and in turn provide97 information on how much the application pointer can be rewound98 safely.99 100- the link time can be used to track long-term drifts between audio101 and system time using the (tstamp-trigger_tstamp)/audio_tstamp102 ratio, the precision helps define how much smoothing/low-pass103 filtering is required. The link time can be either reset on startup104 or reported as is (the latter being useful to compare progress of105 different streams - but may require the wallclock to be always106 running and not wrap-around during idle periods). If supported in107 hardware, the absolute link time could also be used to define a108 precise start time (patches WIP)109 110- including the delay in the audio timestamp may111 counter-intuitively not increase the precision of timestamps, e.g. if a112 codec includes variable-latency DSP processing or a chain of113 hardware components the delay is typically not known with precision.114 115The accuracy is reported in nanosecond units (using an unsigned 32-bit116word), which gives a max precision of 4.29s, more than enough for117audio applications...118 119Due to the varied nature of timestamping needs, even for a single120application, the audio_tstamp_config can be changed dynamically. In121the ``STATUS`` ioctl, the parameters are read-only and do not allow for122any application selection. To work around this limitation without123impacting legacy applications, a new ``STATUS_EXT`` ioctl is introduced124with read/write parameters. ALSA-lib will be modified to make use of125``STATUS_EXT`` and effectively deprecate ``STATUS``.126 127The ALSA API only allows for a single audio timestamp to be reported128at a time. This is a conscious design decision, reading the audio129timestamps from hardware registers or from IPC takes time, the more130timestamps are read the more imprecise the combined measurements131are. To avoid any interpretation issues, a single (system, audio)132timestamp is reported. Applications that need different timestamps133will be required to issue multiple queries and perform an134interpolation of the results135 136In some hardware-specific configuration, the system timestamp is137latched by a low-level audio subsystem, and the information provided138back to the driver. Due to potential delays in the communication with139the hardware, there is a risk of misalignment with the avail and delay140information. To make sure applications are not confused, a141driver_timestamp field is added in the snd_pcm_status structure; this142timestamp shows when the information is put together by the driver143before returning from the ``STATUS`` and ``STATUS_EXT`` ioctl. in most cases144this driver_timestamp will be identical to the regular system tstamp.145 146Examples of timestamping with HDAudio:147 1481. DMA timestamp, no compensation for DMA+analog delay149::150 151 $ ./audio_time -p --ts_type=1152 playback: systime: 341121338 nsec, audio time 342000000 nsec, systime delta -878662153 playback: systime: 426236663 nsec, audio time 427187500 nsec, systime delta -950837154 playback: systime: 597080580 nsec, audio time 598000000 nsec, systime delta -919420155 playback: systime: 682059782 nsec, audio time 683020833 nsec, systime delta -961051156 playback: systime: 852896415 nsec, audio time 853854166 nsec, systime delta -957751157 playback: systime: 937903344 nsec, audio time 938854166 nsec, systime delta -950822158 1592. DMA timestamp, compensation for DMA+analog delay160::161 162 $ ./audio_time -p --ts_type=1 -d163 playback: systime: 341053347 nsec, audio time 341062500 nsec, systime delta -9153164 playback: systime: 426072447 nsec, audio time 426062500 nsec, systime delta 9947165 playback: systime: 596899518 nsec, audio time 596895833 nsec, systime delta 3685166 playback: systime: 681915317 nsec, audio time 681916666 nsec, systime delta -1349167 playback: systime: 852741306 nsec, audio time 852750000 nsec, systime delta -8694168 1693. link timestamp, compensation for DMA+analog delay170::171 172 $ ./audio_time -p --ts_type=2 -d173 playback: systime: 341060004 nsec, audio time 341062791 nsec, systime delta -2787174 playback: systime: 426242074 nsec, audio time 426244875 nsec, systime delta -2801175 playback: systime: 597080992 nsec, audio time 597084583 nsec, systime delta -3591176 playback: systime: 682084512 nsec, audio time 682088291 nsec, systime delta -3779177 playback: systime: 852936229 nsec, audio time 852940916 nsec, systime delta -4687178 playback: systime: 938107562 nsec, audio time 938112708 nsec, systime delta -5146179 180Example 1 shows that the timestamp at the DMA level is close to 1ms181ahead of the actual playback time (as a side time this sort of182measurement can help define rewind safeguards). Compensating for the183DMA-link delay in example 2 helps remove the hardware buffering but184the information is still very jittery, with up to one sample of185error. In example 3 where the timestamps are measured with the link186wallclock, the timestamps show a monotonic behavior and a lower187dispersion.188 189Example 3 and 4 are with USB audio class. Example 3 shows a high190offset between audio time and system time due to buffering. Example 4191shows how compensating for the delay exposes a 1ms accuracy (due to192the use of the frame counter by the driver)193 194Example 3: DMA timestamp, no compensation for delay, delta of ~5ms195::196 197 $ ./audio_time -p -Dhw:1 -t1198 playback: systime: 120174019 nsec, audio time 125000000 nsec, systime delta -4825981199 playback: systime: 245041136 nsec, audio time 250000000 nsec, systime delta -4958864200 playback: systime: 370106088 nsec, audio time 375000000 nsec, systime delta -4893912201 playback: systime: 495040065 nsec, audio time 500000000 nsec, systime delta -4959935202 playback: systime: 620038179 nsec, audio time 625000000 nsec, systime delta -4961821203 playback: systime: 745087741 nsec, audio time 750000000 nsec, systime delta -4912259204 playback: systime: 870037336 nsec, audio time 875000000 nsec, systime delta -4962664205 206Example 4: DMA timestamp, compensation for delay, delay of ~1ms207::208 209 $ ./audio_time -p -Dhw:1 -t1 -d210 playback: systime: 120190520 nsec, audio time 120000000 nsec, systime delta 190520211 playback: systime: 245036740 nsec, audio time 244000000 nsec, systime delta 1036740212 playback: systime: 370034081 nsec, audio time 369000000 nsec, systime delta 1034081213 playback: systime: 495159907 nsec, audio time 494000000 nsec, systime delta 1159907214 playback: systime: 620098824 nsec, audio time 619000000 nsec, systime delta 1098824215 playback: systime: 745031847 nsec, audio time 744000000 nsec, systime delta 1031847216