acacia.system¶
Module Contents¶
Classes¶
An Acacia system has a few states which progress linearly in this order: |
|
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.EnumAn 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.
Systemexposes the two terminal actions in Acacia:make_config_structs-> For all subsystems, create data blobs for theirConfigStructs.write_xml_file-> Create a Microkit XML file containing all elements in theSystem.
Calling either of these actions will cause the
Systemto “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:
Subsystem resolution. For each
Subsystem, invoke theirbuildmethod to finalise them.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_filewill NOT automatically generate config structs.Initialization
- assemble()¶
Run all automated connection steps.
Resolve subsystems and connect their clients.
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=Trueto 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_fileand shouldn’t be called manually unless you need theElementTreefor 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¶