Enums & Flags

Enums & Flags#

PeakRDL-pybind11 turns SystemRDL encode enums and 1-bit field clusters into real Python types so that reads and writes feel idiomatic and stay self-documenting. Two surfaces cover almost every case:

  • Typed enums for fields with encode = MyEnum.

  • Flag-register conveniences for registers whose fields are all single-bit, including a generated IntFlag for bit-mask composition.

Enums via encode = MyEnum#

The exporter emits a real enum.IntEnum per RDL enum, namespaced under the owning module. Reads decode automatically; writes accept the enum, an int, or the member name (handy at the REPL).

from MySoC.uart import BaudRate, Parity

soc.uart.control.baudrate.read()                    # → BaudRate.BAUD_19200
soc.uart.control.baudrate.write(BaudRate.BAUD_115200)
soc.uart.control.baudrate.write(2)
soc.uart.control.baudrate.write("BAUD_115200")
soc.uart.control.baudrate.choices                   # → BaudRate (the type)

Out-of-range values raise on write, with the exception listing the valid options.

Per-bit flags#

Single-bit fields read as bool-compatible values, and accept 0/1 (or True/False) on write:

soc.system.periph_clk_en1.uart0_clk_en.write(1)
soc.system.periph_clk_en1.uart0_clk_en.read()    # True

This is the right tool when you want to flip exactly one bit and don’t care about the rest of the register.

Whole-register set / clear / toggle#

When you want to manipulate several flag bits at once, every flag-style register exposes a small set of name-based helpers:

soc.system.periph_clk_en1.set("uart0_clk_en", "spi0_clk_en", "i2c0_clk_en")
soc.system.periph_clk_en1.clear("uart0_clk_en")
soc.system.periph_clk_en1.toggle("uart0_clk_en")
soc.system.periph_clk_en1.bits()                  # set of names with bit=1
soc.system.periph_clk_en1.modify(uart0_clk_en=1, spi0_clk_en=1)   # canonical

modify(**fields) is the canonical form: it expresses intent declaratively and round-trips cleanly through the read-modify-write path.

IntFlag auto-generation#

When a register carries a *_FLAGS UDP, or every field in the register is 1-bit, the exporter additionally emits an enum.IntFlag named after the register (e.g. PeriphClkEn1Flags). Use it whenever bit-masks beat keyword-by-keyword spelling:

from MySoC.system import PeriphClkEn1Flags

mask = PeriphClkEn1Flags.UART0_CLK_EN | PeriphClkEn1Flags.SPI0_CLK_EN
soc.system.periph_clk_en1.write(mask)
soc.system.periph_clk_en1.read() & PeriphClkEn1Flags.UART0_CLK_EN

The IntFlag composes with |, &, and ~ like the standard library type, and writes accept either the flag value or a plain int.

See also#

  • /values_and_io