acacia.configstruct

Module Contents

Classes

Attributes

Class encapsulating tag attributes in the parsed output of llvm-dwarfdump on a file. This is used internally by Acacia when discovering the layout of ConfigStructs in compiled code. Examples:

CType

Class encapsulating a tag entry or C type found in the parsed output of llvm-dwarfdump on a file. This is used internally by Acacia to represent types found in a compiled file when determining how to pack ConfigStructs. Examples:

ConfigStruct

A representation of a structure in a compiled program that we will pack with configuration data.

ConfigStructResolver

This class records all configuration structs of a system. As structs are added to this class, their target files are dwarf dumped and parsed, and all CTypes they contain are collected into a dictionary.

Data

API

class acacia.configstruct.Attributes

Class encapsulating tag attributes in the parsed output of llvm-dwarfdump on a file. This is used internally by Acacia when discovering the layout of ConfigStructs in compiled code. Examples:

attribute
    at_name     name
    escaped_string      "i2c_cmd_t"

 attribute
   at_name      type
   pair
     number     0x000001a5
     escaped_string     "i2c_cmd"

Sanity checks values for each attribute.

valid_attributes

(‘name’, ‘decl_file’, ‘encoding’, ‘byte_size’, ‘const_value’, ‘decl_line’, ‘decl_column’, ‘data_memb…

static escaped_string(value_tree: lark.Tree) → str

Returns the un-escaped string value from lark trees of the form: escaped_string “DW_ATE_unsigned_32”

static string(value_tree: lark.Tree) → str

Returns the string value from lark trees of the form: string DW_ATE_unsigned

static number(value_tree: lark.Tree) → int

Returns the numeric value from lark trees of the form: number 0x04

static id_number(value_tree: lark.Tree) → int

Returns the numeric value from lark trees of the form: number 0x0000005b

static pair(value_tree: lark.Tree) → Tuple[int, str]

Returns a tuple of the numeric value and string from lark trees of the form: pair number 0x0000005b escaped_string “int”

extract_attribute(tree: lark.Tree)

Given an attribute tree of the form:

attribute
    at_name     name
    escaped_string      "i2c_cmd_t"

extract the value of the attribute.

__getattr__(name: str)
__setattr__(name: str, value: Union[tuple, lark.Tree])
__eq__(other: object)
__repr__()
class acacia.configstruct.CType(entry_tree: lark.Tree, type_collector: Dict[int, acacia.configstruct.CType])

Class encapsulating a tag entry or C type found in the parsed output of llvm-dwarfdump on a file. This is used internally by Acacia to represent types found in a compiled file when determining how to pack ConfigStructs. Examples:

unknown_tag
    id  0000000c

or

base_tag
  id    0000002b
  attribute
    at_name     name
    escaped_string      "DW_ATE_unsigned_32"
  attribute
    at_name     encoding
    string      DW_ATE_unsigned
  attribute
    at_name     byte_size
    number      0x04

or

group
    structure_tag
      id        000000f9
      attribute
        ...
    member_tag
      id        000000fe
      attribute
        ...
    member_tag
      id        00000107
      attribute
        ...
    null
      id        00000110

Initialization

Variables:
  • tag_type – type of tag entry, must be a member of special_tags, single_tags, member_tags or group_tags

  • id – numeric identifier

  • attributes – tag entry attribute values

  • members – IDs of member tags, non-empty only for group_tag types

Parameters:
  • entry_tree – The lark tree corresponding to the tag

  • type_collector – A dictionary of ID to CType mappings of all the CTypes found in the parsed tree from

special_tags

(‘unknown_tag’, ‘null’, ‘compile_unit’)

single_tags

(‘base_tag’, ‘typedef_tag’, ‘pointer_tag’)

member_tags

(‘subrange_tag’, ‘enumerator_tag’, ‘member_tag’)

group_tags

None

required_attributes

None

property id
base_type() → acacia.configstruct.CType

Find the underlying base type of a CType.

Returns self for all CTypes with types not in “typedef_tag”, “member_tag” or “array_tag”.

array_dimensions() → Tuple[int, ...]

Return the array’s dimensions in DWARF/source order.

A dimension is 0 when its subrange does not have a known bound. C arrays have an implicit lower bound of zero, so a DW_AT_upper_bound of N describes N + 1 entries.

array_count() → int

Find the number of entries in an “array_tag” CType. Returns 0 if the subrange type does not have a count attribute.

__eq__(other: object)
static extract_id(id_token: lark.Token)

Returns the numeric value from lark trees of the form: id 0000423e

static sanity_check_type_ids(all_types: Dict[int, acacia.configstruct.CType])

Given a complete dictionary of type IDs to CTypes, ensure all type ID references are contained in the dictionary.

static find_type_by_name(all_types: Dict[int, acacia.configstruct.CType], type_name: str) → acacia.configstruct.CType

Given a type name, find the underlying base type.

__repr__()
class acacia.configstruct.ConfigStruct(fields: Dict[str, Any], type_name: Optional[str] = None, section_name: Optional[pathlib.Path] = None, target_file: Optional[pathlib.Path] = None, empty: bool = False)

A representation of a structure in a compiled program that we will pack with configuration data.

This class provides a template for creating a configuration struct which will be serialised into a matching C struct found in a component’s ELF file.

All ConfigStructs must have:

  • A type_name denoting the C type of this, e.g. sddf_timer_client_config_t.

  • A list of fields - name-value pairs matching the layout of a struct. E.g. “queue_vaddr” : 0x20000000. Names must exactly match the name of the field in C and the value should be an appropriate Python type. All fields in the real struct should be present, otherwise an error will be thrown.

E.g.

  • a string -> character array

  • list of int -> list of integers of some C type (automatically checks if signed!)

  • a bytearray -> list of integers of some C type

  • Another ConfigStruct -> a struct.

If this ConfigStruct is at the top level, i.e. it is corresponding to a symbol to patch as opposed to being a ConfigStruct nested inside another ConfigStruct, it must define:

  • target_file: the name of the ELF file this will be patched into.

  • section_name: The name of the ELF section this belongs to. NOTE: this currently is unused! https://github.com/au-ts/microkit_acacia/issues/48

In the event that a ConfigStruct is unused, or we want to zero-fill a struct inside of another ConfigStruct, you may set the empty field to True. This will cause Acacia to skip trying to populate it while suppressing the “missing field” error that would normally appear if you ignore fields of a struct.

Initialization

Parameters:
  • fields –

    dictionary of field names -> values. Can be:

    • Another ConfigStruct

    • Any int-like value

    • Any string or bytes

    • A list of values

  • type_name – type of struct in C

  • section_name – name of section to patch config struct into

  • target_file – ELF file this will be patched into

__repr__()
acacia.configstruct.BaseTypesMap: Dict[str, Dict[int, Any]]

None

class acacia.configstruct.ConfigStructResolver(build_dir: pathlib.Path, endian='little', dwarfdump_name: str = 'llvm-dwarfdump')

This class records all configuration structs of a system. As structs are added to this class, their target files are dwarf dumped and parsed, and all CTypes they contain are collected into a dictionary.

Once all structs of the system are added, they are serialised one-by-one based on the memory layout of their types derived from the DWARF symbols in the ELF file. Each serialised struct is then written to a file in the build directory.

This is an internal class for Acacia and is not used by end users.

Initialization

Parameters:
  • build_dir – name of the build directory, used for emitting serialised structs

  • endian – endianness of encoding

  • dwarfdump_name – name of dwarf dump command

add_struct(s: acacia.configstruct.ConfigStruct)

Add a configuration struct to the resolver.

add_structs(lst: List[acacia.configstruct.ConfigStruct])

Add a list of configuration structs to the resolver.

resolve_target_file(target_file: pathlib.Path) → Dict[int, acacia.configstruct.CType]

Dwarf dump a target file, parse the output and collect all CTypes into a dictionary.

resolve_and_create_all(dump: bool = False)

Try generate data files for all currently known config structs. Output will be placed in self.build_dir.