V3.0 - Top-Level Requirements

[ReinhardKeil]

This is a list of the top-level requirements for SDS v3.0

SDS v3 adds a control interface in the SDSIO-Server to provide this additional functionality:

• Record or playback switch using the same firmware image (via sdsFlags)
• User flags to configure algorithms or for A/B tests (via sdsFlags).
• Managed playback data streams for regression tests (via sdsio.yml file).

Filenames and data streams

The format of file names is:

<stream>.<label>.sds      # files created during recording have extension .sds
<stream>.<label>.p.sds    # files created during playback have extension .p.sds

• <stream> is the stream name (SCinput, SCoutput, MLoutput)
• <label> files with the same label contain the same timeslots and therefore have corresponding input/output of an algorithm pipeline.

SDSIO-Server allocates labels during recording

• When the first stream is opened for recording, the SDS-Server assigns a new label (index) based on existing filenames. For example, if SCinput.0.sds and SCinput.1.sds exists, the next label is 2.
• Additional streams get the same label. When a file with the same name exists, a *.bak file is created. A previous *.bak file is deleted.

User may break-up files and change labels

For ML training, capture data streams should be saparated into different cases (i.e. video frames with gesture rock, scissors, papers, or audio frames with words "no", "yes", "on", etc. To achieve that *.sds files may be broken up as shown here.

SDSIO-Server usage of labels during playback

• The labels during playback are specified in the sdsio.yml (see below). This file also defines the playback streams.
• Streams that are recorded have the same label, but use the file extension *.p.sds instead of *.sds (this prevents from usage errors and simplifies file compare).
• When a file with the same name exists, a *.bak file is created. A previous *.bak file is deleted.

Add sdsFlags

sdsFlags enable configuration options and compact diagnostic storage in a single word, enabling very fast checking, logging, and transmission of system information. sdsFlags can be modified by the SDS application or by the SDSIO-Server. Therefore the sdsFlags need to be send/received (via the SDSIO module) with the host computer using the SDSIO-Server. This information exchange should not sacrifice recording performance.

It is proposed to use:

• sdsFlags.31 = 1 for start of the SDS recording/playback I/O.
• sdsFlags.30 = 1 for terminating a CI run (on FVP simulation models or pyOCD)
• sdsFlags.29 = 1 for Playback mode
• sdsFlags.24...28 reserved for future enhancements
• sdsFlags.0..23 for user options (i.e. bypassing filter, ect.)

Details see: #207

SDS user interface only via SDSIO module

Currently SDS requires a debug STDIO for (a) diagnostics and (b) start/stop control. Both features should be enabled via the SDSIO-Server (so that this is the only required communication channel with the host computer. In addition error status should be displayed.

Example SDSIO-Server interaction:

Flags: 0x1                                    # Output sdsFlags status
SDS playback ML_In.case1.sds started
Flags: 0x5 [X]   Idle=56%                     # During I/O output rotating characters [/-\]
SDS_ERROR_IO: sds.c#23                        # Output error messages
SDS playback ML_In.case2.sds started     

Pragmatic user control via console I/O:

• a clear bit 0, A set bit 0 (using the letters A...H for the first 8 bits).
• s clear bit 31 (stop recording), S set bit 31 (start recording)

Only one LED used:

Only one LED is blinking: with 0.5Hz when idle, 5Hz when I/O is in progress.

UART output optional:

Introduce SDS_STDIO with default #define SDS_STDIO 1, when set to 0 no UART is used.

Details see: #178 + #207

SDSIO-Server USB can be connected any time

Currently the SDSIO-Server needs to be started before the SDS application. This should be not required in USB mode.

See: #195

Record/Playback in same image

sdsFlags.29 = 1 is always set in Playback mode. This Flag can be used to switch dynamically between Record and Playback mode which effectively means that the SDSIO-Server can be started multiple times without the need to flash a different image:

Example:

>sdsio-server --control path/my.sdsio.yml             # Record or Playback SDS files (change via command line or monitor interface)
>sdsio-server --control path/my.sdsio.yml --playback  # Playback SDS files in CI system

SDSIO-Server Playback Script

The SDSIO-Server is configured with a control file *.sdsio.yml. There is already a sdsio.yml file for the FVP implementation, however this should be consistent with the SDSIO-Server so that the playback works the same for FVP or hardware.

SDSIO-Server specification: #215

Overall the I/O files for the different streams must have the same label.

Without verbose only the flags and stream label is output:

Play stream: case1 (Flags: 0x1, Idle=25%)
Play stream: case2 (Flags: 0) [X]                            # During I/O output rotating characters [/-\]

Previous tickets now obsolete: #191 + #207

SDSIO-Server Pragmatic Command Line Interface

Using the console input the user can:

• 'R' or 'r' start recording
• 'P' or 'p' start playback
• 'S' or 's' stop recording or playback
• 'A' ... 'H' set sdsFlags 0..7
• 'a' ... 'h' clear sdsFlags 0..7
• 'X' or 'x' terminate SDSIO-Server

Overall simpler user view to SDS

The files sds_control and algorithm need to be simpler. Only the items that relate to SDS should be prefixed with sds. The user algorithm code should not use the sds prefix.

This also includes that the directory structure is simplified, i.e.

Directory	Description
Include	Only contains the user visible include files, sds.h, sdsio.h, sdsio_client.h
source	Contains the core part of sds including internal headers
source/sdsio	Contains client implementations, configuration files for the client implementation are also located there

Details see: #188

SDS VS Code Extension

For a VS Code extension a monitor interface using a localhost port should be added to the SDSIO-Server. This monitor interface should enable the following functionality:

• GUI with buttons: Record, Playback, Stop + 8 SDS Flags [checkboxes].
• On close of all streams: open the processed streams automatically: stream names used, label name used.

Interface specification: theory_ctrl-mon-interface.md

Usability

It should be tolerated that the SDSIO-Server is started after the firmware. The SDSIO-Server should allow for USB, RTT, and Serial Interface:

• Restart of the client firmware when the server gets a new start (could be with a sdsFlag.Restart)
• Connect the server to an already running client system

For Socket mode it is accepted that the SDSIO-Server needs to be started before the firmware.

Other

• Playback will no longer be controlled using the file <name>.index.txt.
• Overall a better consistency should be achieved:
  • Example: sds-check parameter -s should be -i to be consistent with other utilities
• timestamp will be renamed into timeslot. In playback the timeslot is used to synchronize the recording files, i.e. all output streams should have the same timeslots as the first input stream.
• Consider a RTT implementation of an sdsio client (that preferable works with Segger J-Link and pyOCD) (see RTT implementation for Segger J-Link and pyOCD #213)