ALSA: doc: ReSTize timestamping document

A simple conversion from a plain text file.
Put to designs subdirectory.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

1 files changed, 0 insertions, 200 deletions

diff --git a/Documentation/sound/alsa/timestamping.txt b/Documentation/sound/alsa/timestamping.txt
deleted file mode 100644
index 9d579aefbffd..000000000000
--- a/Documentation/sound/alsa/timestamping.txt
+++ /dev/null
@@ -1,200 +0,0 @@
-The ALSA API can provide two different system timestamps:
-
-- Trigger_tstamp is the system time snapshot taken when the .trigger
-callback is invoked. This snapshot is taken by the ALSA core in the
-general case, but specific hardware may have synchronization
-capabilities or conversely may only be able to provide a correct
-estimate with a delay. In the latter two cases, the low-level driver
-is responsible for updating the trigger_tstamp at the most appropriate
-and precise moment. Applications should not rely solely on the first
-trigger_tstamp but update their internal calculations if the driver
-provides a refined estimate with a delay.
-
-- tstamp is the current system timestamp updated during the last
-event or application query.
-The difference (tstamp - trigger_tstamp) defines the elapsed time.
-
-The ALSA API provides two basic pieces of information, avail
-and delay, which combined with the trigger and current system
-timestamps allow for applications to keep track of the 'fullness' of
-the ring buffer and the amount of queued samples.
-
-The use of these different pointers and time information depends on
-the application needs:
-
-- 'avail' reports how much can be written in the ring buffer
-- 'delay' reports the time it will take to hear a new sample after all
-queued samples have been played out.
-
-When timestamps are enabled, the avail/delay information is reported
-along with a snapshot of system time. Applications can select from
-CLOCK_REALTIME (NTP corrections including going backwards),
-CLOCK_MONOTONIC (NTP corrections but never going backwards),
-CLOCK_MONOTIC_RAW (without NTP corrections) and change the mode
-dynamically with sw_params
-
-
-The ALSA API also provide an audio_tstamp which reflects the passage
-of time as measured by different components of audio hardware.  In
-ascii-art, this could be represented as follows (for the playback
-case):
-
-
---------------------------------------------------------------> time
-  ^               ^              ^                ^           ^
-  |               |              |                |           |
- analog         link            dma              app       FullBuffer
- time           time           time              time        time
-  |               |              |                |           |
-  |< codec delay >|<--hw delay-->|<queued samples>|<---avail->|
-  |<----------------- delay---------------------->|           |
-			         |<----ring buffer length---->|
-
-The analog time is taken at the last stage of the playback, as close
-as possible to the actual transducer
-
-The link time is taken at the output of the SoC/chipset as the samples
-are pushed on a link. The link time can be directly measured if
-supported in hardware by sample counters or wallclocks (e.g. with
-HDAudio 24MHz or PTP clock for networked solutions) or indirectly
-estimated (e.g. with the frame counter in USB).
-
-The DMA time is measured using counters - typically the least reliable
-of all measurements due to the bursty nature of DMA transfers.
-
-The app time corresponds to the time tracked by an application after
-writing in the ring buffer.
-
-The application can query the hardware capabilities, define which
-audio time it wants reported by selecting the relevant settings in
-audio_tstamp_config fields, thus get an estimate of the timestamp
-accuracy. It can also request the delay-to-analog be included in the
-measurement. Direct access to the link time is very interesting on
-platforms that provide an embedded DSP; measuring directly the link
-time with dedicated hardware, possibly synchronized with system time,
-removes the need to keep track of internal DSP processing times and
-latency.
-
-In case the application requests an audio tstamp that is not supported
-in hardware/low-level driver, the type is overridden as DEFAULT and the
-timestamp will report the DMA time based on the hw_pointer value.
-
-For backwards compatibility with previous implementations that did not
-provide timestamp selection, with a zero-valued COMPAT timestamp type
-the results will default to the HDAudio wall clock for playback
-streams and to the DMA time (hw_ptr) in all other cases.
-
-The audio timestamp accuracy can be returned to user-space, so that
-appropriate decisions are made:
-
-- for dma time (default), the granularity of the transfers can be
-  inferred from the steps between updates and in turn provide
-  information on how much the application pointer can be rewound
-  safely.
-
-- the link time can be used to track long-term drifts between audio
-  and system time using the (tstamp-trigger_tstamp)/audio_tstamp
-  ratio, the precision helps define how much smoothing/low-pass
-  filtering is required. The link time can be either reset on startup
-  or reported as is (the latter being useful to compare progress of
-  different streams - but may require the wallclock to be always
-  running and not wrap-around during idle periods). If supported in
-  hardware, the absolute link time could also be used to define a
-  precise start time (patches WIP)
-
-- including the delay in the audio timestamp may
-  counter-intuitively not increase the precision of timestamps, e.g. if a
-  codec includes variable-latency DSP processing or a chain of
-  hardware components the delay is typically not known with precision.
-
-The accuracy is reported in nanosecond units (using an unsigned 32-bit
-word), which gives a max precision of 4.29s, more than enough for
-audio applications...
-
-Due to the varied nature of timestamping needs, even for a single
-application, the audio_tstamp_config can be changed dynamically. In
-the STATUS ioctl, the parameters are read-only and do not allow for
-any application selection. To work around this limitation without
-impacting legacy applications, a new STATUS_EXT ioctl is introduced
-with read/write parameters. ALSA-lib will be modified to make use of
-STATUS_EXT and effectively deprecate STATUS.
-
-The ALSA API only allows for a single audio timestamp to be reported
-at a time. This is a conscious design decision, reading the audio
-timestamps from hardware registers or from IPC takes time, the more
-timestamps are read the more imprecise the combined measurements
-are. To avoid any interpretation issues, a single (system, audio)
-timestamp is reported. Applications that need different timestamps
-will be required to issue multiple queries and perform an
-interpolation of the results
-
-In some hardware-specific configuration, the system timestamp is
-latched by a low-level audio subsystem, and the information provided
-back to the driver. Due to potential delays in the communication with
-the hardware, there is a risk of misalignment with the avail and delay
-information. To make sure applications are not confused, a
-driver_timestamp field is added in the snd_pcm_status structure; this
-timestamp shows when the information is put together by the driver
-before returning from the STATUS and STATUS_EXT ioctl. in most cases
-this driver_timestamp will be identical to the regular system tstamp.
-
-Examples of typestamping with HDaudio:
-
-1. DMA timestamp, no compensation for DMA+analog delay
-$ ./audio_time  -p --ts_type=1
-playback: systime: 341121338 nsec, audio time 342000000 nsec, 	systime delta -878662
-playback: systime: 426236663 nsec, audio time 427187500 nsec, 	systime delta -950837
-playback: systime: 597080580 nsec, audio time 598000000 nsec, 	systime delta -919420
-playback: systime: 682059782 nsec, audio time 683020833 nsec, 	systime delta -961051
-playback: systime: 852896415 nsec, audio time 853854166 nsec, 	systime delta -957751
-playback: systime: 937903344 nsec, audio time 938854166 nsec, 	systime delta -950822
-
-2. DMA timestamp, compensation for DMA+analog delay
-$ ./audio_time  -p --ts_type=1 -d
-playback: systime: 341053347 nsec, audio time 341062500 nsec, 	systime delta -9153
-playback: systime: 426072447 nsec, audio time 426062500 nsec, 	systime delta 9947
-playback: systime: 596899518 nsec, audio time 596895833 nsec, 	systime delta 3685
-playback: systime: 681915317 nsec, audio time 681916666 nsec, 	systime delta -1349
-playback: systime: 852741306 nsec, audio time 852750000 nsec, 	systime delta -8694
-
-3. link timestamp, compensation for DMA+analog delay
-$ ./audio_time  -p --ts_type=2 -d
-playback: systime: 341060004 nsec, audio time 341062791 nsec, 	systime delta -2787
-playback: systime: 426242074 nsec, audio time 426244875 nsec, 	systime delta -2801
-playback: systime: 597080992 nsec, audio time 597084583 nsec, 	systime delta -3591
-playback: systime: 682084512 nsec, audio time 682088291 nsec, 	systime delta -3779
-playback: systime: 852936229 nsec, audio time 852940916 nsec, 	systime delta -4687
-playback: systime: 938107562 nsec, audio time 938112708 nsec, 	systime delta -5146
-
-Example 1 shows that the timestamp at the DMA level is close to 1ms
-ahead of the actual playback time (as a side time this sort of
-measurement can help define rewind safeguards). Compensating for the
-DMA-link delay in example 2 helps remove the hardware buffering but
-the information is still very jittery, with up to one sample of
-error. In example 3 where the timestamps are measured with the link
-wallclock, the timestamps show a monotonic behavior and a lower
-dispersion.
-
-Example 3 and 4 are with USB audio class. Example 3 shows a high
-offset between audio time and system time due to buffering. Example 4
-shows how compensating for the delay exposes a 1ms accuracy (due to
-the use of the frame counter by the driver)
-
-Example 3: DMA timestamp, no compensation for delay, delta of ~5ms
-$ ./audio_time -p -Dhw:1 -t1
-playback: systime: 120174019 nsec, audio time 125000000 nsec, 	systime delta -4825981
-playback: systime: 245041136 nsec, audio time 250000000 nsec, 	systime delta -4958864
-playback: systime: 370106088 nsec, audio time 375000000 nsec, 	systime delta -4893912
-playback: systime: 495040065 nsec, audio time 500000000 nsec, 	systime delta -4959935
-playback: systime: 620038179 nsec, audio time 625000000 nsec, 	systime delta -4961821
-playback: systime: 745087741 nsec, audio time 750000000 nsec, 	systime delta -4912259
-playback: systime: 870037336 nsec, audio time 875000000 nsec, 	systime delta -4962664
-
-Example 4: DMA timestamp, compensation for delay, delay of ~1ms
-$ ./audio_time -p -Dhw:1 -t1 -d
-playback: systime: 120190520 nsec, audio time 120000000 nsec, 	systime delta 190520
-playback: systime: 245036740 nsec, audio time 244000000 nsec, 	systime delta 1036740
-playback: systime: 370034081 nsec, audio time 369000000 nsec, 	systime delta 1034081
-playback: systime: 495159907 nsec, audio time 494000000 nsec, 	systime delta 1159907
-playback: systime: 620098824 nsec, audio time 619000000 nsec, 	systime delta 1098824
-playback: systime: 745031847 nsec, audio time 744000000 nsec, 	systime delta 1031847