Metadata Inserter (`metadata_inserter`)

Inserts a metadata message into the stream of data when prompted to do so, via either the trigger port or a property write.

Design

Inserts a metadata message, with configurable id and value properties, when the property insert_metadata_message is set to true or, if the optional trigger port receives a sample opcode with a boolean value of true.

Data received on the input port is passed through unchanged to the output port. When a sample message with a value of false is received on the optional trigger port, the behaviour remains unchanged allowing data to pass through unchanged to the output port. When a sample message with a value of true is received on the optional trigger port, or when the property insert_metadata_message is set to true, back pressure is applied to the input interface. A metadata message with id/value set to metadata_id and metadata_value is output. Input back pressure is then removed and data passes onwards.

If the increment_value property is set, metadata_value is incremented after each message insertion. The metadata_value property will then be updated after incrementing.

If the insert_metadata_message property is set to true, a single metadata message is inserted. The insert_metadata_message property is cleared to false by the component after the insertion of a metadata message.

If the trigger port is connected, it discards all non-sample opcodes received on that port. Samples within sample opcode messages are consumed at the same rate as the input port consumes samples when the input port opcode is set to samples. Message boundaries are only observed from the input port, while message boundaries on the trigger port are ignored.

If the trigger port is not connected or the trigger port indicates the EOF flag is set then any sample opcodes on the input port are sent directly to the output port.

Data Flow

The rate at which the trigger and input ports are consumed is dependent on the opcode associated with the port:

Trigger and input port are sample opcodes: Both ports consumed at the same rate.
Trigger port is sample opcode; input port is non-sample opcode: Trigger port blocked; input port consumed.
Trigger port is non-sample opcode; input port is sample opcode: Trigger port consumed; input port blocked.
Trigger port is non-sample opcode; input port is non-sample opcode: Both ports consumed at the same rate.

Interface

<?xml version="1.0"?>
<componentspec>
  <property name="metadata_id" type="ulong" writable="true" default="0"
    description="Sets the id of the metadata messages to insert."/>
  <property name="metadata_value" type="ulonglong" writable="true" volatile="true" default="0"
    description="Sets the value of the metadata message."/>
  <property name="increment_value" type="bool" writable="true" default="true"
    description="When enabled, causes the metadata value field to be incremented after each insertion."/>
  <property name="insert_metadata_message" type="bool" writable="true" volatile="true" default="false"
    description="Inserts a metadata message on write"/>
  <property name="port_width" type="uchar" parameter="true" default="16" description="Defines the input data width in bits."/>
  <port name="trigger" producer="false" optional="true" protocol="bool_timed_sample-prot"/>
  <port name="input" producer="false" numberofopcodes="6" defaultbuffersize="16384"/>
  <port name="output" producer="true" numberofopcodes="6" defaultbuffersize="16384"/>
</componentspec>

Opcode Handling

All messages on the input port are passed through to the output port, regardless of opcode.

A sample opcode received on the trigger port with a value of True will trigger the insertion of a metadata message, all other opcodes on the trigger port are discarded. This insertion will occur such that the matched sample on the input port will be the first sample in the sample message following the inserted metadata message.

Properties

metadata_id: Sets the id of the metadata messages to insert.
- Type: ulong
- Access:
  - Parameter: False
  - Writable: True
  - Initial: False
  - Volatile: False
- Default value: 0
metadata_value: Sets the value of the metadata message.
- Type: ulonglong
- Access:
  - Parameter: False
  - Writable: True
  - Initial: False
  - Volatile: True
- Default value: 0
increment_value: When enabled, causes the metadata value field to be incremented after each insertion.
- Type: bool
- Access:
  - Parameter: False
  - Writable: True
  - Initial: False
  - Volatile: False
- Default value: true
insert_metadata_message: Inserts a metadata message on write. Resets to false after insertion is completed.
- Type: bool
- Access:
  - Parameter: False
  - Writable: True
  - Initial: False
  - Volatile: True
- Default value: false
port_width: Defines the input data width in bits.
- Type: uchar
- Access:
  - Parameter: True
  - Writable: False
  - Initial: False
  - Volatile: False
- Default value: 16

Ports

Inputs:

trigger
- Protocol: bool_timed_sample-prot
- Optional: True
input
- Protocol: None
- Optional: False

Outputs:

output
- Protocol: None
- Optional: False

Implementations

metadata_inserter (HDL)
metadata_inserter (RCC)

Example Application

<?xml version="1.0"?>
<application done="file_write">
  <instance component="ocpi.core.file_read" connect="metadata_inserter" to="input">
    <property name="filename" value="input.bin"/>
  </instance>
  <instance component="ocpi.comp.sdr.interface.metadata_inserter" connect="file_write">
    <property name="metadata_id" value="1"/>
    <property name="metadata_value" value="12"/>
    <property name="increment_value" value="true"/>
    <!-- Setting true here will cause a single metadata message to be inserted
         before the incoming messages -->
    <property name="insert_metadata_message" value="true"/>
  </instance>
  <instance component="ocpi.core.file_write">
    <property name="filename" value="output.bin"/>
  </instance>
</application>

Dependencies

The dependencies to other elements in OpenCPI are:

Metadata inserter primitive v2

There is also a dependency on:

ieee.std_logic_1164

Limitations

Limitations of metadata_inserter are:

Testing of triggers through setting the property insert_metadata_message is not fully tested: It is only set before the input port is ready, so is only tested as a delayed trigger and not on an active input port stream (whether directly during a sample opcode or by a delayed trigger during a non-sample opcode).

Triggering multiple metadata messages through insert_metadata_message when the output is providing back pressure will result in only a single metadata message being inserted.

Testing

Tested platforms: None

Component testing not completed.

Metadata Inserter (metadata_inserter)