Metadata Stressor (`metadata_stressor`)

Tests an HDL worker’s robustness during development. metadata_stressor is an asset in the ocpi.core component library. Implementations include the metadata_stressor HDL Worker (metadata_stressor.hdl) and the metadata_stressor RCC Worker (metadata_stressor.rcc). Tested platforms include alst4, centos7, isim, matchstiq-z1 (PL), ml605, modelsim, xilinx13_3, xsim and Zedboard(PL).

Function

The metadata stressor component tests an HDL worker’s robustness during development as part of the OpenCPI unit test suite. An HDL worker is expected to accept all valid combinations of metadata without failure, though some are unlikely to be encountered in normal operation. It also may starve the unit under test of data and insert delays between messages. The data starvation may be random or based on a duty cycle. The worker is automatically built into the HDL test assemblies generated by the unit test framework. It can also add zero-length messages (ZLMs) between messages. It passes through the data it receives without change.

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

Figure 4: Metadata Stressor Component Block Diagram

Interface

<ComponentSpec>

  <Property Name="enable_give_lsfr" Type="bool" Initial="true" Default="false"
            Description="'true' : MSB of lfsr-15 drives 'give',
                 'false' : use give_duty to set the give duty-cycle."/>

  <Property Name="enable_take_lsfr" Type="bool" Initial="true" Default="false"
            Description="'true'  : MSB of lfsr-7 drives the 'take',
                  'false' : use take_duty to set the take duty-cycle."/>

  <Property Name="give_duty" Type="ushort" Initial="true" Default="1"
            Description="Set the duty cycle for output port 'give'
                1 - constant, 2 (toggle off/on), 3 (1/on, 2/off), 4 (1/on, 3/off)"/>

  <Property Name="take_duty" Type="ushort" Initial="true" Default="1"
           Description="Set the duty cycle for input port 'take'
                 1 - constant, 2 (toggle off/on), 3 (1/on, 2/off), 4 (1/on, 3/off)"/>

  <Property Name="mode" Type="enum" Initial="true" Enums="bypass, metadata, data, full"
            Default="bypass" Description="Sets the operating mode of the worker.
            Bypass: worker is bypassed entirely.
            Data: metadata is passed through unchanged but data will have no-ops
               inserted based on enable_take_lsfr or take_duty.
            Metadata: metadata will cycle through all possible valid combinations,
               but data will pass through unchanged (ex. it receives a no-op, it passes a no-op).
            Full both metadata and data will be manipulated."/>

  <Property Name="seed" Type="ushort" Initial="true"  Default="1"
            Description="Seed value for the lsfr, must not be zero. Only effects data
            when either enable_give_lsfr or enable_take_lsfr is true."/>

  <Property Name="allow_zlms" Type="bool" Initial="true" Default="false"
            Description="If true, worker will send zero length messages."/>

  <Property Name="insert_nop" Type="bool" Initial="true" Default="false"
            Description="If true, worker sets all three metadata lines to zero to
            provide a delay between messages."/>

  <DataInterfaceSpec Name="in" Producer="false"/>

  <DataInterfaceSpec Name="out" Producer="true" buffersize="in"/>

</ComponentSpec>

Properties

enable_give_lsfr: ‘true’ : MSB of lfsr-15 drives ‘give’, ‘false’ : use give_duty to set the give duty-cycle.
- Type: bool
- Access:
  - Parameter: False
  - Writable: False
  - Initial: True
  - Volatile: False
- Default value: false
enable_take_lsfr: ‘true’ : MSB of lfsr-7 drives the ‘take’, ‘false’ : use take_duty to set the take duty-cycle.
- Type: bool
- Access:
  - Parameter: False
  - Writable: False
  - Initial: True
  - Volatile: False
- Default value: false
give_duty: Set the duty cycle for output port ‘give’ 1 - constant, 2 (toggle off/on), 3 (1/on, 2/off), 4 (1/on, 3/off).
- Type: ushort
- Access:
  - Parameter: False
  - Writable: False
  - Initial: True
  - Volatile: False
- Default value: 1
take_duty: Set the duty cycle for input port ‘take’ 1 - constant, 2 (toggle off/on), 3 (1/on, 2/off), 4 (1/on, 3/off).
- Type: ushort
- Access:
  - Parameter: False
  - Writable: False
  - Initial: True
  - Volatile: False
- Default value: 1
mode: Sets the operating mode of the worker. Bypass: worker is bypassed entirely. Data: metadata is passed through unchanged but data will have no-ops inserted based on enable_take_lsfr or take_duty. Metadata: metadata will cycle through all possible valid combinations, but data will pass through unchanged (ex. it receives a no-op, it passes a no-op). Full both metadata and data will be manipulated.
- Type: enum
  - Allowed values: ['bypass', 'metadata', 'data', 'full']
- Access:
  - Parameter: False
  - Writable: False
  - Initial: True
  - Volatile: False
- Default value: bypass
seed: Seed value for the lsfr, must not be zero. Only effects data when either enable_give_lsfr or enable_take_lsfr is true.
- Type: ushort
- Access:
  - Parameter: False
  - Writable: False
  - Initial: True
  - Volatile: False
- Default value: 1
allow_zlms: If true, worker will send zero length messages.
- Type: bool
- Access:
  - Parameter: False
  - Writable: False
  - Initial: True
  - Volatile: False
- Default value: false
insert_nop: If true, worker sets all three metadata lines to zero to provide a delay between messages.
- Type: bool
- Access:
  - Parameter: False
  - Writable: False
  - Initial: True
  - Volatile: False
- Default value: false

Ports

Inputs:

in: 32 bits.
- Protocol: None
- Optional: False

Outputs:

out: 32 bits.
- Protocol: None
- Optional: False

The HDL worker runtime configuration parameter DATA_WIDTH_p can be used to set a custom data width for the ports.

Implementations

metadata_stressor (HDL)

Application worker HDL implementation with a settable runtime configuration parameter for component port data width.
metadata_stressor (RCC)

Application worker RCC implementation that is only a placeholder to fulfill the requirements of the OpenCPI unit test framework. It passes through data without change and should not be included in normal applications, as it provides no real functionality.

Example Application

<?xml version="1.0"?>
<!-- This file is protected by Copyright. Please refer to the COPYRIGHT file
     distributed with this source distribution.

     This file is part of OpenCPI <http://www.opencpi.org>

     OpenCPI is free software: you can redistribute it and/or modify it under
     the terms of the GNU Lesser General Public License as published by the Free
     Software Foundation, either version 3 of the License, or (at your option)
     any later version.

     OpenCPI is distributed in the hope that it will be useful, but WITHOUT ANY
     WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
     FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
     more details.

     You should have received a copy of the GNU Lesser General Public License
     along with this program. If not, see <http://www.gnu.org/licenses/>. -->
<application done="file_write">
  <instance component="ocpi.core.file_read" connect="metadata_stressor">
    <property name="filename" value="input.bin"/>
  </instance>
  <instance component="ocpi.core.metadata_stressor" connect="file_write">
  </instance>
  <instance component="ocpi.core.file_write">
    <property name="filename" value="output.bin"/>
  </instance>
</application>

Dependencies

The dependencies on other elements in OpenCPI are:

None.

Limitations

Limitations of metadata_stressor are:

None.

Testing

The metadata stressor component is tested via the OpenCPI unit test framework. The metadata_stressor.test/ component unit test suite directory contains XML files that describe the combinations of tests. The test cases exercise changes in every property across three cases, though not every property in every case, as that would take a prohibitively long time.

Case 1 - Tests the component with crafted ZLMs and SWMs, backpressure on, timeout set to 120 seconds.

enable_give_lsfr = True: use lsfr to vary give
enable_take_lsfr = True: use lsfr to vary take
insert_nop = True: insert delay between messages
mode = full: vary data and metadata

Case 2 - Tests the component with eight byte messages, backpressure on, timeout set to 120 seconds.

enable_give_lsfr = True: use lsfr to vary give
enable_take_lsfr = True: use lsfr to vary take
insert_nop = True: insert delay between messages
mode = full: vary data and metadata

Case 3 - Tests the component with a single zlm, backpressure on, timeout set to 120 seconds.

enable_give_lsfr = True: use lsfr to vary give
enable_take_lsfr = True: use lsfr to vary take
insert_nop = True: insert delay between messages
mode = full: vary data and metadata

Case 4 - Tests the component with crafted ZLMs and SWMs, backpressure on, timeout set to 120 seconds.

enable_give_lsfr = True: use lsfr to vary give
enable_take_lsfr = True: use lsfr to vary take
insert_nop = True: insert delay between messages
mode = full: vary data and metadata
mode = data: only vary data
mode = metadata: only vary metadata
mode = full: vary data and metadata

Cases 5-11 - Tests ending on different message types, message size set to 4, stressormode set to full, backpressure on, timeout set to 120 seconds.

mode = full: vary data and metadata
insert nop = True: insert delay between messages
insert nop = False: no delay between messages

Case 12 - Tests most of the functionality, message size set to 128, backpressure on, stressormode set to full, timeout set to 240 seconds.

enable_give_lsfr = True: use lsfr to vary give
enable_give_lsfr = False: use duty cycle to vary give
enable_take_lsfr = True: use lsfr to vary take
enable_take_lsfr = False: use duty cycle to vary take
give_duty = 1: constant
give_duty = 4: 1on3off
take_duty = 1: constant
take_duty = 5: 1on4off
mode = data: only vary data
mode = metadata: only vary metadata
mode = full: vary data and metadata
insert_nop = True: insert delay between messages
insert_nop = False: no delay between messages
seed = 35: seed for lsfr

Case 13 - Tests the RCC version of this component, which is nothing but a placeholder, timeout set to 120 seconds.

In all test cases, the data is simply passed through the component and the tests are determined to be successful by comparing the input and output files.

Metadata Stressor (metadata_stressor)