Data src (data_src)

data_src is an asset in the ocpi.assets.misc_comps component library. Implementations include data_src HDL Worker (data_src.hdl). Tested platforms include e3xx, xsim, zed.

Design

Data Src selects one DATA_BIT_WIDTH_p bits-wide data bus from multiple data generation sources, packs the DATA_BIT_WIDTH_p bits in bit-forward order in the least significant bits of the I data bus and bit-reverse order in the most significant bits of the Q data bus, and outputs that I/Q bus to the out port. The DATA_BIT_WIDTH_p bits-wide data sources are:

  • a unsigned counter,

  • a walking ones bus (e.g. b’100 -> b’010 -> b’001 -> b’100 etc),

  • a Linear Feedback Shift Register (LFSR),

  • and a property-driven fixed value.

The bitwidth common to all data source buses is parameterized. In the case that the data source bus width is less than the iqstream I/Q widths of 16 bits, the bus is packed into the most significant bits of I and Q. This aids in data alignment when this component is connected directly to a DAC device worker, which commonly takes the DAC bitwidth-most significant bits of I and Q from an iqstream input port for its data transmission.
This component includes a property-driven setting which can optionally disable the output port once a specified number of samples have been sent. This component can also be parameterized to send an End of File (EOF) once the output port is disabled.

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

data_src block diagram.

Figure 152: data_src block diagram.

Interface

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

  <!-- Parameters -->
  <Property Name="DATA_BIT_WIDTH_p" Type="ushort"
                                   Parameter="true"
                                   Default="16"
                                   Description="Determines the width of the buses for each of the I and Q data generation memory elements - if less than 16, the most significant DATA_BIT_WIDTH_p bits of I and Q on the out port will be filled. Value is expect to be less than or equal to 16."/>
  <Property Name="LFSR_POLYNOMIAL_p" Type="bool"
                                     Arraylength="DATA_BIT_WIDTH_p"
                                     Parameter="true"
                                     Default="0"
                                     Description="E.g., a value of 1,1,0,1 would correspond to an LFSR polynomial of x^4 + x^3 + (0*x^2) + x^1 + 1 (+1 is always implied regardless of value)."/>
  <Property Name="LFSR_SEED_p" Type="bool"
                               Arraylength="DATA_BIT_WIDTH_p"
                               Parameter="true"
                               Default="0"
                               Description="Out-of-reset value of the Linear Feedback Shift Register (only affects output data in LFSR mode). This value should never be all zeros, which would cause the register to always have a value of all zeros regardless of polynomial value."/>
  <Property Name="EOF_WHEN_NUM_SAMPLES_REACHED_p" Type="bool"
                                   Parameter="true"
                                   Default="false"
                                   Description="When value is true and num_samples property value is not -1, worker will generate EOF after num_samples amount of samples have been sent out the output port. Note this functionality is independent of the value of the enable property."/>

  <!-- Initial Properties -->
  <Property Name="messageSize_bytes" Type="ulong"
                                     Initial="true"
                                     Default="0"
                                     Description="Message size in bytes. When the value of (num_samples * num bytes per sample) is less than this property's value, the value of (num_samples * num bytes per sample) is used as the message size."/>

  <!-- Runtime Properties -->
  <Property Name="num_samples" Type="long" 
                               Writable="true"
                               Default="-1"
                               Description="Maximum number of samples which will be sent out of the output port once out of reset. Note that samples are only sent when the enable property has a value of true. When the value of this property is -1, samples will be sent indefinitely (obeying backpressure from the connected worker, of course)."/>
  <Property Name="fixed_value" Type="bool"
                               Arraylength="16"
                               Writable="true"
                               Default="0x5a5a"
                               Description="The value of this property will be used for I (and the bit-reversed version of this value will be used for Q) to send to the output port when the mode property's value is 'fixed'.
                                            Array index 0 corresponds to the 15th (most significant) I bit and the 16-DATA_BIT_WIDTH_p Q bit of the out port,
                                            array index 1 corresponds to the 14th (next-to-most significant) I bit and the 15-DATA_BIT_WIDTH_p Q bit of the out port, etc..."/>
  <Property Name="mode" Type="enum"
                        Enums="count,walking,LFSR,fixed"
                        Writable="true"
                        Default="count"
                        Description="Counter, walking ones, Linear Feedback Shift Register, or fixed value."/>
  <Property Name="enable" Type="bool"
                          Writable="true"
                          Default="true"
                          Description="When the worker is not in reset, this property must have a value of true for the data to be sent to the output. Note that this property has no effect on the EOF operation (see EOF_WHEN_NUM_SAMPLES_REACHED_p parameter property)."/>
  <Property Name="LFSR_bit_reverse" Type="bool"
                                    Writable="true"
                                    Default="true"
                                    Description="Used to determine the LFSR shift direction. When true, the DATA_BIT_WIDTH_p-bits wide LFSR will be reversed for both I and Q."/>
  <Property Name="mask_I" Type="ushort"
                          Writable="true"
                          Default="0xffff"
                          Description="I data will be bitwise anded with this mask before being sent to out port."/>
  <Property Name="mask_Q" Type="ushort"
                          Writable="true"
                          Default="0xffff"
                          Description="Q data will be bitwise anded with this mask before being sent to out port."/>

  <!-- Ports -->
  <!-- Complex signed samples (Q0.15 I, Q0.15 Q). This port generates data while obeying backpressure. This port is disabled when either the enable property has a value of false or when the num_samples property has a value of greater than 0 and num_samples amount of samples have been sent out this port. -->
  <DataInterfaceSpec Name="out" Producer="true"
                                Protocol="iqstream_protocol"
                                ZeroLengthMessages="true"/>

</ComponentSpec>

Properties

  • DATA_BIT_WIDTH_p: Determines the width of the buses for each of the I and Q data generation memory elements - if less than 16, the most significant DATA_BIT_WIDTH_p bits of I and Q on the out port will be filled. Value is expect to be less than or equal to 16.

    • Type: ushort

    • Access:

      • Parameter: True

      • Writable: False

      • Initial: False

      • Volatile: False

    • Default value: 16

  • LFSR_POLYNOMIAL_p: E.g., a value of 1,1,0,1 would correspond to an LFSR polynomial of x^4 + x^3 + (0*x^2) + x^1 + 1 (+1 is always implied regardless of value).

    • Type: bool

      • Array dimensions: ['DATA_BIT_WIDTH_p']

    • Access:

      • Parameter: True

      • Writable: False

      • Initial: False

      • Volatile: False

    • Default value: 0

  • LFSR_SEED_p: Out-of-reset value of the Linear Feedback Shift Register (only affects output data in LFSR mode). This value should never be all zeros, which would cause the register to always have a value of all zeros regardless of polynomial value.

    • Type: bool

      • Array dimensions: ['DATA_BIT_WIDTH_p']

    • Access:

      • Parameter: True

      • Writable: False

      • Initial: False

      • Volatile: False

    • Default value: 0

  • EOF_WHEN_NUM_SAMPLES_REACHED_p: When value is true and num_samples property value is not -1, worker will generate EOF after num_samples amount of samples have been sent out the output port. Note this functionality is independent of the value of the enable property.

    • Type: bool

    • Access:

      • Parameter: True

      • Writable: False

      • Initial: False

      • Volatile: False

    • Default value: false

  • messageSize_bytes: Message size in bytes. When the value of (num_samples * num bytes per sample) is less than this property’s value, the value of (num_samples * num bytes per sample) is used as the message size.

    • Type: ulong

    • Access:

      • Parameter: False

      • Writable: False

      • Initial: True

      • Volatile: False

    • Default value: 0

  • num_samples: Maximum number of samples which will be sent out of the output port once out of reset. Note that samples are only sent when the enable property has a value of true. When the value of this property is -1, samples will be sent indefinitely (obeying backpressure from the connected worker, of course).

    • Type: long

    • Access:

      • Parameter: False

      • Writable: True

      • Initial: False

      • Volatile: False

    • Default value: -1

  • fixed_value: The value of this property will be used for I (and the bit-reversed version of this value will be used for Q) to send to the output port when the mode property’s value is ‘fixed’. Array index 0 corresponds to the 15th (most significant) I bit and the 16-DATA_BIT_WIDTH_p Q bit of the out port, array index 1 corresponds to the 14th (next-to-most significant) I bit and the 15-DATA_BIT_WIDTH_p Q bit of the out port, etc…

    • Type: bool

      • Array dimensions: ['16']

    • Access:

      • Parameter: False

      • Writable: True

      • Initial: False

      • Volatile: False

    • Default value: 0x5a5a

  • mode: Counter, walking ones, Linear Feedback Shift Register, or fixed value.

    • Type: enum

      • Allowed values: ['count', 'walking', 'LFSR', 'fixed']

    • Access:

      • Parameter: False

      • Writable: True

      • Initial: False

      • Volatile: False

    • Default value: count

  • enable: When the worker is not in reset, this property must have a value of true for the data to be sent to the output. Note that this property has no effect on the EOF operation (see EOF_WHEN_NUM_SAMPLES_REACHED_p parameter property).

    • Type: bool

    • Access:

      • Parameter: False

      • Writable: True

      • Initial: False

      • Volatile: False

    • Default value: true

  • LFSR_bit_reverse: Used to determine the LFSR shift direction. When true, the DATA_BIT_WIDTH_p-bits wide LFSR will be reversed for both I and Q.

    • Type: bool

    • Access:

      • Parameter: False

      • Writable: True

      • Initial: False

      • Volatile: False

    • Default value: true

  • mask_I: I data will be bitwise anded with this mask before being sent to out port.

    • Type: ushort

    • Access:

      • Parameter: False

      • Writable: True

      • Initial: False

      • Volatile: False

    • Default value: 0xffff

  • mask_Q: Q data will be bitwise anded with this mask before being sent to out port.

    • Type: ushort

    • Access:

      • Parameter: False

      • Writable: True

      • Initial: False

      • Volatile: False

    • Default value: 0xffff

Ports

Inputs:

None.

Outputs:

  • out

    • Protocol: iqstream_protocol

    • Optional: False

Implementations

Dependencies

The dependencies to other elements in OpenCPI are:

  • assets/components/misc_comps/data_src.hdl/data_src.vhd

  • assets/components/misc_comps/data_src.hdl/out_port_inject_zlm.vhd

  • assets/components/misc_comps/data_src.hdl/set_clr.vhd

  • assets/primitives/misc_prims/lfsr/src/lfsr.vhd

Limitations

Limitations of data_src are:

  • None.

Testing

For verification, multiple test are run with varying values for the num_samples property for each of the available data source modes. The output file is checked for expected length and data contents, with the data content check being specific to the given data source mode.