Tag Select (tag_select)

Selects one channel from a metadata-tagged symbol stream and batches its samples into large output messages, stripping all metadata and all other channels.

Tested platforms include xsim.

Design

The tag_select worker is a metadata-aware diagnostic tap for the folded demodulator front-end pipeline. It operates on the TAGGED streams produced by ted_x16, dsd_x16, and fs_x16, where every symbol decision is preceded by a 4-word metadata message that carries the channel identifier in the low byte of word 2 (the value field of the metadata beat at index 2).

For each incoming symbol, the worker:

  1. Parses the 4-word metadata message to extract the channel tag (cur_ch).

  2. If the extracted tag matches the configured channel property, the following 1-word sample message payload is written into a 2048-deep distributed-RAM FIFO; otherwise it is discarded.

  3. All metadata words are dropped unconditionally, regardless of channel.

Accumulated samples are emitted as batched sample_op_e output messages of up to 1024 samples each (BATCH = 1024). Batching is essential for DMA throughput: emitting one sample per message at symbol rates in the hundreds of kHz would message-rate-limit the host file_write consumer. At EOF the worker flushes any partial batch then asserts the output EOF.

This worker is the metadata-aware counterpart to chan_select. Use tag_select on the tagged outputs of ted_x16/dsd_x16/fs_x16; use chan_select on the positional 16-sample-frame streams from the channelizer, decimate3, bd_x16, and cr_x16.

Interface

<?xml version='1.0' encoding='utf-8'?>
<!-- tag_select: pick ONE channel out of a TAGGED symbol stream (ted_x16 /
     dsd_x16 / fs_x16 output) and write ONLY that channel's sample words,
     batched into large messages so the host file_write DMA keeps up.

     Input framing (tagged, post front end): per symbol decision a 4 word
     metadata message (opcode metadata, SOM on word 0, EOM on word 3; the
     channel id is in the low byte of word 2) followed by a 1 word sample
     message (opcode sample, SOM+EOM) carrying the symbol/soft payload.

     This is the METADATA AWARE counterpart to chan_select (which is POSITIONAL:
     16 sample frames selected by slot, for the channelizer/decimate3/bd/cr
     streams).  Use tag_select on ted/dsd/fs; use chan_select on the positional
     streams.

     The worker tracks the channel from each metadata message, forwards only the
     sample words whose tag == channel (dropping ALL metadata and all other
     channels), and batches the kept samples into BATCH sample messages.  That
     drops the output message rate to symbol_rate/BATCH, so the per symbol
     metadata no longer message rate limits the capture.  Debug tap: wire its
     output to file_write to capture one channel's symbols/soft. -->
<ComponentSpec>
  <property name="channel" type="uchar" writable="true" default="0"
            description="Channel/abs-bin tag to select; samples of all others are dropped"/>
  <port name="input"  producer="false" protocol="complex_short_timed_sample-prot"/>
  <port name="output" producer="true"  protocol="complex_short_timed_sample-prot"/>
</ComponentSpec>

Ports

Inputs:

  • input: Tagged symbol stream from a front-end fold worker (ted_x16, dsd_x16, or fs_x16); complex_short_timed_sample-prot carrying interleaved metadata and sample opcodes.

    • Protocol: complex_short_timed_sample-prot

    • Optional: False

Outputs:

  • output: Batched sample stream for a single selected channel; complex_short_timed_sample-prot, sample opcode only, metadata stripped.

    • Protocol: complex_short_timed_sample-prot

    • Optional: False

Opcode Handling

On the input port, tag_select consumes both metadata_op_e and sample_op_e opcodes. Metadata messages are parsed to extract the channel tag and are then dropped; no metadata words appear on the output. Sample words whose tag matches channel are forwarded; all others are silently discarded.

Output messages carry only the sample_op_e opcode.

Properties

  • channel: Channel/abs-bin tag to select; samples of all others are dropped.

    • Type: uchar

    • Access:

      • Parameter: False

      • Writable: True

      • Initial: False

      • Volatile: False

    • Default value: 0

Implementations

  • tag_select (HDL)

    HDL implementation of a metadata-aware channel selection tap that filters and batches one channel from a tagged front-end fold output stream.

Dependencies

The tag_select HDL worker depends on:

  • ieee.std_logic_1164

  • ieee.numeric_std

  • ocpi.types (OpenCPI-generated protocol opcode constants)

The 2048-entry FIFO is implemented as a ram_style="distributed" LUT RAM inferred from the fifo_t array signal.

Limitations

Limitations of tag_select are:

  • FIFO depth is 2048 samples (fixed at elaboration). If back-pressure on the output stalls the worker for longer than 2048 symbols of the selected channel, older samples are silently overwritten.

  • The channel property is read once per symbol (combinatorially from props_in), so changing it mid-stream produces one cycle of ambiguous selection at the boundary.

  • No metadata is forwarded to the output; downstream consumers receive plain sample words with no channel-ID annotation.

Testing

There is no dedicated unit test directory for tag_select. The worker is exercised end-to-end in the folded-chain assembly test, where its output is validated against known symbol sequences captured from a single channel of the fs_x16 output.

Tested platforms: None