Difference between revisions of "Unit DeviceTree"

From Ultibo.org
Jump to: navigation, search
Line 33: Line 33:
 
----
 
----
  
−
''To be documented''
+
'''Initialization functions'''
  
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">procedure DeviceTreeInit;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Initialize the Device Tree unit</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| Called only during system startup
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
 +
'''Device tree functions'''
 +
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeValidate(Address:PtrUInt; var Size:LongWord):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check the data at the supplied address to determine if it is a valid Device Tree Blob</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeNextNode(Parent,Previous:THandle):THandle;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Find the next DTB node within the Device Tree</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeNextProperty(Node,Previous:THandle):THandle;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Find the next DTB property within the specified node of the Device Tree</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetNode(const Path:String; Parent:THandle):THandle;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the handle of the node matching the specified path, optionally within a specified parent</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetProperty(Node:THandle; const Name:String):THandle;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the handle of the property matching the specified name</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetNodeName(Handle:THandle):String;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the name of the specified node</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">procedure DeviceTreeSplitNodeName(Handle:THandle; var NodeName,UnitAddress:String);</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Split the name of a node into node name and unit address</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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)
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetNodeParent(Handle:THandle):THandle;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the parent node of the specified node</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetNodeRegCells(Handle:THandle; var Address,Size:LongWord):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the #address-cells and #size-cells values that apply to reg properties of the specified node</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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.
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetNodeRangeCells(Handle:THandle; var ParentAddress,NodeAddress,NodeSize:LongWord):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the #address-cells and #size-cells values that apply to range properties of the specified node</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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.
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetPropertyName(Handle:THandle):String;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the name of the specified property</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">procedure DeviceTreeSplitPropertyName(Handle:THandle; var UniquePrefix,PropertyName:String);</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Split the name of a property into property name and unique prefix</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetPropertyValue(Handle:THandle):Pointer;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get a pointer to the raw value of the specified property</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetPropertyLength(Handle:THandle):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the length of the raw value of the specified property</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Handle
 +
| The handle of the property to get the value lenth of
 +
|-
 +
! Return
 +
| The length of the specified property value in bytes or -1 if the property was not valid
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetPropertyString(Handle:THandle):String;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the value of the specified property as a string</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Handle
 +
| The handle of the property to get the value of
 +
|-
 +
! Return
 +
| A string representation of the value or an empty string if the property was not valid
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetPropertyLongWord(Handle:THandle):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the value of the specified property as a longword</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Handle
 +
| The handle of the property to get the value of
 +
|-
 +
! Return
 +
| A longword representation of the value or 0 if the property was not valid
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetPropertyQuadWord(Handle:THandle):UInt64;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the value of the specified property as a quadword</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Handle
 +
| The handle of the property to get the value of
 +
|-
 +
! Return
 +
| A quadword representation of the value or 0 if the property was not valid
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
 +
'''RTL Device tree functions'''
 +
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function SysDeviceTreeRead(const Path,Name:String; Buffer:Pointer; var Size:LongWord):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Implementation of DeviceTreeRead API</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| Not intended to be called directly by applications, use DeviceTreeRead instead.
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function SysDeviceTreeRead32(const Path,Name:String; var Value:LongWord):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Implementation of DeviceTreeRead32 API</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| Not intended to be called directly by applications, use DeviceTreeRead32 instead.
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function SysDeviceTreeRead64(const Path,Name:String; var Value:UInt64):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Implementation of DeviceTreeRead64 API</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| Not intended to be called directly by applications, use DeviceTreeRead64 instead.
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function SysDeviceTreeReadString(const Path,Name:String; var Value:String):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Implementation of DeviceTreeReadString API</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| Not intended to be called directly by applications, use DeviceTreeReadString instead.
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
 +
'''Device tree helper functions'''
 +
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetBootArgs:PChar;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Return a character pointer to the location of the command line in the device tree blob</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetRamdisk(var Address:PtrUInt; var Size:UInt64):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Return the address and size of the initial ram disk specified in the device tree blob</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetMemory(Index:LongWord; var Range:LongWord; var Address:PtrUInt; var Size:UInt64):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Return the address and size of a memory block specified in the device tree blob</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeGetReservation(Index:LongWord; var Address:PtrUInt; var Size:UInt64):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Return the address and size of a memory reservation specified in the device tree blob</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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.
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeLogTree:LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Print information about all nodes and properties in the device tree</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Return
 +
| ERROR_SUCCESS if completed or another error code on failure
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DeviceTreeLogTreeEx(Node:THandle; Output:TDTBLogOutput; Decode:TDTBDecodeValue; Data:Pointer):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Print information about one or all nodes and properties in the device tree with custom value decode callback</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
Return to [[Unit_Reference|Unit Reference]]
 
Return to [[Unit_Reference|Unit Reference]]

Revision as of 05:21, 16 November 2021

Return to Unit Reference


Description

Ultibo Flattened Device Tree (DTB) interface unit

Using Device Tree Blob (DTB) files for passing configuration information to the Linux kernel is now widely accepted as the standard method of providing platform specific information without it needing to be hard coded into the kernel at build time.

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.

Constants

To be documented

Type definitions

To be documented

Public variables

To be documented

Function declarations

Initialization functions 

procedure DeviceTreeInit;
Description: Initialize the Device Tree unit
Note Called only during system startup


Device tree functions 

function DeviceTreeValidate(Address:PtrUInt; var Size:LongWord):Boolean;
Description: Check the data at the supplied address to determine if it is a valid Device Tree Blob
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 


function DeviceTreeNextNode(Parent,Previous:THandle):THandle;
Description: Find the next DTB node within the Device Tree
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 


function DeviceTreeNextProperty(Node,Previous:THandle):THandle;
Description: Find the next DTB property within the specified node of the Device Tree
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 


function DeviceTreeGetNode(const Path:String; Parent:THandle):THandle;
Description: Get the handle of the node matching the specified path, optionally within a specified parent
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 


function DeviceTreeGetProperty(Node:THandle; const Name:String):THandle;
Description: Get the handle of the property matching the specified name
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 


function DeviceTreeGetNodeName(Handle:THandle):String;
Description: Get the name of the specified node
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 


procedure DeviceTreeSplitNodeName(Handle:THandle; var NodeName,UnitAddress:String);
Description: Split the name of a node into node name and unit address
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) 


function DeviceTreeGetNodeParent(Handle:THandle):THandle;
Description: Get the parent node of the specified node
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 


function DeviceTreeGetNodeRegCells(Handle:THandle; var Address,Size:LongWord):Boolean;
Description: Get the #address-cells and #size-cells values that apply to reg properties of the specified node
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. 


function DeviceTreeGetNodeRangeCells(Handle:THandle; var ParentAddress,NodeAddress,NodeSize:LongWord):Boolean;
Description: Get the #address-cells and #size-cells values that apply to range properties of the specified node
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. 


function DeviceTreeGetPropertyName(Handle:THandle):String;
Description: Get the name of the specified property
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 


procedure DeviceTreeSplitPropertyName(Handle:THandle; var UniquePrefix,PropertyName:String);
Description: Split the name of a property into property name and unique prefix
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 


function DeviceTreeGetPropertyValue(Handle:THandle):Pointer;
Description: Get a pointer to the raw value of the specified property
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 


function DeviceTreeGetPropertyLength(Handle:THandle):LongWord;
Description: Get the length of the raw value of the specified property
Handle The handle of the property to get the value lenth of
Return The length of the specified property value in bytes or -1 if the property was not valid 


function DeviceTreeGetPropertyString(Handle:THandle):String;
Description: Get the value of the specified property as a string
Handle The handle of the property to get the value of
Return A string representation of the value or an empty string if the property was not valid 


function DeviceTreeGetPropertyLongWord(Handle:THandle):LongWord;
Description: Get the value of the specified property as a longword
Handle The handle of the property to get the value of
Return A longword representation of the value or 0 if the property was not valid 


function DeviceTreeGetPropertyQuadWord(Handle:THandle):UInt64;
Description: Get the value of the specified property as a quadword
Handle The handle of the property to get the value of
Return A quadword representation of the value or 0 if the property was not valid


RTL Device tree functions 

function SysDeviceTreeRead(const Path,Name:String; Buffer:Pointer; var Size:LongWord):LongWord;
Description: Implementation of DeviceTreeRead API
Note Not intended to be called directly by applications, use DeviceTreeRead instead. 


function SysDeviceTreeRead32(const Path,Name:String; var Value:LongWord):LongWord;
Description: Implementation of DeviceTreeRead32 API
Note Not intended to be called directly by applications, use DeviceTreeRead32 instead. 


function SysDeviceTreeRead64(const Path,Name:String; var Value:UInt64):LongWord;
Description: Implementation of DeviceTreeRead64 API
Note Not intended to be called directly by applications, use DeviceTreeRead64 instead. 


function SysDeviceTreeReadString(const Path,Name:String; var Value:String):LongWord;
Description: Implementation of DeviceTreeReadString API
Note Not intended to be called directly by applications, use DeviceTreeReadString instead.


Device tree helper functions 

function DeviceTreeGetBootArgs:PChar;
Description: Return a character pointer to the location of the command line in the device tree blob
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 


function DeviceTreeGetRamdisk(var Address:PtrUInt; var Size:UInt64):Boolean;
Description: Return the address and size of the initial ram disk specified in the device tree blob
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 


function DeviceTreeGetMemory(Index:LongWord; var Range:LongWord; var Address:PtrUInt; var Size:UInt64):Boolean;
Description: Return the address and size of a memory block specified in the device tree blob
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 


function DeviceTreeGetReservation(Index:LongWord; var Address:PtrUInt; var Size:UInt64):Boolean;
Description: Return the address and size of a memory reservation specified in the device tree blob
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. 


function DeviceTreeLogTree:LongWord;
Description: Print information about all nodes and properties in the device tree
Return ERROR_SUCCESS if completed or another error code on failure 


function DeviceTreeLogTreeEx(Node:THandle; Output:TDTBLogOutput; Decode:TDTBDecodeValue; Data:Pointer):LongWord;
Description: Print information about one or all nodes and properties in the device tree with custom value decode callback
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


Return to Unit Reference

Retrieved from "https://ultibo.org/mediawiki_ultibo_org/index.php?title=Unit_DeviceTree&oldid=5272"