acacia.memory

Module Contents

Classes

MemoryRegion

A Microkit MemoryRegion (MR) as represented in Acacia.

Map

A mapping of a MemoryRegion into a PD or VM. This places the MR into the virtual address space of the target with a given set of permissions.

IOMap

Representation of a Microkit io map: a mapping of a MemoryRegion to an IOAddressSpace.

IOAddressSpace

Representation of a Microkit io space (i.e. an IOMMU protected device address space). https://docs.sel4.systems/projects/microkit/manual/latest/#io_address_space

API

class acacia.memory.MemoryRegion(sdf: acacia.system.System, name: str, size: int, paddr: Optional[int] = None, cached: bool = True, physical: bool = False, prefill_bootinfo: Optional[str] = None)

A Microkit MemoryRegion (MR) as represented in Acacia.

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

Instantiating this class immediately adds it to the System, meaning that it will be in the XML when generated.

Unlike in the raw Microkit, MemoryRegions in Acacia have some additional features for convenience and preventing programming errors.

  • cached flag: rather than needing to hope all Maps are have a matching cached state, Acacia sets it at MR granularity. If true, all Maps of this MR are cached.

  • Large-page optimisation: if a MR is large enough to fit in large pages, it will have its size rounded up to a large page boundary to let Microkit create it as a large page mapping.

  • Automatic physical address allocation: an Acacia MR can be marked as physical without a defined paddr. If this is the case, a paddr will be allocated as the final step before creating ConfigStructs or generating XML (terminal steps).

Initialization

can_be_largepage_optimised() → bool

Return True if Microkit could optimise this MR to a large page. NOTE: Microkit will only actually do this if all mappings are large-page aligned.

find_best_page_size() → acacia.arch.PageSize

Return the PageSize this region fits in best, based on the system architecture. This is a convenience wrap around Arch.determine_region_page_size.

render(system_root: xml.etree.ElementTree.Element)
__repr__() → str
class acacia.memory.Map(mr: acacia.memory.MemoryRegion, vaddr: int, permissions: Union[Permissions, str], setvar_vaddr: Optional[str] = None)

A mapping of a MemoryRegion into a PD or VM. This places the MR into the virtual address space of the target with a given set of permissions.

If the underlying MR could be optimised to a large page by Microkit but the virtual address given isn’t large-page aligned, a warning will be printed.

You do not need to manually allocate Maps if you do not care about the virtual address, use Entity.create_automap() (on PDs or VMs) to automatically assign one. This will automatically align the assigned virtual address to a large or huge page boundary to enable optimisations.

Initialization

class Permissions
r: bool

False

w: bool

False

x: bool

False

__str__()
__post_init__()
__repr__() → str
property size
render(parent: xml.etree.ElementTree.Element) → xml.etree.ElementTree.Element

Render the Map to XML elements. This is called automatically by Acacia and shouldn’t need to be used directly under normal circumstances.

property end_vaddr: int

Return the address where this map ends.

vaddr_in_map(vaddr: int) → bool

Return True if a given address is in the bounds of this Map.

__repr__() → str
class acacia.memory.IOMap(mr: acacia.memory.MemoryRegion, iovaddr: int, allow_reads: bool = True, allow_writes: bool = True)

Representation of a Microkit io map: a mapping of a MemoryRegion to an IOAddressSpace.

This works very similarly to a Map, but is for IOMMU mappings.

NOTE: this currently lacks some of the features of Map. https://github.com/au-ts/microkit_acacia/issues/34

Initialization

render(parent: xml.etree.ElementTree.Element) → xml.etree.ElementTree.Element
property perms: str
__repr__() → str
class acacia.memory.IOAddressSpace(sdf: acacia.system.System, name: str, peripheral_id: str, domain_id: str)

Representation of a Microkit io space (i.e. an IOMMU protected device address space). https://docs.sel4.systems/projects/microkit/manual/latest/#io_address_space

Initialization

add_io_map(iomap: acacia.memory.IOMap)
render(system_root: xml.etree.ElementTree.Element) → xml.etree.ElementTree.Element
__repr__() → str