Configuration Schema Reference

This reference documents the CPU configuration file schema used by RiescueD. Configuration files are JSON format and define the target system’s memory map, features, and test generation parameters.

Required Configuration Elements

reset_pc

The program counter value when the processor starts.

Type: String (hexadecimal) or Integer

Examples:

"reset_pc": "0x8000_0000"
"reset_pc": "0x80000000"
"reset_pc": 2147483648

mmap - Memory Map

The Memory Map is configured with the mmap key, using the Memory class:

class riescue.dtest_framework.config.memory.Memory(dram_ranges: list[~riescue.dtest_framework.config.memory.DramRange] = <factory>, io_ranges: list[~riescue.dtest_framework.config.memory.IoRange] = <factory>, secure_ranges: list[~riescue.dtest_framework.config.memory.DramRange] = <factory>, reserved_ranges: list[~riescue.dtest_framework.config.memory.BaseMem] = <factory>)

Memory object with DRAM, IO, secure, and reserved ranges. Defaults to non-secure DRAM and IO ranges. Frozen after construction to prevent modification of ranges.

Parameters:

dram_ranges – List of DRAM ranges
io_ranges – List of IO ranges
secure_ranges – List of secure ranges
reserved_ranges – List of reserved ranges. Currently unused

Note

Default DRAM Range is 0x8000_0000 - 0xFFFFFFFF_FFFFFFFF Default IO Range is 0x0 - 0x7FFFFFFF

Construct with from_dict(cfg) using a Memory Map structured as:

{
    "dram": {
        "dram": { "address": "0x9000_0000", "size": "0x8000_0000", "secure": false},
        "dram0": { "address": "0x8000_0000", "size": "0x8000_0000", "secure": true},
        "secure0": { "address": "0x10000_0000", "size": "0x8000_0000", "secure": true},
    },
    "io": {
        "io0": {"address" : "0x0", "size" : "0x1_0000"},
        "io1": {"address" : "0x1_0000", "size" : "0x1_0000", "test_access": true},
    },
}

dram is a required key
dram can contain a secure key and boolean value, which marks the range as DRAM and secure.
dram regions that start with secure* are also marked as DRAM and secure.
io is an optional key
io can contain multiple ranges

Note that dram is a required key and io is optional. If io is not present, the default IO range is 0x0 - 0x7FFFFFFF. If an empty dictionary is provided, the default memory ranges are used.

Memory Map Components

dram - DRAM Configuration

class riescue.dtest_framework.config.memory.DramRange(start: int = 0, size: int = 0, secure: bool = False, cacheable: bool = False, configurable: bool = False, name: str = '', permissions: PmpAttributes = PmpAttributes.R_W_X)

Bases: BaseMem

Memory range with start address, end address, size, and secure flag

Parameters:

start – start address
size – size of the range
secure – if True, the range is secure
cacheable – if True, range is cacheable.
configurable – if True, range is configurable and can be modified by Runtime
permissions – PMP attributes of the range. E.g. “rwx”, “rw”, “r”, “none”. Determins the PMP permissions of the given range.Defaults to “rwx”.

Raises:

ValueError – if start or size is not an integer
ValueError – if secure is not a boolean

Example JSON:

{
    "address": "0x8000_0000",
    "size": "0x8000_0000",
    "secure": true,
}

address and size are required. Note that secure, cacheable, and configurable are optional. If not present, the range is not secure, cacheable, or configurable. E.g.

{
    "address": "0x8000_0000",
    "size": "0x8000_0000",
}

Would result in a non-secure, non-cacheable, and non-configurable DRAM range.

classmethod from_dict(cfg: dict[str, str | int | bool], name: str = '') → DramRange: Method to create a Range object from a dictionary.

io - I/O Configuration

Memory-mapped I/O regions and devices.

class riescue.dtest_framework.config.memory.IoRange(start: int = 0, size: int = 0, test_access: bool = False, name: str = '', permissions: PmpAttributes = PmpAttributes.R_W)

Bases: BaseMem

IO range with start address, end address, size, and test_access flag

Parameters:

start – start address
size – size of the range
test_access – if False, the range is test_access and not accessible for testing

Construct with from_dict(cfg) using a Memory Map structured as (JSON format):

{
    "address": "0x200_c000",
    "size": "0x5ff_4000",
    "test_access": true,
}

By default, test_access is False.

classmethod from_dict(cfg: Mapping[str, str | int | bool], name: str = '') → IoRange: Method to create a Range object from a dictionary.

Special I/O Devices:

htif - Host-Target Interface, specifies the default end-of-test address (tohost)

Feature Configuration

features - Extension Configuration

Configures RISC-V extensions and their availability.

Type: Object with extension names as keys

Extension Properties:

supported (required) - Whether extension is supported by target (boolean)
enabled (required) - Whether extension is enabled by default (boolean)
randomize (required) - Percentage chance of randomization (0-100)

Standard Extensions:

rv64 / rv32 - Architecture width
i - Base integer instruction set
m - Integer multiplication and division
a - Atomic instructions
f - Single-precision floating-point
d - Double-precision floating-point
c - Compressed instructions
h - Hypervisor extension
v - Vector extension
u - User mode
s - Supervisor mode

Examples:

"features": {
    "rv64": {"supported": true, "enabled": true, "randomize": 100},
    "i": {"supported": true, "enabled": true, "randomize": 100},
    "m": {"supported": true, "enabled": true, "randomize": 100},
    "a": {"supported": true, "enabled": true, "randomize": 100},
    "f": {"supported": true, "enabled": true, "randomize": 100},
    "d": {"supported": true, "enabled": true, "randomize": 100},
    "c": {"supported": true, "enabled": true, "randomize": 100},
    "h": {"supported": true, "enabled": true, "randomize": 100},
    "v": {"supported": true, "enabled": false, "randomize": 100},
    "u": {"supported": true, "enabled": true, "randomize": 100},
    "s": {"supported": true, "enabled": true, "randomize": 100}
}

Test Generation Parameters

test_generation - Generation Settings

Controls various aspects of test generation behavior.

Type: Object

Properties:

secure_access_probability - Percentage chance of secure access patterns (0-100)
secure_pt_probability - Percentage chance of secure page table generation (0-100)
a_d_bit_randomization - Percentage chance of randomizing accessed/dirty bits (0-100)
pbmt_ncio_randomization - Percentage chance of PBMT NCIO randomization (0-100)

Examples:

"test_generation": {
    "secure_access_probability": 30,
    "secure_pt_probability": 0,
    "a_d_bit_randomization": 0,
    "pbmt_ncio_randomization": 0
}

Complete Configuration Example

Here’s a complete configuration file example:

{
    "reset_pc": "0x8000_0000",
    "mmap": {
        "dram": {
            "region0": {
                "address": "0x8000_0000",
                "size": "0x10_0000_0000_0000"
            }
        },
        "io": {
            "address": "0",
            "size": "0x8000_0000",
            "items": {
                "io0": {
                    "address": "0x0",
                    "size": "0x1_0000"
                },
                "io1": {
                    "address": "0x200_c000",
                    "size": "0x5ff_4000",
                    "test_access": "available"
                },
                "htif": {
                    "address": "0x7000_0000",
                    "size": "0x10"
                }
            }
        }
    },
    "features": {
        "rv64": {"supported": true, "enabled": true, "randomize": 100},
        "i": {"supported": true, "enabled": true, "randomize": 100},
        "m": {"supported": true, "enabled": true, "randomize": 100},
        "a": {"supported": true, "enabled": true, "randomize": 100},
        "f": {"supported": true, "enabled": true, "randomize": 100},
        "d": {"supported": true, "enabled": true, "randomize": 100},
        "c": {"supported": true, "enabled": true, "randomize": 100},
        "h": {"supported": true, "enabled": true, "randomize": 100},
        "v": {"supported": true, "enabled": false, "randomize": 100},
        "u": {"supported": true, "enabled": true, "randomize": 100},
        "s": {"supported": true, "enabled": true, "randomize": 100}
    },
    "test_generation": {
        "secure_access_probability": 30,
        "secure_pt_probability": 0,
        "a_d_bit_randomization": 0,
        "pbmt_ncio_randomization": 0
    }
}

Validation Rules

Address Format: - Addresses can use underscore separators for readability: "0x8000_0000" - Both string and integer formats are supported - Hexadecimal strings must start with "0x"

Size Format: - Sizes follow the same format rules as addresses - Must be positive values

Memory Layout: - DRAM regions must not overlap - I/O items must fit within the parent I/O region - All addresses must be valid for the target architecture

Feature Dependencies: - Some extensions have dependencies (e.g., d requires f) - Architecture width (rv32/rv64) affects address space limits