diff options
Diffstat (limited to 'lib/avtp_pipeline/documents')
5 files changed, 58 insertions, 137 deletions
diff --git a/lib/avtp_pipeline/documents/sdk_avtp_interface_module_dev.md b/lib/avtp_pipeline/documents/sdk_avtp_interface_module_dev.md index 4e6fb69f..aedd7e37 100644 --- a/lib/avtp_pipeline/documents/sdk_avtp_interface_module_dev.md +++ b/lib/avtp_pipeline/documents/sdk_avtp_interface_module_dev.md @@ -7,6 +7,7 @@ Interface modules are the components that sit between the core AVB stack and the platform device drivers that supply access to media hardware. <br> + The Plug-in Architecture {#sdk_avtp_intf_module_plugin} ======================== The OPENAVB AVB stack has a plug-in architecture for the AVTP implementation in the @@ -63,6 +64,7 @@ callback list for the interface module to call into the media queue to access and work with the media queue. <br> + Task / Thread Model {#sdk_avtp_intf_module_task} ================= In the general case the task / threading (hereafter referred to as task) model @@ -85,6 +87,7 @@ it can only be accessed within the scope of a callback into the interface module. <br> + Building an Interface Module {#sdk_avtp_intf_module_building} ============================ There should be minimal dependencies for creation of an interface module. The @@ -96,6 +99,7 @@ handled via callbacks that are available to the interface module in the media queue structure it receives as a parameter on its own callbacks. <br> + Interface Module in a Talker {#sdk_avtp_intf_module_talker} ============================ An interface module when used in a talker pulls data from a media source and @@ -103,12 +107,14 @@ pushes it onto the media queue in the format expected by the mapping module configured for that stream. <br> + Interface Module in a Listener {#sdk_avtp_intf_module_listener} ============================== When called from a listener it pulls data from the media queue and pushes it to the media sink for presentation. <br> + Working With the Media Queue {#working_with_mediaq} ============================ The media queue is the conduit between interface modules and mapping modules. @@ -151,6 +157,7 @@ For a detailed work flow please visit [Media Queue Usage](@ref sdk_notes_media_queue_usage) <br> + Timestamps {#sdk_avtp_intf_module_timestamps} ========== For interface modules often the only requirement for timestamps is to assign a diff --git a/lib/avtp_pipeline/documents/sdk_avtp_stream_cfg.md b/lib/avtp_pipeline/documents/sdk_avtp_stream_cfg.md index f96d0a0e..f254898b 100644 --- a/lib/avtp_pipeline/documents/sdk_avtp_stream_cfg.md +++ b/lib/avtp_pipeline/documents/sdk_avtp_stream_cfg.md @@ -54,7 +54,7 @@ void h264_SampleListenerCfg(openavb_tl_cfg_t *cfg) // On the talker this value is added to the PTP walltime to create the AVTP Timestamp. // On the listener this value is used to validate an expected valid timestamp range. // Note: For the listener the map_nv_item_count value must be set large enough to - // allow buffering at least as many AVTP packets that can be transmitted during this + // allow buffering at least as many AVTP packets that can be transmitted during this // max transit time. cfg->max_transit_usec = 2000; @@ -119,8 +119,8 @@ void h264_SampleListenerCfg(openavb_tl_cfg_t *cfg) // cfg->libCfgNames[cfgIdx] = "map_nv_tx_rate"; // cfg->libCfgValues[cfgIdx++] = "8000"; - // map_nv_max_payload_size: This is the max RTP payload size. See RFC 6184 for details, - // 1412 is the default size + // map_nv_max_payload_size: This is the max RTP payload size. See RFC 6184 for details, + // 1412 is the default size cfg->libCfgNames[cfgIdx] = "map_nv_max_payload_size"; cfg->libCfgValues[cfgIdx++] = "1412"; @@ -153,109 +153,34 @@ void h264_SampleListenerCfg(openavb_tl_cfg_t *cfg) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ <br> + Common Stream Configuration {#sdk_avtp_stream_cfg_common} =========================== These are common stream configuration values. Name | Description --------------------|------------ -role |Sets the process as a talker or listener. Valid values are\ - *talker* or *listener*. -stream_addr |Used on the listener and should be set to the mac address \ - of the talker. -stream_uid |The unique stream ID. The talker and listener must both \ - have this set the same. -dest_addr |Destination multicast address for the stream.<br> \ - If using \ - <ul><li><b>with MAAP</b> - dynamic destination addresses \ - are generated automatically by the talker and passed to \ - the listener, and don't need to be configured.</li> \ - <li><b>without MAAP</b>, locally administered (static) \ - addresses must be configured. Those addresses are in the \ - range of: 91:E0:F0:00:FE:00 - 91:E0:F0:00:FE:FF. Typically\ - use :00 for the first stream, :01 for the second, etc. \ - </li></ul> \ - If <b>SRP</b> \ - <ul><li><b>is being</b> used the static destination \ - address only needs to be set in the talker;</li> \ - <li><b>is not being</b> used the destination address need \ - to be set (to the same value) in both the talker and \ - listener.</li></ul> \ - The destination is a multicast address, not a real MAC \ - address, so it does not match the talker or listener's \ - interface MAC. There are several pools of those addresses \ - for use by AVTP defined in 1722. -max_interval_frames |The maximum number of packets that will be sent during an \ - observation interval. This is only used on the talker. +role |Sets the process as a talker or listener. Valid values are *talker* or *listener*. +stream_addr |Used on the listener and should be set to the mac address of the talker. If not specified on the talker, the talker's detected mac address will be used.<br>If AVDECC is being used, this does not need to be specified for the listener, as AVDECC will tell the listener which value to use. +stream_uid |The unique stream ID. The talker and listener must both have this set the same.<br>If AVDECC is being used, this does not need to be specified for the listener, as AVDECC will tell the listener which value to use. +dest_addr |Destination multicast address for the stream.<br>If using<ul><li><b>with MAAP</b> - dynamic destination addresses are generated automatically by the talker and passed to the listener, and don't need to be configured.<br>However, it is recommended that a locally administered (static) address still be configured, as the dest_addr will be used if the MAAP daemon is not available.</li><li><b>without MAAP</b>, locally administered (static) addresses must be configured. Those addresses are in the range of: 91:E0:F0:00:FE:00 - 91:E0:F0:00:FE:FF. Typically use :00 for the first stream, :01 for the second, etc. </li></ul> If <b>SRP</b> <ul><li><b>is being</b> used the static destination address only needs to be set in the talker;</li> <li><b>is not being</b> used the destination address need to be set (to the same value) in both the talker and listener.</li></ul> The destination is a multicast address, not a real MAC address, so it does not match the talker or listener's interface MAC. There are several pools of those addresses for use by AVTP defined in 1722. +max_interval_frames |The maximum number of packets that will be sent during an observation interval. This is only used on the talker. max_frame_size |Maximum size of the frame -sr_class |A talker only setting. Values are either A or B. If not \ - set an internal default is used. -sr_rank |A talker only setting. If not set an internal default is \ - used. -max_transit_usec |Allows manually specifying a maximum transit time. \ - <ul><li><b>On the talker</b> this value is added to the \ - PTP walltime to create the AVTP Timestamp.</li> \ - <li><b>On the listener</b> this value is used to validate \ - an expected valid timestamp range.</li></ul> \ - <b>Note:</b> For the listener the map_nv_item_count value \ - must be set large enough to allow buffering at least as \ - many AVTP packets that can be transmitted during this max \ - transit time. -max_transmit_deficit_usec |Allows setting the maximum packet transmit rate \ - deficit that will be recovered when a talker falls behind.\ - <p>When a talker can not keep up with the specified \ - transmit rate it builds up a deficit and will attempt to \ - make up for this deficit by sending more packets. There is\ - normally some variability in the transmit rate because of \ - other demands on the system so this is expected. However, \ - without this bounding value the deficit could grew too \ - large in cases such where more streams are started than \ - the system can support and when the number of streams is \ - reduced the remaining streams will attempt to recover this\ - deficit by sending packets at a higher rate. This can \ - cause a problem at the listener side and significantly \ - delay the recovery time before media playback will return \ - to normal.</p> \ - <p>Typically this value can be set to the expected buffer \ - size (in usec) that listeners are expected to be \ - buffering.<br> \ - For low latency solutions this is normally a small value. \ - For non-live media playback such as video playback the \ - listener side buffers can often be large enough to held \ - many seconds of data.</p> \ - <b>Note:</b> This is only used on a talker side. -internal_latency |Allows mannually specifying an internal latency time. This\ - is used only on the talker. -max_stale |The number of microseconds beyond the presentation time \ - that media queue items will be purged because they are too\ - old (past the presentation time).<br> \ - This is only used on listener end stations. \ - <p><b>Note:</b> needing to purge old media queue items is \ - often a sign of some other problem.<br> \ - For example: a delay at stream startup before incoming \ - packets are ready to be processed by the media sink.<br> \ - If this deficit in processing or purging the old (stale) \ - packets is not handled, syncing multiple listeners will be\ - problematic.</p> -raw_tx_buffers |The number of raw socket transmit buffers. Typically 4 - 8\ - are good values. This is only used by the talker. If not \ - set internal defaults are used. -raw_rx_buffers |The number of raw socket receive buffers. Typically 50 - \ - 100 are good values. This is only used by the listener. \ - If not set internal defaults are used. -report_seconds |How often to output stats. Defaults to 10 seconds. 0 turns\ - off the stats. -tx_blocking_in_intf |The interface module will block until data is available. \ - This is a talker only configuration value and not all interface modules support it. -pMapInitFn |Pointer to the mapping module initialization function. \ - Since this is a pointer to a function addresss is it not \ - directly set in platforms that use a .ini file. -IntfInitFn |Pointer to the interface module initialization function. \ - Since this is a pointer to a function addresss is it not \ - directly set in platforms that use a .ini file. - +sr_class |A talker only setting. Values are either A or B. If not set an internal default is used. +sr_rank |A talker only setting. If not set an internal default is used. +max_transit_usec |Allows manually specifying a maximum transit time. <ul><li><b>On the talker</b> this value is added to the PTP walltime to create the AVTP Timestamp.</li><li><b>On the listener</b> this value is used to validate an expected valid timestamp range.</li></ul><b>Note:</b> For the listener the map_nv_item_count value must be set large enough to allow buffering at least as many AVTP packets that can be transmitted during this max transit time. +max_transmit_deficit_usec |Allows setting the maximum packet transmit rate deficit that will be recovered when a talker falls behind. <p>When a talker can not keep up with the specified transmit rate it builds up a deficit and will attempt to make up for this deficit by sending more packets. There is normally some variability in the transmit rate because of other demands on the system so this is expected. However, without this bounding value the deficit could grew too large in cases such where more streams are started than the system can support and when the number of streams is reduced the remaining streams will attempt to recover this deficit by sending packets at a higher rate. This can cause a problem at the listener side and significantly delay the recovery time before media playback will return to normal.</p><p>Typically this value can be set to the expected buffer size (in usec) that listeners are expected to be buffering.<br>For low latency solutions this is normally a small value. For non-live media playback such as video playback the listener side buffers can often be large enough to held many seconds of data.</p><b>Note:</b> This is only used on a talker side. +internal_latency |Allows manually specifying an internal latency time. This is used only on the talker. +max_stale |The number of microseconds beyond the presentation time that media queue items will be purged because they are too old (past the presentation time).<br>This is only used on listener end stations.<p><b>Note:</b> needing to purge old media queue items is often a sign of some other problem.<br>For example: a delay at stream startup before incoming packets are ready to be processed by the media sink.<br>If this deficit in processing or purging the old (stale) packets is not handled, syncing multiple listeners will be problematic.</p> +raw_tx_buffers |The number of raw socket transmit buffers. Typically 4 - 8 are good values. This is only used by the talker. If not set internal defaults are used. +raw_rx_buffers |The number of raw socket receive buffers. Typically 50 - 100 are good values. This is only used by the listener. If not set internal defaults are used. +report_seconds |How often to output stats. Defaults to 10 seconds. 0 turns off the stats. +tx_blocking_in_intf |The interface module will block until data is available. This is a talker only configuration value and not all interface modules support it. +pMapInitFn |Pointer to the mapping module initialization function. Since this is a pointer to a function address is it not directly set in platforms that use a .ini file. +IntfInitFn |Pointer to the interface module initialization function. Since this is a pointer to a function address is it not directly set in platforms that use a .ini file. <br> + # Platform Specific Stream Configuration Values Some platform ports have unique configuration values. @@ -263,26 +188,13 @@ Some platform ports have unique configuration values. Name | Description --------------------------|--------------------------- -map_lib |The name of the library file (commonly a .so file) that \ - implements the Initialize function.<br> \ - Comment out the map_lib name and link in the .c file to \ - the openavb_tl executable to embed the mapper directly into \ - the executable unit. There is no need to change anything \ - else. The Initialize function will still be dynamically \ - linked in. +map_lib |The name of the library file (commonly a .so file) that implements the Initialize function.<br>Comment out the map_lib name and link in the .c file to the openavb_tl executable to embed the mapper directly into the executable unit. There is no need to change anything else. The Initialize function will still be dynamically linked in. map_fn |The name of the initialize function in the mapper -intf_lib | The name of the library file (commonly a .so file) \ - that implements the Initialize function.<br> \ - Comment out the intf_lib name and link in the .c \ - file to the openavb_tl executable to embed the \ - interface directly into the executable unit.<br> \ - There is no need to change anything else. \ - The Initialize function will still be dynamically \ - linked in +intf_lib | The name of the library file (commonly a .so file) that implements the Initialize function.<br>Comment out the intf_lib name and link in the .c file to the openavb_tl executable to embed the interface directly into the executable unit.<br>There is no need to change anything else. The Initialize function will still be dynamically linked in intf_fn | The name of the initialize function in the interface - <br> + Example Interface / Mapping Combinations {#sdk_avtp_stream_cfg_combinations} ======================================== Below are a few interface / mapping module combinations. Notice that a single @@ -291,28 +203,13 @@ mappings may work with multiple interface modules. interface module | mapping module | description ----------------------------|-----------------------|------------ -[echo](@ref echo_host_intf) |[pipe](@ref pipe_map) |Demonstration interface \ - used mostly for \ - verification and testing \ - purposes. -[alsa](@ref alsa_intf) |[uncmp_audio](@ref uncmp_audio_map)|Audio \ - interface created for \ - demonstration on Linux. \ - Can be used to play \ - captured (line in, mic) \ - audio stream via EAVB -[alsa](@ref alsa_intf) |[aaf_audio](@ref aaf_audio_map)|Audio \ - interface created for \ - demonstration on Linux. \ - Can be used to play \ - captured (line in, mic) \ - audio stream via EAVB -[wav_file](@ref wav_file_intf)|[uncmp_audio](@ref uncmp_audio_map)| \ - Configuration for playing \ - wave file via EAVB - +[echo](@ref echo_host_intf) |[pipe](@ref pipe_map) |Demonstration interface used mostly for verification and testing purposes. +[alsa](@ref alsa_intf) |[uncmp_audio](@ref uncmp_audio_map)|Audio interface created for demonstration on Linux. Can be used to play captured (line in, mic) audio stream via EAVB +[alsa](@ref alsa_intf) |[aaf_audio](@ref aaf_audio_map)|Audio interface created for demonstration on Linux. Can be used to play captured (line in, mic) audio stream via EAVB +[wav_file](@ref wav_file_intf)|[uncmp_audio](@ref uncmp_audio_map)|Configuration for playing wave file via EAVB <br> + Interface and Mapping Module Configuration {#sdk_avtp_stream_cfg_intf_map} ========================================== diff --git a/lib/avtp_pipeline/documents/sdk_eavb_integration.md b/lib/avtp_pipeline/documents/sdk_eavb_integration.md index c1200834..e92f07b6 100644 --- a/lib/avtp_pipeline/documents/sdk_eavb_integration.md +++ b/lib/avtp_pipeline/documents/sdk_eavb_integration.md @@ -10,6 +10,7 @@ will be active. The details of stream configuration is described in another section. <br> + AVTP Control {#sdk_integration_avtp_control} ============ Only a handful of functions are needed to control the AVTP component. This is @@ -23,6 +24,7 @@ general flow is: close. <br> + Host Application Integration {#sdk_integration_host_app} ============================ Controlling the non-AVTP components of the AVB stack are platform dependent. diff --git a/lib/avtp_pipeline/documents/sdk_notes_media_queue_usage.md b/lib/avtp_pipeline/documents/sdk_notes_media_queue_usage.md index aaa4cda8..4c6daaf2 100644 --- a/lib/avtp_pipeline/documents/sdk_notes_media_queue_usage.md +++ b/lib/avtp_pipeline/documents/sdk_notes_media_queue_usage.md @@ -9,6 +9,7 @@ and are hidden from interface module implemented. There are also some simplifications to make description as straightforward as possible. <br> + # Workflow The following work flow steps will be described. @@ -22,6 +23,7 @@ and listener streams the Media Queue <br> + Starting {#media_queue_usage_start} ======== @@ -53,6 +55,7 @@ Now the listener/talker stream is running. See next steps below for details of Media Queue interaction for the talker and listener. <br> + Talker specific flow {#media_queue_usage_talker} ==================== @@ -71,6 +74,7 @@ function additionally unlocks the head so the @ref openavbMediaQHeadUnlock call not needed <br> + Listener specific flow {#media_queue_usage_listener} ====================== @@ -90,6 +94,7 @@ additionally unlocks tail, so it is not necessary to call @ref openavbMediaQTailUnlock. <br> + Stopping {#media_queue_usage_stop} ======== @@ -101,6 +106,7 @@ During the stopping process following action are taken the memory taken by all internal structures of Media Queue <br> + Guidelines {#media_queue_usage_rules} ========== diff --git a/lib/avtp_pipeline/documents/sdk_overview.md b/lib/avtp_pipeline/documents/sdk_overview.md index 75d6f926..2f0f9e76 100644 --- a/lib/avtp_pipeline/documents/sdk_overview.md +++ b/lib/avtp_pipeline/documents/sdk_overview.md @@ -4,7 +4,7 @@ EAVB SDK Overview {#sdk_overview} Introduction {#sdk_overview_introduction} ============ -Symphony Teleca Corporation (OPENAVB) has developed a software Protocol Stack to +Harman International Industries, Inc. has developed a software Protocol Stack to support Ethernet Audio Video Bridging (EAVB or AVB) on a variety of platforms. The software includes explicit Operating System and Hardware Abstraction Layers (OSAL and HAL) to facilitate rapid and efficient porting of the generic stack to @@ -30,6 +30,7 @@ guides are separated into four sections: This overview section will cover general architecture. <br> + Glossary {#sdk_overview_glossary} ======== **AAF:** AVTP Audio Format @@ -97,8 +98,6 @@ interface modules and mapping modules communicate. **SRP:** Stream Reservation Protocol -**OPENAVB:** Symphony Teleca Corporation - **Stream:** A series of AVTP data packets **Talker:** Takes an audio or video source and transmits it as an AVTP stream on @@ -106,6 +105,7 @@ the AVB network. It consists of a dedicated task and uses functionality in the AVTP module, one mapping module and one interface module. <br> + Architecture {#sdk_overview_architecture} ============ @@ -117,6 +117,7 @@ What follows in this section are details that more directly effect the use and understanding of the SDK. <br> + Below is the component diagram of the Core AVB stack. Notice that the interface modules are not shown as part of the formal core stack but instead the interfaces that they use in the core stack are shown. This is also true for the @@ -126,6 +127,7 @@ interfaces the host application will use (TL APIs). @image latex Core_AVB.png "Core AVB" width=15cm <br> + General Purpose OSes will generally have the core AVB stack split across multiple processes. Whereas in an RTOS everything sits within a single execution image. Here is a process diagram of the components split across processes in the @@ -135,18 +137,20 @@ Linux reference implementation. @image latex fig1.png "AVB Components" width=15cm As shown above the AVTP component of AVB is present in the application task. -The libopenavbAVBStack library gets initialized and loaded via the APIs exposed and +The AVB stack library gets initialized and loaded via the APIs exposed and documented here. This static library implements that AVTP functionality as well as controlling talker and listener initialization and life cycle. The PTP task initialization is handled during stack initialization. <br> + The common AVTP stream data flow is shown here. @image html AVTP_Data_Flow.png "AVTP Data Flow" @image latex AVTP_Data_Flow.png "AVPT Data Flow" width=15cm <br> + The diagram below shows an audio stream flowing through the AVB system on the Linux platform. Typically the talker and listener will be in different tasks and may use different interfaces. @@ -155,6 +159,7 @@ may use different interfaces. @image latex fig2.png "AVB Audio Stream Flow" width=15cm <br> + Understanding the stream life-cycle is important for use of this SDK. Below are sequence diagrams that show the component interaction for key stream use cases. @@ -162,14 +167,17 @@ sequence diagrams that show the component interaction for key stream use cases. @image latex Stream_Initialize.png "Stream Initialization" width=15cm <br> + @image html Talker_Stream_Data_Flow.png "Talker Stream Data Flow" @image latex Talker_Stream_Data_Flow.png "Talker Stream Data Flow" width=15cm <br> + @image html Listener_Stream_Data_Flow.png "Listener Stream Data Flow" @image latex Listener_Stream_Data_Flow.png "Listener Stream Data Flow" width=15cm <br> + Integration, Extension and Configuration {#sdk_overview_integration} ======================================== Three distinct uses of the SDK are as follows. @@ -195,6 +203,7 @@ area of configuration is related to stream. See the section [AVTP Stream Configuration](@ref sdk_avtp_stream_cfg) for more details. <br> + Platform Specific Considerations {#sdk_overview_platform} ================================ The OPENAVB AVB stack is designed for portability covering both general purpose OSes |