120a1d0f4STakashi Iwai===================== 220a1d0f4STakashi IwaiALSA PCM Timestamping 320a1d0f4STakashi Iwai===================== 420a1d0f4STakashi Iwai 520a1d0f4STakashi IwaiThe ALSA API can provide two different system timestamps: 620a1d0f4STakashi Iwai 720a1d0f4STakashi Iwai- Trigger_tstamp is the system time snapshot taken when the .trigger 820a1d0f4STakashi Iwai callback is invoked. This snapshot is taken by the ALSA core in the 920a1d0f4STakashi Iwai general case, but specific hardware may have synchronization 1020a1d0f4STakashi Iwai capabilities or conversely may only be able to provide a correct 1120a1d0f4STakashi Iwai estimate with a delay. In the latter two cases, the low-level driver 1220a1d0f4STakashi Iwai is responsible for updating the trigger_tstamp at the most appropriate 1320a1d0f4STakashi Iwai and precise moment. Applications should not rely solely on the first 1420a1d0f4STakashi Iwai trigger_tstamp but update their internal calculations if the driver 1520a1d0f4STakashi Iwai provides a refined estimate with a delay. 1620a1d0f4STakashi Iwai 1720a1d0f4STakashi Iwai- tstamp is the current system timestamp updated during the last 1820a1d0f4STakashi Iwai event or application query. 1920a1d0f4STakashi Iwai The difference (tstamp - trigger_tstamp) defines the elapsed time. 2020a1d0f4STakashi Iwai 2120a1d0f4STakashi IwaiThe ALSA API provides two basic pieces of information, avail 2220a1d0f4STakashi Iwaiand delay, which combined with the trigger and current system 2320a1d0f4STakashi Iwaitimestamps allow for applications to keep track of the 'fullness' of 2420a1d0f4STakashi Iwaithe ring buffer and the amount of queued samples. 2520a1d0f4STakashi Iwai 2620a1d0f4STakashi IwaiThe use of these different pointers and time information depends on 2720a1d0f4STakashi Iwaithe application needs: 2820a1d0f4STakashi Iwai 2920a1d0f4STakashi Iwai- ``avail`` reports how much can be written in the ring buffer 3020a1d0f4STakashi Iwai- ``delay`` reports the time it will take to hear a new sample after all 3120a1d0f4STakashi Iwai queued samples have been played out. 3220a1d0f4STakashi Iwai 3320a1d0f4STakashi IwaiWhen timestamps are enabled, the avail/delay information is reported 3420a1d0f4STakashi Iwaialong with a snapshot of system time. Applications can select from 3520a1d0f4STakashi Iwai``CLOCK_REALTIME`` (NTP corrections including going backwards), 3620a1d0f4STakashi Iwai``CLOCK_MONOTONIC`` (NTP corrections but never going backwards), 3720a1d0f4STakashi Iwai``CLOCK_MONOTIC_RAW`` (without NTP corrections) and change the mode 3820a1d0f4STakashi Iwaidynamically with sw_params 3920a1d0f4STakashi Iwai 4020a1d0f4STakashi Iwai 4120a1d0f4STakashi IwaiThe ALSA API also provide an audio_tstamp which reflects the passage 4220a1d0f4STakashi Iwaiof time as measured by different components of audio hardware. In 4320a1d0f4STakashi Iwaiascii-art, this could be represented as follows (for the playback 4420a1d0f4STakashi Iwaicase): 4520a1d0f4STakashi Iwai:: 4620a1d0f4STakashi Iwai 4720a1d0f4STakashi Iwai --------------------------------------------------------------> time 4820a1d0f4STakashi Iwai ^ ^ ^ ^ ^ 4920a1d0f4STakashi Iwai | | | | | 5020a1d0f4STakashi Iwai analog link dma app FullBuffer 5120a1d0f4STakashi Iwai time time time time time 5220a1d0f4STakashi Iwai | | | | | 5320a1d0f4STakashi Iwai |< codec delay >|<--hw delay-->|<queued samples>|<---avail->| 5420a1d0f4STakashi Iwai |<----------------- delay---------------------->| | 5520a1d0f4STakashi Iwai |<----ring buffer length---->| 5620a1d0f4STakashi Iwai 5720a1d0f4STakashi Iwai 5820a1d0f4STakashi IwaiThe analog time is taken at the last stage of the playback, as close 5920a1d0f4STakashi Iwaias possible to the actual transducer 6020a1d0f4STakashi Iwai 6120a1d0f4STakashi IwaiThe link time is taken at the output of the SoC/chipset as the samples 6220a1d0f4STakashi Iwaiare pushed on a link. The link time can be directly measured if 6320a1d0f4STakashi Iwaisupported in hardware by sample counters or wallclocks (e.g. with 6420a1d0f4STakashi IwaiHDAudio 24MHz or PTP clock for networked solutions) or indirectly 6520a1d0f4STakashi Iwaiestimated (e.g. with the frame counter in USB). 6620a1d0f4STakashi Iwai 6720a1d0f4STakashi IwaiThe DMA time is measured using counters - typically the least reliable 6820a1d0f4STakashi Iwaiof all measurements due to the bursty nature of DMA transfers. 6920a1d0f4STakashi Iwai 7020a1d0f4STakashi IwaiThe app time corresponds to the time tracked by an application after 7120a1d0f4STakashi Iwaiwriting in the ring buffer. 7220a1d0f4STakashi Iwai 7320a1d0f4STakashi IwaiThe application can query the hardware capabilities, define which 7420a1d0f4STakashi Iwaiaudio time it wants reported by selecting the relevant settings in 7520a1d0f4STakashi Iwaiaudio_tstamp_config fields, thus get an estimate of the timestamp 7620a1d0f4STakashi Iwaiaccuracy. It can also request the delay-to-analog be included in the 7720a1d0f4STakashi Iwaimeasurement. Direct access to the link time is very interesting on 7820a1d0f4STakashi Iwaiplatforms that provide an embedded DSP; measuring directly the link 7920a1d0f4STakashi Iwaitime with dedicated hardware, possibly synchronized with system time, 8020a1d0f4STakashi Iwairemoves the need to keep track of internal DSP processing times and 8120a1d0f4STakashi Iwailatency. 8220a1d0f4STakashi Iwai 8320a1d0f4STakashi IwaiIn case the application requests an audio tstamp that is not supported 8420a1d0f4STakashi Iwaiin hardware/low-level driver, the type is overridden as DEFAULT and the 8520a1d0f4STakashi Iwaitimestamp will report the DMA time based on the hw_pointer value. 8620a1d0f4STakashi Iwai 8720a1d0f4STakashi IwaiFor backwards compatibility with previous implementations that did not 8820a1d0f4STakashi Iwaiprovide timestamp selection, with a zero-valued COMPAT timestamp type 8920a1d0f4STakashi Iwaithe results will default to the HDAudio wall clock for playback 9020a1d0f4STakashi Iwaistreams and to the DMA time (hw_ptr) in all other cases. 9120a1d0f4STakashi Iwai 9220a1d0f4STakashi IwaiThe audio timestamp accuracy can be returned to user-space, so that 9320a1d0f4STakashi Iwaiappropriate decisions are made: 9420a1d0f4STakashi Iwai 9520a1d0f4STakashi Iwai- for dma time (default), the granularity of the transfers can be 9620a1d0f4STakashi Iwai inferred from the steps between updates and in turn provide 9720a1d0f4STakashi Iwai information on how much the application pointer can be rewound 9820a1d0f4STakashi Iwai safely. 9920a1d0f4STakashi Iwai 10020a1d0f4STakashi Iwai- the link time can be used to track long-term drifts between audio 10120a1d0f4STakashi Iwai and system time using the (tstamp-trigger_tstamp)/audio_tstamp 10220a1d0f4STakashi Iwai ratio, the precision helps define how much smoothing/low-pass 10320a1d0f4STakashi Iwai filtering is required. The link time can be either reset on startup 10420a1d0f4STakashi Iwai or reported as is (the latter being useful to compare progress of 10520a1d0f4STakashi Iwai different streams - but may require the wallclock to be always 10620a1d0f4STakashi Iwai running and not wrap-around during idle periods). If supported in 10720a1d0f4STakashi Iwai hardware, the absolute link time could also be used to define a 10820a1d0f4STakashi Iwai precise start time (patches WIP) 10920a1d0f4STakashi Iwai 11020a1d0f4STakashi Iwai- including the delay in the audio timestamp may 11120a1d0f4STakashi Iwai counter-intuitively not increase the precision of timestamps, e.g. if a 11220a1d0f4STakashi Iwai codec includes variable-latency DSP processing or a chain of 11320a1d0f4STakashi Iwai hardware components the delay is typically not known with precision. 11420a1d0f4STakashi Iwai 11520a1d0f4STakashi IwaiThe accuracy is reported in nanosecond units (using an unsigned 32-bit 11620a1d0f4STakashi Iwaiword), which gives a max precision of 4.29s, more than enough for 11720a1d0f4STakashi Iwaiaudio applications... 11820a1d0f4STakashi Iwai 11920a1d0f4STakashi IwaiDue to the varied nature of timestamping needs, even for a single 12020a1d0f4STakashi Iwaiapplication, the audio_tstamp_config can be changed dynamically. In 12120a1d0f4STakashi Iwaithe ``STATUS`` ioctl, the parameters are read-only and do not allow for 12220a1d0f4STakashi Iwaiany application selection. To work around this limitation without 12320a1d0f4STakashi Iwaiimpacting legacy applications, a new ``STATUS_EXT`` ioctl is introduced 12420a1d0f4STakashi Iwaiwith read/write parameters. ALSA-lib will be modified to make use of 12520a1d0f4STakashi Iwai``STATUS_EXT`` and effectively deprecate ``STATUS``. 12620a1d0f4STakashi Iwai 12720a1d0f4STakashi IwaiThe ALSA API only allows for a single audio timestamp to be reported 12820a1d0f4STakashi Iwaiat a time. This is a conscious design decision, reading the audio 12920a1d0f4STakashi Iwaitimestamps from hardware registers or from IPC takes time, the more 13020a1d0f4STakashi Iwaitimestamps are read the more imprecise the combined measurements 13120a1d0f4STakashi Iwaiare. To avoid any interpretation issues, a single (system, audio) 13220a1d0f4STakashi Iwaitimestamp is reported. Applications that need different timestamps 13320a1d0f4STakashi Iwaiwill be required to issue multiple queries and perform an 13420a1d0f4STakashi Iwaiinterpolation of the results 13520a1d0f4STakashi Iwai 13620a1d0f4STakashi IwaiIn some hardware-specific configuration, the system timestamp is 13720a1d0f4STakashi Iwailatched by a low-level audio subsystem, and the information provided 13820a1d0f4STakashi Iwaiback to the driver. Due to potential delays in the communication with 13920a1d0f4STakashi Iwaithe hardware, there is a risk of misalignment with the avail and delay 14020a1d0f4STakashi Iwaiinformation. To make sure applications are not confused, a 14120a1d0f4STakashi Iwaidriver_timestamp field is added in the snd_pcm_status structure; this 14220a1d0f4STakashi Iwaitimestamp shows when the information is put together by the driver 14320a1d0f4STakashi Iwaibefore returning from the ``STATUS`` and ``STATUS_EXT`` ioctl. in most cases 14420a1d0f4STakashi Iwaithis driver_timestamp will be identical to the regular system tstamp. 14520a1d0f4STakashi Iwai 146*b79de57bSPierre-Louis BossartExamples of timestamping with HDAudio: 14720a1d0f4STakashi Iwai 14820a1d0f4STakashi Iwai1. DMA timestamp, no compensation for DMA+analog delay 14920a1d0f4STakashi Iwai:: 15020a1d0f4STakashi Iwai 15120a1d0f4STakashi Iwai $ ./audio_time -p --ts_type=1 15220a1d0f4STakashi Iwai playback: systime: 341121338 nsec, audio time 342000000 nsec, systime delta -878662 15320a1d0f4STakashi Iwai playback: systime: 426236663 nsec, audio time 427187500 nsec, systime delta -950837 15420a1d0f4STakashi Iwai playback: systime: 597080580 nsec, audio time 598000000 nsec, systime delta -919420 15520a1d0f4STakashi Iwai playback: systime: 682059782 nsec, audio time 683020833 nsec, systime delta -961051 15620a1d0f4STakashi Iwai playback: systime: 852896415 nsec, audio time 853854166 nsec, systime delta -957751 15720a1d0f4STakashi Iwai playback: systime: 937903344 nsec, audio time 938854166 nsec, systime delta -950822 15820a1d0f4STakashi Iwai 15920a1d0f4STakashi Iwai2. DMA timestamp, compensation for DMA+analog delay 16020a1d0f4STakashi Iwai:: 16120a1d0f4STakashi Iwai 16220a1d0f4STakashi Iwai $ ./audio_time -p --ts_type=1 -d 16320a1d0f4STakashi Iwai playback: systime: 341053347 nsec, audio time 341062500 nsec, systime delta -9153 16420a1d0f4STakashi Iwai playback: systime: 426072447 nsec, audio time 426062500 nsec, systime delta 9947 16520a1d0f4STakashi Iwai playback: systime: 596899518 nsec, audio time 596895833 nsec, systime delta 3685 16620a1d0f4STakashi Iwai playback: systime: 681915317 nsec, audio time 681916666 nsec, systime delta -1349 16720a1d0f4STakashi Iwai playback: systime: 852741306 nsec, audio time 852750000 nsec, systime delta -8694 16820a1d0f4STakashi Iwai 16920a1d0f4STakashi Iwai3. link timestamp, compensation for DMA+analog delay 17020a1d0f4STakashi Iwai:: 17120a1d0f4STakashi Iwai 17220a1d0f4STakashi Iwai $ ./audio_time -p --ts_type=2 -d 17320a1d0f4STakashi Iwai playback: systime: 341060004 nsec, audio time 341062791 nsec, systime delta -2787 17420a1d0f4STakashi Iwai playback: systime: 426242074 nsec, audio time 426244875 nsec, systime delta -2801 17520a1d0f4STakashi Iwai playback: systime: 597080992 nsec, audio time 597084583 nsec, systime delta -3591 17620a1d0f4STakashi Iwai playback: systime: 682084512 nsec, audio time 682088291 nsec, systime delta -3779 17720a1d0f4STakashi Iwai playback: systime: 852936229 nsec, audio time 852940916 nsec, systime delta -4687 17820a1d0f4STakashi Iwai playback: systime: 938107562 nsec, audio time 938112708 nsec, systime delta -5146 17920a1d0f4STakashi Iwai 18020a1d0f4STakashi IwaiExample 1 shows that the timestamp at the DMA level is close to 1ms 18120a1d0f4STakashi Iwaiahead of the actual playback time (as a side time this sort of 18220a1d0f4STakashi Iwaimeasurement can help define rewind safeguards). Compensating for the 18320a1d0f4STakashi IwaiDMA-link delay in example 2 helps remove the hardware buffering but 18420a1d0f4STakashi Iwaithe information is still very jittery, with up to one sample of 18520a1d0f4STakashi Iwaierror. In example 3 where the timestamps are measured with the link 18620a1d0f4STakashi Iwaiwallclock, the timestamps show a monotonic behavior and a lower 18720a1d0f4STakashi Iwaidispersion. 18820a1d0f4STakashi Iwai 18920a1d0f4STakashi IwaiExample 3 and 4 are with USB audio class. Example 3 shows a high 19020a1d0f4STakashi Iwaioffset between audio time and system time due to buffering. Example 4 19120a1d0f4STakashi Iwaishows how compensating for the delay exposes a 1ms accuracy (due to 19220a1d0f4STakashi Iwaithe use of the frame counter by the driver) 19320a1d0f4STakashi Iwai 19420a1d0f4STakashi IwaiExample 3: DMA timestamp, no compensation for delay, delta of ~5ms 19520a1d0f4STakashi Iwai:: 19620a1d0f4STakashi Iwai 19720a1d0f4STakashi Iwai $ ./audio_time -p -Dhw:1 -t1 19820a1d0f4STakashi Iwai playback: systime: 120174019 nsec, audio time 125000000 nsec, systime delta -4825981 19920a1d0f4STakashi Iwai playback: systime: 245041136 nsec, audio time 250000000 nsec, systime delta -4958864 20020a1d0f4STakashi Iwai playback: systime: 370106088 nsec, audio time 375000000 nsec, systime delta -4893912 20120a1d0f4STakashi Iwai playback: systime: 495040065 nsec, audio time 500000000 nsec, systime delta -4959935 20220a1d0f4STakashi Iwai playback: systime: 620038179 nsec, audio time 625000000 nsec, systime delta -4961821 20320a1d0f4STakashi Iwai playback: systime: 745087741 nsec, audio time 750000000 nsec, systime delta -4912259 20420a1d0f4STakashi Iwai playback: systime: 870037336 nsec, audio time 875000000 nsec, systime delta -4962664 20520a1d0f4STakashi Iwai 20620a1d0f4STakashi IwaiExample 4: DMA timestamp, compensation for delay, delay of ~1ms 20720a1d0f4STakashi Iwai:: 20820a1d0f4STakashi Iwai 20920a1d0f4STakashi Iwai $ ./audio_time -p -Dhw:1 -t1 -d 21020a1d0f4STakashi Iwai playback: systime: 120190520 nsec, audio time 120000000 nsec, systime delta 190520 21120a1d0f4STakashi Iwai playback: systime: 245036740 nsec, audio time 244000000 nsec, systime delta 1036740 21220a1d0f4STakashi Iwai playback: systime: 370034081 nsec, audio time 369000000 nsec, systime delta 1034081 21320a1d0f4STakashi Iwai playback: systime: 495159907 nsec, audio time 494000000 nsec, systime delta 1159907 21420a1d0f4STakashi Iwai playback: systime: 620098824 nsec, audio time 619000000 nsec, systime delta 1098824 21520a1d0f4STakashi Iwai playback: systime: 745031847 nsec, audio time 744000000 nsec, systime delta 1031847 216