acacia.dtb

Module Contents

Classes

DTB_IRQ_Controller

This is an abstract base class representing different kinds of interrupt controller. This is currently a stub and is only implemented by Arm_GIC, but we want to preserve this interface for future expansion.

Arm_GIC

Representation of the ARM Generic Interrupt Controller.

DTBNode

A representation of a Device Tree node as discovered at runtime.

DeviceTreeBlob

Class encapsulating operations on a device tree. This class parses the DTB using pylibfdt and offers a friendly interface for using it for drivers and other OS functionality.

API

class acacia.dtb.DTB_IRQ_Controller

Bases: abc.ABC

This is an abstract base class representing different kinds of interrupt controller. This is currently a stub and is only implemented by Arm_GIC, but we want to preserve this interface for future expansion.

static create(arch: acacia.arch.Arch, dtb: acacia.dtb.DeviceTreeBlob)

Create an instance of the interrupt controller based upon the Device Tree Blob.

Parameters:
  • arch – Target system architecture, e.g. aarch64

  • dtb – DTB for target system

Returns:

DTB_IRQ_Controller instance.

class acacia.dtb.Arm_GIC(version: int, cpu_paddr: Optional[int] = None, vcpu_paddr: Optional[int] = None, vcpu_size: Optional[int] = None)

Bases: acacia.dtb.DTB_IRQ_Controller

Representation of the ARM Generic Interrupt Controller.

Initialization

class Version
V2

2

V3

3

has_mmio_cpu_interface() → bool

Whether or not the GIC’s CPU/vCPU interface is via MMIO.

static create(arch: acacia.arch.Arch, dtb: acacia.dtb.DeviceTreeBlob) → Optional[acacia.dtb.Arm_GIC]

Finds and parses the GIC node from the device tree.

class acacia.dtb.DTBNode

A representation of a Device Tree node as discovered at runtime.

offset: int

None

path: str

None

property name: str

Return the name of this node … i.e. the final term in the path.

class acacia.dtb.DeviceTreeBlob(dtb_file_path: str)

Class encapsulating operations on a device tree. This class parses the DTB using pylibfdt and offers a friendly interface for using it for drivers and other OS functionality.

The DTB is immediately parsed on __init__.

Initialization

get_compatible(node: acacia.dtb.DTBNode) → List[str]

Return list of compatible strings in (hopefully) human readable form, (hopefully) identical to DTS

get_nodes_by_compatible(compatible_str) → List[acacia.dtb.DTBNode]

Try find a node with a matching compatible string.

get_node_by_path(path_str: str) → acacia.dtb.DTBNode

Given a path string (e.g. /soc/serial@3002000), attempt to find a matching node.

get_node_prop(node: acacia.dtb.DTBNode, prop_name: str)

Get a property from a DTB node given a property name. This will return the raw contents of the property as a bytearray.

Returns None if property doesn’t exist

get_node_parent(node: acacia.dtb.DTBNode) → acacia.dtb.DTBNode

Get the parent of a node if it exists.

get_size_and_addr_cells(node: acacia.dtb.DTBNode) → Tuple[int, int]

Get the size and addr cells values of a node (node its parent).

Returns:

(size cells, addr cells)

get_node_regs(node: acacia.dtb.DTBNode) → List[Tuple]

Given a node, read its regs array and return a list of tuples. Tuples are (addr, len) pairs. This method automatically parses the parent node to figure out the appropriate size of members.

get_node_irqs(node: acacia.dtb.DTBNode) → Tuple[int, ...]

Return the list of words from the IRQ field on a node. We don’t attempt to concetenate the u32s or anything here, since the meaning of the field is entirely dependent on architecture.

get_parsed_irqs(node: acacia.dtb.DTBNode, arch: acacia.arch.Arch) → Sequence[acacia.irq.IRQ]

Parses the ‘interrupts’ property of a node into a list of IRQ objects.

get_reg_paddr(arch: acacia.arch.Arch, node: acacia.dtb.DTBNode, paddr: int) → int

Given an address from a DTB node’s ‘reg’ property, convert it to a mappable MMIO address. This involves traversing any higher-level busses to find the CPU visible address rather than some address relative to the particular bus the address is on. We also align to the smallest page size.