ranges property

Macros
#define	DT_NUM_RANGES(node_id)   DT_CAT(node_id, _RANGES_NUM)
	Get the number of range blocks in the ranges property.
#define	DT_RANGES_HAS_IDX(node_id, idx)    IS_ENABLED(DT_CAT4(node_id, _RANGES_IDX_, idx, _EXISTS))
	Is idx a valid range block index?
#define	DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(node_id, idx)    IS_ENABLED(DT_CAT4(node_id, _RANGES_IDX_, idx, _VAL_CHILD_BUS_FLAGS_EXISTS))
	Does a ranges property have child bus flags at index?
#define	DT_RANGES_CHILD_BUS_FLAGS_BY_IDX(node_id, idx)    DT_CAT4(node_id, _RANGES_IDX_, idx, _VAL_CHILD_BUS_FLAGS)
	Get the ranges property child bus flags at index.
#define	DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(node_id, idx)    DT_CAT4(node_id, _RANGES_IDX_, idx, _VAL_CHILD_BUS_ADDRESS)
	Get the ranges property child bus address at index.
#define	DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX(node_id, idx)    DT_CAT4(node_id, _RANGES_IDX_, idx, _VAL_PARENT_BUS_ADDRESS)
	Get the ranges property parent bus address at index.
#define	DT_RANGES_LENGTH_BY_IDX(node_id, idx)    DT_CAT4(node_id, _RANGES_IDX_, idx, _VAL_LENGTH)
	Get the ranges property length at index.
#define	DT_FOREACH_RANGE(node_id, fn)    DT_CAT(node_id, _FOREACH_RANGE)(fn)
	Invokes fn for each entry of node_id ranges property.

Detailed Description

Macro Definition Documentation

DT_FOREACH_RANGE

#define DT_FOREACH_RANGE	(		node_id,
			fn
	)		DT_CAT(node_id, _FOREACH_RANGE)(fn)

#include <zephyr/devicetree.h>

Invokes fn for each entry of node_id ranges property.

The macro fn must take two parameters, node_id which will be the node identifier of the node with the ranges property and idx the index of the ranges block.

Example devicetree fragment:

n: node@0 {
        reg = <0 0 1>;
 
        ranges = <0x0 0x0 0x0 0x3eff0000 0x10000>,
                 <0x0 0x10000000 0x0 0x10000000 0x2eff0000>;
};

Example usage:

#define RANGE_LENGTH(node_id, idx) DT_RANGES_LENGTH_BY_IDX(node_id, idx),
 
const uint64_t *ranges_length[] = {
        DT_FOREACH_RANGE(DT_NODELABEL(n), RANGE_LENGTH)
};

This expands to:

const char *ranges_length[] = {
    0x10000, 0x2eff0000,
};

Parameters

node_id	node identifier
fn	macro to invoke

DT_NUM_RANGES

#define DT_NUM_RANGES

(

node_id

)

DT_CAT(node_id, _RANGES_NUM)

#include <zephyr/devicetree.h>

Get the number of range blocks in the ranges property.

Use this instead of DT_PROP_LEN(node_id, ranges).

Example devicetree fragment:

pcie0: pcie@0 {
        compatible = "pcie-controller";
        reg = <0 1>;
        #address-cells = <3>;
        #size-cells = <2>;
 
        ranges = <0x1000000 0 0 0 0x3eff0000 0 0x10000>,
                 <0x2000000 0 0x10000000 0 0x10000000 0 0x2eff0000>,
                 <0x3000000 0x80 0 0x80 0 0x80 0>;
};
 
other: other@1 {
        reg = <1 1>;
 
        ranges = <0x0 0x0 0x0 0x3eff0000 0x10000>,
                 <0x0 0x10000000 0x0 0x10000000 0x2eff0000>;
};

Example usage:

DT_NUM_RANGES(DT_NODELABEL(pcie0)) // 3
DT_NUM_RANGES(DT_NODELABEL(other)) // 2

Parameters

node_id

node identifier

DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX

#define DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX	(		node_id,
			idx
	)		DT_CAT4(node_id, _RANGES_IDX_, idx, _VAL_CHILD_BUS_ADDRESS)

#include <zephyr/devicetree.h>

Get the ranges property child bus address at index.

When the node is a PCIe bus, the Child Bus Address has an extra cell used to store some flags, thus this cell is removed from the Child Bus Address.

Example devicetree fragments:

parent {
        #address-cells = <2>;
 
        pcie0: pcie@0 {
                compatible = "pcie-controller";
                reg = <0 0 1>;
                #address-cells = <3>;
                #size-cells = <2>;
 
                ranges = <0x1000000 0 0 0 0x3eff0000 0 0x10000>,
                         <0x2000000 0 0x10000000 0 0x10000000 0 0x2eff0000>,
                         <0x3000000 0x80 0 0x80 0 0x80 0>;
        };
 
        other: other@1 {
                reg = <0 1 1>;
 
                ranges = <0x0 0x0 0x0 0x3eff0000 0x10000>,
                         <0x0 0x10000000 0x0 0x10000000 0x2eff0000>;
        };
};

Example usage:

DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(DT_NODELABEL(pcie0), 0) // 0
DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(DT_NODELABEL(pcie0), 1) // 0x10000000
DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(DT_NODELABEL(pcie0), 2) // 0x8000000000
DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(DT_NODELABEL(other), 0) // 0
DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(DT_NODELABEL(other), 1) // 0x10000000

Parameters

node_id	node identifier
idx	logical index into the ranges array

Returns

range child bus address field at idx

DT_RANGES_CHILD_BUS_FLAGS_BY_IDX

#define DT_RANGES_CHILD_BUS_FLAGS_BY_IDX	(		node_id,
			idx
	)		DT_CAT4(node_id, _RANGES_IDX_, idx, _VAL_CHILD_BUS_FLAGS)

#include <zephyr/devicetree.h>

Get the ranges property child bus flags at index.

When the node is a PCIe bus, the Child Bus Address has an extra cell used to store some flags, thus this cell is extracted from the Child Bus Address as Child Bus Flags field.

Example devicetree fragments:

parent {
        #address-cells = <2>;
 
        pcie0: pcie@0 {
                compatible = "pcie-controller";
                reg = <0 0 1>;
                #address-cells = <3>;
                #size-cells = <2>;
 
                ranges = <0x1000000 0 0 0 0x3eff0000 0 0x10000>,
                         <0x2000000 0 0x10000000 0 0x10000000 0 0x2eff0000>,
                         <0x3000000 0x80 0 0x80 0 0x80 0>;
        };
};

Example usage:

DT_RANGES_CHILD_BUS_FLAGS_BY_IDX(DT_NODELABEL(pcie0), 0) // 0x1000000
DT_RANGES_CHILD_BUS_FLAGS_BY_IDX(DT_NODELABEL(pcie0), 1) // 0x2000000
DT_RANGES_CHILD_BUS_FLAGS_BY_IDX(DT_NODELABEL(pcie0), 2) // 0x3000000

Parameters

node_id	node identifier
idx	logical index into the ranges array

Returns

range child bus flags field at idx

DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX

#define DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX	(		node_id,
			idx
	)		IS_ENABLED(DT_CAT4(node_id, _RANGES_IDX_, idx, _VAL_CHILD_BUS_FLAGS_EXISTS))

#include <zephyr/devicetree.h>

Does a ranges property have child bus flags at index?

If this returns 1, then DT_RANGES_CHILD_BUS_FLAGS_BY_IDX(node_id, idx) is valid. If it returns 0, it is an error to use this macro with index idx. This macro only returns 1 for PCIe buses (i.e. nodes whose bindings specify they are "pcie" bus nodes.)

Example devicetree fragment:

parent {
        #address-cells = <2>;
 
        pcie0: pcie@0 {
                compatible = "pcie-controller";
                reg = <0 0 1>;
                #address-cells = <3>;
                #size-cells = <2>;
 
                ranges = <0x1000000 0 0 0 0x3eff0000 0 0x10000>,
                         <0x2000000 0 0x10000000 0 0x10000000 0 0x2eff0000>,
                         <0x3000000 0x80 0 0x80 0 0x80 0>;
        };
 
        other: other@1 {
                reg = <0 1 1>;
 
                ranges = <0x0 0x0 0x0 0x3eff0000 0x10000>,
                         <0x0 0x10000000 0x0 0x10000000 0x2eff0000>;
        };
};

Example usage:

DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(pcie0), 0) // 1
DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(pcie0), 1) // 1
DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(pcie0), 2) // 1
DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(pcie0), 3) // 0
DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(other), 0) // 0
DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(other), 1) // 0
DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(other), 2) // 0
DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(other), 3) // 0

Parameters

node_id	node identifier
idx	logical index into the ranges array

Returns

1 if idx is a valid child bus flags index, 0 otherwise.

DT_RANGES_HAS_IDX

#define DT_RANGES_HAS_IDX	(		node_id,
			idx
	)		IS_ENABLED(DT_CAT4(node_id, _RANGES_IDX_, idx, _EXISTS))

#include <zephyr/devicetree.h>

Is idx a valid range block index?

If this returns 1, then DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(node_id, idx), DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX(node_id, idx) or DT_RANGES_LENGTH_BY_IDX(node_id, idx) are valid. For DT_RANGES_CHILD_BUS_FLAGS_BY_IDX(node_id, idx) the return value of DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(node_id, idx) will indicate validity. If it returns 0, it is an error to use those macros with index idx, including DT_RANGES_CHILD_BUS_FLAGS_BY_IDX(node_id, idx).

Example devicetree fragment:

pcie0: pcie@0 {
        compatible = "pcie-controller";
        reg = <0 1>;
        #address-cells = <3>;
        #size-cells = <2>;
 
        ranges = <0x1000000 0 0 0 0x3eff0000 0 0x10000>,
                 <0x2000000 0 0x10000000 0 0x10000000 0 0x2eff0000>,
                 <0x3000000 0x80 0 0x80 0 0x80 0>;
};
 
other: other@1 {
        reg = <1 1>;
 
        ranges = <0x0 0x0 0x0 0x3eff0000 0x10000>,
                 <0x0 0x10000000 0x0 0x10000000 0x2eff0000>;
};

Example usage:

DT_RANGES_HAS_IDX(DT_NODELABEL(pcie0), 0) // 1
DT_RANGES_HAS_IDX(DT_NODELABEL(pcie0), 1) // 1
DT_RANGES_HAS_IDX(DT_NODELABEL(pcie0), 2) // 1
DT_RANGES_HAS_IDX(DT_NODELABEL(pcie0), 3) // 0
DT_RANGES_HAS_IDX(DT_NODELABEL(other), 0) // 1
DT_RANGES_HAS_IDX(DT_NODELABEL(other), 1) // 1
DT_RANGES_HAS_IDX(DT_NODELABEL(other), 2) // 0
DT_RANGES_HAS_IDX(DT_NODELABEL(other), 3) // 0

Parameters

node_id	node identifier
idx	index to check

Returns

1 if idx is a valid register block index, 0 otherwise.

DT_RANGES_LENGTH_BY_IDX

#define DT_RANGES_LENGTH_BY_IDX	(		node_id,
			idx
	)		DT_CAT4(node_id, _RANGES_IDX_, idx, _VAL_LENGTH)

#include <zephyr/devicetree.h>

Get the ranges property length at index.

Similarly to DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(), this properly accounts for child bus flags cells when the node is a PCIe bus.

Example devicetree fragment:

parent {
        #address-cells = <2>;
 
        pcie0: pcie@0 {
                compatible = "pcie-controller";
                reg = <0 0 1>;
                #address-cells = <3>;
                #size-cells = <2>;
 
                ranges = <0x1000000 0 0 0 0x3eff0000 0 0x10000>,
                         <0x2000000 0 0x10000000 0 0x10000000 0 0x2eff0000>,
                         <0x3000000 0x80 0 0x80 0 0x80 0>;
        };
 
        other: other@1 {
                reg = <0 1 1>;
 
                ranges = <0x0 0x0 0x0 0x3eff0000 0x10000>,
                         <0x0 0x10000000 0x0 0x10000000 0x2eff0000>;
        };
};

Example usage:

DT_RANGES_LENGTH_BY_IDX(DT_NODELABEL(pcie0), 0) // 0x10000
DT_RANGES_LENGTH_BY_IDX(DT_NODELABEL(pcie0), 1) // 0x2eff0000
DT_RANGES_LENGTH_BY_IDX(DT_NODELABEL(pcie0), 2) // 0x8000000000
DT_RANGES_LENGTH_BY_IDX(DT_NODELABEL(other), 0) // 0x10000
DT_RANGES_LENGTH_BY_IDX(DT_NODELABEL(other), 1) // 0x2eff0000

Parameters

node_id	node identifier
idx	logical index into the ranges array

Returns

range length field at idx

DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX

#define DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX	(		node_id,
			idx
	)		DT_CAT4(node_id, _RANGES_IDX_, idx, _VAL_PARENT_BUS_ADDRESS)

#include <zephyr/devicetree.h>

Get the ranges property parent bus address at index.

Similarly to DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(), this properly accounts for child bus flags cells when the node is a PCIe bus.

Example devicetree fragment:

parent {
        #address-cells = <2>;
 
        pcie0: pcie@0 {
                compatible = "pcie-controller";
                reg = <0 0 1>;
                #address-cells = <3>;
                #size-cells = <2>;
 
                ranges = <0x1000000 0 0 0 0x3eff0000 0 0x10000>,
                         <0x2000000 0 0x10000000 0 0x10000000 0 0x2eff0000>,
                         <0x3000000 0x80 0 0x80 0 0x80 0>;
        };
 
        other: other@1 {
                reg = <0 1 1>;
 
                ranges = <0x0 0x0 0x0 0x3eff0000 0x10000>,
                         <0x0 0x10000000 0x0 0x10000000 0x2eff0000>;
        };
};

Example usage:

DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX(DT_NODELABEL(pcie0), 0) // 0x3eff0000
DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX(DT_NODELABEL(pcie0), 1) // 0x10000000
DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX(DT_NODELABEL(pcie0), 2) // 0x8000000000
DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX(DT_NODELABEL(other), 0) // 0x3eff0000
DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX(DT_NODELABEL(other), 1) // 0x10000000

Parameters

node_id	node identifier
idx	logical index into the ranges array

Returns

range parent bus address field at idx