5. Understanding RISCOF Inputs¶
There are three major inputs that are required by most of the subcommand of riscof listed in the RISCOF Commands section:
The
config.ini
fileThe
DUT plugin directory
The
Reference plugin directory
This section will discuss each of the above requirements in detail
5.1. Config.ini Syntax¶
The config.ini
file follows the ini syntax and is
used to specify the name of the dut and reference plugins, path of the model plugins, plugin
specific parameters and paths to the DUT’s riscv-config based isa and platform yamls.
A generic format of the config.ini
file required by riscof is presented below. A similar
template file can be generated using the --setup
command of RISCOF.
[RISCOF]
ReferencePlugin=<name-of-ref-plugin>
ReferencePluginPath<path-to-ref-plugin>
DUTPlugin=<name-of-dut-plugin>
DUTPluginPath=<path-to-dut-plugin>
[dut-name]
pluginpath=<path-to-dut-plugin>
ispec=<path-to-isa-spec>
pspec=<path-to-platform-spec>
jobs=<num-of-jobs> #OPTIONAL
PATH=<executable-path> #OPTIONAL
[ref-name]
pluginpath=<path-to-dut-plugin>
jobs=<num-of-jobs> #OPTIONAL
PATH=<executable-path> #OPTIONAL
The config file also allows you to define specific nodes/fields
which can be used by the respective model plugins. For e.g., in the above template the
pluginpath variable under the [dut-name] header is available to the DUT python plugin file
via RISCOF. The plugin may use this pluginpath to detect the env
files, scripts and other
collaterals that may be required during execution.
Similarly one can define more variables and prefixes here which can directly be
used in the respective plugins. This allows one to build parameterized and configurable plugins, the
values of which are defined in the the config.ini
file.
For example, in the case of sail we can define a PATH
variable which can point to where the C
emulator binaries are located. This allows the plugin to directly probe the variable and use this
as part of the execution commands.
The idea here is to have a single place of change which is easy rather than hard-coding the same within the plugins.
5.1.1. File path specification¶
Different values are allowed for the entries in config.ini
to specify a path.
They are checked in the following order, with the first found valid entry being used:
Absolute path: Usage of user home (
~
) is allowed.Relative to current working directory: The path within the location where RISCOF command was executed.
Relative to
config.ini
location: A path starting from the point whereconfig.ini
is stored.
5.2. Model Plugin Directories¶
Majority of the RISCOF commands also require access to the DUT and Reference Model plugins for successful execution.
A typical DUT plugin directory has the following structure:
├──dut-name/ # DUT plugin templates
├── env
│ ├── link.ld # DUT linker script
│ └── model_test.h # DUT specific header file
├── riscof_dut-name.py # DUT python plugin
├── dut-name_isa.yaml # DUT ISA yaml based on riscv-config
└── dut-name_platform.yaml # DUT Platform yaml based on riscv-config
A typical Reference directory has the following structure:
├──ref-name/ # Reference plugin templates
├── env
│ ├── link.ld # Reference linker script
│ └── model_test.h # Reference specific header file
├── riscof_ref-name.py # Reference python plugin
5.2.1. env directory¶
The env
directory in each must contain:
model_test.h
header file which provides the model specific macros as described in the TestFormat Spec.
link.ld
linker script which can be used by the plugin during test-compilation.
The env
folder can also contain other necessary plugin specific files for pre/post processing of
logs, signatures, elfs, etc.
5.2.2. YAML specs¶
The yaml specs in the DUT plugin directory are the most important inputs to the RISCOF framework. All decisions of filtering tests depend on the these YAML files. The files must follow the syntax/format specified by riscv-config. These YAMLs are validated in RISCOF using riscv-config.
The YAMLs are only required for the DUT plugin, since the reference plugin should use the same YAMLS for its configuration and execution.
Note
It is not necessary to have the YAML files in the plugin directory, but is recommended as
a good practice. The files can exist anywhere in your system, as long as the respective paths in
the config.ini
file correctly point to it.
5.2.3. Python Plugin¶
The python files prefixed with riscof_
are the most important component of the model plugins.
These python files define how the particular model compiles a test, runs it on the DUT and extracts the
signature.
To provide a standardized interface for all models, the python plugins must define all actions of the model under specific functions defined by the Abstract Base Classes specified by RISCOF. A more detailed explanation on how to build this file for you model can be found in the Plugin Function Definitions section.