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>

Documentation/sound/designs/index.rst

@@ -7,6 +7,7 @@ Designs and Implementations
    control-names
    channel-mapping-api
    compress-offload
+   timestamping
    procfile
    powersave
    oss-emulation

Documentation/sound/designs/timestamping.rst

@@ -1,3 +1,7 @@
+=====================
+ALSA PCM Timestamping
+=====================
+
 The ALSA API can provide two different system timestamps:
 
 - Trigger_tstamp is the system time snapshot taken when the .trigger
@@ -22,15 +26,15 @@ 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
+- ``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
+``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
 
 
@@ -38,7 +42,7 @@ 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
     ^               ^              ^                ^           ^
@@ -50,6 +54,7 @@ case):
     |<----------------- delay---------------------->|           |
                                    |<----ring buffer length---->|
 
+
 The analog time is taken at the last stage of the playback, as close
 as possible to the actual transducer
 
@@ -113,11 +118,11 @@ 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
+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
+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.
+``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
@@ -135,12 +140,14 @@ 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
+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
@@ -150,6 +157,8 @@ playback: systime: 852896415 nsec, audio time 853854166 nsec, 	systime delta -95
   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
@@ -158,6 +167,8 @@ playback: systime: 681915317 nsec, audio time 681916666 nsec, 	systime delta -13
   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
@@ -181,6 +192,8 @@ 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
@@ -191,6 +204,8 @@ playback: systime: 745087741 nsec, audio time 750000000 nsec, 	systime delta -49
   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