Data Structures
struct	CompatStr

struct	CompatibilityInfo

Macros
#define	GET_DT_REG_ADDRESS_OFFSET(Index, AddrCells, SizeCells)

#define	GET_DT_REG_SIZE_OFFSET(Index, AddrCells, SizeCells)

#define	COMPATIBLE_STR_LEN (32U)
	Maximum string length for compatible names.

#define	PPI_OFFSET (16U)
	Interrupt macros.

#define	SPI_OFFSET (32U)

#define	DT_PPI_IRQ (1U)

#define	DT_SPI_IRQ (0U)

#define	DT_IRQ_IS_EDGE_TRIGGERED(x) ((((x) & (BIT0 \| BIT1)) != 0))

#define	DT_IRQ_IS_ACTIVE_LOW(x) ((((x) & (BIT1 \| BIT3)) != 0))

#define	IRQ_TYPE_OFFSET (0U)

#define	IRQ_NUMBER_OFFSET (1U)

#define	IRQ_FLAGS_OFFSET (2U)

Typedefs
typedef struct CompatStr	COMPATIBILITY_STR

typedef struct CompatibilityInfo	COMPATIBILITY_INFO

typedef BOOLEAN(EFIAPI *	NODE_CHECKER_FUNC) (IN CONST VOID Fdt, IN INT32 NodeOffset, IN CONST VOID Context)

Functions
UINT32 EFIAPI	FdtGetInterruptId (UINT32 CONST *Data)

UINT32 EFIAPI	FdtGetInterruptFlags (UINT32 CONST *Data)

BOOLEAN EFIAPI	FdtNodeIsCompatible (IN CONST VOID Fdt, IN INT32 Node, IN CONST VOID CompatInfo)

BOOLEAN EFIAPI	FdtNodeHasProperty (IN CONST VOID Fdt, IN INT32 Node, IN CONST VOID PropertyName)

EFI_STATUS EFIAPI	FdtGetNextNamedNodeInBranch (IN CONST VOID Fdt, IN INT32 FdtBranch, IN CONST CHAR8 NodeName, IN OUT INT32 *Node)

EFI_STATUS EFIAPI	FdtGetNextCompatNodeInBranch (IN CONST VOID Fdt, IN INT32 FdtBranch, IN CONST COMPATIBILITY_INFO CompatNamesInfo, IN OUT INT32 *Node)

EFI_STATUS EFIAPI	FdtGetNextPropNodeInBranch (IN CONST VOID Fdt, IN INT32 FdtBranch, IN CONST CHAR8 PropName, IN OUT INT32 *Node)

EFI_STATUS EFIAPI	FdtCountNamedNodeInBranch (IN CONST VOID Fdt, IN INT32 FdtBranch, IN CONST CHAR8 NodeName, OUT UINT32 *NodeCount)

EFI_STATUS EFIAPI	FdtCountCompatNodeInBranch (IN CONST VOID Fdt, IN INT32 FdtBranch, IN CONST COMPATIBILITY_INFO CompatNamesInfo, OUT UINT32 *NodeCount)

EFI_STATUS EFIAPI	FdtCountPropNodeInBranch (IN CONST VOID Fdt, IN INT32 FdtBranch, IN CONST CHAR8 PropName, OUT UINT32 *NodeCount)

EFI_STATUS EFIAPI	FdtGetIntcParentNode (IN CONST VOID Fdt, IN INT32 Node, OUT INT32 IntcNode)

EFI_STATUS EFIAPI	FdtGetInterruptCellsInfo (IN CONST VOID Fdt, IN INT32 IntcNode, OUT INT32 InterruptCells)

EFI_STATUS EFIAPI	FdtGetAddressInfo (IN CONST VOID Fdt, IN INT32 Node, OUT INT32 AddressCells, OPTIONAL OUT INT32 *SizeCells OPTIONAL)

EFI_STATUS EFIAPI	FdtGetParentAddressInfo (IN CONST VOID Fdt, IN INT32 Node, OUT INT32 AddressCells, OPTIONAL OUT INT32 *SizeCells OPTIONAL)

EFI_STATUS EFIAPI	FdtGetIntcAddressCells (IN CONST VOID Fdt, IN INT32 Node, OUT INT32 AddressCells, OPTIONAL OUT INT32 *SizeCells OPTIONAL)

Detailed Description

Flattened device tree utility.

Copyright (c) 2021, ARM Limited. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Reference(s):

Device tree Specification - Release v0.3
linux/Documentation/devicetree/bindings/interrupt-controller/arm%2Cgic.yaml
linux//Documentation/devicetree/bindings/interrupt-controller/arm%2Cgic.yaml

Definition in file FdtUtility.h.

Macro Definition Documentation

◆ COMPATIBLE_STR_LEN

#define COMPATIBLE_STR_LEN (32U)

Maximum string length for compatible names.

Definition at line 56 of file FdtUtility.h.

◆ DT_IRQ_IS_ACTIVE_LOW

#define DT_IRQ_IS_ACTIVE_LOW ( x ) ((((x) & (BIT1 | BIT3)) != 0))

Definition at line 64 of file FdtUtility.h.

◆ DT_IRQ_IS_EDGE_TRIGGERED

#define DT_IRQ_IS_EDGE_TRIGGERED ( x ) ((((x) & (BIT0 | BIT1)) != 0))

Definition at line 63 of file FdtUtility.h.

◆ DT_PPI_IRQ

#define DT_PPI_IRQ (1U)

Definition at line 61 of file FdtUtility.h.

◆ DT_SPI_IRQ

#define DT_SPI_IRQ (0U)

Definition at line 62 of file FdtUtility.h.

◆ GET_DT_REG_ADDRESS_OFFSET

#define GET_DT_REG_ADDRESS_OFFSET	(	Index,
		AddrCells,
		SizeCells
	)

Value:

          (           \
          (Index) * ((AddrCells) + (SizeCells))                             \
          )

Get the offset of an address in a "reg" Device Tree property.

In a Device Tree, the "reg" property stores address/size couples. They are stored on N 32-bits cells. Based on the value of the #address-cells, the size-cells and the index in the "reg" property, compute the number of 32-bits cells to skip.

Parameters

[in]	Index	Index in the reg property.
[in]	AddrCells	Number of cells used to store an address.
[in]	SizeCells	Number of cells used to store the size of an address.

Return values

Number of 32-bits cells to skip to access the address.

Definition at line 31 of file FdtUtility.h.

◆ GET_DT_REG_SIZE_OFFSET

#define GET_DT_REG_SIZE_OFFSET	(	Index,
		AddrCells,
		SizeCells
	)

Value:

          (              \
          GET_DT_REG_ADDRESS_OFFSET ((Index), (AddrCells), (SizeCells)) +   \
          (SizeCells)                                                       \
          )

Get the offset of an address size in a "reg" Device Tree property.

In a Device Tree, the "reg" property stores address/size couples. They are stored on N 32-bits cells. Based on the value of the #address-cells, the size-cells and the index in the "reg" property, compute the number of 32-bits cells to skip.

Parameters

[in]	Index	Index in the reg property.
[in]	AddrCells	Number of cells used to store an address.
[in]	SizeCells	Number of cells used to store the size of an address.

Return values

Number of 32-bits cells to skip to access the address size.

Definition at line 50 of file FdtUtility.h.

◆ IRQ_FLAGS_OFFSET

#define IRQ_FLAGS_OFFSET (2U)

Definition at line 67 of file FdtUtility.h.

◆ IRQ_NUMBER_OFFSET

#define IRQ_NUMBER_OFFSET (1U)

Definition at line 66 of file FdtUtility.h.

◆ IRQ_TYPE_OFFSET

#define IRQ_TYPE_OFFSET (0U)

Definition at line 65 of file FdtUtility.h.

◆ PPI_OFFSET

#define PPI_OFFSET (16U)

Interrupt macros.

Definition at line 59 of file FdtUtility.h.

◆ SPI_OFFSET

#define SPI_OFFSET (32U)

Definition at line 60 of file FdtUtility.h.

Typedef Documentation

◆ COMPATIBILITY_INFO

typedef struct CompatibilityInfo COMPATIBILITY_INFO

Structure containing a list of compatible names and their count.

◆ COMPATIBILITY_STR

typedef struct CompatStr COMPATIBILITY_STR

A structure describing a compatibility string.

◆ NODE_CHECKER_FUNC

typedef BOOLEAN(EFIAPI * NODE_CHECKER_FUNC) (IN CONST VOID *Fdt, IN INT32 NodeOffset, IN CONST VOID *Context)

Operate a check on a Device Tree node.

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree.
[in]	NodeOffset	Offset of the node to compare input string.
[in]	Context	Context to operate the check on the node.

Return values

True	The check is correct.
FALSE	Otherwise, or error.

Definition at line 126 of file FdtUtility.h.

Function Documentation

◆ FdtCountCompatNodeInBranch()

EFI_STATUS EFIAPI FdtCountCompatNodeInBranch	(	IN CONST VOID *	Fdt,
		IN INT32	FdtBranch,
		IN CONST COMPATIBILITY_INFO *	CompatNamesInfo,
		OUT UINT32 *	NodeCount
	)

Count the number of nodes in a branch with at least one compatible property.

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree.
[in]	FdtBranch	Only search in the sub-nodes of this branch. Write (-1) to search the whole tree.
[in]	CompatibleTable	Table of compatible strings to compare with the compatible property of the node.
[out]	NodeCount	If success, contains the count of nodes fulfilling the condition. Can be 0.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_ABORTED	An error occurred.
EFI_INVALID_PARAMETER	Invalid parameter.

Count the number of nodes in a branch with at least one compatible property.

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree.
[in]	FdtBranch	Only search in the sub-nodes of this branch. Write (-1) to search the whole tree.
[in]	CompatNamesInfo	Table of compatible strings to compare with the compatible property of the node.
[out]	NodeCount	If success, contains the count of nodes fulfilling the condition. Can be 0.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_ABORTED	An error occurred.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 573 of file FdtUtility.c.

◆ FdtCountNamedNodeInBranch()

EFI_STATUS EFIAPI FdtCountNamedNodeInBranch	(	IN CONST VOID *	Fdt,
		IN INT32	FdtBranch,
		IN CONST CHAR8 *	NodeName,
		OUT UINT32 *	NodeCount
	)

Count the number of nodes in a branch with the input name.

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree.
[in]	FdtBranch	Only search in the sub-nodes of this branch. Write (-1) to search the whole tree.
[in]	NodeName	Node name to search. This is a NULL terminated string.
[out]	NodeCount	If success, contains the count of nodes fulfilling the condition. Can be 0.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_ABORTED	An error occurred.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 538 of file FdtUtility.c.

◆ FdtCountPropNodeInBranch()

EFI_STATUS EFIAPI FdtCountPropNodeInBranch	(	IN CONST VOID *	Fdt,
		IN INT32	FdtBranch,
		IN CONST CHAR8 *	PropName,
		OUT UINT32 *	NodeCount
	)

Count the number of nodes in a branch having the PropName property.

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree.
[in]	FdtBranch	Only search in the sub-nodes of this branch. Write (-1) to search the whole tree.
[in]	PropName	Name of the property to search. This is a NULL terminated string.
[out]	NodeCount	If success, contains the count of nodes fulfilling the condition. Can be 0.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_ABORTED	An error occurred.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 606 of file FdtUtility.c.

◆ FdtGetAddressInfo()

EFI_STATUS EFIAPI FdtGetAddressInfo	(	IN CONST VOID *	Fdt,
		IN INT32	Node,
		OUT INT32 *	AddressCells,
		OPTIONAL OUT INT32 *SizeCells	OPTIONAL
	)

Get the "#address-cells" and/or "#size-cells" property of the node.

According to the Device Tree specification, s2.3.5 "#address-cells and #size-cells": "If missing, a client program should assume a default value of 2 for #address-cells, and a value of 1 for #size-cells."

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree.
[in]	Node	Offset of the node having to get the "#address-cells" and "#size-cells" properties from.
[out]	AddressCells	If success, number of address-cells. If the property is not available, default value is 2.
[out]	SizeCells	If success, number of size-cells. If the property is not available, default value is 1.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_ABORTED	An error occurred.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 778 of file FdtUtility.c.

◆ FdtGetIntcAddressCells()

EFI_STATUS EFIAPI FdtGetIntcAddressCells	(	IN CONST VOID *	Fdt,
		IN INT32	Node,
		OUT INT32 *	AddressCells,
		OPTIONAL OUT INT32 *SizeCells	OPTIONAL
	)

For relevant architectures, get the "#address-cells" and/or "#size-cells" property of the node.

According to the Device Tree specification, s2.3.5 "#address-cells and #size-cells": "If missing, a client program should assume a default value of 2 for #address-cells, and a value of 1 for #size-cells."

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree.
[in]	Node	Offset of the node having to get the "#address-cells" and "#size-cells" properties from.
[out]	AddressCells	If success, number of address-cells. If the property is not available, default value is 2.
[out]	SizeCells	If success, number of size-cells. If the property is not available, default value is 1.

Return values

EFI_INVALID_PARAMETER Invalid parameter.

Definition at line 110 of file ArmFdtInterrupt.c.

◆ FdtGetIntcParentNode()

EFI_STATUS EFIAPI FdtGetIntcParentNode	(	IN CONST VOID *	Fdt,
		IN INT32	Node,
		OUT INT32 *	IntcNode
	)

Get the interrupt-controller node handling the interrupts of the input node.

To do this, recursively search a node with either the "interrupt-controller" or the "interrupt-parent" property in the parents of Node.

Devicetree Specification, Release v0.3, 2.4.1 "Properties for Interrupt Generating Devices": Because the hierarchy of the nodes in the interrupt tree might not match the devicetree, the interrupt-parent property is available to make the definition of an interrupt parent explicit. The value is the phandle to the interrupt parent. If this property is missing from a device, its interrupt parent is assumed to be its devicetree parent.

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree.
[in]	Node	Offset of the node to start the search.
[out]	IntcNode	If success, contains the offset of the interrupt-controller node.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_NOT_FOUND	No interrupt-controller node found.
EFI_ABORTED	An error occurred.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 650 of file FdtUtility.c.

◆ FdtGetInterruptCellsInfo()

EFI_STATUS EFIAPI FdtGetInterruptCellsInfo	(	IN CONST VOID *	Fdt,
		IN INT32	IntcNode,
		OUT INT32 *	IntCells
	)

Get the "interrupt-cells" property value of the node.

The "interrupts" property requires to know the number of cells used to encode an interrupt. This information is stored in the interrupt-controller of the input Node.

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree (Fdt).
[in]	IntcNode	Offset of an interrupt-controller node.
[out]	IntCells	If success, contains the "interrupt-cells" property of the IntcNode.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_UNSUPPORTED	Unsupported.

Definition at line 726 of file FdtUtility.c.

◆ FdtGetInterruptFlags()

UINT32 EFIAPI FdtGetInterruptFlags ( UINT32 CONST * Data )

Get the ACPI interrupt flags of an interrupt described in a fdt.

Data must describe a GIC interrupt. A GIC interrupt is on at least 3 UINT32 cells.

Parameters

[in] Data Pointer to the first cell of an "interrupts" property.

Return values

The	interrupt flags (for ACPI).

Get the ACPI interrupt flags of an interrupt described in a fdt.

Data must describe a GIC interrupt. A GIC interrupt is on at least 3 UINT32 cells.

PPI interrupt cpu mask on bits [15:8] are ignored.

Parameters

[in] Data Pointer to the first cell of an "interrupts" property.

Return values

The	interrupt flags (for ACPI).

Definition at line 70 of file ArmFdtInterrupt.c.

◆ FdtGetInterruptId()

UINT32 EFIAPI FdtGetInterruptId ( UINT32 CONST * Data )

Get the interrupt Id of an interrupt described in a fdt.

Data must describe a GIC interrupt. A GIC interrupt is on at least 3 UINT32 cells. This function DOES NOT SUPPORT extended SPI range and extended PPI range.

Parameters

[in] Data Pointer to the first cell of an "interrupts" property.

Return values

The	interrupt id.

Definition at line 28 of file ArmFdtInterrupt.c.

◆ FdtGetNextCompatNodeInBranch()

EFI_STATUS EFIAPI FdtGetNextCompatNodeInBranch	(	IN CONST VOID *	Fdt,
		IN INT32	FdtBranch,
		IN CONST COMPATIBILITY_INFO *	CompatNamesInfo,
		IN OUT INT32 *	Node
	)

Get the next node in a branch with at least one compatible property.

The Device tree is traversed in a depth-first search, starting from Node. The input Node is skipped.

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree.
[in]	FdtBranch	Only search in the sub-nodes of this branch. Write (-1) to search the whole tree.
[in]	CompatNamesInfo	Table of compatible strings to compare with the compatible property of the node.
[in,out]	Node	At entry: Node offset to start the search. This first node is skipped. Write (-1) to search the whole tree. At exit: If success, contains the offset of the next node in the branch being compatible.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_ABORTED	An error occurred.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_NOT_FOUND	No matching node found.

Definition at line 398 of file FdtUtility.c.

◆ FdtGetNextNamedNodeInBranch()

EFI_STATUS EFIAPI FdtGetNextNamedNodeInBranch	(	IN CONST VOID *	Fdt,
		IN INT32	FdtBranch,
		IN CONST CHAR8 *	NodeName,
		IN OUT INT32 *	Node
	)

Get the next node in a branch having a matching name.

The Device tree is traversed in a depth-first search, starting from Node. The input Node is skipped.

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree.
[in]	FdtBranch	Only search in the sub-nodes of this branch. Write (-1) to search the whole tree.
[in]	NodeName	The node name to search. This is a NULL terminated string.
[in,out]	Node	At entry: Node offset to start the search. This first node is skipped. Write (-1) to search the whole tree. At exit: If success, contains the offset of the next node in the branch having a matching name.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_ABORTED	An error occurred.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_NOT_FOUND	No matching node found.

Definition at line 358 of file FdtUtility.c.

◆ FdtGetNextPropNodeInBranch()

EFI_STATUS EFIAPI FdtGetNextPropNodeInBranch	(	IN CONST VOID *	Fdt,
		IN INT32	FdtBranch,
		IN CONST CHAR8 *	PropName,
		IN OUT INT32 *	Node
	)

Get the next node in a branch having the PropName property.

The Device tree is traversed in a depth-first search, starting from Node. The input Node is skipped.

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree.
[in]	FdtBranch	Only search in the sub-nodes of this branch. Write (-1) to search the whole tree.
[in]	PropName	Name of the property to search. This is a NULL terminated string.
[in,out]	Node	At entry: Node offset to start the search. This first node is skipped. Write (-1) to search the whole tree. At exit: If success, contains the offset of the next node in the branch being compatible.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_ABORTED	An error occurred.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_NOT_FOUND	No matching node found.

Definition at line 438 of file FdtUtility.c.

◆ FdtGetParentAddressInfo()

EFI_STATUS EFIAPI FdtGetParentAddressInfo	(	IN CONST VOID *	Fdt,
		IN INT32	Node,
		OUT INT32 *	AddressCells,
		OPTIONAL OUT INT32 *SizeCells	OPTIONAL
	)

Get the "#address-cells" and/or "#size-cells" property of the parent node.

According to the Device Tree specification, s2.3.5 "#address-cells and #size-cells": "If missing, a client program should assume a default value of 2 for #address-cells, and a value of 1 for #size-cells."

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree.
[in]	Node	Offset of the node having to get the "#address-cells" and "#size-cells" properties from its parent.
[out]	AddressCells	If success, number of address-cells. If the property is not available, default value is 2.
[out]	SizeCells	If success, number of size-cells. If the property is not available, default value is 1.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_ABORTED	An error occurred.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 833 of file FdtUtility.c.

◆ FdtNodeHasProperty()

BOOLEAN EFIAPI FdtNodeHasProperty	(	IN CONST VOID *	Fdt,
		IN INT32	Node,
		IN CONST VOID *	PropertyName
	)

Check whether a node has a property.

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree.
[in]	Node	Offset of the node to operate the check on.
[in]	PropertyName	Name of the property to search. This is a NULL terminated string.

Return values

True	The node has the property.
FALSE	Otherwise, or error.

Definition at line 144 of file FdtUtility.c.

◆ FdtNodeIsCompatible()

BOOLEAN EFIAPI FdtNodeIsCompatible	(	IN CONST VOID *	Fdt,
		IN INT32	Node,
		IN CONST VOID *	CompatInfo
	)

Iterate through the list of strings in the Context, and check whether at least one string is matching the "compatible" property of the node.

Parameters

[in]	Fdt	Pointer to a Flattened Device Tree.
[in]	Node	Offset of the node to operate the check on.
[in]	CompatInfo	COMPATIBILITY_INFO containing the list of compatible strings to compare with the "compatible" property of the node.

Return values

TRUE	At least one string matched, the node is compatible.
FALSE	Otherwise, or error.

Definition at line 90 of file FdtUtility.c.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ COMPATIBLE_STR_LEN

◆ DT_IRQ_IS_ACTIVE_LOW

◆ DT_IRQ_IS_EDGE_TRIGGERED

◆ DT_PPI_IRQ

◆ DT_SPI_IRQ

◆ GET_DT_REG_ADDRESS_OFFSET

◆ GET_DT_REG_SIZE_OFFSET

◆ IRQ_FLAGS_OFFSET

◆ IRQ_NUMBER_OFFSET

◆ IRQ_TYPE_OFFSET

◆ PPI_OFFSET

◆ SPI_OFFSET

Typedef Documentation

◆ COMPATIBILITY_INFO

◆ COMPATIBILITY_STR

◆ NODE_CHECKER_FUNC

Function Documentation

◆ FdtCountCompatNodeInBranch()

◆ FdtCountNamedNodeInBranch()

◆ FdtCountPropNodeInBranch()

◆ FdtGetAddressInfo()

◆ FdtGetIntcAddressCells()

◆ FdtGetIntcParentNode()

◆ FdtGetInterruptCellsInfo()

◆ FdtGetInterruptFlags()

◆ FdtGetInterruptId()

◆ FdtGetNextCompatNodeInBranch()

◆ FdtGetNextNamedNodeInBranch()

◆ FdtGetNextPropNodeInBranch()

◆ FdtGetParentAddressInfo()

◆ FdtNodeHasProperty()

◆ FdtNodeIsCompatible()