acacia.pd

Module Contents

Classes

SchedulingProperties

Properties of an entity (PD or VM) for the seL4 MCS scheduler. https://docs.sel4.systems/projects/microkit/manual/latest/#scheduling

Entity

An executing entity. I.e. a PD or VM, or anything else that appears in future which: a. has scheduling paramters b. can be targeted by maps

VirtualMachine

A Microkit Virtual Machine. VMs always belong to a ProtectionDomain and cannot exist independently. This inherits from entity as VMs can be targeted with maps and has scheduling parameters.

ProtectionDomain

A Microkit Protection Domain (PD) as seen by Acacia.

Data

API

acacia.pd.MAX_IDS

62

class acacia.pd.SchedulingProperties

Properties of an entity (PD or VM) for the seL4 MCS scheduler. https://docs.sel4.systems/projects/microkit/manual/latest/#scheduling

priority: int

None

period: Optional[int]

None

budget: Optional[int]

None

passive: bool

False

__post_init__()
__repr__() → str
class acacia.pd.Entity(name: str, scheduling: Optional[acacia.pd.SchedulingProperties], map_start_vaddr: int = 536870912)

An executing entity. I.e. a PD or VM, or anything else that appears in future which: a. has scheduling paramters b. can be targeted by maps

This is a base class that ProtectionDomain and VirtualMachine inherit from for shared logic.

Initialization

property priority
property budget
property period
add_map(map: acacia.memory.Map)

Add a Map to this entity; i.e. put this mapping into the virtual address space.

create_automap(mr: acacia.memory.MemoryRegion, perms: Union[acacia.memory.Map.Permissions, str]) → acacia.memory.Map

Given a memory region, automatically create a map and assign it a vaddr that doesn’t overlap with any existing maps. This function will automatically try to align the vaddr to the largest suitable page size boundary. Maps are allocated upwards from this PD’s map_start_vaddr.

Parameters:
  • mr – MemoryRegion to map

  • perms – Map permissions - read, write, execute

Returns:

created map object.

NOTE: This replaces getMapVaddr in zig sdfgen.

render(parent: xml.etree.ElementTree.Element, elem_name: str)

Render the XML elements for this entity. This is called by super() from PDs and VMs.

class acacia.pd.VirtualMachine(name: str, vcpus: Sequence[VCPU], scheduling: Optional[acacia.pd.SchedulingProperties] = None)

Bases: acacia.pd.Entity

A Microkit Virtual Machine. VMs always belong to a ProtectionDomain and cannot exist independently. This inherits from entity as VMs can be targeted with maps and has scheduling parameters.

https://docs.sel4.systems/projects/microkit/manual/latest/#vm

Initialization

class VCPU

A representation of a Microkit virtual CPU (VCPU) used by a virtual machine.

id: int

None

cpu: Optional[int]

None

__post_init__()
render(parent: xml.etree.ElementTree.Element)

Return the XML defining this element. This is called internally by Acacia and shouldn’t be called directly in normal circumstances.

render(parent: xml.etree.ElementTree.Element, elem_name: str = 'virtual_machine') → xml.etree.ElementTree.Element
class acacia.pd.ProtectionDomain(sdf: acacia.system.System, name: str, prog_image: str, stack_size: Optional[int] = None, cpu: Optional[int] = None, smc: bool = False, scheduling: Optional[acacia.pd.SchedulingProperties] = None, priority: Optional[int] = None)

Bases: acacia.pd.Entity

A Microkit Protection Domain (PD) as seen by Acacia.

https://docs.sel4.systems/projects/microkit/manual/latest/#pd

As soon as a PD is instantiated, it is added to the System and will be in the XML when Acacia generates it.

Acacia PDs have a few convenience features:

  • Scheduling can be defined via either a simple priority or a full SchedulingProperties. The priority API is a legacy feature inherited from sdf_gen.

  • Acacia keeps a pool of available channel, IRQ and IOPort IDs to allow automatic assignment of these IDs. They are automatically assigned when added to the PD if they aren’t specified explicitly. NOTE: automatic assignments may clash with manual assignments, we may prevent this in the future.

Initialization

render(parent: xml.etree.ElementTree.Element, elem_name: str = 'protection_domain')

Render the XML elements describing this PD in the Microkit XML format. This is automatically called by Acacia and shouldn’t be required under normal usage.

allocate_id(requested_id: Optional[int] = None)

Allocate an ID (or test a requested id) for a channel or IRQ.

An ID may be requested while the system is in the “specification” stage … i.e. before a terminal action has been called and Acacia begins to assemble subsystems. NOTE: IOPort assignment occurs from a separate pool and thus doesn’t involve this method.

add_irq(irq: acacia.irq.IRQ)

Add an interrupt to this PD. This will automatically assign an ID if needed.

add_ioport(ioport: acacia.x86.IOPort)

Add an IOPort to this PD. This will automatically assign an ID if needed.

add_child_pd(child, child_id: Optional[int] = None)

Mark a PD as a child of this PD. This will remove the PD from the top-level system and make it render as a child element of this PD’s XML instead.

add_vm(vm: acacia.pd.VirtualMachine)

Add a virtual machine to be managed by this PD.

NOTE:

  • On x86, VMs do not have scheduling properties.

  • On x86, a PD may only host a VM with a single VCPU. On other architectures they may host a VM with multiple VCPUs.

add_cap_map(cap_map: acacia.cspace.CapMap)
__repr__()