acacia.system

Module Contents

Classes

SystemState

An Acacia system has a few states which progress linearly in this order:

System

An Acacia Microkit system. This is the top-level container for any single Acacia invocation, encapsulating all Microkit primitives and instantiated subsystems for a single build.

API

exception acacia.system.AcaciaSystemError

Bases: RuntimeError

class acacia.system.SystemState

Bases: enum.Enum

An Acacia system has a few states which progress linearly in this order:

Specification : Metaprogram still adding new things / YAML being parsed
Assembly: All things added, Acacia starts to put together subsystems
Allocation: Subsystems assembled. Allocate final objects (unassigned paddrs)
Final: Acacia is done. Calling terminal actions no longer has an effect

The specication stage is the most permissive, allowing users to manually assign sensitive things like map virtual addresses or channel IDs. Manual assignment of these properties (used commonly by clients of subsystems) is only safe here, since once subsystems build, it must be an invariant that automatic allocation always succeeds.

The assembly state is triggered by calling a terminal action (write_xml_file or create_config_structs).

Once in the final state, all subsystems are considered “finished”.

SPECIFICATION

0

ASSEMBLY

1

ALLOCATION

2

FINAL

3

class acacia.system.System(sys_arch: acacia.arch.Arch, paddr_top: int, dtb: Optional[acacia.dtb.DeviceTreeBlob] = None)

An Acacia Microkit system. This is the top-level container for any single Acacia invocation, encapsulating all Microkit primitives and instantiated subsystems for a single build.

For end-users, the System is an object that is used to create most Microkit primitives and all Acacia subsystems.

System exposes the two terminal actions in Acacia:

  • make_config_structs -> For all subsystems, create data blobs for their ConfigStructs.

  • write_xml_file -> Create a Microkit XML file containing all elements in the System.

Calling either of these actions will cause the System to “assemble” … this involves several internal steps, after which no further Microkit elements or subsystems can be instantiated.

Assembly performs the following steps in the following order:

  1. Subsystem resolution. For each Subsystem, invoke their build method to finalise them.

  2. Auto-allocation. For Microkit objects like MRs, some work like assigning physical addresses can only happen after all subsystems are built. Currently, this only involves physical address allocation for physical MRs without a paddr.

Both of these steps are completed strictly BEFORE generating config structs. This ensures that all addresses, IDs, etc. are evaluated before we try save configuration data.

Note: Calling write_xml_file will NOT automatically generate config structs.

Initialization

assemble()

Run all automated connection steps.

  1. Resolve subsystems and connect their clients.

  2. Allocate any memory addresses that are not assigned yet,

resolve_subsystems()

Construct all subsystems and their client connections.

auto_allocate()

Allocate all un-allocated memory and other resources which can be left blank for automatic assignment.

Currently this only handles assigning paddrs to physical memory regions without explicit addresses.

make_config_structs(build_dir: pathlib.Path = pathlib.Path('./'), dump: bool = False)

Generate config struct data blobs for all Subsystems and patch them into ELFs if flagged (currently WIP, manual objcopies in Makefile needed for now https://github.com/au-ts/microkit_acacia/issues/47 https://github.com/au-ts/microkit_acacia/issues/48 )

All data blobs are placed in the provided build_dir.

For debugging purposes, set dump=True to generate a human-readable JSON file named identically to each data blob. This is a helpful way to check if your config serialisation works correctly.

This is a TERMINAL ACTION - it will cause this System to assemble itself and prevent any additional elements from being added to the system.

render() → xml.etree.ElementTree.Element

Render the XML hierarchically for all Microkit elements in the system. All elements render themselves and their child elements. This is called automatically by write_xml_file and shouldn’t be called manually unless you need the ElementTree for some unusual usage.

This is a TERMINAL ACTION - it will cause this System to assemble itself and prevent any additional elements from being added to the system.

write_xml_file(path: pathlib.Path)

Write a Microkit XML file to path.

This is a TERMINAL ACTION - it will cause this System to assemble itself and prevent any additional elements from being added to the system.

property microkit_alloc_allowed: bool

Return True if allocating Microkit objects is allowed. I.e. has the system fully finished assembling and has made XML or config structs?

property manual_alloc_allowed: bool

Return True if it is safe to manually allocate vaddrs, IDs for channels/irqs/ ioports/children, etc. or anything else that may conflict with automatic allocation when assembling subsystems.

We only allow these things before the assembly phase as this prevents a lot of complexity. We want to be able to eagerly auto-allocate such things when making client connections since this removes a lot of possible foot guns.

property system_assembled: bool

Return true if the assembly stage is completed.

__repr__() → str