Difference between revisions of "Unit DeviceTree"

Revision as of 03:58, 17 November 2021

With this adoption of device tree by Linux it is becoming increasingly common for the only source of information about the runtime configuration of specific hardware to be found in the blob loaded and configured during startup by the firmware and passed to the kernel at the beginning of the boot process.

While Ultibo targets a much smaller range of devices than Linux and does not need the generic kernel model it still requires detailed configuration information in order to be able to interface with the full range of available devices.

It can also benefit from the ability to adapt to the runtime environment by checking for known device tree parameters while registering and initializing hardware and devices. Use of device tree is considered optional and Ultibo will operate correctly with or without the information provided, however some devices may be forced to operate in a fall back or default mode without the complete configuration.

@@ Line 108: / Line 108: @@
 {| class="wikitable" style="font-size: 14px; background: white;"
 |-
-|colspan="2"|Standard nodes
+|colspan="2"|''Standard nodes''
 |-
 | <code>DTB_NODE_ROOT = '/';</code>
@@ Line 125: / Line 125: @@
 | &nbsp;
 |-
-|colspan="2"|Other nodes
+|colspan="2"|''Other nodes''
 |-
 | <code>DTB_NODE_SYMBOLS = '__symbols__';</code>
@@ Line 184: / Line 184: @@
 {| class="wikitable" style="font-size: 14px; background: white;"
 |-
-|colspan="2"|Standard properties
+|colspan="2"|''Standard properties''
 |-
 | <code>DTB_PROPERTY_COMPATIBLE = 'compatible';</code>
@@ Line 222: / Line 222: @@
 | The device_type property was used in IEEE 1275 to describe the device (Type: <string>)
 |-
-|colspan="2"|Additional properties for Interrupt Generating Devices
+|colspan="2"|''Additional properties for Interrupt Generating Devices''
 |-
 | <code>DTB_PROPERTY_INTERRUPTS = 'interrupts';</code>
@@ Line 233: / Line 233: @@
 | The interrupts-extended property lists the interrupt(s) generated by a device (Type: <phandle> <prop-encoded-array>)
 |-
-|colspan="2"|Additional properties for Interrupt Controllers
+|colspan="2"|''Additional properties for Interrupt Controllers''
 |-
 | <code>DTB_PROPERTY_INTERRUPT_CELLS = '#interrupt-cells';</code>
@@ Line 241: / Line 241: @@
 | The presence of an interrupt-controller property defines a node as an interrupt controller node (Type: <empty>)
 |-
-|colspan="2"|Additional Interrupt Nexus properties
+|colspan="2"|''Additional Interrupt Nexus properties''
 |-
 | <code>DTB_PROPERTY_INTERRUPT_MAP = 'interrupt-map';</code>
@@ Line 249: / Line 249: @@
 | An interrupt-map-mask property is specified for a nexus node in the interrupt tree (Type: <prop-encoded-array>)
 |-
-|colspan="2"|Additional Memory Node properties
+|colspan="2"|''Additional Memory Node properties''
 |-
 | <code>DTB_PROPERTY_INITIAL_MAPPED_AREA = 'initial-mapped-area';</code>
 | Specifies the address and size of the Initial Mapped Area (Type: <prop-encoded-array>)
 |-
-|colspan="2"|Additional Chosen Node properties
+|colspan="2"|''Additional Chosen Node properties''
 |-
 | <code>DTB_PROPERTY_BOOTARGS = 'bootargs';</code>
@@ Line 271: / Line 271: @@
 | The ending address of the initial ram disk (Type: <u32>)
 |-
-|colspan="2"|Additional CPUs Node properties
+|colspan="2"|''Additional CPUs Node properties''
 |-
 | <code>DTB_PROPERTY_CLOCK_FREQUENCY = 'clock-frequency';</code>

`DTB_VERSION_17 = 17;`
`DTB_VERSION_16 = 16;`

`DTB_VERSION_CURRENT = DTB_VERSION_17;`
`DTB_VERSION_COMPATIBLE = DTB_VERSION_16;`

`DTB_BEGIN_NODE = $00000001;`	The FDT_BEGIN_NODE token marks the beginning of a node’s representation, followed by the node’s unit name as extra data.
`DTB_END_NODE = $00000002;`	The FDT_END_NODE token marks the end of a node’s representation
`DTB_PROP = $00000003;`	The FDT_PROP token marks the beginning of the representation of one property, followed by extra data describing the property.
`DTB_NOP = $00000004;`	The FDT_NOP token will be ignored by any program parsing the device tree
`DTB_END = $00000009;`	The FDT_END token marks the end of the structure block

`DTB_NODE_OFFSET = 4;`	Token
`DTB_PROPERTY_OFFSET = 12;`	Token + Value Length + Name Offset

`DTB_STRUCTURE_ALIGNMENT = 4;`
`DTB_RESERVATION_ALIGNMENT = 8;`

Standard nodes
`DTB_NODE_ROOT = '/';`
`DTB_NODE_CPUS = 'cpus';`
`DTB_NODE_MEMORY = 'memory';`
`DTB_NODE_CHOSEN = 'chosen';`
`DTB_NODE_ALIASES = 'aliases';`
Other nodes
`DTB_NODE_SYMBOLS = '__symbols__';`
`DTB_NODE_OVERRIDES = '__overrides__';`

`DTB_TYPE_UNKNOWN = 0;`
`DTB_TYPE_EMPTY = 1;`	Value is empty. Used for conveying true-false information.
`DTB_TYPE_U32 = 2;`	A 32-bit integer in big-endian format
`DTB_TYPE_U64 = 3;`	Represents a 64-bit integer in big-endian format
`DTB_TYPE_STRING = 4;`	Strings are printable and null-terminated
`DTB_TYPE_ENCODED_ARRAY = 5;`	Format is specific to the property. See the property definition.
`DTB_TYPE_PHANDLE = 6;`	A <u32> value. A phandle value is a way to reference another node in the devicetree.
`DTB_TYPE_STRINGLIST = 7;`	A list of <string> values concatenated together

Standard properties
`DTB_PROPERTY_COMPATIBLE = 'compatible';`	The compatible property value consists of one or more strings that define the specific programming model for the device (Type: <stringlist>)
`DTB_PROPERTY_MODEL = 'model';`	The model property value specifies the manufacturer’s model number of the device (Type: <string>)
`DTB_PROPERTY_PHANDLE = 'phandle';`	The phandle property specifies a numerical identifier for a node that is unique within the devicetree (Type: <u32>)
`DTB_PROPERTY_STATUS = 'status';`	The status property indicates the operational status of a device (Type: <string>)
`DTB_PROPERTY_ADDRESS_CELLS = '#address-cells';`	Specifies the number of <u32> cells to represent the address in the reg property (Type: <u32>)
`DTB_PROPERTY_SIZE_CELLS = '#size-cells';`	Specifies the number of <u32> cells to represent the size in the reg property (Type: <u32>)
`DTB_PROPERTY_REG = 'reg';`	The reg property describes the address of the device’s resources within the address space defined by its parent bus (Type: <prop-encoded-array>)
`DTB_PROPERTY_VIRTUAL_REG = 'virtual-reg';`	The virtual-reg property specifies an effective address that maps to the first physical address specified in the reg property of the device node (Type: <u32>)
`DTB_PROPERTY_RANGES = 'ranges';`	The ranges property provides a means of defining a mapping or translation between address spaces (Type: <empty> or <prop-encoded-array>)
`DTB_PROPERTY_DMA_RANGES = 'dma-ranges';`	The dma-ranges property is used to describe the direct memory access (DMA) structure of a memory-mapped bus (Type: <empty> or <prop-encoded-array>)
`DTB_PROPERTY_NAME = 'name';`	The name property is a string specifying the name of the node (Type: <string>)
`DTB_PROPERTY_DEVICE_TYPE = 'device_type';`	The device_type property was used in IEEE 1275 to describe the device (Type: <string>)
Additional properties for Interrupt Generating Devices
`DTB_PROPERTY_INTERRUPTS = 'interrupts';`	The interrupts property defines the interrupt or interrupts that are generated by the device (Type: <prop-encoded-array>)
`DTB_PROPERTY_INTERRUPT_PARENT = 'interrupt-parent';`	The interrupt-parent property provides an explicit definition of an interrupt parent (Type: <phandle>)
`DTB_PROPERTY_INTERRUPTS_EXTENDED = 'interrupts-extended';`	The interrupts-extended property lists the interrupt(s) generated by a device (Type: <phandle> <prop-encoded-array>)
Additional properties for Interrupt Controllers
`DTB_PROPERTY_INTERRUPT_CELLS = '#interrupt-cells';`	The #interrupt-cells property defines the number of cells required to encode an interrupt specifier for an interrupt domain (Type: <u32>)
`DTB_PROPERTY_INTERRUPT_CONTROLLER = 'interrupt-controller';`	The presence of an interrupt-controller property defines a node as an interrupt controller node (Type: <empty>)
Additional Interrupt Nexus properties
`DTB_PROPERTY_INTERRUPT_MAP = 'interrupt-map';`	An interrupt-map is a property on a nexus node that bridges an interrupt domain to a parent domain (Type: <prop-encoded-array>)
`DTB_PROPERTY_INTERRUPT_MAP_MASK = 'interrupt-map-mask';`	An interrupt-map-mask property is specified for a nexus node in the interrupt tree (Type: <prop-encoded-array>)
Additional Memory Node properties
`DTB_PROPERTY_INITIAL_MAPPED_AREA = 'initial-mapped-area';`	Specifies the address and size of the Initial Mapped Area (Type: <prop-encoded-array>)
Additional Chosen Node properties
`DTB_PROPERTY_BOOTARGS = 'bootargs';`	A string that specifies the boot arguments for the client program (Type: <string>>)
`DTB_PROPERTY_STDOUT_PATH = 'stdout-path';`	A string that specifies the full path to the node representing the device to be used for boot console output (Type: <string>>)
`DTB_PROPERTY_STDIN_PATH = 'stdin-path';`	A string that specifies the full path to the node representing the device to be used for boot console input (Type: <string>>)
`DTB_PROPERTY_INITRD_START = 'initrd-start';`	The starting address of the initial ram disk (Type: <u32>)
`DTB_PROPERTY_INITRD_END = 'initrd-end';`	The ending address of the initial ram disk (Type: <u32>)
Additional CPUs Node properties
`DTB_PROPERTY_CLOCK_FREQUENCY = 'clock-frequency';`	Specifies the current clock speed of the CPU in Hertz (Type: <prop-encoded-array>)
`DTB_PROPERTY_TIMEBASE_FREQUENCY = 'timebase-frequency';`	Specifies the current frequency at which the timebase and decrementer registers are updated (Type: <propencoded-array>)
`DTB_PROPERTY_ENABLE_METHOD = 'enable-method';`	Describes the method by which a CPU in a disabled state is enabled (Type: <stringlist>)
`DTB_PROPERTY_CPU_RELEASE_ADDR = 'cpu-release-addr';`	The cpu-release-addr property is required for cpu nodes that have an enable-method property value of "spin-table" (Type: <u64>)

`DTB_PROPERTY_POWER_ISA_VERSION = 'power-isa-version';`	A string that specifies the numerical portion of the Power ISA version string (Type: <string>)
`DTB_PROPERTY_CACHE_OP_BLOCK_SIZE = 'cache-op-block-size';`	The block size in bytes upon which cache block instructions operate (Type: <u32>)
`DTB_PROPERTY_RESERVATION_GRANULE_SIZE = 'reservation-granule-size';`	The reservation granule size supported by this processor in bytes (Type: <u32>)
`DTB_PROPERTY_MMU_TYPE = 'mmu-type';`	Specifies the CPU’s MMU type (Type: <string>)

`DTB_PROPERTY_TLB_SPLIT = 'tlb-split';`	Specifies that the TLB has a split configuration (Type: <empty>)
`DTB_PROPERTY_TLB_SIZE = 'tlb-size';`	Specifies the number of entries in the TLB (Type: <u32>)
`DTB_PROPERTY_TLB_SETS = 'tlb-sets';`	Specifies the number of associativity sets inthe TLB (Type: <u32>)
`DTB_PROPERTY_D_TLB_SIZE = 'd-tlb-size';`	Specifies the number of entries in the data TLB (Type: <u32>)
`DTB_PROPERTY_D_TLB_SETS = 'd-tlb-sets';`	Specifies the number of associativity sets in the data TLB (Type: <u32>)
`DTB_PROPERTY_I_TLB_SIZE = 'i-tlb-size';`	Specifies the number of entries in the instruction TLB (Type: <u32>)
`DTB_PROPERTY_I_TLB_SETS = 'i-tlb-sets';`	Specifies the number of associativity sets in the instruction TLB (Type: <u32>)

`DTB_PROPERTY_CACHE_UNIFIED = 'cache-unified';`	Specifies the cache has a unified organization (Type: <empty>)
`DTB_PROPERTY_CACHE_SIZE = 'cache-size';`	Specifies the size in bytes of a unified cache (Type: <u32>)
`DTB_PROPERTY_CACHE_SETS = 'cache-sets';`	Specifies the number of associativity sets in a unified cache (Type: <u32>)
`DTB_PROPERTY_CACHE_BLOCK_SIZE = 'cache-block-size';`	Specifies the block size in bytes of a unified cache (Type: <u32>)
`DTB_PROPERTY_CACHE_LINE_SIZE = 'cache-line-size';`	Specifies the line size in bytes of a unified cache (Type: <u32>)
`DTB_PROPERTY_I_CACHE_SIZE = 'i-cache-size';`	Specifies the size in bytes of the instruction cache (Type: <u32>)
`DTB_PROPERTY_I_CACHE_SETS = 'i-cache-sets';`	Specifies the number of associativity sets in the instruction cache (Type: <u32>)
`DTB_PROPERTY_I_CACHE_BLOCK_SIZE = 'i-cache-block-size';`	Specifies the block size in bytes of the instruction cache (Type: <u32>)
`DTB_PROPERTY_I_CACHE_LINE_SIZE = 'i-cache-line-size';`	Specifies the line size in bytes of the instruction cache (Type: <u32>)
`DTB_PROPERTY_D_CACHE_SIZE = 'd-cache-size';`	Specifies the size in bytes of the data cache (Type: <u32>)
`DTB_PROPERTY_D_CACHE_SETS = 'd-cache-sets';`	Specifies the number of associativity sets in the data cache (Type: <u32>)
`DTB_PROPERTY_D_CACHE_BLOCK_SIZE = 'd-cache-block-size';`	Specifies the block size in bytes of the data cache (Type: <u32>)
`DTB_PROPERTY_D_CACHE_LINE_SIZE = 'd-cache-line-size';`	Specifies the line size in bytes of the data cache (Type: <u32>)
`DTB_PROPERTY_NEXT_LEVEL_CACHE = 'next-level-cache';`	If present, indicates that another level of cache exists. (Type: <phandle>)

`DTB_PROPERTY_CACHE_LEVEL = 'cache-level';`	Specifies the level in the cache hierarchy (Type: <u32>)
Other Additional properties
`DTB_PROPERTY_SERIAL_NUMBER = 'serial-number';`	Serial Number (Type: <string>)
`DTB_PROPERTY_ALLOC_RANGES = 'alloc-ranges';`	Allocated Ranges (Type: <prop-encoded-array>)
`DTB_PROPERTY_RESETS = 'resets';`	Resets (Type: <prop-encoded-array>)
`DTB_PROPERTY_CLOCK_CELLS = '#clock-cells';`	Number of clock cells (Type: <u32>)
`DTB_PROPERTY_LINUX_INITRD_START = 'linux,initrd-start';`	The starting address of the initial ram disk (Type: <u32>)
`DTB_PROPERTY_LINUX_INITRD_END = 'linux,initrd-end';`	The ending address of the initial ram disk (Type: <u32>)

Address	The address to be validated
Size	On return contains the total size of the Device Tree Blob if valid
Return	True if the address points to a valid Device Tree Blob, False if not.
Note	Does not overwrite passed Size unless the DTB is valid

Parent	Handle of the parent node to search in, INVALID_HANDLE_VALUE to search the entire tree
Previous	Handle of the node to start from, INVALID_HANDLE_VALUE to start from the root node
Return	The handle of the next node in the tree or INVALID_HANDLE_VALUE if no node was found

Node	The node to print information about (INVALID_HANDLE_VALUE for all nodes)
Output	The log output callback to print information to (nil to use the default output)
Decode	The callback to decode a value into a string (nil to use the default decode)
Data	A pointer to call specific data which should be passed to the callbacks (Optional)
Return	ERROR_SUCCESS if completed or another error code on failure

Node	Handle of the node to search in
Previous	Handle of the property to start from, INVALID_HANDLE_VALUE to start from the first property
Return	The handle of the next property in the node or INVALID_HANDLE_VALUE if no property was found

Path	The path of the node to find, relative to parent node or fully qualified if parent not specified (eg /chosen or /cpus/cpu0).
Parent	Handle of the parent node to search in, INVALID_HANDLE_VALUE to search the entire tree.
Return	The handle of the node which matches the path or INVALID_HANDLE_VALUE if no node was found

Node	Handle of the node to search in
Name	The name of the node to find (eg compatible)
Return	The handle of the property which matches the name or INVALID_HANDLE_VALUE if no property was found

Handle	The handle of the node to get the name of
Return	The name of the specified node or an empty string if the node was not valid

Handle	The handle of the node to split the name of
NodeName	The node name on return or an empty string if the node was not valid
UnitAddress	The unit address on return (If applicable)

Handle	The handle of the node to get the parent of
Return	The handle of the parent node or INVALID_HANDLE_VALUE if the node was not valid

Handle	The handle of the node to get the cell sizes for
Address	The #address-cells value on return (or the default value if not found)
Size	The #size-cells value on return (or the default value if not found)
Return	True if the cell sizes were found or False if the node was not valid
Note	The address and size values applicable to a given node will be those from a parent node, not those found in the node itself (if present). Used by early stage boot stage processing which must limit the use of strings and other memory allocations. This function uses a memory compare for names.

Handle	The handle of the node to get the cell sizes for
ParentAddress	The #address-cells value from the parent on return (or the default value if not found)
NodeAddress	The #address-cells value from this node on return (or the default value if not found)
NodeSize	The #size-cells value from this node on return (or the default value if not found)
Return	True if the cell sizes were found or False if the node was not valid
Note	Range properties use the address value from the parent node and the address and size values from the node itself to determine the size of each range. Used by early stage boot stage processing which must limit the use of strings and other memory allocations. This function uses a memory compare for names.

Handle	The handle of the property to get the name of
Return	The name of the specified property or an empty string if the property was not valid

Handle	The handle of the property to split the name of
UniquePrefix	The unique prefix on return (If applicable)
PropertyName	The property name on return or an empty string if the property was not valid

Difference between revisions of "Unit DeviceTree"

Revision as of 03:58, 17 November 2021

Contents

Description

Constants

Type definitions

Public variables

Function declarations

Navigation menu

Search

Handle	The handle of the property to get the value of
Return	A pointer to the specified property value or nil if the property was not valid
Note	The returned value points to the memory block where device tree is stored and should not be modified or freed

Address	Used to return the address value
Size	Used to return the size value
Return	True if an initial ram disk was specified in the device tree, False if not.
Note	Intended primarily for use by early boot stage processing which must limit the use of strings and other memory allocations For normal use see DeviceTreeGetNode and DeviceTreeGetProperty

Index	The index of the memory block to return (The first block is 0)
Range	Used to return the page range value (If applicable)
Address	Used to return the address value
Size	Used to return the size value
Return	True if the memory block requested was found in the device tree, False if not.
Note	Intended primarily for use by early boot stage processing which must limit the use of strings and other memory allocations For normal use see DeviceTreeGetNode and DeviceTreeGetProperty

Index	The index of the memory reservation to return (The first reservation is 0)
Address	Used to return the address value
Size	Used to return the size value
Return	True if the memory reservation requested was found in the device tree, False if not.