API Reference
Configuration defines
Demo and hardware specific
Demo parameters and hardware port definitions are set in a header configuration file named app_config.h within the src/ directory of the application.
-
AVB_DEMO_ENABLE_TALKER
Global switch to enable or disable AVB Talker functionality in the demo.
-
AVB_DEMO_ENABLE_LISTENER
Global switch to enable or disable AVB Listener functionality in the demo.
-
AVB_DEMO_NUM_CHANNELS
Number of input/output audio channels in the demo application For simplicity, input and output is identical in size but can be configured differently in avb_conf.h.
Core AVB parameters
Each application using the AVB modules must include a header configuration file named avb_conf.h within the src/ directory of the application and this file must set the #defines in the following two sections.
See the demo application for a realistic example.
Defaults for these #defines are assigned in their absence, but may cause compilation failure or unpredictable/erroneous behaviour.
Ethernet
See the Ethernet documentation for detailed information on its parameters:
https://www.xmos.com/published/xmos-layer-2-ethernet-mac-component?version=latest
Audio subsystem
-
AVB_MAX_AUDIO_SAMPLE_RATE
The maximum sample rate in Hz of audio that is to be input or output.
-
AVB_NUM_SOURCES
The total number of AVB sources (streams that are to be transmitted).
-
AVB_NUM_TALKER_UNITS
The total number or Talker components (typically the number of tasks running the avb_1722_talker() function).
-
AVB_MAX_CHANNELS_PER_TALKER_STREAM
The maximum number of channels permitted per 1722 Talker stream.
-
AVB_NUM_MEDIA_INPUTS
The total number of media inputs (typically number of I2S input channels).
-
AVB_NUM_SINKS
The total number of AVB sinks (incoming streams that can be listened to).
-
AVB_NUM_LISTENER_UNITS
The total number or listener components (typically the number of tasks running the avb_1722_listener() function).
-
AVB_MAX_CHANNELS_PER_LISTENER_STREAM
The maximum number of channels permitted per 1722 Listener stream.
-
AVB_NUM_MEDIA_OUTPUTS
The total number of media outputs (typically the number of I2S output channels).
-
AVB_NUM_MEDIA_UNITS
The number of components in the endpoint that will register and initialize media FIFOs (typically an audio interface component such as I2S).
-
AVB_NUM_MEDIA_CLOCKS
The number of media clocks in the endpoint.
Typically the number of clock domains, each with a separate PLL and master clock.
1722.1
-
AVB_ENABLE_1722_1
Enable 1722.1 AVDECC on the entity.
-
AVB_1722_1_TALKER_ENABLED
Enable the 1722.1 Talker functionality.
-
AVB_1722_1_LISTENER_ENABLED
Enable the 1722.1 Listener functionality.
-
AVB_1722_1_CONTROLLER_ENABLED
Enable 1722.1 Controller functionality on the entity.
Descriptor specific strings can be modified in a header configuration file named aem_entity_strings.h.in within the src/ directory. It is post-processed by a script in the build stage to expand strings to 64 octet padded with zeros.
Define |
Description |
---|---|
AVB_1722_1_ENTITY_NAME_STRING |
A string (64 octet max) containing an Entity name |
AVB_1722_1_FIRMWARE_VERSION_STRING |
A string (64 octet max) containing the firmware version of the Entity |
AVB_1722_1_GROUP_NAME_STRING |
A string (64 octet max) containing the group name of the Entity |
AVB_1722_1_SERIAL_NUMBER_STRING |
A string (64 octet max) containing the serial number of the Entity |
AVB_1722_1_VENDOR_NAME_STRING |
A string (64 octet max) containing the vendor name of the Entity |
AVB_1722_1_MODEL_NAME_STRING |
A string (64 octet max) containing the model name of the Entity |
Component tasks and functions
The following functions provide components that can be combined in the top-level main.
Core components
-
[[combinable]] void avb_manager(server interface avb_interface i_avb[num_avb_clients], unsigned num_avb_clients, client interface srp_interface i_srp, chanend c_media_ctl[], chanend(& ?c_listener_ctl)[], chanend(& ?c_talker_ctl)[], chanend c_mac_tx, client interface media_clock_if ?i_media_clock_ctl, chanend c_ptp)
Core AVB API management task that can be combined with other AVB tasks such as SRP or 1722.1.
Parameters
i_avb[]
array of avb_interface server interfaces connected to clients of avb_manager
num_avb_clients
number of client interface connections to the server and the number of elements of i_avb[]
i_srp
client interface of type srp_interface into an srp_task() task
c_media_ctl[]
array of chanends connected to components that register/control media FIFOs
c_listener_ctl[]
array of chanends connected to components that register/control IEEE 1722 sinks
c_talker_ctl[]
array of chanends connected to components that register/control IEEE 1722 sources
c_mac_tx
chanend connection to the Ethernet TX server
i_media_clock_ctl
client interface of type media_clock_if connected to the media clock server
c_ptp
chanend connection to the PTP server
-
avb_srp_info_t
Struct containing fields required for SRP reservations.
Structure Members:
-
unsigned stream_id
64-bit Stream ID of the stream
-
unsigned char dest_mac_addr
Stream destination MAC address.
-
short vlan_id
VLAN ID for Stream.
-
short tspec_max_frame_size
Maximum frame size sent by Talker.
-
short tspec_max_interval
Maximum number of frames sent per class measurement interval.
-
unsigned char tspec
Data Frame Priority and Rank fields.
-
unsigned accumulated_latency
Latency at ingress port for Talker registrations, or latency at end of egress media for Listener Declarations.
-
unsigned char failure_bridge_id
-
unsigned char failure_code
-
-
interface srp_interface
-
short register_stream_request(avb_srp_info_t stream_info)
Used by a Talker application entity to issue a request to the MSRP Participant to initiate the advertisement of an available Stream.
Parameters
stream_info
Struct of type avb_srp_info_t containing parameters of the stream to register
Returns
The VLAN ID actually joined
-
void deregister_stream_request(unsigned stream_id[2])
Used by a Talker application entity to request removal of the Talker’s advertisement declaration, and thus remove the advertisement of a Stream, from the network.
Parameters
stream_id
two int array containing the Stream ID of the stream to deregister
-
short register_attach_request(unsigned stream_id[2], short vlan_id)
Used by a Listener application entity to issue a request to attach to the referenced Stream.
Parameters
stream_id
two int array containing the Stream ID of the stream to register
vlan_id
the VLAN ID to join
Returns
The VLAN ID actually joined
-
void deregister_attach_request(unsigned stream_id[2])
Used by a Listener application entity to remove the request to attach to the referenced Stream.
Parameters
stream_id
two int array containing the Stream ID of the stream to deregister
-
-
[[combinable]] void avb_srp_task(client interface avb_interface i_avb, server interface srp_interface i_srp, chanend c_mac_rx, chanend c_mac_tx)
SRP task that implements MSRP and MVRP protocols.
Can be combined with other combinable tasks.
Parameters
i_avb
client interface of type avb_interface into the avb_manager() for API control of the stack
i_srp
server interface of type srp_interface that offers client tasks access to SRP reservation functionality
c_mac_rx
chanend into the Ethernet RX server
c_mac_tx
chanend into the Ethernet TX server
-
avb_1722_1_aecp_aem_status_code
Enum Values:
-
AECP_AEM_STATUS_SUCCESS
The AVDECC Entity successfully performed the command and has valid results.
-
AECP_AEM_STATUS_NOT_IMPLEMENTED
The AVDECC Entity does not support the command type.
-
AECP_AEM_STATUS_NO_SUCH_DESCRIPTOR
A descriptor with the descriptor_type and descriptor_index specified does not exist.
-
AECP_AEM_STATUS_ENTITY_LOCKED
The AVDECC Entity has been locked by another AVDECC Controller.
-
AECP_AEM_STATUS_ENTITY_ACQUIRED
The AVDECC Entity has been acquired by another AVDECC Controller.
-
AECP_AEM_STATUS_NOT_AUTHENTICATED
The AVDECC Controller is not authenticated with the AVDECC Entity.
-
AECP_AEM_STATUS_AUTHENTICATION_DISABLED
The AVDECC Controller is trying to use an authentication command when authentication isn’t enable on the AVDECC Entity.
-
AECP_AEM_STATUS_BAD_ARGUMENTS
One or more of the values in the fields of the frame were deemed to be bad by the AVDECC Entity (unsupported, incorrect combination, etc).
-
AECP_AEM_STATUS_NO_RESOURCES
The AVDECC Entity cannot complete the command because it does not have the resources to support it.
-
AECP_AEM_STATUS_IN_PROGRESS
The AVDECC Entity is processing the command and will send a second response at a later time with the result of the command.
-
AECP_AEM_STATUS_ENTITY_MISBEHAVING
The AVDECC Entity is generated an internal error while trying to process the command.
-
AECP_AEM_STATUS_NOT_SUPPORTED
The command is implemented but the target of the command is not supported.
For example trying to set the value of a read-only Control.
-
AECP_AEM_STATUS_STREAM_IS_RUNNING
The Stream is currently streaming and the command is one which cannot be executed on an Active Stream.
-
-
interface avb_1722_1_control_callbacks
-
unsigned char get_control_value(unsigned short control_index, unsigned short &values_length, char values[AEM_MAX_CONTROL_VALUES_LENGTH_BYTES])
This function events on a GET_CONTROL 1722.1 command received from a Controller.
Parameters
control_index
the index of the CONTROL descriptor
values_length
a reference to the length in bytes of the values array
values
an array of values to return to the Controller The contents of this field are dependent on the Control being fetched.
Returns
an AEM status code of enum avb_1722_1_aecp_aem_status_code for the GET_CONTROL response
-
unsigned char set_control_value(unsigned short control_index, unsigned short values_length, char values[AEM_MAX_CONTROL_VALUES_LENGTH_BYTES])
This function events on a SET_CONTROL 1722.1 command received from a Controller.
The response should always contain the current value (i.e. it contains the new value if the commands succeeds, or the old value if it fails)
Parameters
control_index
the index of the CONTROL descriptor
values_length
the length in bytes of the values array
values
an array of values to set from the Controller. The contents of this field are dependent on the Control being addressed.
Returns
an AEM status code of enum avb_1722_1_aecp_aem_status_code for the SET_CONTROL response
-
-
[[combinable]] void avb_1722_1_maap_task(otp_ports_t &otp_ports, client interface avb_interface i_avb, client interface avb_1722_1_control_callbacks i_1722_1_entity, client interface spi_interface ?i_spi, chanend c_mac_rx, chanend c_mac_tx, chanend c_ptp)
1722.1 task that runs ADP, ACMP and AECP protocols and interacts with the rest of the AVB stack.
Can be combined with other combinable tasks.
Parameters
otp_ports
reference to an OTP ports structure of type otp_ports_t
i_avb
client interface of type avb_interface into avb_manager()
i_1722_1_entity
client interface of type avb_1722_1_control_callbacks
i_spi
client interface of type spi_interface into avb_srp_task()
c_mac_rx
chanend into the Ethernet RX server
c_mac_tx
chanend into the Ethernet TX server
c_ptp
chanend into the PTP server
-
fl_spi_ports
Struct containing ports and clocks used to access a flash device.
Structure Members:
-
buffered in port:8 spiMISO
Master input, slave output (MISO) port.
-
out port spiSS
Slave select (SS) port.
-
buffered out port:32 spiCLK
Serial clock (SCLK) port.
-
buffered out port:8 spiMOSI
Master output, slave input (MOSI) port.
-
clock spiClkblk
Clock block for use with SPI ports.
-
-
interface spi_interface
-
int command_status(int cmd, unsigned returnBytes)
This function issues a single command without parameters to the SPI, and reads up to 4 bytes status value from the device.
Parameters
cmd
command value - listed above
returnBytes
The number of bytes that are to be read from the device after the command is issued. 0 means no bytes will be read.
Returns
the read bytes, or zero if no bytes were requested. If multiple bytes are requested, then the last byte read is in the least-significant byte of the return value.
-
void command_address_status(int cmd, unsigned int address, unsigned char data[], int returnBytes)
This function issues a single command with a 3-byte address parameter and an optional data-set to be output to or input form the device.
Parameters
cmd
command value - listed above
address
the address to send to the SPI device. Only the least significant 24 bits are used.
data
an array of data that contains either data to be written to the device, or which is used to store that that is read from the device.
returnBytes
If positive, then this is the number of bytes that are to be read from the device, into data. If negative, then this is (minus) the number of bytes to be written to the device from data. 0 means no bytes will be read or written.
-
-
[[distributable]] void spi_task(server interface spi_interface i_spi, fl_spi_ports &spi_ports)
Task that implements a SPI interface to serial flash, typically the boot flash.
Can be combined or distributed into other tasks.
Parameters
i_spi
server interface of type spi_interface
spi_ports
reference to a fl_spi_ports structure containing the SPI flash ports and clockblock
-
void ptp_server(chanend mac_rx, chanend mac_tx, chanend ptp_clients[], int num_clients, enum ptp_server_type server_type)
This function runs the PTP server.
It requires one logical core and runs indefinitely
Parameters
mac_rx
chanend connected to the ethernet server (receive)
mac_tx
chanend connected to the ethernet server (transmit)
ptp_clients
an array of chanends to connect to clients of the ptp server
num_clients
The number of clients attached
server_type
The type of the server (PTP_GRANDMASTER_CAPABLE or PTP_SLAVE_ONLY)
-
void media_clock_server(server interface media_clock_if media_clock_ctl, chanend ?ptp_svr, chanend(& ?buf_ctl)[num_buf_ctl], unsigned num_buf_ctl, out buffered port:32 p_fs[])
The media clock server.
Parameters
media_clock_ctl
server interface of type media_clock_if connected to the avb_manager() task and passed into avb_init()
ptp_svr
chanend connected to the PTP server
buf_ctl[]
array of links to listener components requiring buffer management
num_buf_ctl
size of the buf_ctl array
p_fs
output port to drive PLL reference clock
c_rx
chanend connected to the ethernet server (receive)
c_tx
chanend connected to the ethernet server (transmit)
c_ptp[]
an array of chanends to connect to clients of the ptp server
num_ptp
The number of PTP clients attached
server_type
The type of the PTP server (PTP_GRANDMASTER_CAPABLE or PTP_SLAVE_ONLY)
-
void avb_1722_listener(chanend c_mac_rx, chanend ?c_buf_ctl, chanend ?c_ptp_ctl, chanend c_listener_ctl, int num_streams)
An AVB IEEE 1722 audio listener task.
This task implements a listener. It takes IEEE 1722 packets from the ethernet MAC and splits them into output FIFOs. The buffer fill level of these streams is set in conjunction with communication to the media clock server. This task is dynamically configured using the AVB control API.
Parameters
c_mac_rx
receive link to the ethernet MAC
c_buf_ctl
buffer control link to the media clock server
c_ptp_ctl
PTP server link for retrieving PTP time info
c_listener_ctl
channel to configure the listener (given to avb_init())
num_streams
the number of streams the unit will handle
-
void avb_1722_talker(chanend c_ptp, chanend c_mac_tx, chanend c_talker_ctl, int num_streams)
An AVB IEEE 1722 audio talker task.
This task implements a talker, taking media input FIFOs and combining them into 1722 packets to be sent to the ethernet component. It is dynamically configured using the AVB control API.
Parameters
c_ptp
link to the PTP timing server
c_mac_tx
transmit link to the ethernet MAC
c_talker_ctl
channel to configure the talker (given to avb_init())
num_streams
the number of streams the unit controls
Audio components
The following types are used by the AVB audio components:
-
media_output_fifo_t
This type provides a handle to a media output FIFO.
-
media_output_fifo_data_t
This type provides the data structure used by a media output FIFO.
-
media_input_fifo_t
This type provides a handle to a media input fifo.
-
media_input_fifo_data_t
This type provides the data structure used by a media input fifo.
The following functions implement AVB audio components:
-
void init_media_input_fifos(media_input_fifo_t ififos[], media_input_fifo_data_t ififo_data[], int n)
Initialize media input fifos.
This function intializes media input FIFOs and ties the handles to their associated data structures. It should be called before the main component function on a task to setup the FIFOs.
Parameters
ififos
an array of media input FIFO handles to initialize
ififo_data
an array of associated data structures
n
the number of FIFOs to initialize
-
void init_media_output_fifos(media_output_fifo_t ofifos[], media_output_fifo_data_t ofifo_data[], int n)
Initialize media output FIFOs.
This function initializes media output FIFOs and ties the handles to their associated data structures. It should be called before the main component function on a thread to setup the FIFOs.
Parameters
ofifos
an array of media output FIFO handles to initialize
ofifo_data
an array of associated data structures
n
the number of FIFOs to initialize
-
static void i2s_master(i2s_ports_t &ports, in buffered port:32(& ?p_din)[], int num_in, out buffered port:32(& ?p_dout)[], int num_out, int master_to_word_clock_ratio, media_input_fifo_t(& ?input_fifos)[], media_output_fifo_t(& ?output_fifos)[], chanend media_ctl, int clk_ctl_index)
Input and output audio data using I2S format with the XCore acting as master.
This function implements a task that can handle several synchronous I2S interfaces. It inputs and outputs 24-bit data packed into 32 bits.
This function can handle up to 8in and 8out at 48KHz.
Parameters
ports
a reference to a structure of type i2s_ports_t containing the I2S port definitions
p_din
array of ports to input data from
num_in
number of input ports
p_dout
array of ports to output data to
num_out
number of output ports
master_to_word_clock_ratio
the ratio of the master clock to the word clock; must be one of 128, 256 or 512
input_fifos
a map from the inputs to local talker streams. The channels of the inputs are interleaved, for example, if you have two input ports, the map {0,1,0,1} would map to the two stereo local talker streams 0 and 1.
output_fifos
a map from the outputs to local Listener streams
media_ctl
a media clock control chanend connected to an avb_manager() task
clk_ctl_index
the index of the clock control, default 0
-
void media_output_fifo_to_xc_channel(streaming chanend samples_out, media_output_fifo_t ofifos[], int num_channels)
Output audio streams from media fifos to an XC channel.
This function outputs samples from several media output FIFOs over an XC channel over the streaming chanend samples_out.
The protocol over the channel is that the thread expects a timestamp to be sent to it and then it will output num_channels samples, pulling from the ofifos array. It will then expect another timestamp before the next set of samples.
Parameters
samples_out
the chanend on which samples are output
ofifos
array of media output FIFOs to pull from
num_channels
the number of channels (or FIFOs)
-
void media_output_fifo_to_xc_channel_split_lr(streaming chanend samples_out, media_output_fifo_t output_fifos[], int num_channels)
Output audio streams from media FIFOs to an XC channel, splitting left and right pairs.
This function outputs samples from several media output FIFOs over an XC channel over the streaming chanend samples_out. The media FIFOs are assumed to be grouped in left/right stereo pairs which are then split.
The protocol over the channel is that the thread expects a timestamp to be sent to it and then it will first output num_channels/2 samples, pulling from all the even indexed elements of the ofifos array and then output all the odd elements. It will then expect another timestamp before the next set of samples.
Parameters
samples_out
the chanend on which samples are output
output_fifos
array of media output fifos to pull from
num_channels
the number of channels (or FIFOs)
Video components
The following functions implement AVB video components:
-
void tsi_output(clock clk, out buffered port:32 p_data, in port p_clk, out buffered port:4 p_sync, out port p_valid, media_output_fifo_data_t &output_fifo)
Hardware interface for the MPEG synchronous parallel interface.
Parameters
clk
the clock block for the output
p_data
MPEG data, an 8 bit port to be driven as a 32 bit buffered port
p_clk
a one bit clock input with the 13.5 MHz MPEG SPI clock
p_sync
MPEG start of packet but, a one bit port to be driven as a 4 bit buffered port
p_valid
Valid bit for the data and sync bits. A one bit pin
output_fifo
The media FIFO from which to draw samples
-
void tsi_input(clock clk, in buffered port:32 p_data, in port p_clk, in buffered port:4 p_sync, in port p_valid, ififo_t &ififo)
Hardware interface for the MPEG synchronous parallel interface.
Parameters
clk
a clock block for controlling the input
p_data
MPEG data, an 8 bit port to be driven as a 32 bit buffered port
p_clk
a one bit clock input with the 13.5 MHz MPEG SPI clock
p_sync
MPEG start of packet but, a one bit port
p_valid
Valid bit for the data and sync bits. A one bit pin
ififo
The media FIFO from which to draw samples
AVB API
General control functions
-
void avb_get_control_packet(chanend c_rx, unsigned int buf[], unsigned int &nbytes, unsigned int &port_num)
Receives an 802.1Qat SRP packet or an IEEE 1722 control packet.
This function receives an AVB control packet from the ethernet MAC. It is selectable so can be used in a select statement as a case.
Parameters
c_rx
chanend connected to the ethernet component
buf
buffer to retrieve the packet into; buffer must have length at least MAX_AVB_CONTROL_PACKET_SIZE bytes
nbytes
a reference parameter that is filled with the length of the received packet
-
void avb_process_srp_control_packet(client interface avb_interface i_avb, unsigned int buf[], unsigned len, chanend c_tx, unsigned int port_num)
Process an AVB SRP control packet.
This function processes an 802.1Qat ethernet packet
This function should always be called on the buffer filled by avb_get_control_packet().
Parameters
i_avb
client interface of type avb_interface into avb_manager()
buf
the incoming message buffer
len
the length (in bytes) of the incoming buffer
c_tx
chanend connected to the ethernet mac (TX)
port_num
the id of the Ethernet interface the packet was received
-
void avb_process_1722_control_packet(unsigned int buf[], unsigned nbytes, chanend c_tx, client interface avb_interface i_avb, client interface avb_1722_1_control_callbacks i_1722_1_entity, client interface spi_interface ?i_spi)
Process an AVB 1722 control packet.
This function processes a 1722 ethernet packet with the control data bit set
This function should always be called on the buffer filled by avb_get_control_packet().
Parameters
buf
the incoming message buffer
nbytes
the length (in bytes) of the incoming buffer
c_tx
chanend connected to the ethernet mac (TX)
i_avb
client interface of type avb_interface into avb_manager()
i_1722_1_entity
client interface of type avb_1722_1_control_callbacks
i_spi
client interface of type spi_interface into avb_srp_task()
Multicast Address Allocation commands
-
void avb_1722_maap_request_addresses(int num_addresses, char(& ?start_address)[])
Request a range of multicast addresses.
This function requests a range of multicast addresses to use as destination addresses for IEEE 1722 streams. It starts the reservation process according to the 1722 MAAP protocol. If the reservation is successful it is reported via the status return value of avb_periodic().
Parameters
num_addresses
number of addresses to try and reserve; will be reserved in a contiguous range
start_address
an optional six byte array specifying the required start address of the range NOTE: must be within the MAAP reserved pool; if argument is null then the start address will be picked at random from the MAAP reserved pool
-
void avb_1722_maap_rerequest_addresses()
Re-request a claim on the existing address range.
If there is a current address reservation, this will reset the state machine into the PROBE state, in order to cause the protocol to re-probe and re-allocate the addresses.
-
void avb_1722_maap_relinquish_addresses()
Relinquish the reserved MAAP address range.
This function abandons the claim to the reserved address range
MAAP application hooks
-
void avb_talker_on_source_address_reserved(client interface avb_interface i_avb, int source_num, unsigned char mac_addr[6])
MAAP has indicated that a multicast address has been successfully reserved for this Talker stream.
Parameters
i_avb
client interface of type avb_interface into avb_manager()
source_num
The local source ID of the Talker
mac_addr
The destination MAC address reserved for this Talker
AVB Control API
-
device_media_clock_type_t
Enum Values:
-
DEVICE_MEDIA_CLOCK_INPUT_STREAM_DERIVED
-
DEVICE_MEDIA_CLOCK_LOCAL_CLOCK
-
-
device_media_clock_state_t
Enum Values:
-
DEVICE_MEDIA_CLOCK_STATE_DISABLED
-
DEVICE_MEDIA_CLOCK_STATE_ENABLED
-
-
interface avb_interface
-
void initialise(void)
-
avb_source_info_t _get_source_info(unsigned source_num)
Intended for internal use within client interface get and set extensions only.
-
void _set_source_info(unsigned source_num, avb_source_info_t info)
Intended for internal use within client interface get and set extensions only.
-
avb_sink_info_t _get_sink_info(unsigned sink_num)
Intended for internal use within client interface get and set extensions only.
-
void _set_sink_info(unsigned sink_num, avb_sink_info_t info)
Intended for internal use within client interface get and set extensions only.
-
media_clock_info_t _get_media_clock_info(unsigned clock_num)
Intended for internal use within client interface get and set extensions only.
-
void _set_media_clock_info(unsigned clock_num, media_clock_info_t info)
Intended for internal use within client interface get and set extensions only.
-
int get_source_format(unsigned source_num, enum avb_stream_format_t &format, int &rate)
Get the format of an AVB source.
Parameters
source_num
the local source number
format
the format of the stream
rate
the sample rate of the stream in Hz
-
int set_source_format(unsigned source_num, enum avb_stream_format_t format, int rate)
Set the format of an AVB source.
The AVB source format covers the encoding and sample rate of the source. Currently the format is limited to a single encoding MBLA 24 bit signed integers.
This setting will not take effect until the next time the source state moves from disabled to potential.
Parameters
source_num
the local source number
format
the format of the stream
rate
the sample rate of the stream in Hz
-
int get_source_channels(unsigned source_num, int &channels)
Get the channel count of an AVB source.
Parameters
source_num
the local source number
channels
the number of channels
-
int set_source_channels(unsigned source_num, int channels)
Set the channel count of an AVB source.
Sets the number of channels in the stream.
This setting will not take effect until the next time the source state moves from disabled to potential.
Parameters
source_num
the local source number
channels
the number of channels
-
int get_source_sync(unsigned source_num, int &sync)
Get the media clock of an AVB source.
Parameters
source_num
the local source number
sync
the media clock number
-
int set_source_sync(unsigned source_num, int sync)
Set the media clock of an AVB source.
Sets the media clock of the stream.
Parameters
source_num
the local source number
sync
the media clock number
-
int get_source_presentation(unsigned source_num, int &presentation)
Get the presentation time offset of an AVB source.
Parameters
source_num
the local source number to set
presentation
the presentation offset in ms
-
int set_source_presentation(unsigned source_num, int presentation)
Set the presentation time offset of an AVB source.
Sets the presentation time offset of a source i.e. the time after sampling that the stream should be played. The default value for this is 2ms.
This setting will not take effect until the next time the source state moves from disabled to potential.
Parameters
source_num
the local source number to set
presentation
the presentation offset in ms
-
int get_source_vlan(unsigned source_num, int &vlan)
Get the destination vlan of an AVB source.
Parameters
source_num
the local source number
vlan
the destination vlan id
-
int set_source_vlan(unsigned source_num, int vlan)
Set the destination vlan of an AVB source.
Sets the vlan that the source will transmit on. This defaults to 2.
This setting will not take effect until the next time the source state moves from disabled to potential.
Parameters
source_num
the local source number
vlan
the destination vlan id
-
int get_source_state(unsigned source_num, enum avb_source_state_t &state)
Get the current state of an AVB source.
Parameters
source_num
the local source number
state
the state of the source
-
int set_source_state(unsigned source_num, enum avb_source_state_t state)
Set the current state of an AVB source.
Sets the current state of an AVB source. You cannot set the state to ENABLED. Changing the state to AVB_SOURCE_STATE_POTENTIAL turns the stream on and it will automatically change to ENABLED when connected to a listener and streaming.
Parameters
source_num
the local source number
state
the state of the source
-
int get_source_map(unsigned source_num, int map[], int &len)
Get the channel map of an avb source.
Parameters
source_num
the local source number to set
map
the map, an array of integers giving the input FIFOs that make up the stream
len
the length of the map; should be equal to the number of channels in the stream
-
int set_source_map(unsigned source_num, int map[len], unsigned len)
Set the channel map of an avb source.
Sets the channel map of a source i.e. the list of input FIFOs that constitute the stream.
This setting will not take effect until the next time the source state moves from disabled to potential.
Parameters
source_num
the local source number to set
map
the map, an array of integers giving the input FIFOs that make up the stream
len
the length of the map; should be equal to the number of channels in the stream
-
int get_source_dest(unsigned source_num, unsigned char addr[], int &len)
Get the destination address of an avb source.
Parameters
source_num
the local source number
addr
the destination address as an array of 6 bytes
len
the length of the address, should always be equal to 6
-
int set_source_dest(unsigned source_num, unsigned char addr[len], unsigned len)
Set the destination address of an avb source.
Sets the destination MAC address of a source. This setting will not take effect until the next time the source state moves from disabled to potential.
Parameters
source_num
the local source number
addr
the destination address as an array of 6 bytes
len
the length of the address, should always be equal to 6
-
int get_source_id(unsigned source_num, unsigned int stream_id[2])
Get the stream id that an AVB source is using.
Parameters
source_num
the number of the source
stream_id
int array containing the 64-bit ID of the stream
-
int get_sink_id(unsigned sink_num, unsigned int stream_id[2])
Get the stream id that an AVB sink listens to.
Parameters
sink_num
the number of the sink
stream_id
int array containing the 64-bit ID of the stream
-
int set_sink_id(unsigned sink_num, unsigned int stream_id[2])
Set the stream id that an AVB sink listens to.
Sets the stream id that an AVB sink listens to.
This setting will not take effect until the next time the sink state moves from disabled to potential.
Parameters
sink_num
the number of the sink
stream_id
int array containing the 64-bit of the stream
-
int get_sink_format(unsigned sink_num, enum avb_stream_format_t &format, int &rate)
Get the format of an AVB sink.
Parameters
sink_num
the local sink number
format
the format of the stream
rate
the sample rate of the stream in Hz
-
int set_sink_format(unsigned sink_num, enum avb_stream_format_t format, int rate)
Set the format of an AVB sink.
The AVB sink format covers the encoding and sample rate of the sink. Currently the format is limited to a single encoding MBLA 24 bit signed integers.
This setting will not take effect until the next time the sink state moves from disabled to potential.
Parameters
sink_num
the local sink number
format
the format of the stream
rate
the sample rate of the stream in Hz
-
int get_sink_channels(unsigned sink_num, int &channels)
Get the channel count of an AVB sink.
Parameters
sink_num
the local sink number
channels
the number of channels
-
int set_sink_channels(unsigned sink_num, int channels)
Set the channel count of an AVB sink.
Sets the number of channels in the stream.
This setting will not take effect until the next time the sink state moves from disabled to potential.
Parameters
sink_num
the local sink number
channels
the number of channels
-
int get_sink_sync(unsigned sink_num, int &sync)
Get the media clock of an AVB sink.
Parameters
sink_num
the local sink number
sync
the media clock number
-
int set_sink_sync(unsigned sink_num, int sync)
Set the media clock of an AVB sink.
Sets the media clock of the stream.
Parameters
sink_num
the local sink number
sync
the media clock number
-
int get_sink_vlan(unsigned sink_num, int &vlan)
Get the virtual lan id of an AVB sink.
Parameters
sink_num
the number of the sink
vlan
the vlan id of the sink
-
int set_sink_vlan(unsigned sink_num, int vlan)
Set the virtual lan id of an AVB sink.
Sets the vlan id of the incoming stream.
This setting will not take effect until the next time the sink state moves from disabled to potential.
Parameters
sink_num
the number of the sink
vlan
the vlan id of the sink
-
int get_sink_addr(unsigned sink_num, unsigned char addr[], int &len)
Get the incoming destination mac address of an avb sink.
Parameters
sink_num
The local sink number
addr
The mac address as an array of 6 bytes.
len
The length of the address, should always be equal to 6.
-
int set_sink_addr(unsigned sink_num, unsigned char addr[len], unsigned len)
Set the incoming destination mac address of an avb sink.
Set the incoming destination mac address of a sink. This needs to be set if the address is a multicast address so the endpoint can register for that multicast group with the switch.
This setting will not take effect until the next time the sink state moves from disabled to potential.
Parameters
sink_num
The local sink number
addr
The mac address as an array of 6 bytes.
len
The length of the address, should always be equal to 6.
-
int get_sink_state(unsigned sink_num, enum avb_sink_state_t &state)
Get the state of an AVB sink.
Parameters
sink_num
the number of the sink
state
the state of the sink
-
int set_sink_state(unsigned sink_num, enum avb_sink_state_t state)
Set the state of an AVB sink.
Sets the current state of an AVB sink. You cannot set the state to ENABLED. Changing the state to POTENTIAL turns the stream on and it will automatically change to ENABLED when connected to a talker and receiving samples.
Parameters
sink_num
the number of the sink
state
the state of the sink
-
int get_sink_map(unsigned sink_num, int map[], int &len)
Get the map of an AVB sink.
Parameters
sink_num
the number of the sink
map
array containing the media output FIFOs that the stream will be split into
len
the length of the map; should equal to the number of channels in the stream
-
int set_sink_map(unsigned sink_num, int map[len], unsigned len)
Set the map of an AVB sink.
Sets the map i.e. the mapping from the 1722 stream to output FIFOs.
This setting will not take effect until the next time the sink state moves from disabled to potential.
Parameters
sink_num
the number of the sink
map
array containing the media output FIFOs that the stream will be split into
len
the length of the map; should equal to the number of channels in the stream
-
int get_device_media_clock_rate(int clock_num, int &rate)
Get the rate of a media clock.
Parameters
clock_num
the number of the media clock
rate
the rate of the clock in Hz
-
int set_device_media_clock_rate(int clock_num, int rate)
Set the rate of a media clock.
Sets the rate of the media clock.
Parameters
clock_num
the number of the media clock
rate
the rate of the clock in Hz
-
int get_device_media_clock_state(int clock_num, enum device_media_clock_state_t &state)
Get the state of a media clock.
Parameters
clock_num
the number of the media clock
state
the state of the clock
-
int set_device_media_clock_state(int clock_num, enum device_media_clock_state_t state)
Set the state of a media clock.
This function can be used to enabled/disable a media clock.
Parameters
clock_num
the number of the media clock
state
the state of the clock
-
int get_device_media_clock_source(int clock_num, int &source)
Get the source of a media clock.
Parameters
clock_num
the number of the media clock
source
the output FIFO number to base the clock on
-
int set_device_media_clock_source(int clock_num, int source)
Set the source of a media clock.
For clocks that are derived from an output FIFO. This function gets/sets which FIFO the clock should be derived from.
Parameters
clock_num
the number of the media clock
source
the output FIFO number to base the clock on
-
int get_device_media_clock_type(int clock_num, enum device_media_clock_type_t &clock_type)
Get the type of a media clock.
Parameters
clock_num
the number of the media clock
clock_type
the type of the clock
-
int set_device_media_clock_type(int clock_num, enum device_media_clock_type_t clock_type)
Set the type of a media clock.
Parameters
clock_num
the number of the media clock
clock_type
the type of the clock
-
1722.1 Controller commands
-
void avb_1722_1_controller_connect(const_guid_ref_t talker_guid, const_guid_ref_t listener_guid, int talker_id, int listener_id, chanend c_tx)
Setup a new stream connection between a Talker and Listener entity.
The Controller shall send a CONNECT_RX_COMMAND to the Listener Entity. The Listener Entity shall then send a CONNECT_TX_COMMAND to the Talker Entity.
Parameters
talker_guid
the GUID of the Talker being targeted by the command
listener_guid
the GUID of the Listener being targeted by the command
talker_id
the unique id of the Talker stream source to connect. For entities using AEM, this corresponds to the id of the STREAM_OUTPUT descriptor
listener_id
the unique id of the Listener stream source to connect. For entities using AEM, this corresponds to the id of the STREAM_INPUT descriptor
c_tx
a transmit chanend to the Ethernet server
-
void avb_1722_1_controller_disconnect(const_guid_ref_t talker_guid, const_guid_ref_t listener_guid, int talker_id, int listener_id, chanend c_tx)
Disconnect an existing stream connection between a Talker and Listener entity.
The Controller shall send a DISCONNECT_RX_COMMAND to the Listener Entity. The Listener Entity shall then send a DISCONNECT_TX_COMMAND to the Talker Entity.
Parameters
talker_guid
the GUID of the Talker being targeted by the command
listener_guid
the GUID of the Listener being targeted by the command
talker_id
the unique id of the Talker stream source to disconnect. For entities using AEM, this corresponds to the id of the STREAM_OUTPUT descriptor
listener_id
the unique id of the Listener stream source to disconnect. For entities using AEM, this corresponds to the id of the STREAM_INPUT descriptor
c_tx
a transmit chanend to the Ethernet server
-
void avb_1722_1_controller_disconnect_all_listeners(int talker_id, chanend c_tx)
Disconnect all Listener sinks currently connected to the Talker stream source with talker_id.
Parameters
talker_id
the unique id of the Talker stream source to disconnect its listeners. For entities using AEM, this corresponds to the id of the STREAM_OUTPUT descriptor
c_tx
a transmit chanend to the Ethernet server
-
void avb_1722_1_controller_disconnect_talker(int listener_id, chanend c_tx)
Disconnect the Talker source currently connected to the Listener stream sink with listener_id.
Parameters
listener_id
the unique id of the Listener stream source to disconnect its Talker. For entities using AEM, this corresponds to the id of the STREAM_INPUT descriptor
c_tx
a transmit chanend to the Ethernet server
1722.1 Discovery commands
-
void avb_1722_1_adp_announce(void)
Start advertising information about this entity via ADP.
-
void avb_1722_1_adp_depart(void)
Stop advertising information about this entity via ADP.
-
void avb_1722_1_adp_discover(const_guid_ref_t guid)
Ask to discover the information for a specific entity GUID.
Parameters
guid
The GUID of the entity to discover
-
void avb_1722_1_adp_discover_all(void)
Ask to discover all available entities via ADP.
-
void avb_1722_1_entity_database_flush(void)
Remove all discovered entities from the database.
1722.1 application hooks
These hooks are called on events that can be acted upon by the application. They can be overridden by user defined hooks of the same name to perform custom functionality not present in the core stack.
-
avb_1722_1_entity_record
Structure Members:
-
guid_t guid
-
unsigned int vendor_id
-
unsigned int entity_model_id
-
unsigned int capabilities
-
unsigned short talker_stream_sources
-
unsigned short talker_capabilities
-
unsigned short listener_stream_sinks
-
unsigned short listener_capabilities
-
unsigned int controller_capabilities
-
unsigned int available_index
-
gmid_t gptp_grandmaster_id
-
unsigned char gptp_domain_number
-
unsigned short identify_control_index
-
unsigned int association_id
-
unsigned timeout
-
-
void avb_entity_on_new_entity_available(client interface avb_interface i_avb, const_guid_ref_t my_guid, avb_1722_1_entity_record *entity, chanend c_tx)
A new AVDECC entity has advertised itself as available.
It may be an entity starting up or a previously seen entity that had timed out.
Parameters
i_avb
client interface of type avb_interface into avb_manager()
my_guid
The GUID of this entity
entity
The information advertised by the remote entity
c_tx
A transmit channel end to the Ethernet server
-
void avb_talker_on_listener_connect(client interface avb_interface i_avb, int source_num, const_guid_ref_t listener_guid)
A Controller has indicated that a Listener is connecting to this Talker stream source.
Parameters
i_avb
client interface of type avb_interface into avb_manager()
source_num
The local id of the Talker stream source
listener_guid
The GUID of the Listener entity that is connecting
-
void avb_talker_on_listener_disconnect(client interface avb_interface i_avb, int source_num, const_guid_ref_t listener_guid, int connection_count)
A Controller has indicated that a Listener is disconnecting from this Talker stream source.
Parameters
i_avb
client interface of type avb_interface into avb_manager()
source_num
The local id of the Talker stream source
listener_guid
The GUID of the Listener entity that is disconnecting
connection_count
The number of connections a Talker thinks it has on it’s stream source, i.e. the number of connect TX stream commands it has received less the number of disconnect TX stream commands it has received. This number may not be accurate since an AVDECC Entity may not have sent a disconnect command if the cable was disconnected or the AVDECC Entity abruptly powered down.
-
avb_1722_1_acmp_status_t avb_listener_on_talker_connect(client interface avb_interface i_avb, int sink_num, const_guid_ref_t talker_guid, unsigned char dest_addr[6], unsigned int stream_id[2], unsigned short vlan_id, const_guid_ref_t my_guid)
A Controller has indicated to connect this Listener sink to a Talker stream.
Parameters
i_avb
client interface of type avb_interface into avb_manager()
sink_num
The local id of the Listener stream sink
talker_guid
The GUID of the Talker entity that is connecting
dest_addr
The destination MAC address of the Talker stream
stream_id
The 64 bit Stream ID of the Talker stream
vlan_id
The VLAN ID of the Talker stream
my_guid
The GUID of this entity
-
void avb_listener_on_talker_disconnect(client interface avb_interface i_avb, int sink_num, const_guid_ref_t talker_guid, unsigned char dest_addr[6], unsigned int stream_id[2], const_guid_ref_t my_guid)
A Controller has indicated to disconnect this Listener sink from a Talker stream.
Parameters
i_avb
client interface of type avb_interface into avb_manager()
sink_num
The local id of the Listener stream sink
talker_guid
The GUID of the Talker entity that is disconnecting
dest_addr
The destination MAC address of the Talker stream
stream_id
The 64 bit Stream ID of the Talker stream
my_guid
The GUID of this entity
1722.1 descriptors
The XMOS AVB reference design provides an AVDECC Entity Model (AEM) consisting of descriptors to describe the internal components of the Entity. For a complete overview of AEM, see section 7 of the 1722.1 specification.
An AEM descriptor is a fixed field structure followed by variable length data which describes an object in the AEM Entity model. The maximum length of a descriptor is 508 octets.
All descriptors share two common fields which are used to uniquely identify a descriptor by a type and an index. AEM defines a number of descriptors for specific parts of the Entity model. The descriptor types that XMOS currently provide in the reference design are listed in the table below.
Editing descriptors
The descriptors are declared in the a header configuration file named aem_descriptors.h.in within the src/ directory of the application. The XMOS Reference column in the table refers to the array names of the descriptors in this file.
This file is post-processed by a script in the build stage to expand strings to 64 octet padded with zeros.
Name |
Description |
XMOS Reference |
---|---|---|
ENTITY |
This is the top level descriptor defining the Entity. |
desc_entity |
CONFIGURATION |
This is the descriptor defining a configuration of the Entity. |
desc_configuration_0 |
AUDIO_UNIT |
This is the descriptor defining an audio unit. |
desc_audio_unit_0 |
STREAM_INPUT |
This is the descriptor defining an input stream to the Entity. |
desc_stream_input_0 |
STREAM_OUTPUT |
This is the descriptor defining an output stream from the Entity. |
desc_stream_output_0 |
JACK_INPUT |
This is the descriptor defining an input jack on the Entity. |
desc_jack_input_0 |
JACK_OUTPUT |
This is the descriptor defining an output jack on the Entity. |
desc_jack_output_0 |
AVB_INTERFACE |
This is the descriptor defining an AVB interface. |
desc_avb_interface_0 |
CLOCK_SOURCE |
This is the descriptor describing a clock source. |
desc_clock_source_0..1 |
LOCALE |
This is the descriptor defining a locale. |
desc_locale_0 |
STRINGS |
This is the descriptor defining localized strings. |
desc_strings_0 |
STREAM_PORT_INPUT |
This is the descriptor defining an input stream port on a unit. |
desc_stream_port_input_0 |
STREAM_PORT_OUTPUT |
This is the descriptor defining an output stream port on a unit. |
desc_stream_port_output_0 |
EXTERNAL_PORT_INPUT |
This is the descriptor defining an input external port on a unit. |
desc_external_input_port_0 |
EXTERNAL_PORT_OUTPUT |
This is the descriptor defining an output external port on a unit. |
desc_external_output_port_0 |
AUDIO_CLUSTER |
This is the descriptor defining a cluster of channels within an audio stream. |
desc_audio_cluster_0..N |
AUDIO_MAP |
This is the descriptor defining the mapping between the channels of an audio stream and the channels of the audio port. |
desc_audio_map_0..N |
CLOCK_DOMAIN |
This is the descriptor describing a clock domain. |
desc_clock_domain_0 |
Adding and removing descriptors
Descriptors are indexed by a descriptor list named aem_descriptor_list in the aem_descriptors.h.in file.
The format for this list is as follows:
Descriptor type |
Number of descriptors of type (N) |
Size of descriptor 0 (bytes) |
Address of descriptor 0 |
... |
Size of descriptor N (bytes) |
Address of descriptor N |
For example:
AEM_ENTITY_TYPE, 1, sizeof(desc_entity), (unsigned)desc_entity
PTP client API
The PTP client API can be used if you want extra information about the PTP time domain. An application does not need to directly use this to control the AVB endpoint since the talker, listener and media clock server units communicate with the PTP server directly.
Time data structures
-
ptp_timestamp
This type represents a timestamp in the gptp clock domain.
Structure Members:
-
unsigned int seconds
-
unsigned int nanoseconds
-
Getting PTP time information
-
ptp_time_info
This type is used to relate local XCore time with gptp time.
It can be retrieved from the PTP server using the ptp_get_time_info() function.
-
ptp_time_info_mod64
This structure is used to relate local XCore time with the least significant 64 bits of gptp time.
The 64 bits of time is the PTP time in nanoseconds from the epoch.
It can be retrieved from the PTP server using the ptp_get_time_info_mod64() function.
-
void ptp_get_time_info(chanend ptp_server, ptp_time_info &info)
Retrieve port progatation delay from the ptp server.
Parameters
ptp_server
chanend connected to the ptp_server
pdelay
unsigned int with delay in ns
-
void ptp_get_time_info_mod64(chanend ?ptp_server, ptp_time_info_mod64 &info)
Retrieve time information from the ptp server.
This function gets an up-to-date structure of type ptp_time_info_mod64 to use to convert local time to ptp time (modulo 64 bits).
Parameters
ptp_server
chanend connected to the ptp_server
info
structure to be filled with time information
-
void ptp_request_time_info(chanend ptp_server)
This function requests a ptp_time_info structure from the PTP server.
This is an asynchronous call so needs to be completed later with a call to ptp_get_requested_time_info().
Parameters
ptp_server
chanend connecting to the ptp server
-
void ptp_request_time_info_mod64(chanend ptp_server)
This function requests a ptp_time_info_mod64 structure from the PTP server.
This is an asynchronous call so needs to be completed later with a call to ptp_get_requested_time_info_mod64().
Parameters
ptp_server
chanend connecting to the PTP server
-
void ptp_get_requested_time_info(chanend ptp_server, ptp_time_info &info)
This function receives a ptp_time_info structure from the PTP server.
This completes an asynchronous transaction initiated with a call to ptp_request_time_info(). The function can be placed in a select case which will activate when the PTP server is ready to send.
Parameters
ptp_server
chanend connecting to the PTP server
info
a reference parameter to be filled with the time information structure
-
void ptp_get_requested_time_info_mod64(chanend ptp_server, ptp_time_info_mod64 &info)
This function receives a ptp_time_info_mod64 structure from the PTP server.
This completes an asynchronous transaction initiated with a call to ptp_request_time_info_mod64(). The function can be placed in a select case which will activate when the PTP server is ready to send.
Parameters
ptp_server
chanend connecting to the PTP server
info
a reference parameter to be filled with the time information structure
Converting timestamps
-
void local_timestamp_to_ptp(ptp_timestamp &ptp_ts, unsigned local_ts, ptp_time_info &info)
Convert a timestamp from the local XCore timer to PTP time.
This function takes a 32-bit timestamp taken from an XCore timer and converts it to PTP time.
Parameters
ptp_ts
the PTP timestamp structure to be filled with the converted time
local_ts
the local timestamp to be converted
info
a time information structure retrieved from the ptp server
-
unsigned local_timestamp_to_ptp_mod32(unsigned local_ts, ptp_time_info_mod64 &info)
Convert a timestamp from the local XCore timer to the least significant 32 bits of PTP time.
This function takes a 32-bit timestamp taken from an XCore timer and converts it to the least significant 32 bits of global PTP time.
Parameters
local_ts
the local timestamp to be converted
info
a time information structure retrieved from the PTP server
Returns
the least significant 32-bits of ptp time in nanoseconds
-
unsigned ptp_timestamp_to_local(ptp_timestamp &ts, ptp_time_info &info)
Convert a PTP timestamp to a local XCore timestamp.
This function takes a PTP timestamp and converts it to a local 32-bit timestamp that is related to the XCore timer.
Parameters
ts
the PTP timestamp to convert
info
a time information structure retrieved from the PTP server.
Returns
the local timestamp