Fifo (fifo)

fifo is an asset in the ocpi.assets.util_comps component library. Implementations include fifo HDL Worker (fifo.hdl). Tested platforms include xsim.

Design

The FIFO component passes complex signed samples (Q0.15 I, Q0.15 Q) from the input port through a First-In-First-Out (FIFO) buffer and onward to the output port. The depth, in number of complex samples, of the FIFO buffer is parameterized. This component includes a property-driven oneshot mode which, when enabled, allows the first FIFO depth number of samples to be sent to the output port and then discontinues data flow to the output port. After data flow is discontinued, the input port still ingests available samples, effectively operating as a data sink. This worker can also be parameterized to send a Zero-Length Message (ZLM) once data flow is discontinued.

A block diagram representation of the implementation is given in Figure 163:

fifo block diagram.

Figure 163: fifo block diagram.

Interface

<!-- This is the spec file (OCS) for: fifo
     Add component spec attributes, like "protocol".
     Add property elements for spec properties.
     Add port elements for i/o ports -->
<ComponentSpec>

  <!-- Parameters -->
  <Property Name="FIFO_DEPTH_p" Type="ulong"
                                Parameter="true"
                                Default="1024"
                                Description="Maximum number of complex samples which the FIFO can hold at any given time."/>
  <Property Name="ZLM_WHEN_ONESHOT_DONE_p" Type="bool"
                                           Parameter="true"
                                           Default="false"
                                           Description="When true, worker will generate Zero-Length-Message after oneshot was enabled and completed."/>
  <Property Name="RESTART_WHEN_ONESHOT_DONE_p" Type="bool"
                                           Parameter="true"
                                           Default="false"
                                           Description="When true, worker will restart buffering once emptied. This allows contiguous blocks of data to be passed through. DO NOT set ZLM_WHEN_ONESHOT_DONE_p when this is set"/>
  <Property Name="BACKPRESSURE_B4_RESTART_p" Type="bool"
                                           Parameter="true"
                                           Default="false"
                                           Description="When true, worker will apply backpressure to the input while restarting so as not to lose samples. Valid when RESTART_WHEN_ONESHOT_DONE_p is true. Useful for test simulation but in real life will break contiguous sample blocks"/>

  <!-- Properties -->
  <Property Name="oneshot" Type="bool"
                           Initial="true"
                           Default="false"
                           Description="If false, the FIFO operates normally, i.e. it allows data to flow from adc_in to adc_passthrough_out and transfers backpressure accordingly. If true, the functionality is as follows. The FIFO receives data from adc_in and holds it until the FIFO is full. One the FIFO is full, data is pulled from the FIFO and sent out the adc_passthrough_out port, all the while data is pulled from adc_in but unused, effectively making the adc_in port a data sink. Note that a control plane reset will always reset the FIFO and start this operation over."/>

  <!-- Ports -->
  <!-- Complex signed samples (Q0.15 I, Q0.15 Q). This port effectively becomes a data sink when oneshot is true and FIFO_DEPTH_p samples have been passed through this port. Note that input Zero-Length Messages will not be counted when using oneshot mode. -->
  <DataInterfaceSpec Name="in" Producer="false"
                               Protocol="iqstream_protocol"
                               ZeroLengthMessages="true"/>
  <!-- Complex signed samples (Q0.15 I, Q0.15 Q). This port will pass through all samples from the input port, enforcing backpressure. If oneshot is true and FIFO_DEPTH_p samples have been passed through this port, no more data will be passed through this port until a reset occurs. Note that Zero-Length Messages will not be counted when using oneshot mode. -->
  <DataInterfaceSpec Name="out" Producer="true"
                                Protocol="iqstream_protocol"
                                ZeroLengthMessages="true"/>

</ComponentSpec>

Properties

  • FIFO_DEPTH_p: Maximum number of complex samples which the FIFO can hold at any given time.

    • Type: ulong

    • Access:

      • Parameter: True

      • Writable: False

      • Initial: False

      • Volatile: False

    • Default value: 1024

  • ZLM_WHEN_ONESHOT_DONE_p: When true, worker will generate Zero-Length-Message after oneshot was enabled and completed.

    • Type: bool

    • Access:

      • Parameter: True

      • Writable: False

      • Initial: False

      • Volatile: False

    • Default value: false

  • RESTART_WHEN_ONESHOT_DONE_p: When true, worker will restart buffering once emptied. This allows contiguous blocks of data to be passed through. DO NOT set ZLM_WHEN_ONESHOT_DONE_p when this is set.

    • Type: bool

    • Access:

      • Parameter: True

      • Writable: False

      • Initial: False

      • Volatile: False

    • Default value: false

  • BACKPRESSURE_B4_RESTART_p: When true, worker will apply backpressure to the input while restarting so as not to lose samples. Valid when RESTART_WHEN_ONESHOT_DONE_p is true. Useful for test simulation but in real life will break contiguous sample blocks.

    • Type: bool

    • Access:

      • Parameter: True

      • Writable: False

      • Initial: False

      • Volatile: False

    • Default value: false

  • oneshot: If false, the FIFO operates normally, i.e. it allows data to flow from adc_in to adc_passthrough_out and transfers backpressure accordingly. If true, the functionality is as follows. The FIFO receives data from adc_in and holds it until the FIFO is full. One the FIFO is full, data is pulled from the FIFO and sent out the adc_passthrough_out port, all the while data is pulled from adc_in but unused, effectively making the adc_in port a data sink. Note that a control plane reset will always reset the FIFO and start this operation over.

    • Type: bool

    • Access:

      • Parameter: False

      • Writable: False

      • Initial: True

      • Volatile: False

    • Default value: false

Ports

Inputs:

  • in

    • Protocol: iqstream_protocol

    • Optional: False

Outputs:

  • out

    • Protocol: iqstream_protocol

    • Optional: False

Implementations

Dependencies

The dependencies to other elements in OpenCPI are:

  • assets/components/util_comps/fifo.hdl/fifo.vhd

  • core/hdl/primitives/bsv/bsv_pkg.vhd

  • core/hdl/primitives/bsv/imports/SizedFIFO.v

Limitations

Limitations of fifo are:

  • None.

Testing

For verification, multiple test files are generated of varying lengths. Each test file is passed into the input port, and the output of the output port is saved to a file. The output file is compared against the input file to make sure they have the same binary contents and length. For the tests that use oneshot mode, the output file is only compared to the first min(input file size,8192) samples, with 8192 hardcoded to correspond to FIFO_DEPTH_p.