"Fossies" - the Fresh Open Source Software Archive

Member "alsa-plugins-1.2.2/doc/aaf.txt" (19 Feb 2020, 6338 Bytes) of package /linux/misc/alsa-plugins-1.2.2.tar.bz2:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "aaf.txt" see the Fossies "Dox" file reference documentation.

    1 AVTP Audio Format (AAF) Plugin
    2 ==============================
    3 
    4 Overview
    5 --------
    6 
    7 The AAF plugin is a PCM plugin that uses Audio Video Transport Protocol (AVTP)
    8 to transmit/receive audio samples through a Time-Sensitive Network (TSN)
    9 capable network. The plugin enables media applications to easily implement AVTP
   10 Talker and Listener functionalities.
   11 
   12 AVTP is designed to take advantage of generalized Precision Time Protocol
   13 (gPTP) and Forwarding and Queuing Enhancements for Time-Sensitive Streams
   14 (FQTSS). gPTP ensures AVTP talkers and listeners share the same time reference
   15 so the presentation time from AVTP can be used to inform when PCM samples
   16 should be presented to the application layer. FQTSS provides bandwidth
   17 reservation and traffic prioritization for the AVTP stream.
   18 
   19 gPTP functionality is provided by the Linuxptp project while FQTSS
   20 functionality is provided by Linux Traffic Control system since kernel version
   21 4.15.
   22 
   23 gPTP Setup
   24 ----------
   25 
   26 The Linuxptp project provides the ptp4l daemon, which synchronizes the PTP
   27 clock from NIC, and the pmc tool which communicates with ptp4l to get/set
   28 some runtime settings. The project also provides the phc2sys daemon which
   29 synchronizes the PTP clock and system clock.
   30 
   31 The AAF Plugin requires system clock is synchronized with PTP clock and TAI
   32 offset is properly set in the kernel. ptp4l and phc2sys can be set up in many
   33 different ways, below we provide an example that fullfils the plugin
   34 requirements. For further information check ptp4l(8) and phc2sys(8).
   35 
   36 In the following instructions, replace $IFNAME by your PTP capable NIC
   37 interface. The gPTP.cfg file mentioned below can be found in /usr/share/
   38 doc/linuxptp/ (depending on your distro).
   39 
   40 Synchronize PTP clock with PTP time:
   41 
   42 	$ ptp4l -f gPTP.cfg -i $IFNAME
   43 
   44 Enable TAI offset to be automatically set by phc2sys:
   45 
   46 	$ pmc -u -t 1 -b 0 'SET GRANDMASTER_SETTINGS_NP \
   47 		clockClass 248 clockAccuracy 0xfe \
   48 		offsetScaledLogVariance 0xffff \
   49 		currentUtcOffset 37 leap61 0 leap59 0 \
   50 		currentUtcOffsetValid 1 pTimescale 1 \
   51 		timeTraceable 1 frequencyTraceable 0 timeSource 0xa0'
   52 
   53 Synchronize system clock with PTP clock:
   54 
   55 	$ phc2sys -f gPTP.cfg -s $IFNAME -c CLOCK_REALTIME -w
   56 
   57 The commands above should be run on both AVTP Talker and Listener hosts.
   58 
   59 Traffic Control Setup
   60 ---------------------
   61 
   62 The Linux Traffic Control system provides the mqprio and cbs qdiscs which
   63 enable FQTSS on Linux. Below we provide an example to configure those qdiscs in
   64 order to transmit an AAF stream with the following features: class A, 6 audio
   65 frames per AVTPDU, 48 kHz sampling rate, 16-bit sample size, stereo. For
   66 further information on how to configure these qdiscs check tc-mqprio(8) and
   67 tc-cbs(8) man pages.
   68 
   69 On the host that will run as AVTP Talker (i.e. plugin in playback mode), run
   70 the following commands:
   71 
   72 Configure mpqrio qdisc (replace $MQPRIO_HANDLE_ID by an unused handle ID):
   73 
   74 	$ tc qdisc add dev $IFNAME parent root handle $MQPRIO_HANDLE_ID \
   75 			mqprio num_tc 3 map 2 2 1 0 2 2 2 2 2 2 2 2 2 2 2 2 \
   76 			queues 1@0 1@1 2@2 hw 0
   77 
   78 Configure cbs qdisc (replace $CBS_HANDLE_ID by an unused handle ID):
   79 
   80 	$ tc qdisc replace dev $IFNAME parent $MQPRIO_HANDLE_ID:1 \
   81 			handle $CBS_HANDLE_ID cbs idleslope 5760 \
   82 			sendslope -994240 hicredit 9 locredit -89 offload 1
   83 
   84 The plugin implements a transmission mechanism that relies on ETF qdisc so make
   85 sure it is properly configured in the system. It could be configured many way,
   86 below follows an example.
   87 
   88 	$ tc qdisc add dev $IFNAME parent $CBS_HANDLE_ID:1 etf \
   89 			clockid CLOCK_TAI delta 500000 offload
   90 
   91 No Traffic Control configuration is required at the host running as AVTP
   92 Listener.
   93 
   94 Plugin Dependencies
   95 -------------------
   96 
   97 The AAF plugin uses libavtp to handle AVTP packetization. Libavtp source code
   98 can be found in https://github.com/AVnu/libavtp as well as instructions to
   99 build and install it.
  100 
  101 The plugin also depends on some kernel API headers such as linux/if_ether.h so
  102 make sure you have them installed in your system.
  103 
  104 If libavtp or the kernel headers aren't detected by configure, the plugin isn't
  105 built.
  106 
  107 Plugin Configuration
  108 --------------------
  109 
  110 The plugin parameters are passed via ALSA configuration file. They are defined
  111 as follows:
  112 
  113 	* ifname: Network interface used to transmit/receive AVTP packets.
  114 
  115 	* addr: Stream destination MAC address.
  116 
  117 	* prio: Priority used by the plugin to transmit AVTP traffic. This
  118 	  option is relevant only when operating in playback mode.
  119 
  120 	* streamid: Stream ID associated with the AAF stream transmitted or
  121 	  received by the plugin.
  122 
  123 	* mtt: Maximum Transit Time (in microseconds) as defined in AVTP spec
  124 	  section 4.3.3. This option is relevant only when operating in
  125 	  playback mode.
  126 
  127 	* time_uncertainty: Maximum Time Uncertainty (in microseconds) as
  128 	  defined by AVTP spec section 4.3.3. This option is relevant only when
  129 	  operating in playback mode.
  130 
  131 	* frames_per_pdu: Number of audio frames transmitted in one AVTPDU.
  132 
  133 	* ptime_tolerance: Presentation time tolerance in microseconds.
  134 	  AVTPDUs with presentation time off by +- ptime_tolerance are not
  135 	  considered invalid. This option is relevant only when operating in
  136 	  capture mode.
  137 
  138 Plugin Usage
  139 ------------
  140 
  141 The plugin provides the PCM type "aaf". Configure an AAF PCM virtual device
  142 according to the AAF stream you want to transmit or receive. A hypothetical
  143 configuration for the stream described in the 'FQTSS Setup' section is shown
  144 below:
  145 
  146 	pcm.aaf0 {
  147 		type aaf
  148 		ifname eth0
  149 		addr 01:AA:AA:AA:AA:AA
  150 		prio 3
  151 		streamid AA:BB:CC:DD:EE:FF:0000
  152 		mtt 2000
  153 		time_uncertainty 125
  154 		frames_per_pdu 6
  155 		ptime_tolerance 100
  156 	}
  157 
  158 Put the above to ~/.asoundrc (or /etc/asound.conf), and use the AAF PCM virtual
  159 device 'aaf0' with your favorite alsa-utils tool. Note that the plugin requires
  160 the period size is multiple of the 'frames_per_pdu' configuration.
  161 
  162 For example, to stream the pink noise generated by 'speaker-test', run:
  163 
  164 	$ speaker-test -F S16_BE -c 2 -r 48000 -D aaf0 -p 12500
  165 
  166 To receive the AAF stream generated by the command above, run the following
  167 command in another host:
  168 
  169 	$ arecord -t raw -f S16_BE -c 2 -r 48000 -D aaf0 -vv /dev/null -F 12500
  170 
  171 If you want to playback the contents of the AAF stream, change the command-line
  172 above so the output from 'arecord' is redirected to 'aplay', or simply use the
  173 'alsaloop' tool.