acacia.configstruct¶
Module Contents¶
Classes¶
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: |
|
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: |
|
A representation of a structure in a compiled program that we will pack with configuration data. |
|
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 0000000cor
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 0x04or
group structure_tag id 000000f9 attribute ... member_tag id 000000fe attribute ... member_tag id 00000107 attribute ... null id 00000110Initialization
- 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_namedenoting 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
ConfigStructis at the top level, i.e. it is corresponding to a symbol to patch as opposed to being aConfigStructnested inside anotherConfigStruct, 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 theemptyfield 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.