Support Code

sentinel-rt

sentinel-rt is an currently-empty Rust support crate. If necessary, it will contain support routines optimized for the Sentinel RISC-V implementation that LLVM or Rust wouldn’t generally know about. I have three potential use cases:

1. Wrappers over custom opcodes[1] and the slow shift operators :),

2. Related to 1., compiler-builtins specialization if possible[2].

3. Runtime/Machine Mode code that is incompatible with the existing riscv-rt, but compatible with the RISC-V spec[3].

However, at present, I don’t need any special support code, so sentinel-rt is just a reserved crate with example code for demo bitstreams.

Note

If I expand demos such that multiple linker scripts are required, the examples directory will become an examples crate. Do not depend on sentinel-rt/examples being stable; the source root is already a workspace!

Verilog Generator

See sentinel_cpu.gen.

Examples

AttoSoC

Small example SoC to demonstrate Sentinel on small FPGAs.

class examples.attosoc.WBMemory(*args, src_loc_at=0, **kwargs)

Memory exposed over the Wishbone bus.

Granularity is always 8, and data width is always 32. The RAM itself consumes 25 bits (32 MB) of address space starting at address 0.

Parameters:

num_bytes (int) – Size of the memory in number of bytes.

bus

Wishbone bus interface.

Type:

In(wishbone.Signature)

num_bytes

Size of the memory in number of bytes.

Type:

int

property init

User contents of memory, if any.

Contents always start at address 0.

elaborate(plat)

class examples.attosoc.WBLeds(*args, src_loc_at=0, **kwargs)

GPIO peripheral over the CSR bus.

bus

Wishbone bus interface.

Type:

In(wishbone.Signature)

leds

LED outputs.

Type:

Out(8)

gpio

Array of 8 GPIO pins. Each GPIO pin has the following signature:

Signature({
    "i": In(1),
    "o": Out(1),
    "oe": Out(1)
})

Registers

• LEDs Output Register

• Bidirectional GPIO Register

• Bidirectional Output Enable Register

  • Bit set == Output Enabled.

elaborate(plat)

class examples.attosoc.RWStrobe(*args, src_loc_at=0, **kwargs)

A read/write field action, without built-in storage.

Parameters:

shape (shape-castable) – Shape of the field.

port

Field port.

Type:

FieldPort

r_data

Read data. Drives port.r_data. See FieldPort.

Type:

Signal(shape)

r_stb

Read strobe. Driven by port.r_stb. See FieldPort.

Type:

Signal()

w_data

Write data. Driven by port.w_data. See FieldPort.

Type:

Signal(shape)

w_stb

Write strobe. Driven by port.w_stb. See FieldPort.

Type:

Signal()

elaborate(platform)

class examples.attosoc.CSRLeds(*args, src_loc_at=0, **kwargs)

GPIO peripheral over the CSR bus.

bus

CSR bus interface- forwards to CSR bridge bus.

Type:

In(csr.Signature)

leds

LED outputs.

Type:

Out(8)

gpio

Array of 8 GPIO pins. Each GPIO pin has the following signature:

Signature({
    "i": In(1),
    "o": Out(1),
    "oe": Out(1)
})

bridge

CSR bridge holding the registers.

Type:

csr.Bridge

class Leds(*args, src_loc_at=0, **kwargs)

A CSR register.

Parameters:

fields (dict or list or Field) – Collection of register fields. If None (default), a dict is populated from Python variable annotations. fields is used to create a FieldActionMap, FieldActionArray, or FieldAction, depending on its type (dict, list, or Field).

Interface attributes

elementElement

Interface between this register and a CSR bus primitive.

field

Collection of field instances.

Type:

FieldActionMap or FieldActionArray or FieldAction

f

Shorthand for Register.field.

Type:

FieldActionMap or FieldActionArray or FieldAction

raises TypeError:

If fields is neither None, a dict, a list, or a Field.

raises ValueError:

If fields is not None and at least one variable annotation is a Field.

raises ValueError:

If element.access is not readable and at least one field is readable.

raises ValueError:

If element.access is not writable and at least one field is writable.

leds: <amaranth_soc.csr.reg.Field object at 0x7078c5119a30>

class InOut(*args, src_loc_at=0, **kwargs)

A CSR register.

Parameters:

fields (dict or list or Field) – Collection of register fields. If None (default), a dict is populated from Python variable annotations. fields is used to create a FieldActionMap, FieldActionArray, or FieldAction, depending on its type (dict, list, or Field).

Interface attributes

elementElement

Interface between this register and a CSR bus primitive.

field

Collection of field instances.

Type:

FieldActionMap or FieldActionArray or FieldAction

f

Shorthand for Register.field.

Type:

FieldActionMap or FieldActionArray or FieldAction

raises TypeError:

If fields is neither None, a dict, a list, or a Field.

raises ValueError:

If fields is not None and at least one variable annotation is a Field.

raises ValueError:

If element.access is not readable and at least one field is readable.

raises ValueError:

If element.access is not writable and at least one field is writable.

inout: <amaranth_soc.csr.reg.Field object at 0x7078c5118ec0>

class OE(*args, src_loc_at=0, **kwargs)

A CSR register.

Parameters:

fields (dict or list or Field) – Collection of register fields. If None (default), a dict is populated from Python variable annotations. fields is used to create a FieldActionMap, FieldActionArray, or FieldAction, depending on its type (dict, list, or Field).

Interface attributes

elementElement

Interface between this register and a CSR bus primitive.

field

Collection of field instances.

Type:

FieldActionMap or FieldActionArray or FieldAction

f

Shorthand for Register.field.

Type:

FieldActionMap or FieldActionArray or FieldAction

raises TypeError:

If fields is neither None, a dict, a list, or a Field.

raises ValueError:

If fields is not None and at least one variable annotation is a Field.

raises ValueError:

If element.access is not readable and at least one field is readable.

raises ValueError:

If element.access is not writable and at least one field is writable.

oe: <amaranth_soc.csr.reg.Field object at 0x7078c5119070>

elaborate(plat)

class examples.attosoc.WBTimer(*args, src_loc_at=0, **kwargs)

Basic 15-bit timer with IRQ, exposed over the Wishbone bus.

IRQ is set whenever bit 14 is set. IRQ and bit 14 is cleared on read of the IRQ register.

bus

Wishbone bus holding the registers.

Type:

In(wishbone.Signature)

irq

IRQ line

Type:

Out(1)

Registers

• IRQ Register

elaborate(plat)

class examples.attosoc.CSRTimer(*args, src_loc_at=0, **kwargs)

Basic 15-bit timer with IRQ, exposed over the CSR bus.

IRQ is set whenever bit 14 is set. IRQ and bit 14 is cleared on read of the IRQ register.

bus

CSR bus interface- forwards to CSR bridge bus.

Type:

In(csr.Signature)

irq

IRQ line

Type:

Out(1)

bridge

CSR bridge holding the registers.

Type:

csr.Bridge

class IRQ(*args, src_loc_at=0, **kwargs)

A CSR register.

Parameters:

fields (dict or list or Field) – Collection of register fields. If None (default), a dict is populated from Python variable annotations. fields is used to create a FieldActionMap, FieldActionArray, or FieldAction, depending on its type (dict, list, or Field).

Interface attributes

elementElement

Interface between this register and a CSR bus primitive.

field

Collection of field instances.

Type:

FieldActionMap or FieldActionArray or FieldAction

f

Shorthand for Register.field.

Type:

FieldActionMap or FieldActionArray or FieldAction

raises TypeError:

If fields is neither None, a dict, a list, or a Field.

raises ValueError:

If fields is not None and at least one variable annotation is a Field.

raises ValueError:

If element.access is not readable and at least one field is readable.

raises ValueError:

If element.access is not writable and at least one field is writable.

irq: <amaranth_soc.csr.reg.Field object at 0x7078c5118bf0>

elaborate(plat)

class examples.attosoc.UART(*args, src_loc_at=0, **kwargs)

Basic hardcoded UART.

Parameters:

• divisor (int) – Set to round(clk-rate / baud-rate). E.g. 12e6 / 115200 = 104.

• data_bits (int) – Number of data bits in character.

elaborate(platform)

class examples.attosoc.WBSerial(*args, src_loc_at=0, **kwargs)

UART exposed over the Wishbone bus.

bus

Wishbone bus holding the registers.

Type:

In(wishbone.Signature)

rx

Serial RX

Type:

In(1)

tx

Serial TX

Type:

Out(1)

irq

IRQ line

Type:

Out(1)

serial

The wrapper serial device

Type:

UART

Registers

• Transmit and Receive Register

• IRQ Register

  • Bit 0: RX register full

  • Bit 1: TX register empty

elaborate(plat)

class examples.attosoc.CSRSerial(*args, src_loc_at=0, **kwargs)

UART exposed over the CSR bus.

bus

CSR bus interface- forwards to CSR bridge bus.

Type:

In(csr.Signature)

rx

Serial RX

Type:

In(1)

tx

Serial TX

Type:

Out(1)

irq

IRQ line

Type:

Out(1)

bridge

CSR bridge holding the registers.

Type:

csr.Bridge

class TXRX(*args, src_loc_at=0, **kwargs)

A CSR register.

Parameters:

fields (dict or list or Field) – Collection of register fields. If None (default), a dict is populated from Python variable annotations. fields is used to create a FieldActionMap, FieldActionArray, or FieldAction, depending on its type (dict, list, or Field).

Interface attributes

elementElement

Interface between this register and a CSR bus primitive.

field

Collection of field instances.

Type:

FieldActionMap or FieldActionArray or FieldAction

f

Shorthand for Register.field.

Type:

FieldActionMap or FieldActionArray or FieldAction

raises TypeError:

If fields is neither None, a dict, a list, or a Field.

raises ValueError:

If fields is not None and at least one variable annotation is a Field.

raises ValueError:

If element.access is not readable and at least one field is readable.

raises ValueError:

If element.access is not writable and at least one field is writable.

txrx: <amaranth_soc.csr.reg.Field object at 0x7078c5118e00>

class IRQ(*args, src_loc_at=0, **kwargs)

A CSR register.

Parameters:

fields (dict or list or Field) – Collection of register fields. If None (default), a dict is populated from Python variable annotations. fields is used to create a FieldActionMap, FieldActionArray, or FieldAction, depending on its type (dict, list, or Field).

Interface attributes

elementElement

Interface between this register and a CSR bus primitive.

field

Collection of field instances.

Type:

FieldActionMap or FieldActionArray or FieldAction

f

Shorthand for Register.field.

Type:

FieldActionMap or FieldActionArray or FieldAction

raises TypeError:

If fields is neither None, a dict, a list, or a Field.

raises ValueError:

If fields is not None and at least one variable annotation is a Field.

raises ValueError:

If element.access is not readable and at least one field is readable.

raises ValueError:

If element.access is not writable and at least one field is writable.

irq: <amaranth_soc.csr.reg.Field object at 0x7078c5118d70>

elaborate(plat)

class examples.attosoc.BusType(*values)

Choose between Wishbone and CSR Peripheral Interfacing.

WB = 'wishbone'

Use Wishbone bus.

Type:

str

CSR = 'csr'

Use CSR bus.

Type:

str

class examples.attosoc.AttoSoC(*args, src_loc_at=0, **kwargs)

AttoSoC constructor.

Create a Sentinel SoC with LEDs/GPIO, timer, and UART.

Parameters:

• num_bytes (int) – Size of the RAM in bytes.

• bus_type (BusType) – Bus used for peripherals.

cpu

The Sentinel CPU

mem

CPU Memory

leds

The LEDs/GPIO peripheral

timer

The timer peripheral

serial

The UART peripheral

property rom

Memory contents of user program, if any.

print_memory_map()

Print out memory map of attached AttoSoC peripherals.

elaborate(plat)

examples.attosoc.demo(args)

AttoSoC generator entry point.

examples.attosoc.main()

AttoSoC generator command-line parser.

Footnotes

[1]

A memcpy instruction is a good candidate for custom microcoded instruction with speedups.

[2]

Not clear to me that this is possible! Just something I thought of.

[3]

The big one here is that RISC-V permits hardcoding MTVEC, but last I checked, this was not supported. This would likely be a size win, but I don’t want to create a fork of riscv-rt just for this one edge case, so I deal.