1 =====================
2 ALSA PCM Timestamping
3 =====================
4
5 The ALSA API can provide two different system
6
7 - Trigger_tstamp is the system time snapshot t
8 callback is invoked. This snapshot is taken
9 general case, but specific hardware may have
10 capabilities or conversely may only be able
11 estimate with a delay. In the latter two cas
12 is responsible for updating the trigger_tsta
13 and precise moment. Applications should not
14 trigger_tstamp but update their internal cal
15 provides a refined estimate with a delay.
16
17 - tstamp is the current system timestamp updat
18 event or application query.
19 The difference (tstamp - trigger_tstamp) def
20
21 The ALSA API provides two basic pieces of info
22 and delay, which combined with the trigger and
23 timestamps allow for applications to keep trac
24 the ring buffer and the amount of queued sampl
25
26 The use of these different pointers and time i
27 the application needs:
28
29 - ``avail`` reports how much can be written in
30 - ``delay`` reports the time it will take to h
31 queued samples have been played out.
32
33 When timestamps are enabled, the avail/delay i
34 along with a snapshot of system time. Applicat
35 ``CLOCK_REALTIME`` (NTP corrections including
36 ``CLOCK_MONOTONIC`` (NTP corrections but never
37 ``CLOCK_MONOTIC_RAW`` (without NTP corrections
38 dynamically with sw_params
39
40
41 The ALSA API also provide an audio_tstamp whic
42 of time as measured by different components of
43 ascii-art, this could be represented as follow
44 case):
45 ::
46
47 --------------------------------------------
48 ^ ^ ^
49 | | |
50 analog link dma
51 time time time
52 | | |
53 |< codec delay >|<--hw delay-->|<queued sa
54 |<----------------- delay-----------------
55 |<----ring
56
57
58 The analog time is taken at the last stage of
59 as possible to the actual transducer
60
61 The link time is taken at the output of the So
62 are pushed on a link. The link time can be dir
63 supported in hardware by sample counters or wa
64 HDAudio 24MHz or PTP clock for networked solut
65 estimated (e.g. with the frame counter in USB)
66
67 The DMA time is measured using counters - typi
68 of all measurements due to the bursty nature o
69
70 The app time corresponds to the time tracked b
71 writing in the ring buffer.
72
73 The application can query the hardware capabil
74 audio time it wants reported by selecting the
75 audio_tstamp_config fields, thus get an estima
76 accuracy. It can also request the delay-to-ana
77 measurement. Direct access to the link time is
78 platforms that provide an embedded DSP; measur
79 time with dedicated hardware, possibly synchro
80 removes the need to keep track of internal DSP
81 latency.
82
83 In case the application requests an audio tsta
84 in hardware/low-level driver, the type is over
85 timestamp will report the DMA time based on th
86
87 For backwards compatibility with previous impl
88 provide timestamp selection, with a zero-value
89 the results will default to the HDAudio wall c
90 streams and to the DMA time (hw_ptr) in all ot
91
92 The audio timestamp accuracy can be returned t
93 appropriate decisions are made:
94
95 - for dma time (default), the granularity of t
96 inferred from the steps between updates and
97 information on how much the application poin
98 safely.
99
100 - the link time can be used to track long-term
101 and system time using the (tstamp-trigger_ts
102 ratio, the precision helps define how much s
103 filtering is required. The link time can be
104 or reported as is (the latter being useful t
105 different streams - but may require the wall
106 running and not wrap-around during idle peri
107 hardware, the absolute link time could also
108 precise start time (patches WIP)
109
110 - including the delay in the audio timestamp m
111 counter-intuitively not increase the precisi
112 codec includes variable-latency DSP processi
113 hardware components the delay is typically n
114
115 The accuracy is reported in nanosecond units (
116 word), which gives a max precision of 4.29s, m
117 audio applications...
118
119 Due to the varied nature of timestamping needs
120 application, the audio_tstamp_config can be ch
121 the ``STATUS`` ioctl, the parameters are read-
122 any application selection. To work around this
123 impacting legacy applications, a new ``STATUS_
124 with read/write parameters. ALSA-lib will be m
125 ``STATUS_EXT`` and effectively deprecate ``STA
126
127 The ALSA API only allows for a single audio ti
128 at a time. This is a conscious design decision
129 timestamps from hardware registers or from IPC
130 timestamps are read the more imprecise the com
131 are. To avoid any interpretation issues, a sin
132 timestamp is reported. Applications that need
133 will be required to issue multiple queries and
134 interpolation of the results
135
136 In some hardware-specific configuration, the s
137 latched by a low-level audio subsystem, and th
138 back to the driver. Due to potential delays in
139 the hardware, there is a risk of misalignment
140 information. To make sure applications are not
141 driver_timestamp field is added in the snd_pcm
142 timestamp shows when the information is put to
143 before returning from the ``STATUS`` and ``STA
144 this driver_timestamp will be identical to the
145
146 Examples of timestamping with HDAudio:
147
148 1. DMA timestamp, no compensation for DMA+anal
149 ::
150
151 $ ./audio_time -p --ts_type=1
152 playback: systime: 341121338 nsec, audio tim
153 playback: systime: 426236663 nsec, audio tim
154 playback: systime: 597080580 nsec, audio tim
155 playback: systime: 682059782 nsec, audio tim
156 playback: systime: 852896415 nsec, audio tim
157 playback: systime: 937903344 nsec, audio tim
158
159 2. DMA timestamp, compensation for DMA+analog
160 ::
161
162 $ ./audio_time -p --ts_type=1 -d
163 playback: systime: 341053347 nsec, audio tim
164 playback: systime: 426072447 nsec, audio tim
165 playback: systime: 596899518 nsec, audio tim
166 playback: systime: 681915317 nsec, audio tim
167 playback: systime: 852741306 nsec, audio tim
168
169 3. link timestamp, compensation for DMA+analog
170 ::
171
172 $ ./audio_time -p --ts_type=2 -d
173 playback: systime: 341060004 nsec, audio tim
174 playback: systime: 426242074 nsec, audio tim
175 playback: systime: 597080992 nsec, audio tim
176 playback: systime: 682084512 nsec, audio tim
177 playback: systime: 852936229 nsec, audio tim
178 playback: systime: 938107562 nsec, audio tim
179
180 Example 1 shows that the timestamp at the DMA
181 ahead of the actual playback time (as a side t
182 measurement can help define rewind safeguards)
183 DMA-link delay in example 2 helps remove the h
184 the information is still very jittery, with up
185 error. In example 3 where the timestamps are m
186 wallclock, the timestamps show a monotonic beh
187 dispersion.
188
189 Example 3 and 4 are with USB audio class. Exam
190 offset between audio time and system time due
191 shows how compensating for the delay exposes a
192 the use of the frame counter by the driver)
193
194 Example 3: DMA timestamp, no compensation for
195 ::
196
197 $ ./audio_time -p -Dhw:1 -t1
198 playback: systime: 120174019 nsec, audio tim
199 playback: systime: 245041136 nsec, audio tim
200 playback: systime: 370106088 nsec, audio tim
201 playback: systime: 495040065 nsec, audio tim
202 playback: systime: 620038179 nsec, audio tim
203 playback: systime: 745087741 nsec, audio tim
204 playback: systime: 870037336 nsec, audio tim
205
206 Example 4: DMA timestamp, compensation for del
207 ::
208
209 $ ./audio_time -p -Dhw:1 -t1 -d
210 playback: systime: 120190520 nsec, audio tim
211 playback: systime: 245036740 nsec, audio tim
212 playback: systime: 370034081 nsec, audio tim
213 playback: systime: 495159907 nsec, audio tim
214 playback: systime: 620098824 nsec, audio tim
215 playback: systime: 745031847 nsec, audio tim
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.