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