acacia.subsystem

Module Contents

Classes

Subsystem

A subsystem is a grouping of PDs, as well as channels, memory regions and maps between them. It is the primary abstraction Acacia offers to modularise Microkit applications and modules.

Functions

build_hook

Mark a Subsystem instance method to be called during build(). Hooks are run top-to-bottom in their class and should have no arguments except possibly self.

API

exception acacia.subsystem.SubsystemBuildError

Bases: RuntimeError

Something caused a subsystem to fail to assemble itself.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class acacia.subsystem.Subsystem(sdf: acacia.system.System, name: str, clients_allowed: bool = True)

Bases: abc.ABC

A subsystem is a grouping of PDs, as well as channels, memory regions and maps between them. It is the primary abstraction Acacia offers to modularise Microkit applications and modules.

If a subsystem allows clients, these are ProtectionDomains using the services supplied by the subsystem (by default - this can be overridden if needed).

This class is designed to be used exclusively by subclassing it to define your module.

We strongly recommend reading the Subsystem programming model guide in ./docs/subsystem_model.md before writing your first module!

Subsystems offer three fundamental capabilities:

  1. A “client-server” style API, where subclasses implement the server logic in __init__() and clients PDs are added with add_client() (possibly overloaded if the client needs additional options).

  2. Infrastructure to “build” the subsystem by invoking some number of build_hooks. A build hook is a class method annotated with the @build_hook decorator, which is run when the top-level Acacia System decides to construct this class. Build hooks are run top-to-bottom in the file (or in MRO if inheriting them, i.e. parents run first).

  3. An encapsulation of ConfigStructs that describe the configuration of the server components and any data to tell clients how to interact with the server.

Subsystems may have no clients if the superclass is instantiated with allow_clients=False. This allows representing arbitrary modules, or possibly modules that instrument some other subsystem, or maybe only a single client (see https://github.com/au-ts/sddf/blob/main/acacia_sddf/ipstacks.py).

When a subsystem is built by Acacia: 1. All build hooks are executed in top-to-bottom order within the class, or MRO for superclass methods. 2. Config structs are generated afterwards by Acacia, by calling generate_config_structs.

WRITING A SUBSYSTEM

Consider what your subsystem needs to do.

Your __init__() should build anything that clients depend on as well as any dependencies for the whole subsystem (e.g. references to another subsystem this subsystem is a client to). E.g. for a driver subsystem, you should probably create your driver PD and associated virtualiser.

Depending on other subsystems

Per the Subsystem programming model, you should ALWAYS take references to other subsystems you depend on in __init__(). E.g. if you are writing an ethernet subsystem which needs to give the driver access to a timer subsystem, you should: a. Take the timer subsystem instance as an arg … __init__(self, timer ...); b. Create the driver PD in __init__; c. Add the driver as a client to the timer subsystem in __init__.

You should never add clients to other subsystems in a build hook as this may lead to undefined behaviour! E.g. you could add yourself as a client to a subsystem that has already assembled, meaning connections never get made.

Why create infrastructure in __init__?

You could technically do everything in a build hook, but it is useful to create PDs etc. early since this allows users to modify them in the metaprogram… E.g. changing which CPU core the driver runs on, adding the driver as a client to a different subsystem, etc.

Dealing with clients

Your add_client() method can remain as default in most cases, i.e. if you just need to specify “this PD is related to this subsystem”. The easiest way to remember that some config belongs to clients is to create a dictionary called client_configs: Dict[ProtectionDomain, Dict | dataclass], where you simply store the args from your overload in it.

To deal with your clients, you will need to add at least one build_hook (conventionally named connect_clients). This should probably run AFTER any other build hooks (i.e. declared last) and should create channels, MRs, maps and and anything else needed for clients.

Configuring PDs with ConfigStructs

If you require ConfigStructs, you should declare a generate_config_structs method in your subclass. It should return a List[ConfigStruct]. You should probably create your ConfigStructs or keep the associated metadata somewhere in a class instance variable.

If you do not want multiple clients

…you should instantiate your subclass with `super().init(sdf, name, allow_clients=False).

You can then make your subsystem do whatever you’d like … if you only need a single client, a useful pattern is to accept a reference to the client PD in __init__() - see ipstacks.py in the seL4 Device Driver Framework.

Final words on dependencies

WARNING: you should always add clients BEFORE any build hooks run! Subsystems are created in the order they are declared (i.e. when super().init() is called). This will mean that if the subsystem you depend on was created first, it will be built first, but you should not depend on this, as it is subject to change.

We have a WIP dependency graph resolver that can ensure a correct build order, but it is not yet merged as it introduces a lot of complexity and it is not obvious that it is required for these cases.

Initialization

add_client(client: acacia.pd.ProtectionDomain) → None

Add a client to the subsystem list, but do nothing else just yet.

This method may be overloaded by some classes to add extra parameters to clients, e.g. assigning MAC addresses for networking or I2C addresses for I2C.

get_clients() → List[acacia.pd.ProtectionDomain]

Get all client PDs.

generate_config_structs() → List[acacia.configstruct.ConfigStruct]

Generate any config structs this subsystem requires and return them as a list.

Subsystems that use config structs should override this method. It is not abstract so subclasses without config structs can ignore it.

build() → None

Run the subsystem’s build hooks. This can only occur once per subsystem.

This is automatically called when invoking a terminal action in Acacia, i.e. generating Microkit XML or config structs.

classmethod __init_subclass__(**kwargs: Any) → None

Set up build hooks, handling the possibility of a parent class defining some.

__repr__() → str
acacia.subsystem.build_hook(method: acacia.subsystem._BuildHookMethod) → acacia.subsystem._BuildHookMethod

Mark a Subsystem instance method to be called during build(). Hooks are run top-to-bottom in their class and should have no arguments except possibly self.

If inheriting, all parent hooks run before the child’s hooks.