Driver Model

Uclass and Driver

structuclass: a U-Boot drive class, collecting together similar drivers

Definition

struct uclass {
 void *priv_;
 struct uclass_driver *uc_drv;
 struct list_head dev_head;
 struct list_head sibling_node;
};

Members

priv_: Private data for this uclass (do not access outside driver model)
uc_drv: The driver for the uclass itself, not to be confused with a ‘struct driver’
dev_head: List of devices in this uclass (devices are attached to their uclass when their bind method is called)
sibling_node: Next uclass in the linked list of uclasses

Description

A uclass provides an interface to a particular function, which is implemented by one or more drivers. Every driver belongs to a uclass even if it is the only driver in that uclass. An example uclass is GPIO, which provides the ability to change read inputs, set and clear outputs, etc. There may be drivers for on-chip SoC GPIO banks, I2C GPIO expanders and PMIC IO lines, all made available in a unified way through the uclass.

structuclass_driver: Driver for the uclass

Definition

struct uclass_driver {
 const char *name;
 enum uclass_id id;
 int (*post_bind)(struct udevice *dev);
 int (*pre_unbind)(struct udevice *dev);
 int (*pre_probe)(struct udevice *dev);
 int (*post_probe)(struct udevice *dev);
 int (*pre_remove)(struct udevice *dev);
 int (*child_post_bind)(struct udevice *dev);
 int (*child_pre_probe)(struct udevice *dev);
 int (*child_post_probe)(struct udevice *dev);
 int (*init)(struct uclass *class);
 int (*destroy)(struct uclass *class);
 int priv_auto;
 int per_device_auto;
 int per_device_plat_auto;
 int per_child_auto;
 int per_child_plat_auto;
 uint32_t flags;
};

Members

name: Name of uclass driver
id: ID number of this uclass
post_bind: Called after a new device is bound to this uclass
pre_unbind: Called before a device is unbound from this uclass
pre_probe: Called before a new device is probed
post_probe: Called after a new device is probed
pre_remove: Called before a device is removed
child_post_bind: Called after a child is bound to a device in this uclass
child_pre_probe: Called before a child in this uclass is probed
child_post_probe: Called after a child in this uclass is probed
init: Called to set up the uclass
destroy: Called to destroy the uclass
priv_auto: If non-zero this is the size of the private data to be allocated in the uclass’s ->priv pointer. If zero, then the uclass driver is responsible for allocating any data required.
per_device_auto: Each device can hold private data owned by the uclass. If required this will be automatically allocated if this value is non-zero.
per_device_plat_auto: Each device can hold platform data owned by the uclass as ‘dev->uclass_plat’. If the value is non-zero, then this will be automatically allocated.
per_child_auto: Each child device (of a parent in this uclass) can hold parent data for the device/uclass. This value is only used as a fallback if this member is 0 in the driver.
per_child_plat_auto: A bus likes to store information about its children. If non-zero this is the size of this data, to be allocated in the child device’s parent_plat pointer. This value is only used as a fallback if this member is 0 in the driver.
flags: Flags for this uclass (DM_UC_...)

Description

A uclass_driver provides a consistent interface to a set of related drivers.

DM_UCLASS_DRIVER_REF

DM_UCLASS_DRIVER_REF (_name)

Get a reference to a uclass driver

Parameters

_name: Name of the uclass_driver. This must be a valid C identifier, used by the linker_list.

Description

This is useful in data structures and code for referencing a uclass_driver at build time. Before this is used, an extern UCLASS_DRIVER() must have been declared.

For example:

extern UCLASS_DRIVER(clk);
struct uclass_driver *drvs[] = {
 DM_UCLASS_DRIVER_REF(clk),
};

Return

struct uclass_driver * for the uclass driver

void*uclass_get_priv(conststructuclass *uc): Get the private data for a uclass

Parameters

const struct uclass *uc: Uclass to check

Return

private data, or NULL if none

intuclass_get(enumuclass_idkey, structuclass **ucp): Get a uclass based on an ID, creating it if needed

Parameters

enum uclass_id key: ID to look up
struct uclass **ucp: Returns pointer to uclass (there is only one per ID)

Description

Every uclass is identified by an ID, a number from 0 to n-1 where n is the number of uclasses. This function allows looking up a uclass by its ID.

Return

0 if OK, -EDEADLK if driver model is not yet inited, other -ve on other error

constchar*uclass_get_name(enumuclass_idid): Get the name of a uclass driver

Parameters

enum uclass_id id: ID to look up

Return

the name of the uclass driver for that ID, or NULL if none

enumuclass_iduclass_get_by_namelen(constchar*name, intlen): Look up a uclass by its driver name

Parameters

const char *name: Name to look up
int len: Length of name (the uclass driver name must have the same length)

Return

the associated uclass ID, or UCLASS_INVALID if not found

enumuclass_iduclass_get_by_name(constchar*name): Look up a uclass by its driver name

Parameters

const char *name: Name to look up

Return

the associated uclass ID, or UCLASS_INVALID if not found

intuclass_get_device(enumuclass_idid, intindex, structudevice **devp): Get a uclass device based on an ID and index

Parameters

enum uclass_id id: ID to look up
int index: Device number within that uclass (0=first)
struct udevice **devp: Returns pointer to device (there is only one per for each ID)

Description

The device is probed to activate it ready for use.

Return

0 if OK, -ve on error

intuclass_get_device_by_name(enumuclass_idid, constchar*name, structudevice **devp): Get a uclass device by its name

Parameters

enum uclass_id id: ID to look up
const char *name: name of a device to get
struct udevice **devp: Returns pointer to device (the first one with the name)

Description

This searches the devices in the uclass for one with the exactly given name.

The device is probed to activate it ready for use.

Return

0 if OK, -ve on error

intuclass_get_device_by_seq(enumuclass_idid, intseq, structudevice **devp): Get a uclass device based on an ID and sequence

Parameters

enum uclass_id id: ID to look up
int seq: Sequence number to find (0=first)
struct udevice **devp: Returns pointer to device (there is only one for each seq)

Description

If an active device has this sequence it will be returned. If there is no such device then this will check for a device that is requesting this sequence.

The device is probed to activate it ready for use.

Return

0 if OK, -ve on error

intuclass_get_device_by_of_offset(enumuclass_idid, intnode, structudevice **devp): Get a uclass device by device tree node

Parameters

enum uclass_id id: ID to look up
int node: Device tree offset to search for (if -ve then -ENODEV is returned)
struct udevice **devp: Returns pointer to device (there is only one for each node)

Description

This searches the devices in the uclass for one attached to the given device tree node.

The device is probed to activate it ready for use.

Return

0 if OK, -ve on error

intuclass_get_device_by_ofnode(enumuclass_idid, ofnodenode, structudevice **devp): Get a uclass device by device tree node

Parameters

enum uclass_id id: ID to look up
ofnode node: Device tree node to search for (if NULL then -ENODEV is returned)
struct udevice **devp: Returns pointer to device (there is only one for each node)

Description

This searches the devices in the uclass for one attached to the given device tree node.

The device is probed to activate it ready for use.

Return

0 if OK, -ve on error

intuclass_get_device_by_of_path(enumuclass_idid, constchar*path, structudevice **devp): Get a uclass device by device tree path

Parameters

enum uclass_id id: ID to look up
const char *path: Device tree path to search for (if no such path then -ENODEV is returned)
struct udevice **devp: Returns pointer to device (there is only one for each node)

Description

This searches the devices in the uclass for one attached to the device tree node corresponding to the given path (which may also be an alias).

The device is probed to activate it ready for use.

Return

0 if OK, -ve on error

intuclass_get_device_by_phandle_id(enumuclass_idid, uintphandle_id, structudevice **devp): Get a uclass device by phandle id

Parameters

enum uclass_id id: uclass ID to look up
uint phandle_id: the phandle id to look up
struct udevice **devp: Returns pointer to device (there is only one for each node). NULL if there is no such device.

Description

This searches the devices in the uclass for one with the given phandle id.

The device is probed to activate it ready for use.

Return

0 if OK, -ENODEV if there is no device match the phandle, other -ve on error

intuclass_get_device_by_phandle(enumuclass_idid, structudevice *parent, constchar*name, structudevice **devp): Get a uclass device by phandle

Parameters

enum uclass_id id: uclass ID to look up
struct udevice *parent: Parent device containing the phandle pointer
const char *name: Name of property in the parent device node
struct udevice **devp: Returns pointer to device (there is only one for each node)

Description

This searches the devices in the uclass for one with the given phandle.

The device is probed to activate it ready for use.

Return

0 if OK, -ENOENT if there is no name present in the node, other -ve on error

intuclass_get_device_by_driver(enumuclass_idid, conststructdriver *drv, structudevice **devp): Get a uclass device for a driver

Parameters

enum uclass_id id: ID to look up
const struct driver *drv: Driver to look for
struct udevice **devp: Returns pointer to the first device with that driver

Description

This searches the devices in the uclass for one that uses the given driver. Use DM_DRIVER_GET(name) for the drv argument, where ‘name’ is the driver name - as used in U_BOOT_DRIVER(name).

The device is probed to activate it ready for use.

Return

0 if OK, -ve on error

intuclass_get_device_by_endpoint(enumuclass_idclass_id, structudevice *dev, intport_idx, intep_idx, structudevice **target): Get a uclass device for a remote endpoint

Parameters

enum uclass_id class_id: uclass ID to look up
struct udevice *dev: Device to start from
int port_idx: Index of the port to follow, -1 if there is a single ‘port’ node without reg.
int ep_idx: Index of the endpoint to follow, -1 if there is a single ‘endpoint’ node without reg.
struct udevice **target: Returns pointer to the first device matching the expected uclass.

Description

This searches through the parents of the specified remote endpoint for the first device matching the uclass. Said otherwise, this helper goes through the graph (endpoint) representation and searches for matching devices. Endpoints can be subnodes of the "port" node or subnodes of ports identified with a reg property, themselves in a "ports" container.

The device is probed to activate it ready for use.

Return

0 if OK, -ve on error

voiduclass_first_device(enumuclass_idid, structudevice **devp): Get the first device in a uclass

Parameters

enum uclass_id id: Uclass ID to look up
struct udevice **devp: Returns pointer to the first device in that uclass if no error occurred, or NULL if there is no usable device

Description

The device returned is probed if necessary, and ready for use Devices that fail to probe are skipped

This function is useful to start iterating through a list of devices which are functioning correctly and can be probed.

voiduclass_next_device(structudevice **devp): Get the next device in a uclass

Parameters

struct udevice **devp: On entry, pointer to device to lookup. On exit, returns pointer to the next device in the uclass if no error occurred, or NULL if there is no next device

Description

The device returned is probed if necessary, and ready for use Devices that fail to probe are skipped

This function is useful to iterate through a list of devices which are functioning correctly and can be probed.

intuclass_first_device_err(enumuclass_idid, structudevice **devp): Get the first device in a uclass

Parameters

enum uclass_id id: Uclass ID to look up
struct udevice **devp: Returns pointer to the first device in that uclass, or NULL if none

Description

The device returned is probed if necessary, and ready for use if no error is returned

Return

0 if found, -ENODEV if not found, other -ve on error

intuclass_next_device_err(structudevice **devp): Get the next device in a uclass

Parameters

struct udevice **devp: On entry, pointer to device to lookup. On exit, returns pointer to the next device in the uclass if no error occurred, or NULL if there is no next device.

Description

The device returned is probed if necessary, and ready for use if no error is returned

Return

0 if found, -ENODEV if not found, other -ve on error

intuclass_first_device_check(enumuclass_idid, structudevice **devp): Get the first device in a uclass

Parameters

enum uclass_id id: Uclass ID to look up
struct udevice **devp: Returns pointer to the first device in that uclass, or NULL if there is no first device

Description

The device returned is probed if necessary, and ready for use if no error is returned

This function is useful to start iterating through a list of devices which are functioning correctly and can be probed.

Return

0 if OK (found or not found), other -ve on error. If an error occurs it is still possible to move to the next device.

intuclass_next_device_check(structudevice **devp): Get the next device in a uclass

Parameters

struct udevice **devp: On entry, pointer to device to lookup. On exit, returns pointer to the next device in the uclass if any

Description

The device returned is probed if necessary, and ready for use if no error is returned

This function is useful to start iterating through a list of devices which are functioning correctly and can be probed.

Return

0 if OK (found or not found), other -ve on error. If an error occurs it is still possible to move to the next device.

intuclass_first_device_drvdata(enumuclass_idid, ulongdriver_data, structudevice **devp): Find the first device with given driver data

Parameters

enum uclass_id id: Uclass ID to check
ulong driver_data: Driver data to search for
struct udevice **devp: Returns pointer to the first matching device in that uclass, if found

Description

This searches through the devices for a particular uclass looking for one that has the given driver data.

Return

0 if found, -ENODEV if not found, other -ve on error

structudevice *uclass_try_first_device(enumuclass_idid): See if there is a device for a uclass

Parameters

enum uclass_id id: Uclass ID to check

Description

If the uclass exists, this returns the first device on that uclass, without probing it. If the uclass does not exist, it gives up

Return

Pointer to device, if found, else NULL

intuclass_probe_all(enumuclass_idid): Probe all devices based on an uclass ID

Parameters

enum uclass_id id: uclass ID to look up

Description

This function probes all devices associated with a uclass by looking for its ID.

Return

0 if OK, other -ve on error

intuclass_id_count(enumuclass_idid): Count the number of devices in a uclass

Parameters

enum uclass_id id: uclass ID to look up

Return

number of devices in that uclass (0 if none)

uclass_id_foreach_dev

uclass_id_foreach_dev (id, pos, uc)

iterate through devices of a given uclass ID

Parameters

id: enum uclass_id ID to use
pos: struct udevice * to hold the current device. Set to NULL when there are no more devices.
uc: temporary uclass variable (struct uclass *)

Description

This creates a for() loop which works through the available devices in a uclass ID in order from start to end.

If for some reason the uclass cannot be found, this does nothing.

uclass_foreach_dev

uclass_foreach_dev (pos, uc)

iterate through devices of a given uclass

Parameters

pos: struct udevice * to hold the current device. Set to NULL when there are no more devices.
uc: uclass to scan (struct uclass *)

Description

This creates a for() loop which works through the available devices in a uclass in order from start to end.

uclass_foreach_dev_safe

uclass_foreach_dev_safe (pos, next, uc)

safely iterate through devices of a given uclass

Parameters

pos: struct udevice * to hold the current device. Set to NULL when there are no more devices.
next: struct udevice * to hold the next next
uc: uclass to scan (struct uclass *)

Description

This creates a for() loop which works through the available devices in a uclass in order from start to end. Inside the loop, it is safe to remove pos if required.

uclass_foreach_dev_probe

uclass_foreach_dev_probe (id, dev)

iterate through devices of a given uclass ID

Parameters

id: Uclass ID
dev: struct udevice * to hold the current device. Set to NULL when there are no more devices.

Description

This creates a for() loop which works through the available devices in a uclass in order from start to end. Devices are probed if necessary, and ready for use.

structdm_stats: Information about driver model memory usage

Definition

struct dm_stats {
 int total_size;
 int dev_count;
 int dev_size;
 int dev_name_size;
 int uc_count;
 int uc_size;
 int tag_count;
 int tag_size;
 int uc_attach_count;
 int uc_attach_size;
 int attach_count_total;
 int attach_size_total;
 int attach_count[DM_TAG_ATTACH_COUNT];
 int attach_size[DM_TAG_ATTACH_COUNT];
};

Members

total_size: All data
dev_count: Number of devices
dev_size: Size of all devices (just the struct udevice)
dev_name_size: Bytes used by device names
uc_count: Number of uclasses
uc_size: Size of all uclasses (just the struct uclass)
tag_count: Number of tags
tag_size: Bytes used by all tags
uc_attach_count: Number of uclasses with attached data (priv)
uc_attach_size: Total size of that attached data
attach_count_total: Total number of attached data items for all udevices and uclasses
attach_size_total: Total number of bytes of attached data
attach_count: Number of devices with attached, for each type
attach_size: Total number of bytes of attached data, for each type

structudevice *dm_root(void): Return pointer to the top of the driver tree

Parameters

void: no arguments

Description

This function returns pointer to the root node of the driver tree,

Return

pointer to root device, or NULL if not inited yet

voiddm_fixup_for_gd_move(structglobal_data *new_gd): Handle global_data moving to a new place

Parameters

struct global_data *new_gd: Pointer to the new global data

Description

The uclass list is part of global_data. Due to the way lists work, moving the list will cause it to become invalid. This function fixes that up so that the uclass list will work correctly.

intdm_scan_plat(boolpre_reloc_only): Scan all platform data and bind drivers

Parameters

bool pre_reloc_only: If true, bind only drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.

Description

This scans all available plat and creates drivers for each

Return

0 if OK, -ve on error

intdm_scan_fdt(boolpre_reloc_only): Scan the device tree and bind drivers

Parameters

bool pre_reloc_only: If true, bind only nodes with special devicetree properties, or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.

Description

This scans the device tree and creates a driver for each node. Only the top-level subnodes are examined.

Return

0 if OK, -ve on error

intdm_extended_scan(boolpre_reloc_only): Scan the device tree and bind drivers

Parameters

bool pre_reloc_only: If true, bind only nodes with special devicetree properties, or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.

Description

This calls dm_scna_dft() which scans the device tree and creates a driver for each node. the top-level subnodes are examined and also all sub-nodes of "clocks" node.

Return

0 if OK, -ve on error

intdm_scan_other(boolpre_reloc_only): Scan for other devices

Parameters

bool pre_reloc_only: If true, bind only nodes with special devicetree properties, or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.

Description

Some devices may not be visible to Driver Model. This weak function can be provided by boards which wish to create their own devices programmaticaly. They should do this by calling device_bind() on each device.

Return

0 if OK, -ve on error

intdm_init_and_scan(boolpre_reloc_only): Initialise Driver Model structures and scan for devices

Parameters

bool pre_reloc_only: If true, bind only nodes with special devicetree properties, or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.

Description

This function initialises the roots of the driver tree and uclass trees, then scans and binds available devices from platform data and the FDT. This calls dm_init() to set up Driver Model structures.

Return

0 if OK, -ve on error

intdm_autoprobe(void): Probe devices which are marked for probe-after-bind

Parameters

void: no arguments

Description

This probes all devices with a DM_FLAG_PROBE_AFTER_BIND flag. It checks the entire tree, so parent nodes need not have the flag set.

It recursively probes parent nodes, so they do not need to have the flag set themselves. Since parents are always probed before children, if a child has the flag set, then its parent (and any devices up the chain to the root device) will be probed too.

Return

0 if OK, -ve on error

intdm_init(boolof_live): Initialise Driver Model structures

Parameters

bool of_live: Enable live device tree

Description

This function will initialize roots of driver tree and class tree. This needs to be called before anything uses the DM

Return

0 if OK, -ve on error

intdm_uninit(void): Uninitialise Driver Model structures

Parameters

void: no arguments

Description

All devices will be removed and unbound

Return

0 if OK, -ve on error

intdm_remove_devices_flags(uintflags): Call remove function of all drivers with specific removal flags set to selectively remove drivers

Parameters

uint flags: Flags for selective device removal

Description

All devices with the matching flags set will be removed

Return

0 if OK, -ve on error

voiddm_remove_devices_active(void): Call remove function of all active drivers heeding device dependencies as far as know, i.e. removing devices marked with DM_FLAG_VITAL last.

Parameters

void: no arguments

Description

All active devices will be removed

voiddm_get_stats(int*device_countp, int*uclass_countp): Get some stats for driver mode

Parameters

int *device_countp: Returns total number of devices that are bound
int *uclass_countp: Returns total number of uclasses in use

voiddm_get_mem(structdm_stats *stats): Get stats on memory usage in driver model

Parameters

struct dm_stats *stats: Place to put the information

structdriver *lists_driver_lookup_name(constchar*name): Return u_boot_driver corresponding to name

Parameters

const char *name: Name of driver to look up

Description

This function returns a pointer to a driver given its name. This is used for binding a driver given its name and plat.

Return

pointer to driver, or NULL if not found

structuclass_driver *lists_uclass_lookup(enumuclass_idid): Return uclass_driver based on ID of the class

Parameters

enum uclass_id id: ID of the class

Description

This function returns the pointer to uclass_driver, which is the class’s base structure based on the ID of the class. Returns NULL on error.

intlists_bind_drivers(structudevice *parent, boolpre_reloc_only): search for and bind all drivers to parent

Parameters

struct udevice *parent: parent device (root)
bool pre_reloc_only: If true, bind only drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.

Description

This searches the U_BOOT_DRVINFO() structures and creates new devices for each one. The devices will have parent as their parent.

intlists_bind_fdt(structudevice *parent, ofnodenode, structudevice **devp, structdriver *drv, boolpre_reloc_only): bind a device tree node

Parameters

struct udevice *parent: parent device (root)
ofnode node: device tree node to bind
struct udevice **devp: if non-NULL, returns a pointer to the bound device
struct driver *drv: if non-NULL, force this driver to be bound
bool pre_reloc_only: If true, bind only nodes with special devicetree properties, or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.

Description

This creates a new device bound to the given device tree node, with parent as its parent.

Return

0 if device was bound, -EINVAL if the device tree is invalid, other -ve value on error

intdevice_bind_driver(structudevice *parent, constchar*drv_name, constchar*dev_name, structudevice **devp): bind a device to a driver

Parameters

struct udevice *parent: Parent device
const char *drv_name: Name of driver to attach to this parent
const char *dev_name: Name of the new device thus created
struct udevice **devp: If non-NULL, returns the newly bound device

Description

This binds a new device to a driver.

Return

0 if OK, -ve on error

intdevice_bind_driver_to_node(structudevice *parent, constchar*drv_name, constchar*dev_name, ofnodenode, structudevice **devp): bind a device to a driver for a node

Parameters

struct udevice *parent: Parent device
const char *drv_name: Name of driver to attach to this parent
const char *dev_name: Name of the new device thus created
ofnode node: Device tree node
struct udevice **devp: If non-NULL, returns the newly bound device

Description

This binds a new device to a driver for a given device tree node. This should only be needed if the node lacks a compatible strings.

Return

0 if OK, -ve on error

structdriver_info: Information required to instantiate a device

Definition

struct driver_info {
 const char *name;
 const void *plat;
#if CONFIG_IS_ENABLED(OF_PLATDATA);
 unsigned short plat_size;
 short parent_idx;
#endif;
};

Members

name: Driver name
plat: Driver-specific platform data
plat_size: Size of platform data structure
parent_idx: Index of the parent driver_info structure

NOTE

Avoid using this except in extreme circumstances, where device tree is not feasible (e.g. serial driver in SPL where <8KB of SRAM is available). U-Boot’s driver model uses device tree for configuration.

structdriver_rt: runtime information set up by U-Boot

Definition

struct driver_rt {
 struct udevice *dev;
};

Members

dev: Device created from this idx

Description

There is one of these for every driver_info in the linker list, indexed by the driver_info idx value.

Device

structudevice: An instance of a driver

Definition

struct udevice {
 const struct driver *driver;
 const char *name;
 void *plat_;
 void *parent_plat_;
 void *uclass_plat_;
 ulong driver_data;
 struct udevice *parent;
 void *priv_;
 struct uclass *uclass;
 void *uclass_priv_;
 void *parent_priv_;
 struct list_head uclass_node;
 struct list_head child_head;
 struct list_head sibling_node;
#if !CONFIG_IS_ENABLED(OF_PLATDATA_RT);
 u32 flags_;
#endif;
 int seq_;
#if CONFIG_IS_ENABLED(OF_REAL);
 ofnode node_;
#endif;
#if CONFIG_IS_ENABLED(DEVRES);
 struct list_head devres_head;
#endif;
#if CONFIG_IS_ENABLED(DM_DMA);
 ulong dma_offset;
#endif;
#if CONFIG_IS_ENABLED(IOMMU);
 struct udevice *iommu;
#endif;
};

Members

driver: The driver used by this device
name: Name of device, typically the FDT node name
plat_: Configuration data for this device (do not access outside driver model)
parent_plat_: The parent bus’s configuration data for this device (do not access outside driver model)
uclass_plat_: The uclass’s configuration data for this device (do not access outside driver model)
driver_data: Driver data word for the entry that matched this device with its driver
parent: Parent of this device, or NULL for the top level device
priv_: Private data for this device (do not access outside driver model)
uclass: Pointer to uclass for this device
uclass_priv_: The uclass’s private data for this device (do not access outside driver model)
parent_priv_: The parent’s private data for this device (do not access outside driver model)
uclass_node: Used by uclass to link its devices
child_head: List of children of this device
sibling_node: Next device in list of all devices
flags_: Flags for this device DM_FLAG_... (do not access outside driver model)
seq_: Allocated sequence number for this device (-1 = none). This is set up when the device is bound and is unique within the device’s uclass. If the device has an alias in the devicetree then that is used to set the sequence number. Otherwise, the next available number is used. Sequence numbers are used by certain commands that need device to be numbered (e.g. ‘mmc dev’). (do not access outside driver model)
node_: Reference to device tree node for this device (do not access outside driver model)
devres_head: List of memory allocations associated with this device. When CONFIG_DEVRES is enabled, devm_kmalloc() and friends will add to this list. Memory so-allocated will be freed automatically when the device is removed / unbound
dma_offset: Offset between the physical address space (CPU’s) and the device’s bus address space
iommu: IOMMU device associated with this device

Description

This holds information about a device, which is a driver bound to a particular port or peripheral (essentially a driver instance).

A device will come into existence through a ‘bind’ call, either due to a U_BOOT_DRVINFO() macro (in which case plat is non-NULL) or a node in the device tree (in which case of_offset is >= 0). In the latter case we translate the device tree information into plat in a function implemented by the driver of_to_plat method (called just before the probe method if the device has a device tree node.

All three of plat, priv and uclass_priv can be allocated by the driver, or you can use the auto members of struct driver and struct uclass_driver to have driver model do this automatically.

structudevice_rt: runtime information set up by U-Boot

Definition

struct udevice_rt {
 u32 flags_;
};

Members

flags_: Flags for this device DM_FLAG_... (do not access outside driver model)

Description

This is only used with OF_PLATDATA_RT

There is one of these for every udevice in the linker list, indexed by the udevice_info idx value.

__attribute_const__ofnodedev_ofnode(conststructudevice *dev): get the DT node reference associated with a udevice

Parameters

const struct udevice *dev: device to check

Return

reference of the device’s DT node

structudevice_id: Lists the compatible strings supported by a driver

Definition

struct udevice_id {
 const char *compatible;
 ulong data;
};

Members

compatible: Compatible string
data: Data for this compatible string

structdriver: A driver for a feature or peripheral

Definition

struct driver {
 char *name;
 enum uclass_id id;
 const struct udevice_id *of_match;
 int (*bind)(struct udevice *dev);
 int (*probe)(struct udevice *dev);
 int (*remove)(struct udevice *dev);
 int (*unbind)(struct udevice *dev);
 int (*of_to_plat)(struct udevice *dev);
 int (*child_post_bind)(struct udevice *dev);
 int (*child_pre_probe)(struct udevice *dev);
 int (*child_post_remove)(struct udevice *dev);
 int priv_auto;
 int plat_auto;
 int per_child_auto;
 int per_child_plat_auto;
 const void *ops;
 uint32_t flags;
#if CONFIG_IS_ENABLED(ACPIGEN);
 struct acpi_ops *acpi_ops;
#endif;
};

Members

name: Device name
id: Identifies the uclass we belong to
of_match: List of compatible strings to match, and any identifying data for each.
bind: Called to bind a device to its driver
probe: Called to probe a device, i.e. activate it
remove: Called to remove a device, i.e. de-activate it
unbind: Called to unbind a device from its driver
of_to_plat: Called before probe to decode device tree data
child_post_bind: Called after a new child has been bound
child_pre_probe: Called before a child device is probed. The device has memory allocated but it has not yet been probed.
child_post_remove: Called after a child device is removed. The device has memory allocated but its device_remove() method has been called.
priv_auto: If non-zero this is the size of the private data to be allocated in the device’s ->priv pointer. If zero, then the driver is responsible for allocating any data required.
plat_auto: If non-zero this is the size of the platform data to be allocated in the device’s ->plat pointer. This is typically only useful for device-tree-aware drivers (those with an of_match), since drivers which use plat will have the data provided in the U_BOOT_DRVINFO() instantiation.
per_child_auto: Each device can hold private data owned by its parent. If required this will be automatically allocated if this value is non-zero.
per_child_plat_auto: A bus likes to store information about its children. If non-zero this is the size of this data, to be allocated in the child’s parent_plat pointer.
ops: Driver-specific operations. This is typically a list of function pointers defined by the driver, to implement driver functions required by the uclass.
flags: driver flags - see DM_FLAG_...
acpi_ops: Advanced Configuration and Power Interface (ACPI) operations, allowing the device to add things to the ACPI tables passed to Linux

Description

This holds methods for setting up a new device, and also removing it. The device needs information to set itself up - this is provided either by plat or a device tree node (which we find by looking up matching compatible strings with of_match).

Drivers all belong to a uclass, representing a class of devices of the same type. Common elements of the drivers can be implemented in the uclass, or the uclass can provide a consistent interface to the drivers within it.

U_BOOT_DRIVER

U_BOOT_DRIVER (__name)

Declare a new U-Boot driver

Parameters

__name: name of the driver

DM_DRIVER_GET

DM_DRIVER_GET (__name)

Get a pointer to a given driver

Parameters

__name: Name of the driver. This must be a valid C identifier, used by the linker_list

Description

This is useful in code for referencing a driver at build time. Before this is used, an extern U_BOOT_DRIVER() must have been declared.

Return

struct driver * for the driver

DM_DRIVER_REF

DM_DRIVER_REF (_name)

Get a reference to a driver

Parameters

_name: Name of the driver. This must be a valid C identifier, used by the linker_list

Description

This is useful in data structures and code for referencing a driver at build time. Before this is used, an extern U_BOOT_DRIVER() must have been declared. This is like DM_DRIVER_GET, but without the extra code, so it is suitable for putting into data structures.

For example:

extern U_BOOT_DRIVER(sandbox_fixed_clock);
struct driver *drvs[] = {
 DM_DRIVER_REF(sandbox_fixed_clock),
};

Return

struct driver * for the driver

DM_DRIVER_ALIAS

DM_DRIVER_ALIAS (__name, __alias)

Declare a macro to state an alias for a driver name

Parameters

__name: name of driver
__alias: alias for the driver name

Description

This macro will produce no code but its information will be parsed by tools like dtoc

DM_PHASE

DM_PHASE (_phase)

Declare a macro to indicate which phase of U-Boot this driver is for.

Parameters

_phase: Associated phase of U-Boot ("spl", "tpl")

Description

This macro produces no code but its information will be parsed by dtoc. The macro can be only be used once in a driver. Put it within the U_BOOT_DRIVER() declaration, e.g.:

U_BOOT_DRIVER(cpu) = {
 .name = ...
 ...
 DM_PHASE(tpl)
};

DM_HEADER

DM_HEADER (_hdr)

Declare a macro to declare a header needed for a driver.

Parameters

_hdr: header needed for a driver

Description

Often the correct header can be found automatically, but only for struct declarations. For enums and #defines used in the driver declaration and declared in a different header from the structs, this macro must be used.

This macro produces no code but its information will be parsed by dtoc. The macro can be used multiple times with different headers, for the same driver. Put it within the U_BOOT_DRIVER() declaration, e.g.:

U_BOOT_DRIVER(cpu) = {
 .name = ...
 ...
 DM_HEADER(<asm/cpu.h>)
};

void*dev_get_plat(conststructudevice *dev): Get the platform data for a device

Parameters

const struct udevice *dev: Device to check

Description

This checks that dev is not NULL, but no other checks for now

Return

platform data, or NULL if none

void*dev_get_parent_plat(conststructudevice *dev): Get the parent platform data for a device

Parameters

const struct udevice *dev: Device to check

Description

This checks that dev is not NULL, but no other checks for now

Return

parent’s platform data, or NULL if none

void*dev_get_uclass_plat(conststructudevice *dev): Get the uclass platform data for a device

Parameters

const struct udevice *dev: Device to check

Description

This checks that dev is not NULL, but no other checks for now

Return

uclass’s platform data, or NULL if none

void*dev_get_priv(conststructudevice *dev): Get the private data for a device

Parameters

const struct udevice *dev: Device to check

Description

This checks that dev is not NULL, but no other checks for now

Return

private data, or NULL if none

void*dev_get_parent_priv(conststructudevice *dev): Get the parent private data for a device

Parameters

const struct udevice *dev: Device to check

Description

The parent private data is data stored in the device but owned by the parent. For example, a USB device may have parent data which contains information about how to talk to the device over USB.

This checks that dev is not NULL, but no other checks for now

Return

parent data, or NULL if none

void*dev_get_uclass_priv(conststructudevice *dev): Get the private uclass data for a device

Parameters

const struct udevice *dev: Device to check

Description

This checks that dev is not NULL, but no other checks for now

Return

private uclass data for this device, or NULL if none

void*dev_get_attach_ptr(conststructudevice *dev, enumdm_tag_ttag): Get the value of an attached pointed tag

Parameters

const struct udevice *dev: Device to look at
enum dm_tag_t tag: Tag to access return value of tag, or NULL if there is no tag of this type

Description

The tag is assumed to hold a pointer, if it exists

intdev_get_attach_size(conststructudevice *dev, enumdm_tag_ttag): Get the size of an attached tag

Parameters

const struct udevice *dev: Device to look at
enum dm_tag_t tag: Tag to access return size of auto-allocated data, 0 if none

Description

Core tags have an automatic-allocation mechanism where the allocated size is defined by the device, parent or uclass. This returns the size associated with a particular tag

structudevice *dev_get_parent(conststructudevice *child): Get the parent of a device

Parameters

const struct udevice *child: Child to check

Return

parent of child, or NULL if this is the root device

ulongdev_get_driver_data(conststructudevice *dev): get the driver data used to bind a device

Parameters

const struct udevice *dev: Device to check

Description

When a device is bound using a device tree node, it matches a particular compatible string in struct udevice_id. This function returns the associated data value for that compatible string. This is the ‘data’ field in struct udevice_id.

As an example, consider this structure:

static const struct udevice_id tegra_i2c_ids[] = {
 { .compatible = "nvidia,tegra114-i2c", .data = TYPE_114 },
 { .compatible = "nvidia,tegra20-i2c", .data = TYPE_STD },
 { .compatible = "nvidia,tegra20-i2c-dvc", .data = TYPE_DVC },
 { }
};

When driver model finds a driver for this it will store the ‘data’ value corresponding to the compatible string it matches. This function returns that value. This allows the driver to handle several variants of a device.

For USB devices, this is the driver_info field in struct usb_device_id.

Return

driver data (0 if none is provided)

constvoid*dev_get_driver_ops(conststructudevice *dev): get the device’s driver’s operations

Parameters

const struct udevice *dev: Device to check

Description

This checks that dev is not NULL, and returns the pointer to device’s driver’s operations.

Return

void pointer to driver’s operations or NULL for NULL-dev or NULL-ops

enumuclass_iddevice_get_uclass_id(conststructudevice *dev): return the uclass ID of a device

Parameters

const struct udevice *dev: Device to check

Return

uclass ID for the device

constchar*dev_get_uclass_name(conststructudevice *dev): return the uclass name of a device

Parameters

const struct udevice *dev: Device to check

Description

This checks that dev is not NULL.

Return

pointer to the uclass name for the device

intdevice_get_child(conststructudevice *parent, intindex, structudevice **devp): Get the child of a device by index

Parameters

const struct udevice *parent: Parent device to check
int index: Child index
struct udevice **devp: Returns pointer to device

Description

Returns the numbered child, 0 being the first. This does not use sequence numbers, only the natural order.

Return

0 if OK, -ENODEV if no such device, other error if the device fails to probe

intdevice_get_child_count(conststructudevice *parent): Get the child count of a device

Parameters

const struct udevice *parent: Parent device to check

Description

Returns the number of children to a device.

intdevice_get_decendent_count(conststructudevice *parent): Get the total number of decendents of a device

Parameters

const struct udevice *parent: Parent device to check

Description

Returns the total number of decendents, including all children

intdevice_find_child_by_seq(conststructudevice *parent, intseq, structudevice **devp): Find a child device based on a sequence

Parameters

const struct udevice *parent: Parent device
int seq: Sequence number to find (0=first)
struct udevice **devp: Returns pointer to device (there is only one per for each seq). Set to NULL if none is found

Description

This searches for a device with the given seq.

Return

0 if OK, -ENODEV if not found

intdevice_get_child_by_seq(conststructudevice *parent, intseq, structudevice **devp): Get a child device based on a sequence

Parameters

const struct udevice *parent: Parent device
int seq: Sequence number to find (0=first)
struct udevice **devp: Returns pointer to device (there is only one per for each seq) Set to NULL if none is found

Description

If an active device has this sequence it will be returned. If there is no such device then this will check for a device that is requesting this sequence.

The device is probed to activate it ready for use.

Return

0 if OK, -ve on error

intdevice_find_child_by_of_offset(conststructudevice *parent, intof_offset, structudevice **devp): Find a child device based on FDT offset

Parameters

const struct udevice *parent: Parent device
int of_offset: Device tree offset to find
struct udevice **devp: Returns pointer to device if found, otherwise this is set to NULL

Description

Locates a child device by its device tree offset.

Return

0 if OK, -ve on error

intdevice_get_child_by_of_offset(conststructudevice *parent, intof_offset, structudevice **devp): Get a child device based on FDT offset

Parameters

const struct udevice *parent: Parent device
int of_offset: Device tree offset to find
struct udevice **devp: Returns pointer to device if found, otherwise this is set to NULL

Description

Locates a child device by its device tree offset.

The device is probed to activate it ready for use.

Return

0 if OK, -ve on error

intdevice_find_global_by_ofnode(ofnodenode, structudevice **devp): Get a device based on ofnode

Parameters

ofnode node: Device tree ofnode to find
struct udevice **devp: Returns pointer to device if found, otherwise this is set to NULL

Description

Locates a device by its device tree ofnode, searching globally throughout the all driver model devices.

The device is NOT probed

Return

0 if OK, -ve on error

intdevice_get_global_by_ofnode(ofnodenode, structudevice **devp): Get a device based on ofnode

Parameters

ofnode node: Device tree ofnode to find
struct udevice **devp: Returns pointer to device if found, otherwise this is set to NULL

Description

Locates a device by its device tree ofnode, searching globally throughout the all driver model devices.

The device is probed to activate it ready for use.

Return

0 if OK, -ve on error

intdevice_get_by_ofplat_idx(uintidx, structudevice **devp): Get a device based on of-platdata index

Parameters

uint idx: Index number of the driver_info/udevice structure (0=first)
struct udevice **devp: Returns pointer to device if found, otherwise this is set to NULL

Description

Locates a device by either its struct driver_info index, or its struct udevice index. The latter is used with OF_PLATDATA_INST, since we have a list of build-time instantiated struct udevice records, The former is used with !OF_PLATDATA_INST since in that case we have a list of struct driver_info records.

The index number is written into the idx field of struct phandle_1_arg, etc. It is the position of this driver_info/udevice in its linker list.

The device is probed to activate it ready for use.

Return

0 if OK, -ve on error

intdevice_find_first_child(conststructudevice *parent, structudevice **devp): Find the first child of a device

Parameters

const struct udevice *parent: Parent device to search
struct udevice **devp: Returns first child device, or NULL if none

Return

intdevice_find_next_child(structudevice **devp): Find the next child of a device

Parameters

struct udevice **devp: Pointer to previous child device on entry. Returns pointer to next child device, or NULL if none

Return

intdevice_find_first_inactive_child(conststructudevice *parent, enumuclass_id uclass_id, structudevice **devp): Find the first inactive child

Parameters

const struct udevice *parent: Parent device to search
enum uclass_id uclass_id: Uclass to look for
struct udevice **devp: Returns device found, if any, else NULL

Description

This is used to locate an existing child of a device which is of a given uclass.

The device is NOT probed

Return

0 if found, else -ENODEV

intdevice_find_first_child_by_uclass(conststructudevice *parent, enumuclass_id uclass_id, structudevice **devp): Find the first child of a device in uc

Parameters

const struct udevice *parent: Parent device to search
enum uclass_id uclass_id: Uclass to look for
struct udevice **devp: Returns first child device in that uclass, if any, else NULL

Return

0 if found, else -ENODEV

intdevice_find_child_by_namelen(conststructudevice *parent, constchar*name, intlen, structudevice **devp): Find a child by device name

Parameters

const struct udevice *parent: Parent device to search
const char *name: Name to look for
int len: Length of the name
struct udevice **devp: Returns device found, if any

Return

0 if found, else -ENODEV

intdevice_find_child_by_name(conststructudevice *parent, constchar*name, structudevice **devp): Find a child by device name

Parameters

const struct udevice *parent: Parent device to search
const char *name: Name to look for
struct udevice **devp: Returns device found, if any

Return

0 if found, else -ENODEV

intdevice_first_child_ofdata_err(structudevice *parent, structudevice **devp): Find the first child and reads its plat

Parameters

struct udevice *parent: Parent to check
struct udevice **devp: Returns child that was found, if any

Description

The of_to_plat() method is called on the child before it is returned, but the child is not probed.

Return

0 on success, -ENODEV if no children, other -ve on error

intdevice_first_child_err(structudevice *parent, structudevice **devp): Get the first child of a device

Parameters

struct udevice *parent: Parent device to search
struct udevice **devp: Returns device found, if any

Description

The device returned is probed if necessary, and ready for use

Return

0 if found, -ENODEV if not, -ve error if device failed to probe

intdevice_next_child_err(structudevice **devp): Get the next child of a parent device

Parameters

struct udevice **devp: On entry, pointer to device to lookup. On exit, returns pointer to the next sibling if no error occurred

Description

The device returned is probed if necessary, and ready for use

Return

0 if found, -ENODEV if not, -ve error if device failed to probe

booldevice_has_children(conststructudevice *dev): check if a device has any children

Parameters

const struct udevice *dev: Device to check

Return

true if the device has one or more children

booldevice_has_active_children(conststructudevice *dev): check if a device has any active children

Parameters

const struct udevice *dev: Device to check

Return

true if the device has one or more children and at least one of them is active (probed).

booldevice_is_last_sibling(conststructudevice *dev): check if a device is the last sibling

Parameters

const struct udevice *dev: Device to check

Description

This function can be useful for display purposes, when special action needs to be taken when displaying the last sibling. This can happen when a tree view of devices is being displayed.

Return

true if there are no more siblings after this one - i.e. is it last in the list.

intdevice_set_name(structudevice *dev, constchar*name): set the name of a device

Parameters

struct udevice *dev: Device to update
const char *name: New name (this string is allocated new memory and attached to the device)

Description

This must be called in the device’s bind() method and no later. Normally this is unnecessary but for probed devices which don’t get a useful name this function can be helpful.

The name is allocated and will be freed automatically when the device is unbound.

Return

0 if OK, -ENOMEM if there is not enough memory to allocate the string

voiddevice_set_name_alloced(structudevice *dev): note that a device name is allocated

Parameters

struct udevice *dev: Device to update

Description

This sets the DM_FLAG_NAME_ALLOCED flag for the device, so that when it is unbound the name will be freed. This avoids memory leaks.

booldevice_is_compatible(conststructudevice *dev, constchar*compat): check if the device is compatible with the compat

Parameters

const struct udevice *dev: udevice pointer for which compatible needs to be verified.
const char *compat: Compatible string which needs to verified in the given device

Description

This allows to check whether the device is comaptible with the compat.

Return

true if OK, false if the compatible is not found

boolof_machine_is_compatible(constchar*compat): check if the machine is compatible with the compat

Parameters

const char *compat: Compatible string which needs to verified

Description

This allows to check whether the machine is comaptible with the compat.

Return

true if OK, false if the compatible is not found

intdev_disable_by_path(constchar*path): Disable a device given its device tree path

Parameters

const char *path: The device tree path identifying the device to be disabled

Return

0 on success, -ve on error

intdev_enable_by_path(constchar*path): Enable a device given its device tree path

Parameters

const char *path: The device tree path identifying the device to be enabled

Return

0 on success, -ve on error

booldevice_is_on_pci_bus(conststructudevice *dev): Test if a device is on a PCI bus

Parameters

const struct udevice *dev: device to test

Return

true if it is on a PCI bus, false otherwise

device_foreach_child_safe

device_foreach_child_safe (pos, next, parent)

iterate through child devices safely

Parameters

pos: struct udevice * for the current device
next: struct udevice * for the next device
parent: parent device to scan

Description

This allows the pos child to be removed in the loop if required.

device_foreach_child

device_foreach_child (pos, parent)

iterate through child devices

Parameters

pos: struct udevice * for the current device
parent: parent device to scan

device_foreach_child_of_to_plat

device_foreach_child_of_to_plat (pos, parent)

iterate through children

Parameters

pos: struct udevice * for the current device
parent: parent device to scan

Description

This stops when it gets an error, with pos set to the device that failed to read ofdata.

This creates a for() loop which works through the available children of a device in order from start to end. Device ofdata is read by calling device_of_to_plat() on each one. The devices are not probed.

device_foreach_child_probe

device_foreach_child_probe (pos, parent)

iterate through children, probing them

Parameters

pos: struct udevice * for the current device
parent: parent device to scan

Description

This creates a for() loop which works through the available children of a device in order from start to end. Devices are probed if necessary, and ready for use.

This stops when it gets an error, with pos set to the device that failed to probe

intdm_scan_fdt_dev(structudevice *dev): Bind child device in the device tree

Parameters

struct udevice *dev: Device to scan

Description

This handles device which have sub-nodes in the device tree. It scans all sub-nodes and binds drivers for each node where a driver can be found.

If this is called prior to relocation, only pre-relocation devices will be bound (those marked with bootph-all in the device tree, or where the driver has the DM_FLAG_PRE_RELOC flag set). Otherwise, all devices will be bound.

Return

0 if OK, -ve on error

structdevres_stats: Information about devres allocations for a device

Definition

struct devres_stats {
 int allocs;
 int total_size;
};

Members

allocs: Number of allocations
total_size: Total size of allocations in bytes

devres_alloc

devres_alloc (release, size, gfp)

Allocate device resource data

Parameters

release: Release function devres will be associated with
size: Allocation size
gfp: Allocation flags

Description

Allocate devres of size bytes. The allocated area is associated with release. The returned pointer can be passed to other devres_*() functions.

Return

Pointer to allocated devres on success, NULL on failure.

voiddevres_free(void*res): Free device resource data

Parameters

void *res: Pointer to devres data to free

Description

Free devres created with devres_alloc().

voiddevres_add(structudevice *dev, void*res): Register device resource

Parameters

struct udevice *dev: Device to add resource to
void *res: Resource to register

Description

Register devres res to dev. res should have been allocated using devres_alloc(). On driver detach, the associated release function will be invoked and devres will be freed automatically.

void*devres_find(structudevice *dev, dr_release_trelease, dr_match_tmatch, void*match_data): Find device resource

Parameters

struct udevice *dev: Device to lookup resource from
dr_release_t release: Look for resources associated with this release function
dr_match_t match: Match function (optional)
void *match_data: Data for the match function

Description

Find the latest devres of dev which is associated with release and for which match returns 1. If match is NULL, it’s considered to match all.

Return

pointer to found devres, NULL if not found.

void*devres_get(structudevice *dev, void*new_res, dr_match_tmatch, void*match_data): Find devres, if non-existent, add one atomically

Parameters

struct udevice *dev: Device to lookup or add devres for
void *new_res: Pointer to new initialized devres to add if not found
dr_match_t match: Match function (optional)
void *match_data: Data for the match function

Description

Find the latest devres of dev which has the same release function as new_res and for which match return 1. If found, new_res is freed; otherwise, new_res is added atomically.

Return

pointer to found or added devres.

void*devres_remove(structudevice *dev, dr_release_trelease, dr_match_tmatch, void*match_data): Find a device resource and remove it

Parameters

struct udevice *dev: Device to find resource from
dr_release_t release: Look for resources associated with this release function
dr_match_t match: Match function (optional)
void *match_data: Data for the match function

Description

Find the latest devres of dev associated with release and for which match returns 1. If match is NULL, it’s considered to match all. If found, the resource is removed atomically and returned.

Return

pointer to removed devres on success, NULL if not found.

intdevres_destroy(structudevice *dev, dr_release_trelease, dr_match_tmatch, void*match_data): Find a device resource and destroy it

Parameters

struct udevice *dev: Device to find resource from
dr_release_t release: Look for resources associated with this release function
dr_match_t match: Match function (optional)
void *match_data: Data for the match function

Description

Note that the release function for the resource will not be called, only the devres-allocated data will be freed. The caller becomes responsible for freeing any other data.

Return

0 if devres is found and freed, -ENOENT if not found.

intdevres_release(structudevice *dev, dr_release_trelease, dr_match_tmatch, void*match_data): Find a device resource and destroy it, calling release

Parameters

struct udevice *dev: Device to find resource from
dr_release_t release: Look for resources associated with this release function
dr_match_t match: Match function (optional)
void *match_data: Data for the match function

Description

Return

0 if devres is found and freed, -ENOENT if not found.

void*devm_kmalloc(structudevice *dev, size_tsize, gfp_tgfp): Resource-managed kmalloc

Parameters

struct udevice *dev: Device to allocate memory for
size_t size: Allocation size
gfp_t gfp: Allocation gfp flags

Description

Managed kmalloc. Memory allocated with this function is automatically freed on driver detach. Like all other devres resources, guaranteed alignment is unsigned long long.

Return

pointer to allocated memory on success, NULL on failure.

voiddevm_kfree(structudevice *dev, void*ptr): Resource-managed kfree

Parameters

struct udevice *dev: Device this memory belongs to
void *ptr: Memory to free

Description

Free memory allocated with devm_kmalloc().

intdev_read_u8(conststructudevice *dev, constchar*propname, u8*outp): read a 8-bit integer from a device’s DT property

Parameters

const struct udevice *dev: device to read DT property from
const char *propname: name of the property to read from
u8 *outp: place to put value (if found)

Return

0 if OK, -ve on error

u8dev_read_u8_default(conststructudevice *dev, constchar*propname, u8def): read a 8-bit integer from a device’s DT property

Parameters

const struct udevice *dev: device to read DT property from
const char *propname: name of the property to read from
u8 def: default value to return if the property has no value

Return

property value, or def if not found

intdev_read_u16(conststructudevice *dev, constchar*propname, u16*outp): read a 16-bit integer from a device’s DT property

Parameters

const struct udevice *dev: device to read DT property from
const char *propname: name of the property to read from
u16 *outp: place to put value (if found)

Return

0 if OK, -ve on error

u16dev_read_u16_default(conststructudevice *dev, constchar*propname, u16def): read a 16-bit integer from a device’s DT property

Parameters

const struct udevice *dev: device to read DT property from
const char *propname: name of the property to read from
u16 def: default value to return if the property has no value

Return

property value, or def if not found

intdev_read_u32(conststructudevice *dev, constchar*propname, u32*outp): read a 32-bit integer from a device’s DT property

Parameters

const struct udevice *dev: device to read DT property from
const char *propname: name of the property to read from
u32 *outp: place to put value (if found)

Return

0 if OK, -ve on error

intdev_read_u32_default(conststructudevice *dev, constchar*propname, intdef): read a 32-bit integer from a device’s DT property

Parameters

const struct udevice *dev: device to read DT property from
const char *propname: name of the property to read from
int def: default value to return if the property has no value

Return

property value, or def if not found

intdev_read_u32_index(structudevice *dev, constchar*propname, intindex, u32*outp): read an indexed 32-bit integer from a device’s DT property

Parameters

struct udevice *dev: device to read DT property from
const char *propname: name of the property to read from
int index: index of the integer to return
u32 *outp: place to put value (if found)

Return

0 if OK, -ve on error

u32dev_read_u32_index_default(structudevice *dev, constchar*propname, intindex, u32def): read an indexed 32-bit integer from a device’s DT property

Parameters

struct udevice *dev: device to read DT property from
const char *propname: name of the property to read from
int index: index of the integer to return
u32 def: default value to return if the property has no value

Return

property value, or def if not found

intdev_read_s32(conststructudevice *dev, constchar*propname, s32*outp): read a signed 32-bit integer from a device’s DT property

Parameters

const struct udevice *dev: device to read DT property from
const char *propname: name of the property to read from
s32 *outp: place to put value (if found)

Return

0 if OK, -ve on error

intdev_read_s32_default(conststructudevice *dev, constchar*propname, intdef): read a signed 32-bit int from a device’s DT property

Parameters

const struct udevice *dev: device to read DT property from
const char *propname: name of the property to read from
int def: default value to return if the property has no value

Return

property value, or def if not found

intdev_read_u32u(conststructudevice *dev, constchar*propname, uint*outp): read a 32-bit integer from a device’s DT property

Parameters

const struct udevice *dev: device to read DT property from
const char *propname: name of the property to read from
uint *outp: place to put value (if found)

Description

This version uses a standard uint type.

Return

0 if OK, -ve on error

intdev_read_u64(conststructudevice *dev, constchar*propname, u64*outp): read a 64-bit integer from a device’s DT property

Parameters

const struct udevice *dev: device to read DT property from
const char *propname: name of the property to read from
u64 *outp: place to put value (if found)

Return

0 if OK, -ve on error

u64dev_read_u64_default(conststructudevice *dev, constchar*propname, u64def): read a 64-bit integer from a device’s DT property

Parameters

const struct udevice *dev: device to read DT property from
const char *propname: name of the property to read from
u64 def: default value to return if the property has no value

Return

property value, or def if not found

constchar*dev_read_string(conststructudevice *dev, constchar*propname): Read a string from a device’s DT property

Parameters

const struct udevice *dev: device to read DT property from
const char *propname: name of the property to read

Return

string from property value, or NULL if there is no such property

booldev_read_bool(conststructudevice *dev, constchar*propname): read a boolean value from a device’s DT property

Parameters

const struct udevice *dev: device to read DT property from
const char *propname: name of property to read

Return

true if property is present (meaning true), false if not present

ofnodedev_read_subnode(conststructudevice *dev, constchar*subnode_name): find a named subnode of a device

Parameters

const struct udevice *dev: device whose DT node contains the subnode
const char *subnode_name: name of subnode to find

Return

reference to subnode (which can be invalid if there is no such subnode)

intdev_read_size(conststructudevice *dev, constchar*propname): read the size of a property

Parameters

const struct udevice *dev: device to check
const char *propname: property to check

Return

size of property if present, or -EINVAL if not

fdt_addr_tdev_read_addr_index(conststructudevice *dev, intindex): Get the indexed reg property of a device

Parameters

const struct udevice *dev: Device to read from
int index: the ‘reg’ property can hold a list of <addr, size> pairs and index is used to select which one is required

Return

address or FDT_ADDR_T_NONE if not found

void*dev_read_addr_index_ptr(conststructudevice *dev, intindex): Get the indexed reg property of a device as a pointer

Parameters

const struct udevice *dev: Device to read from
int index: the ‘reg’ property can hold a list of <addr, size> pairs and index is used to select which one is required

Return

pointer or NULL if not found

fdt_addr_tdev_read_addr_size_index(conststructudevice *dev, intindex, fdt_size_t*size): Get the indexed reg property of a device

Parameters

const struct udevice *dev: Device to read from
int index: the ‘reg’ property can hold a list of <addr, size> pairs and index is used to select which one is required
fdt_size_t *size: place to put size value (on success)

Return

address or FDT_ADDR_T_NONE if not found

void*dev_read_addr_size_index_ptr(conststructudevice *dev, intindex, fdt_size_t*size): Get the indexed reg property of a device as a pointer

Parameters

const struct udevice *dev: Device to read from
int index: the ‘reg’ property can hold a list of <addr, size> pairs and index is used to select which one is required
fdt_size_t *size: place to put size value (on success)

Return

pointer or NULL if not found

void*dev_remap_addr_index(conststructudevice *dev, intindex): Get the indexed reg property of a device as a memory-mapped I/O pointer

Parameters

const struct udevice *dev: Device to read from
int index: the ‘reg’ property can hold a list of <addr, size> pairs and index is used to select which one is required

Return

pointer or NULL if not found

fdt_addr_tdev_read_addr_name(conststructudevice *dev, constchar*name): Get the reg property of a device, indexed by name

Parameters

const struct udevice *dev: Device to read from
const char *name: the ‘reg’ property can hold a list of <addr, size> pairs, with the ‘reg-names’ property providing named-based identification. name indicates the value to search for in ‘reg-names’.

Return

address or FDT_ADDR_T_NONE if not found

void*dev_read_addr_name_ptr(conststructudevice *dev, constchar*name): Get the reg property of a device as a pointer, indexed by name

Parameters

const struct udevice *dev: Device to read from
const char *name: the ‘reg’ property can hold a list of <addr, size> pairs, with the ‘reg-names’ property providing named-based identification. name indicates the value to search for in ‘reg-names’.

Return

pointer or NULL if not found

fdt_addr_tdev_read_addr_size_name(conststructudevice *dev, constchar*name, fdt_size_t*size): Get the reg property of a device, indexed by name

Parameters

const struct udevice *dev: Device to read from
const char *name: the ‘reg’ property can hold a list of <addr, size> pairs, with the ‘reg-names’ property providing named-based identification. name indicates the value to search for in ‘reg-names’.
fdt_size_t *size: place to put size value (on success)

Return

address or FDT_ADDR_T_NONE if not found

void*dev_read_addr_size_name_ptr(conststructudevice *dev, constchar*name, fdt_size_t*size): Get the reg property of a device as a pointer, indexed by name

Parameters

const struct udevice *dev: Device to read from
const char *name: the ‘reg’ property can hold a list of <addr, size> pairs, with the ‘reg-names’ property providing named-based identification. name indicates the value to search for in ‘reg-names’.
fdt_size_t *size: place to put size value (on success)

Return

pointer or NULL if not found

void*dev_remap_addr_name(conststructudevice *dev, constchar*name): Get the reg property of a device, indexed by name, as a memory-mapped I/O pointer

Parameters

const struct udevice *dev: Device to read from
const char *name: the ‘reg’ property can hold a list of <addr, size> pairs, with the ‘reg-names’ property providing named-based identification. name indicates the value to search for in ‘reg-names’.

Return

pointer or NULL if not found

fdt_addr_tdev_read_addr(conststructudevice *dev): Get the reg property of a device

Parameters

const struct udevice *dev: Device to read from

Return

address or FDT_ADDR_T_NONE if not found

void*dev_read_addr_ptr(conststructudevice *dev): Get the reg property of a device as a pointer

Parameters

const struct udevice *dev: Device to read from

Return

pointer or NULL if not found

fdt_addr_tdev_read_addr_pci(conststructudevice *dev, fdt_size_t*sizep): Read an address and handle PCI address translation

Parameters

const struct udevice *dev: Device to read from
fdt_size_t *sizep: If non-NULL, returns size of address space found

Description

At present U-Boot does not have address translation logic for PCI in the livetree implementation (of_addr.c). This special function supports this for the flat tree implementation.

This function should be removed (and code should use dev_read() instead) once:

PCI address translation is added; and either
everything uses livetree where PCI translation is used (which is feasible in SPL and U-Boot proper) or PCI address translation is added to fdtdec_get_addr() and friends.

Return

address or FDT_ADDR_T_NONE if not found

void*dev_remap_addr(conststructudevice *dev): Get the reg property of a device as a memory-mapped I/O pointer

Parameters

const struct udevice *dev: Device to read from

Return

pointer or NULL if not found

fdt_addr_tdev_read_addr_size(conststructudevice *dev, fdt_size_t*sizep): Get the reg property of a device

Parameters

const struct udevice *dev: Device to read from
fdt_size_t *sizep: place to put size value (on success)

Return

address value, or FDT_ADDR_T_NONE on error

constchar*dev_read_name(conststructudevice *dev): get the name of a device’s node

Parameters

const struct udevice *dev: Device to read from

Return

name of node

intdev_read_stringlist_search(conststructudevice *dev, constchar*propname, constchar*string): find string in a string list and return index

Parameters

const struct udevice *dev: device to check
const char *propname: name of the property containing the string list
const char *string: string to look up in the string list

Description

Note that it is possible for this function to succeed on property values that are not NUL-terminated. That’s because the function will stop after finding the first occurrence of string. This can for example happen with small-valued cell properties, such as #address-cells, when searching for the empty string.

Return

the index of the string in the list of strings -ENODATA if the property is not found -EINVAL on some other error

intdev_read_string_index(conststructudevice *dev, constchar*propname, intindex, constchar**outp): obtain an indexed string from a string list

Parameters

const struct udevice *dev: device to examine
const char *propname: name of the property containing the string list
int index: index of the string to return
const char **outp: return location for the string

Return

length of string, if found or -ve error value if not found

intdev_read_string_count(conststructudevice *dev, constchar*propname): find the number of strings in a string list

Parameters

const struct udevice *dev: device to examine
const char *propname: name of the property containing the string list

Return

number of strings in the list, or -ve error value if not found

intdev_read_string_list(conststructudevice *dev, constchar*propname, constchar***listp): read a list of strings

Parameters

const struct udevice *dev: device to examine
const char *propname: name of the property containing the string list
const char ***listp: returns an allocated, NULL-terminated list of strings if the return value is > 0, else is set to NULL

Description

This produces a list of string pointers with each one pointing to a string in the string list. If the property does not exist, it returns {NULL}.

The data is allocated and the caller is reponsible for freeing the return value (the list of string pointers). The strings themselves may not be changed as they point directly into the devicetree property.

Return

number of strings in list, 0 if none, -ENOMEM if out of memory, -ENOENT if no such property

intdev_read_phandle_with_args(conststructudevice *dev, constchar*list_name, constchar*cells_name, intcell_count, intindex, structofnode_phandle_args*out_args): Find a node pointed by phandle in a list

Parameters

const struct udevice *dev: device whose node containing a list
const char *list_name: property name that contains a list
const char *cells_name: property name that specifies phandles’ arguments count
int cell_count: Cell count to use if cells_name is NULL
int index: index of a phandle to parse out
struct ofnode_phandle_args *out_args: optional pointer to output arguments structure (will be filled)

Description

This function is useful to parse lists of phandles and their arguments. Returns 0 on success and fills out_args, on error returns appropriate errno value.

Caller is responsible to call of_node_put() on the returned out_args->np pointer.

phandle1: node1 {
 #list-cells = <2>;
};
phandle2: node2 {
 #list-cells = <1>;
};
node3 {
 list = <&phandle1 1 2 &phandle2 3>;
};

To get a device_node of the node2’ node you may call this: dev_read_phandle_with_args(dev, "list", "#list-cells", 0, 1, :c:type:`args);

Example

Return

0 on success (with out_args filled out if not NULL), -ENOENT if: list_name does not exist, -EINVAL if a phandle was not found, cells_name could not be found, the arguments were truncated or there were too many arguments.

intdev_count_phandle_with_args(conststructudevice *dev, constchar*list_name, constchar*cells_name, intcell_count): Return phandle number in a list

Parameters

const struct udevice *dev: device whose node containing a list
const char *list_name: property name that contains a list
const char *cells_name: property name that specifies phandles’ arguments count
int cell_count: Cell count to use if cells_name is NULL

Description

This function is usefull to get phandle number contained in a property list. For example, this allows to allocate the right amount of memory to keep clock’s reference contained into the "clocks" property.

Return

number of phandle found on success, on error returns appropriate errno value.

intdev_read_addr_cells(conststructudevice *dev): Get the number of address cells for a device’s node

Parameters

const struct udevice *dev: device to check

Description

This walks back up the tree to find the closest #address-cells property which controls the given node.

Return

number of address cells this node uses

intdev_read_size_cells(conststructudevice *dev): Get the number of size cells for a device’s node

Parameters

const struct udevice *dev: device to check

Description

This walks back up the tree to find the closest #size-cells property which controls the given node.

Return

number of size cells this node uses

intdev_read_simple_addr_cells(conststructudevice *dev): Get the address cells property in a node

Parameters

const struct udevice *dev: device to check

Description

This function matches fdt_address_cells().

Return

number of address cells this node uses

intdev_read_simple_size_cells(conststructudevice *dev): Get the size cells property in a node

Parameters

const struct udevice *dev: device to check

Description

This function matches fdt_size_cells().

Return

number of size cells this node uses

intdev_read_phandle(conststructudevice *dev): Get the phandle from a device

Parameters

const struct udevice *dev: device to check

Return

phandle (1 or greater), or 0 if no phandle or other error

constvoid*dev_read_prop(conststructudevice *dev, constchar*propname, int*lenp)

read a property from a device’s node

Parameters

const struct udevice *dev: device to check
const char *propname: property to read
int *lenp: place to put length on success

Return

pointer to property, or NULL if not found

intdev_read_first_prop(conststructudevice *dev, structofprop*prop): get the reference of the first property

Parameters

const struct udevice *dev: device to check
struct ofprop *prop: place to put argument reference

Description

Get reference to the first property of the node, it is used to iterate and read all the property with dev_read_prop_by_prop().

Return

0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found

intdev_read_next_prop(structofprop*prop): get the reference of the next property

Parameters

struct ofprop *prop: reference of current argument and place to put reference of next one

Description

Get reference to the next property of the node, it is used to iterate and read all the property with dev_read_prop_by_prop().

Return

0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found

constvoid*dev_read_prop_by_prop(structofprop*prop, constchar**propname, int*lenp): get a pointer to the value of a property

Parameters

struct ofprop *prop: reference on property
const char **propname: If non-NULL, place to property name on success,
int *lenp: If non-NULL, place to put length on success

Description

Get value for the property identified by the provided reference.

Return

0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found

intdev_read_alias_seq(conststructudevice *dev, int*devnump): Get the alias sequence number of a node

Parameters

const struct udevice *dev: device to look up
int *devnump: set to the sequence number if one is found

Description

This works out whether a node is pointed to by an alias, and if so, the sequence number of that alias. Aliases are of the form <base><num> where <num> is the sequence number. For example spi2 would be sequence number 2.

Return

0 if a sequence was found, -ve if not

intdev_read_u32_array(conststructudevice *dev, constchar*propname, u32*out_values, size_tsz): Find and read an array of 32 bit integers

Parameters

const struct udevice *dev: device to look up
const char *propname: name of the property to read
u32 *out_values: pointer to return value, modified only if return value is 0
size_t sz: number of array elements to read

Description

Search for a property in a device node and read 32-bit value(s) from it.

The out_values is modified only if a valid u32 value can be decoded.

Return

0 on success, -EINVAL if the property does not exist, -ENODATA if property does not have a value, and -EOVERFLOW if the property data isn’t large enough.

ofnodedev_read_first_subnode(conststructudevice *dev): find the first subnode of a device’s node

Parameters

const struct udevice *dev: device to look up

Return

reference to the first subnode (which can be invalid if the device’s node has no subnodes)

ofnodedev_read_next_subnode(ofnodenode): find the next sibling of a subnode

Parameters

ofnode node: valid reference to previous node (sibling)

Return

reference to the next subnode (which can be invalid if the node has no more siblings)

constuint8_t*dev_read_u8_array_ptr(conststructudevice *dev, constchar*propname, size_tsz): find an 8-bit array

Parameters

const struct udevice *dev: device to look up
const char *propname: name of property to find
size_t sz: number of array elements

Description

Look up a device’s node property and return a pointer to its contents as a byte array of given length. The property must have at least enough data for the array (count bytes). It may have more, but this will be ignored. The data is not copied.

Return

pointer to byte array if found, or NULL if the property is not found or there is not enough data

intdev_read_enabled(conststructudevice *dev): check whether a node is enabled

Parameters

const struct udevice *dev: device to examine

Description

This looks for a ‘status’ property. If this exists, then returns 1 if the status is ‘ok’ and 0 otherwise. If there is no status property, it returns 1 on the assumption that anything mentioned should be enabled by default.

Return

integer value 0 (not enabled) or 1 (enabled)

intdev_read_resource(conststructudevice *dev, uintindex, structresource*res): obtain an indexed resource from a device.

Parameters

const struct udevice *dev: device to examine
uint index: index of the resource to retrieve (0 = first)
struct resource *res: returns the resource

Return

0 if ok, negative on error

intdev_read_resource_byname(conststructudevice *dev, constchar*name, structresource*res): obtain a named resource from a device.

Parameters

const struct udevice *dev: device to examine
const char *name: name of the resource to retrieve
struct resource *res: returns the resource

Return

0 if ok, negative on error

u64dev_translate_address(conststructudevice *dev, constfdt32_t*in_addr): Translate a device-tree address

Parameters

const struct udevice *dev: device giving the context in which to translate the address
const fdt32_t *in_addr: pointer to the address to translate

Description

Translate an address from the device-tree into a CPU physical address. This function walks up the tree and applies the various bus mappings along the way.

Return

the translated address; OF_BAD_ADDR on error

u64dev_translate_dma_address(conststructudevice *dev, constfdt32_t*in_addr): Translate a device-tree DMA address

Parameters

const struct udevice *dev: device giving the context in which to translate the DMA address
const fdt32_t *in_addr: pointer to the DMA address to translate

Description

Translate a DMA address from the device-tree into a CPU physical address. This function walks up the tree and applies the various bus mappings along the way.

Return

the translated DMA address; OF_BAD_ADDR on error

intdev_get_dma_range(conststructudevice *dev, phys_addr_t*cpu, dma_addr_t*bus, u64*size): Get a device’s DMA constraints

Parameters

const struct udevice *dev: device giving the context in which to translate the DMA address
phys_addr_t *cpu: base address for CPU’s view of memory
dma_addr_t *bus: base address for BUS’s view of memory
u64 *size: size of the address space

Description

Provide the address bases and size of the linear mapping between the CPU and a device’s BUS address space.

Return

0 if ok, negative on error

intdev_read_alias_highest_id(constchar*stem): Get highest alias id for the given stem

Parameters

const char *stem: Alias stem to be examined

Description

The function travels the lookup table to get the highest alias id for the given alias stem.

Return

alias ID, if found, else -1

intdev_get_child_count(conststructudevice *dev): get the child count of a device

Parameters

const struct udevice *dev: device to use for interation (struct udevice *)

Return

the count of child subnode

intdev_read_pci_bus_range(conststructudevice *dev, structresource*res): Read PCI bus-range resource

Parameters

const struct udevice *dev: device to examine
struct resource *res: returns the resource

Description

Look at the bus range property of a device node and return the pci bus range for this node.

Return

0 if ok, negative on error

intdev_decode_display_timing(conststructudevice *dev, intindex, structdisplay_timing*config): decode display timings

Parameters

const struct udevice *dev: device to read DT display timings from. The node linked to the device contains a child node called ‘display-timings’ which in turn contains one or more display timing nodes.
int index: index number to read (0=first timing subnode)
struct display_timing *config: place to put timings

Description

Decode display timings from the supplied ‘display-timings’ node. See doc/device-tree-bindings/video/display-timing.txt for binding information.

Return

0 if OK, -FDT_ERR_NOTFOUND if not found

intdev_decode_panel_timing(conststructudevice *dev, structdisplay_timing*config): decode panel timings

Parameters

const struct udevice *dev: device to read DT display timings from. The node linked to the device contains a child node called ‘display-timings’ which in turn contains one or more display timing nodes.
struct display_timing *config: place to put timings

Description

Decode display timings from the supplied ‘panel-timings’ node.

Return

0 if OK, -FDT_ERR_NOTFOUND if not found

ofnodedev_get_phy_node(conststructudevice *dev): Get PHY node for a MAC (if not fixed-link)

Parameters

const struct udevice *dev: device representing the MAC

Description

This function parses PHY handle from the Ethernet controller’s ofnode (trying all possible PHY handle property names), and returns the PHY ofnode.

Before this is used, ofnode_phy_is_fixed_link() should be checked first, and if the result to that is true, this function should not be called.

Return

ofnode of the PHY, if it exists, otherwise an invalid ofnode

phy_interface_tdev_read_phy_mode(conststructudevice *dev): Read PHY connection type from a MAC

Parameters

const struct udevice *dev: device representing the MAC

Description

This function parses the "phy-mode" / "phy-connection-type" property and returns the corresponding PHY interface type.

Return

one of PHY_INTERFACE_MODE_* constants, PHY_INTERFACE_MODE_NA on: error

dev_for_each_subnode

dev_for_each_subnode (subnode, dev)

Helper function to iterate through subnodes

Parameters

subnode: ofnode holding the current subnode
dev: device to use for interation (struct udevice *)

Description

This creates a for() loop which works through the subnodes in a device’s device-tree node.

dev_for_each_property

dev_for_each_property (prop, dev)

Helper function to iterate through property

Parameters

prop: struct ofprop holding the current property
dev: device to use for interation (struct udevice *)

Description

This creates a for() loop which works through the property in a device’s device-tree node.

Device tree

structproperty

Definition

struct property {
 char *name;
 int length;
 void *value;
 struct property *next;
};

Members

name: Property name
length: Length of property in bytes
value: Pointer to property value
next: Pointer to next property, or NULL if none

structdevice_node

Definition

struct device_node {
 const char *name;
 const char *type;
 phandle phandle;
 const char *full_name;
 struct property *properties;
 struct device_node *parent;
 struct device_node *child;
 struct device_node *sibling;
};

Members

name: Node name, "" for the root node
type: Node type (value of device_type property) or "<NULL>" if none
phandle: Phandle value of this none, or 0 if none
full_name: Full path to node, e.g. "/bus**1**/spi**1100**" ("/" for the root node)
properties: Pointer to head of list of properties, or NULL if none
parent: Pointer to parent node, or NULL if this is the root node
child: Pointer to head of child node list, or NULL if no children
sibling: Pointer to the next sibling node, or NULL if this is the last

Description

The top of this tree is typically gd->of_root which points to the root node.

The head of the list of children for the root node (and any other node) is in child, with sibling providing a link to the next child.

Each child has a pointer to its parent in parent.

A node may have properties in which case the head of the list of properties properties pointers to the first one, with struct property->**next** pointing to the next one.

structof_phandle_args: structure to hold phandle and arguments

Definition

struct of_phandle_args {
 struct device_node *np;
 int args_count;
 uint32_t args[OF_MAX_PHANDLE_ARGS];
};

Members

np: Node that the phandle refers to
args_count: Number of arguments
args: Argument values

Description

This is used when decoding a phandle in a device tree property. Typically these look like this:

wibble {
 phandle = <5>;
};
...
some-prop = <&wibble 1 2 3>

Here node is the phandle of the node ‘wibble’, i.e. 5. There are three arguments: 1, 2, 3.

So when decoding the phandle in some-prop, np will point to wibble, args_count will be 3 and the three arguments will be in args.

boolof_live_active(void): check if livetree is active

Parameters

void: no arguments

Description

returns true if livetree is active, false it not

voidoftree_reset(void): reset the state of the oftree list

Parameters

void: no arguments

Description

Reset the oftree list so it can be started again. This should be called once the control FDT is in place, but before the ofnode interface is used.

__attribute_const__void*ofnode_to_fdt(ofnodenode): convert an ofnode to a flat DT pointer

Parameters

ofnode node: Reference containing offset (possibly invalid)

Description

This cannot be called if the reference contains a node pointer.

Return

DT offset (can be NULL)

__attribute_const__intofnode_to_offset(ofnodenode): convert an ofnode to a flat DT offset

Parameters

ofnode node: Reference containing offset (possibly invalid)

Description

This cannot be called if the reference contains a node pointer.

Return

DT offset (can be -1)

oftreeoftree_from_fdt(void*fdt): Returns an oftree from a flat device tree pointer

Parameters

void *fdt: Device tree to use

Description

If fdt is not already registered in the list of current device trees, it is added to the list.

Return

reference to the given node

ofnodenoffset_to_ofnode(ofnodeother_node, intof_offset): convert a DT offset to an ofnode

Parameters

ofnode other_node: Node in the same tree to use as a reference
int of_offset: DT offset (either valid, or -1)

Return

reference to the associated DT offset

intoftree_new(oftree*treep): Create a new, empty tree

Parameters

oftree *treep: Returns a pointer to the tree, on success

Return

0 on success, -ENOMEM if out of memory, -E2BIG if !OF_LIVE and there are too many (flattrees) already

intoftree_to_fdt(oftreetree, structabuf*buf): Convert an oftree to a flat FDT

Parameters

oftree tree: tree to flatten (if livetree) or copy (if not)
struct abuf *buf: Returns inited buffer containing the newly created flat tree. Note that for flat tree the buffer is not allocated. In either case the caller must call abut_uninit() to free any memory used by buf

Return

0 on success, -ENOMEM if out of memory, other -ve value for any other error

structdevice_node *ofnode_to_np(ofnodenode): convert an ofnode to a live DT node pointer

Parameters

ofnode node: Reference containing struct device_node * (possibly invalid)

Description

This cannot be called if the reference contains an offset.

Return

pointer to device node (can be NULL)

boolofnode_valid(ofnodenode): check if an ofnode is valid

Parameters

ofnode node: Reference containing offset (possibly invalid)

Return

true if the reference contains a valid ofnode, false if not

void*oftree_lookup_fdt(oftreetree): obtain the FDT pointer from an oftree

Parameters

oftree tree: Tree to look at return FDT pointer from the tree

Description

This can only be called when flat tree is enabled

ofnodeoffset_to_ofnode(intof_offset): convert a DT offset to an ofnode

Parameters

int of_offset: DT offset (either valid, or -1)

Return

reference to the associated DT offset

ofnodenp_to_ofnode(structdevice_node *np): convert a node pointer to an ofnode

Parameters

struct device_node *np: Live node pointer (can be NULL)

Return

reference to the associated node pointer

boolofnode_is_np(ofnodenode): check if a reference is a node pointer

Parameters

ofnode node: reference to check (possibly invalid)

Description

This function associated that if there is a valid live tree then all references will use it. This is because using the flat DT when the live tree is valid is not permitted.

Return

true if the reference is a live node pointer, false if it is a DT offset

boolofnode_equal(ofnoderef1, ofnoderef2): check if two references are equal

Parameters

ofnode ref1: first reference to check (possibly invalid)
ofnode ref2: second reference to check (possibly invalid)

Return

true if equal, else false

booloftree_valid(oftreetree): check if an oftree is valid

Parameters

oftree tree: Reference containing oftree

Return

true if the reference contains a valid oftree, false if node

oftreeoftree_null(void): Obtain a null oftree

Parameters

void: no arguments

Description

This returns an oftree which points to no tree. It works both with the flat tree and livetree.

ofnodeofnode_null(void): Obtain a null ofnode

Parameters

void: no arguments

Description

This returns an ofnode which points to no node. It works both with the flat tree and livetree.

boolofprop_valid(structofprop*prop): check if an ofprop is valid

Parameters

struct ofprop *prop: Pointer to ofprop to check

Return

true if the reference contains a valid ofprop, false if not

oftreeoftree_default(void): Returns the default device tree (U-Boot’s control FDT)

Parameters

void: no arguments

Return

reference to the control FDT

oftreeoftree_from_np(structdevice_node *root): Returns an oftree from a node pointer

Parameters

struct device_node *root: Root node of the tree

Return

reference to the given node

voidoftree_dispose(oftreetree): Dispose of an oftree

Parameters

oftree tree: Tree to dispose

Description

This can be used to dispose of a tree that has been created (other than the control FDT which must not be disposed)

boolofnode_name_eq(ofnodenode, constchar*name): Check a node name ignoring its unit address

Parameters

ofnode node: valid node to compared, which may have a unit address
const char *name: name (without unit address) to compare with the node name

Return

true if matches, false if it doesn’t match

boolofnode_name_eq_unit(ofnodenode, constchar*name): Check a node name ignoring its unit address

Parameters

ofnode node: valid node to compared, which may have a unit address
const char *name: name to compare with the node name. If this contains a unit address, it is matched, otherwise the unit address is ignored when searching for matches

Description

This is separate from ofnode_name_eq() to avoid code-size increase for boards which don’t need this function

Return

true if matches, false if it doesn’t match

intofnode_read_u8(ofnodenode, constchar*propname, u8*outp): Read a 8-bit integer from a property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read from
u8 *outp: place to put value (if found)

Return

0 if OK, -ve on error

u8ofnode_read_u8_default(ofnodenode, constchar*propname, u8def): Read a 8-bit integer from a property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read from
u8 def: default value to return if the property has no value

Return

property value, or def if not found

intofnode_read_u16(ofnodenode, constchar*propname, u16*outp): Read a 16-bit integer from a property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read from
u16 *outp: place to put value (if found)

Return

0 if OK, -ve on error

u16ofnode_read_u16_default(ofnodenode, constchar*propname, u16def): Read a 16-bit integer from a property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read from
u16 def: default value to return if the property has no value

Return

property value, or def if not found

intofnode_read_u32(ofnodenode, constchar*propname, u32*outp): Read a 32-bit integer from a property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read from
u32 *outp: place to put value (if found)

Return

0 if OK, -ve on error

intofnode_read_u32_index(ofnodenode, constchar*propname, intindex, u32*outp): Read a 32-bit integer from a multi-value property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read from
int index: index of the integer to return
u32 *outp: place to put value (if found)

Return

0 if OK, -ve on error

intofnode_read_u64_index(ofnodenode, constchar*propname, intindex, u64*outp): Read a 64-bit integer from a multi-value property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read from
int index: index of the integer to return
u64 *outp: place to put value (if found)

Return

0 if OK, -ve on error

intofnode_read_s32(ofnodenode, constchar*propname, s32*outp): Read a 32-bit integer from a property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read from
s32 *outp: place to put value (if found)

Return

0 if OK, -ve on error

u32ofnode_read_u32_default(ofnodenode, constchar*propname, u32def): Read a 32-bit integer from a property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read from
u32 def: default value to return if the property has no value

Return

property value, or def if not found

u32ofnode_read_u32_index_default(ofnodenode, constchar*propname, intindex, u32def): Read a 32-bit integer from a multi-value property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read from
int index: index of the integer to return
u32 def: default value to return if the property has no value

Return

property value, or def if not found

intofnode_read_s32_default(ofnodenode, constchar*propname, s32def): Read a 32-bit integer from a property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read from
s32 def: default value to return if the property has no value

Return

property value, or def if not found

intofnode_read_u64(ofnodenode, constchar*propname, u64*outp): Read a 64-bit integer from a property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read from
u64 *outp: place to put value (if found)

Return

0 if OK, -ve on error

u64ofnode_read_u64_default(ofnodenode, constchar*propname, u64def): Read a 64-bit integer from a property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read from
u64 def: default value to return if the property has no value

Return

property value, or def if not found

constvoid*ofnode_read_prop(ofnodenode, constchar*propname, int*sizep): Read a property from a node

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read
int *sizep: if non-NULL, returns the size of the property, or an error code if not found

Return

property value, or NULL if there is no such property

constchar*ofnode_read_string(ofnodenode, constchar*propname): Read a string from a property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read

Return

string from property value, or NULL if there is no such property

intofnode_read_u32_array(ofnodenode, constchar*propname, u32*out_values, size_tsz): Find and read an array of 32 bit integers

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of the property to read
u32 *out_values: pointer to return value, modified only if return value is 0
size_t sz: number of array elements to read

Return

0 on success, -EINVAL if the property does not exist, -ENODATA if property does not have a value, and -EOVERFLOW if the property data isn’t large enough

Description

Search for a property in a device node and read 32-bit value(s) from it.

The out_values is modified only if a valid u32 value can be decoded.

boolofnode_read_bool(ofnodenode, constchar*propname): read a boolean value from a property

Parameters

ofnode node: valid node reference to read property from
const char *propname: name of property to read

Return

true if property is present (meaning true), false if not present

ofnodeofnode_find_subnode(ofnodenode, constchar*subnode_name): find a named subnode of a parent node

Parameters

ofnode node: valid reference to parent node
const char *subnode_name: name of subnode to find

Return

reference to subnode (which can be invalid if there is no such subnode)

ofnodeofnode_find_subnode_unit(ofnodenode, constchar*subnode_name): find a named subnode of a parent node

Parameters

ofnode node: valid reference to parent node
const char *subnode_name: name of subnode to find, including any unit address. If the unit address is omitted, any subnode which matches the name (excluding any unit address) is returned

Return

reference to subnode (which can be invalid if there is no such subnode)

boolofnode_is_enabled(ofnodenode): Checks whether a node is enabled. This looks for a ‘status’ property. If this exists, then returns true if the status is ‘okay’ and false otherwise. If there is no status property, it returns true on the assumption that anything mentioned should be enabled by default.

Parameters

ofnode node: node to examine

Return

false (not enabled) or true (enabled)

ofnodeofnode_first_subnode(ofnodenode): find the first subnode of a parent node

Parameters

ofnode node: valid reference to a valid parent node

Return

reference to the first subnode (which can be invalid if the parent node has no subnodes)

ofnodeofnode_next_subnode(ofnodenode): find the next sibling of a subnode

Parameters

ofnode node: valid reference to previous node (sibling)

Return

reference to the next subnode (which can be invalid if the node has no more siblings)

ofnodeofnode_get_parent(ofnodenode): get the ofnode’s parent (enclosing ofnode)

Parameters

ofnode node: valid node to look up

Return

ofnode reference of the parent node

constchar*ofnode_get_name(ofnodenode): get the name of a node

Parameters

ofnode node: valid node to look up

Return

name of node (for the root node this is "")

intofnode_get_path(ofnodenode, char*buf, intbuflen): get the full path of a node

Parameters

ofnode node: valid node to look up
char *buf: buffer to write the node path into
int buflen: buffer size

Return

0 if OK, -ve on error

ofnodeofnode_get_by_phandle(uintphandle): get ofnode from phandle

Parameters

uint phandle: phandle to look up

Description

This uses the default (control) device tree

Return

ofnode reference to the phandle

ofnodeoftree_get_by_phandle(oftreetree, uintphandle): get ofnode from phandle

Parameters

oftree tree: tree to use
uint phandle: phandle to look up

Return

ofnode reference to the phandle

intofnode_read_size(ofnodenode, constchar*propname): read the size of a property

Parameters

ofnode node: node to check
const char *propname: property to check

Return

size of property if present, or -EINVAL if not

fdt_addr_tofnode_get_addr_size_index(ofnodenode, intindex, fdt_size_t*size): get an address/size from a node based on index

Parameters

ofnode node: node to read from
int index: Index of address to read (0 for first)
fdt_size_t *size: Pointer to size of the address

Description

This reads the register address/size from a node based on index

Return

address, or FDT_ADDR_T_NONE if not present or invalid

fdt_addr_tofnode_get_addr_size_index_notrans(ofnodenode, intindex, fdt_size_t*size): get an address/size from a node based on index, without address translation

Parameters

ofnode node: node to read from
int index: Index of address to read (0 for first)
fdt_size_t *size: Pointer to size of the address

Description

This reads the register address/size from a node based on index. The resulting address is not translated. Useful for example for on-disk addresses.

Return

address, or FDT_ADDR_T_NONE if not present or invalid

fdt_addr_tofnode_get_addr_index(ofnodenode, intindex): get an address from a node

Parameters

ofnode node: node to read from
int index: Index of address to read (0 for first)

Description

This reads the register address from a node

Return

address, or FDT_ADDR_T_NONE if not present or invalid

fdt_addr_tofnode_get_addr(ofnodenode): get an address from a node

Parameters

ofnode node: node to read from

Description

This reads the register address from a node

Return

address, or FDT_ADDR_T_NONE if not present or invalid

fdt_size_tofnode_get_size(ofnodenode): get size from a node

Parameters

ofnode node: node to read from

Description

This reads the register size from a node

Return

size of the address, or FDT_SIZE_T_NONE if not present or invalid

intofnode_stringlist_search(ofnodenode, constchar*propname, constchar*string): find a string in a string list and return index

Parameters

ofnode node: node to check
const char *propname: name of the property containing the string list
const char *string: string to look up in the string list

Description

Return

the index of the string in the list of strings -ENODATA if the property is not found -EINVAL on some other error

intofnode_read_string_index(ofnodenode, constchar*propname, intindex, constchar**outp): obtain an indexed string from a string list

Parameters

ofnode node: node to check
const char *propname: name of the property containing the string list
int index: index of the string to return (cannot be negative)
const char **outp: return location for the string

Description

Note that this will successfully extract strings from properties with non-NUL-terminated values. For example on small-valued cell properties this function will return the empty string.

If non-NULL, the length of the string (on success) or a negative error-code (on failure) will be stored in the integer pointer to by lenp.

Return

0 if found or -ve error value if not found

intofnode_read_string_count(ofnodenode, constchar*property): find the number of strings in a string list

Parameters

ofnode node: node to check
const char *property: name of the property containing the string list

Return

number of strings in the list, or -ve error value if not found

intofnode_read_string_list(ofnodenode, constchar*property, constchar***listp): read a list of strings

Parameters

ofnode node: node to check
const char *property: name of the property containing the string list
const char ***listp: returns an allocated, NULL-terminated list of strings if the return value is > 0, else is set to NULL

Description

This produces a list of string pointers with each one pointing to a string in the string list. If the property does not exist, it returns {NULL}.

Return

number of strings in list, 0 if none, -ENOMEM if out of memory, -EINVAL if no such property, -EENODATA if property is empty

ofnodeofnode_parse_phandle(ofnodenode, constchar*phandle_name, intindex): Resolve a phandle property to an ofnode

Parameters

ofnode node: node to check
const char *phandle_name: Name of property holding a phandle value
int index: For properties holding a table of phandles, this is the index into the table

Return

ofnode that the phandle points to or ofnode_null() on error.

intofnode_parse_phandle_with_args(ofnodenode, constchar*list_name, constchar*cells_name, intcell_count, intindex, structofnode_phandle_args*out_args): Find a node pointed by phandle in a list

Parameters

ofnode node: device tree node containing a list
const char *list_name: property name that contains a list
const char *cells_name: property name that specifies phandles’ arguments count
int cell_count: Cell count to use if cells_name is NULL
int index: index of a phandle to parse out
struct ofnode_phandle_args *out_args: optional pointer to output arguments structure (will be filled)

Description

This function is useful to parse lists of phandles and their arguments. Returns 0 on success and fills out_args, on error returns appropriate errno value.

Caller is responsible to call of_node_put() on the returned out_args->np pointer.

phandle1: node1 {
 #list-cells = <2>;
};
phandle2: node2 {
 #list-cells = <1>;
};
node3 {
 list = <&phandle1 1 2 &phandle2 3>;
};

To get a device_node of the node2’ node you may call this: ofnode_parse_phandle_with_args(node3, "list", "#list-cells", 0, 1, :c:type:`args);

Example

Return

0 on success (with out_args filled out if not NULL), -ENOENT if list_name does not exist, -EINVAL if a phandle was not found, cells_name could not be found, the arguments were truncated or there were too many arguments.

intofnode_count_phandle_with_args(ofnodenode, constchar*list_name, constchar*cells_name, intcell_count): Count number of phandle in a list

Parameters

ofnode node: device tree node containing a list
const char *list_name: property name that contains a list
const char *cells_name: property name that specifies phandles’ arguments count
int cell_count: Cell count to use if cells_name is NULL

Description

This function is useful to count phandles into a list. Returns number of phandle on success, on error returns appropriate errno value.

Return

number of phandle on success, -ENOENT if list_name does not exist, -EINVAL if a phandle was not found, cells_name could not be found.

ofnodeoftree_parse_phandle(oftreetree, ofnodenode, constchar*phandle_name, intindex): Resolve a phandle property to an ofnode from a root node

Parameters

oftree tree: device tree to use
ofnode node: node to check
const char *phandle_name: Name of property holding a phandle value
int index: For properties holding a table of phandles, this is the index into the table

Return

ofnode that the phandle points to or ofnode_null() on error.

intoftree_parse_phandle_with_args(oftreetree, ofnodenode, constchar*list_name, constchar*cells_name, intcell_count, intindex, structofnode_phandle_args*out_args): Find a node pointed by phandle in a list from a root node

Parameters

oftree tree: device tree to use
ofnode node: device tree node containing a list
const char *list_name: property name that contains a list
const char *cells_name: property name that specifies phandles’ arguments count
int cell_count: Cell count to use if cells_name is NULL
int index: index of a phandle to parse out
struct ofnode_phandle_args *out_args: optional pointer to output arguments structure (will be filled)

Description

This function is useful to parse lists of phandles and their arguments. Returns 0 on success and fills out_args, on error returns appropriate errno value.

Caller is responsible to call of_node_put() on the returned out_args->np pointer.

phandle1: node1 {
 #list-cells = <2>;
};
phandle2: node2 {
 #list-cells = <1>;
};
node3 {
 list = <&phandle1 1 2 &phandle2 3>;
};

To get a device_node of the node2’ node you may call this: oftree_parse_phandle_with_args(node3, "list", "#list-cells", 0, 1, :c:type:`args);

Example

Return

0 on success (with out_args filled out if not NULL), -ENOENT if list_name does not exist, -EINVAL if a phandle was not found, cells_name could not be found, the arguments were truncated or there were too many arguments.

intoftree_count_phandle_with_args(oftreetree, ofnodenode, constchar*list_name, constchar*cells_name, intcell_count): Count number of phandle in a list from a root node

Parameters

oftree tree: device tree to use
ofnode node: device tree node containing a list
const char *list_name: property name that contains a list
const char *cells_name: property name that specifies phandles’ arguments count
int cell_count: Cell count to use if cells_name is NULL

Description

This function is useful to count phandles into a list. Returns number of phandle on success, on error returns appropriate errno value.

Return

number of phandle on success, -ENOENT if list_name does not exist, -EINVAL if a phandle was not found, cells_name could not be found.

ofnodeofnode_path(constchar*path): find a node by full path

Parameters

const char *path: Full path to node, e.g. "/bus/spi**1**"

Description

This uses the control FDT.

Return

reference to the node found. Use ofnode_valid() to check if it exists

ofnodeoftree_path(oftreetree, constchar*path): find a node by full path from a root node

Parameters

oftree tree: Device tree to use
const char *path: Full path to node, e.g. "/bus/spi**1**"

Return

reference to the node found. Use ofnode_valid() to check if it exists

ofnodeoftree_root(oftreetree): get the root node of a tree

Parameters

oftree tree: Device tree to use

Return

reference to the root node

constvoid*ofnode_read_chosen_prop(constchar*propname, int*sizep): get the value of a chosen property

Parameters

const char *propname: Property name to look for
int *sizep: Returns size of property, or FDT_ERR_... error code if function returns NULL

Description

This looks for a property within the /chosen node and returns its value.

This only works with the control FDT.

Return

property value if found, else NULL

constchar*ofnode_read_chosen_string(constchar*propname): get the string value of a chosen property

Parameters

const char *propname: Property name to look for

Description

This looks for a property within the /chosen node and returns its value, checking that it is a valid nul-terminated string

This only works with the control FDT.

Return

string value if found, else NULL

ofnodeofnode_get_chosen_node(constchar*propname): get a referenced node from the chosen node

Parameters

const char *propname: Property name to look for

Description

This looks up a named property in the chosen node and uses that as a path to look up a code.

This only works with the control FDT.

Return

the referenced node if present, else ofnode_null()

intofnode_read_baud(void): get the baudrate from string value of chosen property

Parameters

void: no arguments

Description

This looks for stdout-path property within the /chosen node and parses its value to return baudrate.

This only works with the control FDT.

Return

baudrate value if found, else -ve error code

constvoid*ofnode_read_aliases_prop(constchar*propname, int*sizep): get the value of a aliases property

Parameters

const char *propname: Property name to look for
int *sizep: Returns size of property, or FDT_ERR_... error code if function returns NULL

Description

This looks for a property within the /aliases node and returns its value

Return

property value if found, else NULL

ofnodeofnode_get_aliases_node(constchar*propname): get a referenced node from the aliases node

Parameters

const char *propname: Property name to look for

Description

This looks up a named property in the aliases node and uses that as a path to look up a code.

This only works with the control FDT.

Return

the referenced node if present, else ofnode_null()

intofnode_decode_display_timing(ofnodenode, intindex, structdisplay_timing*config): decode display timings

Parameters

ofnode node: ‘display-timing’ node containing the timing subnodes
int index: Index number to read (0=first timing subnode)
struct display_timing *config: Place to put timings

Description

Decode display timings from the supplied ‘display-timings’ node. See doc/device-tree-bindings/video/display-timing.txt for binding information.

Return

0 if OK, -FDT_ERR_NOTFOUND if not found

intofnode_decode_panel_timing(ofnodenode, structdisplay_timing*config): decode display timings

Parameters

ofnode node: ‘display-timing’ node containing the timing subnodes
struct display_timing *config: Place to put timings

Description

Decode panel timings from the supplied ‘panel-timings’ node.

Return

0 if OK, -FDT_ERR_NOTFOUND if not found

constvoid*ofnode_get_property(ofnodenode, constchar*propname, int*lenp): get a pointer to the value of a node property

Parameters

ofnode node: node to read
const char *propname: property to read
int *lenp: place to put length on success

Return

pointer to property value, or NULL if not found or empty

boolofnode_has_property(ofnodenode, constchar*propname): check if a node has a named property

Parameters

ofnode node: node to read
const char *propname: property to read

Return

true if the property exists in the node, false if not

intofnode_first_property(ofnodenode, structofprop*prop): get the reference of the first property

Parameters

ofnode node: node to read
struct ofprop *prop: place to put argument reference

Description

Get reference to the first property of the node, it is used to iterate and read all the property with ofprop_get_property().

Return

0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found

intofnode_next_property(structofprop*prop): get the reference of the next property

Parameters

struct ofprop *prop: reference of current argument and place to put reference of next one

Description

Get reference to the next property of the node, it is used to iterate and read all the property with ofprop_get_property().

Return

0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found

ofnode_for_each_prop

ofnode_for_each_prop (prop, node)

iterate over all properties of a node

Parameters

prop: struct ofprop
node: node (lvalue, ofnode)

Description

This is a wrapper around a for loop and is used like this:

ofnode node;
struct ofprop prop;
ofnode_for_each_prop(prop, node) {
 ...use prop...
}

Note that this is implemented as a macro and prop is used as iterator in the loop. The parent variable can be a constant or even a literal.

constvoid*ofprop_get_property(conststructofprop*prop, constchar**propname, int*lenp): get a pointer to the value of a property

Parameters

const struct ofprop *prop: reference on property
const char **propname: If non-NULL, place to property name on success,
int *lenp: If non-NULL, place to put length on success, or error code on failure

Description

Get value for the property identified by the provided reference.

Return

pointer to property, or NULL if not found

fdt_addr_tofnode_get_addr_size(ofnodenode, constchar*propname, fdt_size_t*sizep): get address and size from a property

Parameters

ofnode node: node to read from
const char *propname: property to read
fdt_size_t *sizep: place to put size value (on success)

Description

This does no address translation. It simply reads an property that contains an address and a size value, one after the other.

Return

address value, or FDT_ADDR_T_NONE on error

constuint8_t*ofnode_read_u8_array_ptr(ofnodenode, constchar*propname, size_tsz): find an 8-bit array

Parameters

ofnode node: node to examine
const char *propname: name of property to find
size_t sz: number of array elements

Description

Look up a property in a node and return a pointer to its contents as a byte array of given length. The property must have at least enough data for the array (count bytes). It may have more, but this will be ignored. The data is not copied.

Return

pointer to byte array if found, or NULL if the property is not found or there is not enough data

intofnode_read_pci_addr(ofnodenode, enumfdt_pci_spacetype, constchar*propname, structfdt_pci_addr*addr, fdt_size_t*size): look up a PCI address

Parameters

ofnode node: node to examine
enum fdt_pci_space type: pci address type (FDT_PCI_SPACE_xxx)
const char *propname: name of property to find
struct fdt_pci_addr *addr: returns pci address in the form of fdt_pci_addr
fdt_size_t *size: if non-null, returns register-space size

Description

Look at an address property in a node and return the PCI address which corresponds to the given type in the form of fdt_pci_addr. The property must hold one fdt_pci_addr with a lengh.

Return

0 if ok, -ENOENT if the property did not exist, -EINVAL if the format of the property was invalid, -ENXIO if the requested address type was not found

intofnode_read_pci_vendev(ofnodenode, u16*vendor, u16*device): look up PCI vendor and device id

Parameters

ofnode node: node to examine
u16 *vendor: vendor id of the pci device
u16 *device: device id of the pci device

Description

Look at the compatible property of a device node that represents a PCI device and extract pci vendor id and device id from it.

Return

0 if ok, negative on error

intofnode_read_eth_phy_id(ofnodenode, u16*vendor, u16*device): look up eth phy vendor and device id

Parameters

ofnode node: node to examine
u16 *vendor: vendor id of the eth phy device
u16 *device: device id of the eth phy device

Description

Look at the compatible property of a device node that represents a eth phy device and extract phy vendor id and device id from it.

Return

0 if ok, negative on error

intofnode_read_addr_cells(ofnodenode): Get the number of address cells for a node

Parameters

ofnode node: Node to check

Description

This walks back up the tree to find the closest #address-cells property which controls the given node.

Return

number of address cells this node uses

intofnode_read_size_cells(ofnodenode): Get the number of size cells for a node

Parameters

ofnode node: Node to check

Description

This walks back up the tree to find the closest #size-cells property which controls the given node.

Return

number of size cells this node uses

intofnode_read_simple_addr_cells(ofnodenode): Get the address cells property in a node

Parameters

ofnode node: Node to check

Description

This function matches fdt_address_cells().

Return

value of #address-cells property in this node, or 2 if none

intofnode_read_simple_size_cells(ofnodenode): Get the size cells property in a node

Parameters

ofnode node: Node to check

Description

This function matches fdt_size_cells().

Return

value of #size-cells property in this node, or 2 if none

boolofnode_pre_reloc(ofnodenode): check if a node should be bound before relocation

Parameters

ofnode node: node to check

Description

Device tree nodes can be marked as needing-to-be-bound in the loader stages via special device tree properties.

Before relocation this function can be used to check if nodes are required in either SPL or TPL stages.

After relocation and jumping into the real U-Boot binary it is possible to determine if a node was bound in one of SPL/TPL stages.

There are 4 settings currently in use - bootph-some-ram: U-Boot proper pre-relocation phase - bootph-all: all phases Existing platforms only use it to indicate nodes needed in SPL. Should probably be replaced by bootph-pre-ram for new platforms. - bootph-pre-ram: SPL phase - bootph-pre-sram: TPL phase

Return

true if node should be or was bound, false otherwise

intofnode_read_resource(ofnodenode, uintindex, structresource*res): Read a resource from a node

Parameters

ofnode node: Node to read from
uint index: Index of resource to read (0 = first)
struct resource *res: Returns resource that was read, on success

Description

Read resource information from a node at the given index

Return

0 if OK, -ve on error

intofnode_read_resource_byname(ofnodenode, constchar*name, structresource*res): Read a resource from a node by name

Parameters

ofnode node: Node to read from
const char *name: Name of resource to read
struct resource *res: Returns resource that was read, on success

Description

Read resource information from a node matching the given name. This uses a ‘reg-names’ string list property with the names matching the associated ‘reg’ property list.

Return

0 if OK, -ve on error

ofnodeofnode_by_compatible(ofnodefrom, constchar*compat): Find the next compatible node

Parameters

ofnode from: ofnode to start from (use ofnode_null() to start at the beginning)
const char *compat: Compatible string to match

Description

Find the next node after from that is compatible with compat

Return

ofnode found, or ofnode_null() if none

ofnodeofnode_by_prop_value(ofnodefrom, constchar*propname, constvoid*propval, intproplen): Find the next node with given property value

Parameters

ofnode from: ofnode to start from. Use ofnode_null() to start at the beginning, or the return value from oftree_root() to start at the first child of the root
const char *propname: property name to check
const void *propval: property value to search for
int proplen: length of the value in propval

Description

Find the next node after from that has a propname with a value propval and a length proplen.

Return

ofnode found, or ofnode_null() if none

ofnode_for_each_subnode

ofnode_for_each_subnode (node, parent)

iterate over all subnodes of a parent

Parameters

node: child node (ofnode, lvalue)
parent: parent node (ofnode)

Description

This is a wrapper around a for loop and is used like so:

ofnode node;
ofnode_for_each_subnode(node, parent) {
 Use node
 ...
}

Note that this is implemented as a macro and node is used as iterator in the loop. The parent variable can be a constant or even a literal.

ofnode_for_each_compatible_node

ofnode_for_each_compatible_node (node, compat)

iterate over all nodes with a given compatible string

Parameters

node: child node (ofnode, lvalue)
compat: compatible string to match

Description

This is a wrapper around a for loop and is used like so:

ofnode node;
ofnode_for_each_compatible_node(node, parent, compatible) {
 Use node
 ...
}

Note that this is implemented as a macro and node is used as iterator in the loop.

intofnode_get_child_count(ofnodeparent): get the child count of a ofnode

Parameters

ofnode parent: valid node to get its child count

Return

the number of subnodes

u64ofnode_translate_address(ofnodenode, constfdt32_t*in_addr): Translate a device-tree address

Parameters

ofnode node: Device tree node giving the context in which to translate the address
const fdt32_t *in_addr: pointer to the address to translate

Description

Translate an address from the device-tree into a CPU physical address. This function walks up the tree and applies the various bus mappings along the way.

Return

the translated address; OF_BAD_ADDR on error

u64ofnode_translate_dma_address(ofnodenode, constfdt32_t*in_addr): Translate a device-tree DMA address

Parameters

ofnode node: Device tree node giving the context in which to translate the DMA address
const fdt32_t *in_addr: pointer to the DMA address to translate

Description

Translate a DMA address from the device-tree into a CPU physical address. This function walks up the tree and applies the various bus mappings along the way.

Return

the translated DMA address; OF_BAD_ADDR on error

intofnode_get_dma_range(ofnodenode, phys_addr_t*cpu, dma_addr_t*bus, u64*size): get dma-ranges for a specific DT node

Parameters

ofnode node: Device tree node
phys_addr_t *cpu: Pointer to variable storing the range’s cpu address
dma_addr_t *bus: Pointer to variable storing the range’s bus address
u64 *size: Pointer to variable storing the range’s size

Description

Get DMA ranges for a specifc node, this is useful to perform bus->cpu and cpu->bus address translations

Return

translated DMA address or OF_BAD_ADDR on error

intofnode_device_is_compatible(ofnodenode, constchar*compat): check if the node is compatible with compat

Parameters

ofnode node: Device tree node for which compatible needs to be verified.
const char *compat: Compatible string which needs to verified in the given node.

Description

This allows to check whether the node is comaptible with the compat.

Return

true if OK, false if the compatible is not found

intofnode_write_prop(ofnodenode, constchar*propname, constvoid*value, intlen, boolcopy): Set a property of a ofnode

Parameters

ofnode node: The node for whose property should be set
const char *propname: The name of the property to set
const void *value: The new value of the property (must be valid prior to calling the function)
int len: The length of the new value of the property
bool copy: true to allocate memory for the value. This only has any effect with live tree, since flat tree handles this automatically. It allows a node’s value to be written to the tree, without requiring that the caller allocate it

Description

Note that if copy is false, the value passed to the function is not allocated by the function itself, but must be allocated by the caller if necessary. However it does allocate memory for the property struct and name.

Return

0 if successful, -ve on error

intofnode_write_string(ofnodenode, constchar*propname, constchar*value): Set a string property of a ofnode

Parameters

ofnode node: The node for whose string property should be set
const char *propname: The name of the string property to set
const char *value: The new value of the string property (must be valid prior to calling the function)

Description

Note that the value passed to the function is not allocated by the function itself, but must be allocated by the caller if necessary.

Return

0 if successful, -ve on error

intofnode_write_u32(ofnodenode, constchar*propname, u32value): Set an integer property of an ofnode

Parameters

ofnode node: The node for whose string property should be set
const char *propname: The name of the string property to set
u32 value: The new value of the 32-bit integer property

Return

0 if successful, -ve on error

intofnode_write_u64(ofnodenode, constchar*propname, u64value): Set an integer property of an ofnode

Parameters

ofnode node: The node for whose string property should be set
const char *propname: The name of the string property to set
u64 value: The new value of the 64-bit integer property

Return

0 if successful, -ve on error

intofnode_write_bool(ofnodenode, constchar*propname, boolvalue): Set a boolean property of an ofnode

Parameters

ofnode node: The node for whose string property should be set
const char *propname: The name of the string property to set
bool value: The new value of the boolean property

Description

This either adds or deleted a property with a zero-length value

Return

0 if successful, -ve on error

intofnode_delete_prop(ofnodenode, constchar*propname): Delete a property

Parameters

ofnode node: Node containing the property to delete
const char *propname: Name of property to delete

Return

0 if successful, -ve on error

intofnode_set_enabled(ofnodenode, boolvalue): Enable or disable a device tree node given by its ofnode

Parameters

ofnode node: The node to enable
bool value: Flag that tells the function to either disable or enable the node

Description

This function effectively sets the node’s "status" property to either "okay" or "disable", hence making it available for driver model initialization or not.

Return

0 if successful, -ve on error

ofnodeofnode_get_phy_node(ofnodeeth_node): Get PHY node for a MAC (if not fixed-link)

Parameters

ofnode eth_node: ofnode belonging to the Ethernet controller

Description

This function parses PHY handle from the Ethernet controller’s ofnode (trying all possible PHY handle property names), and returns the PHY ofnode.

Before this is used, ofnode_phy_is_fixed_link() should be checked first, and if the result to that is true, this function should not be called.

Return

ofnode of the PHY, if it exists, otherwise an invalid ofnode

phy_interface_tofnode_read_phy_mode(ofnodemac_node): Read PHY connection type from a MAC node

Parameters

ofnode mac_node: ofnode containing the property

Description

This function parses the "phy-mode" / "phy-connection-type" property and returns the corresponding PHY interface type.

Return

one of PHY_INTERFACE_MODE_* constants, PHY_INTERFACE_MODE_NA on: error

boolofnode_conf_read_bool(constchar*prop_name): Read a boolean value from the U-Boot config

Parameters

const char *prop_name: property name to look up

Description

This reads a property from the /config node of the devicetree.

This only works with the control FDT.

See doc/device-tree-bindings/config.txt for bindings

Return

true, if it exists, false if not

intofnode_conf_read_int(constchar*prop_name, intdefault_val): Read an integer value from the U-Boot config

Parameters

const char *prop_name: property name to look up
int default_val: default value to return if the property is not found

Description

This reads a property from the /config node of the devicetree.

See doc/device-tree-bindings/config.txt for bindings

Return

integer value, if found, or default_val if not

constchar*ofnode_conf_read_str(constchar*prop_name): Read a string value from the U-Boot config

Parameters

const char *prop_name: property name to look up

Description

This reads a property from the /config node of the devicetree.

This only works with the control FDT.

See doc/device-tree-bindings/config.txt for bindings

Return

string value, if found, or NULL if not

boolofnode_options_read_bool(constchar*prop_name): Read a boolean value from the U-Boot options

Parameters

const char *prop_name: property name to look up

Description

This reads a property from the /options/u-boot/ node of the devicetree.

This only works with the control FDT.

See dtschema/schemas/options/u-boot.yaml in dt-schema project for bindings

Return

true, if it exists, false if not

intofnode_options_read_int(constchar*prop_name, intdefault_val): Read an integer value from the U-Boot options

Parameters

const char *prop_name: property name to look up
int default_val: default value to return if the property is not found

Description

This reads a property from the /options/u-boot/ node of the devicetree.

See dtschema/schemas/options/u-boot.yaml in dt-schema project for bindings

Return

integer value, if found, or default_val if not

constchar*ofnode_options_read_str(constchar*prop_name): Read a string value from the U-Boot options

Parameters

const char *prop_name: property name to look up

Description

This reads a property from the /options/u-boot/ node of the devicetree.

This only works with the control FDT.

See dtschema/schemas/options/u-boot.yaml in dt-schema project for bindings

Return

string value, if found, or NULL if not

intofnode_options_get_by_phandle(constchar*prop_name, ofnode*nodep): Get a ofnode from phandle from the U-Boot options

Parameters

const char *prop_name: property name to look up
ofnode *nodep: pointer to ofnode where node is stored

Description

This reads a property from the /options/u-boot/ node of the devicetree.

This only works with the control FDT.

See dtschema/schemas/options/u-boot.yaml in dt-schema project for bindings

Return

0, if found, or negative error if not

intofnode_read_bootscript_address(u64*bootscr_address, u64*bootscr_offset): Read bootscr-address or bootscr-ram-offset

Parameters

u64 *bootscr_address: pointer to 64bit address where bootscr-address property value is stored
u64 *bootscr_offset: pointer to 64bit offset address where bootscr-ram-offset property value is stored

Description

This reads a bootscr-address or bootscr-ram-offset property from the /options/u-boot/ node of the devicetree. bootscr-address holds the full address of the boot script file. bootscr-ram-offset holds the boot script file offset from the start of the ram base address. When bootscr-address is defined, bootscr-ram-offset property is ignored.

This only works with the control FDT.

Return

0 if OK, -EINVAL if property is not found.

intofnode_read_bootscript_flash(u64*bootscr_flash_offset, u64*bootscr_flash_size): Read bootscr-flash-offset/size

Parameters

u64 *bootscr_flash_offset: pointer to 64bit offset where bootscr-flash-offset property value is stored
u64 *bootscr_flash_size: pointer to 64bit size where bootscr-flash-size property value is stored

Description

This reads a bootscr-flash-offset and bootscr-flash-size properties from the /options/u-boot/ node of the devicetree. bootscr-flash-offset holds the offset of the boot script file from start of flash. bootscr-flash-size holds the boot script size in flash. When bootscr-flash-size is not defined, bootscr-flash-offset property is cleaned.

This only works with the control FDT.

Return

0 if OK, -EINVAL if property is not found or incorrect.

intofnode_add_subnode(ofnodeparent, constchar*name, ofnode*nodep): add a new subnode to a node

Parameters

ofnode parent: parent node to add to
const char *name: name of subnode (allocated by this function)
ofnode *nodep: returns pointer to new subnode (valid if the function returns 0 or -EEXIST) Returns 0 if OK, -EEXIST if already exists, -ENOMEM if out of memory, other -ve on other error

intofnode_copy_props(ofnodedst, ofnodesrc): copy all properties from one node to another

Parameters

ofnode dst: Destination node to write properties to
ofnode src: Source node to read properties from

Description

Makes a copy of all properties from the source node to the destination node. Existing properties in the destination node remain unchanged, except that any with the same name are overwritten, including changing the size of the property.

For livetree, properties are copied / allocated, so the source tree does not need to be present afterwards.

intofnode_copy_node(ofnodedst_parent, constchar*name, ofnodesrc, ofnode*nodep): Copy a node to another place

Parameters

ofnode dst_parent: Parent of the newly copied node
const char *name: Name to give the new node
ofnode src: Source node to copy
ofnode *nodep: Returns the new node, or the existing node if there is one

Description

If a node with this name already exists in dst_parent, this returns an .error

Return

0 if OK, -EEXIST if dst_parent already has a node with this parent

intofnode_delete(ofnode*nodep): Delete a node

Parameters

ofnode *nodep: Pointer to node to delete (set to ofnode_null() on success)

Description

Delete a node from the tree

Return

0 if OK, -ENOENT if the node does not exist, -EPERM if it is the root node (wWhich cannot be removed), -EFAULT if the tree is broken (to_remove is not a child of its parent),

intofnode_read_fmap_entry(ofnodenode, structfmap_entry*entry): Read a flash entry from the fdt

Parameters

ofnode node: Reference to node to read
struct fmap_entry *entry: Place to put offset and size of this node

Return

0 if ok, -ve on error

intofnode_decode_region(ofnodenode, constchar*prop_name, fdt_addr_t*basep, fdt_size_t*sizep): Decode a memory region from a node

Parameters

ofnode node: ofnode to examine
const char *prop_name: name of property to find
fdt_addr_t *basep: Returns base address of region
fdt_size_t *sizep: Returns size of region

Description

Look up a property in a node which contains a memory region address and size. Then return a pointer to this address.

The property must hold one address with a length. This is only tested on 32-bit machines.

Return

0 if ok, -1 on error (property not found)

intofnode_decode_memory_region(ofnodeconfig_node, constchar*mem_type, constchar*suffix, fdt_addr_t*basep, fdt_size_t*sizep): Decode a named region within a memory bank

Parameters

ofnode config_node: ofnode containing the properties (invalid for "/config")
const char *mem_type: Type of memory to use, which is a name, such as "u-boot" or "kernel".
const char *suffix: String to append to the memory/offset property names
fdt_addr_t *basep: Returns base of region
fdt_size_t *sizep: Returns size of region

Description

This function handles selection of a memory region. The region is specified as an offset/size within a particular type of memory.

The properties used are:

<mem_type>-memory<suffix> for the name of the memory bank <mem_type>-offset<suffix> for the offset in that bank

The property value must have an offset and a size. The function checks that the region is entirely within the memory bank.5

Return

0 if OK, -ive on error

boolofnode_phy_is_fixed_link(ofnodeeth_node, ofnode*phy_node): Detect fixed-link pseudo-PHY device

Parameters

ofnode eth_node: ofnode containing the fixed-link subnode/property
ofnode *phy_node: if fixed-link PHY detected, containing the PHY ofnode

Description

This function detects whether the ethernet controller connects to a fixed-link pseudo-PHY device.

This function supports the following two DT bindings: - the new DT binding, where ‘fixed-link’ is a sub-node of the Ethernet device - the old DT binding, where ‘fixed-link’ is a property with 5 cells encoding various information about the fixed PHY

If both new and old bindings exist, the new one is preferred.

Return

true if a fixed-link pseudo-PHY device exists, false otherwise

boolofnode_eth_uses_inband_aneg(ofnodeeth_node): Detect whether MAC should use in-band autoneg

Parameters

ofnode eth_node: ofnode belonging to the Ethernet controller

Description

This function detects whether the Ethernet controller should use IEEE 802.3 clause 37 in-band autonegotiation for serial protocols such as 1000base-x, SGMII, USXGMII, etc. The property is relevant when the Ethernet controller is connected to an on-board PHY or an SFP cage, and is not relevant when it has a fixed link (in that case, in-band autoneg should not be used).

Return

true if in-band autoneg should be used, false otherwise

structdevice_node *of_find_all_nodes(structdevice_node *prev): Get next node in global list

Parameters

struct device_node *prev: Previous node or NULL to start iteration of_node_put() will be called on it

Description

Returns a node pointer with refcount incremented, use of_node_put() on it when done.

intof_n_addr_cells(conststructdevice_node *np): Get the number of address cells for a node

Parameters

const struct device_node *np: Node pointer to check

Description

This walks back up the tree to find the closest #address-cells property which controls the given node.

Return

number of address cells this node uses

intof_n_size_cells(conststructdevice_node *np): Get the number of size cells for a node

Parameters

const struct device_node *np: Node pointer to check

Description

This walks back up the tree to find the closest #size-cells property which controls the given node.

Return

number of size cells this node uses

intof_simple_addr_cells(conststructdevice_node *np): Get the address cells property in a node

Parameters

const struct device_node *np: Node pointer to check

Description

This function matches fdt_address_cells().

Return

value of #address-cells property in this node, or 2 if none

intof_simple_size_cells(conststructdevice_node *np): Get the size cells property in a node

Parameters

const struct device_node *np: Node pointer to check

Description

This function matches fdt_size_cells().

Return

value of #size-cells property in this node, or 2 if none

structproperty *of_find_property(conststructdevice_node *np, constchar*name, int*lenp): find a property in a node

Parameters

const struct device_node *np: Pointer to device node holding property
const char *name: Name of property
int *lenp: If non-NULL, returns length of property

Return

pointer to property, or NULL if not found

constvoid*of_get_property(conststructdevice_node *np, constchar*name, int*lenp): get a property value

Parameters

const struct device_node *np: Pointer to device node holding property
const char *name: Name of property
int *lenp: If non-NULL, returns length of property

Description

Find a property with a given name for a given node and return the value.

Return

pointer to property value, or NULL if not found

conststructproperty *of_get_first_property(conststructdevice_node *np): get to the pointer of the first property

Parameters

const struct device_node *np: Pointer to device node

Description

Get pointer to the first property of the node, it is used to iterate and read all the property with of_get_next_property_by_prop().

Return

pointer to property or NULL if not found

conststructproperty *of_get_next_property(conststructdevice_node *np, conststructproperty *property): get to the pointer of the next property

Parameters

const struct device_node *np: Pointer to device node
const struct property *property: pointer of the current property

Description

Get pointer to the next property of the node, it is used to iterate and read all the property with of_get_property_by_prop().

Return

pointer to next property or NULL if not found

constvoid*of_get_property_by_prop(conststructdevice_node *np, conststructproperty *property, constchar**name, int*lenp): get a property value of a node property

Parameters

const struct device_node *np: Pointer to device node
const struct property *property: pointer of the property to read
const char **name: place to property name on success
int *lenp: place to put length on success

Description

Get value for the property identified by node and property pointer.

Return

pointer to property value or NULL if error

intof_device_is_compatible(conststructdevice_node *np, constchar*compat, constchar*type, constchar*name): Check if the node matches given constraints

Parameters

const struct device_node *np: Pointer to device node
const char *compat: required compatible string, NULL or "" for any match
const char *type: required device_type value, NULL or "" for any match
const char *name: required node name, NULL or "" for any match

Description

Checks if the given compat, type and name strings match the properties of the given device. A constraints can be skipped by passing NULL or an empty string as the constraint.

specific compatible && type && name
specific compatible && type
specific compatible && name
specific compatible
general compatible && type && name
general compatible && type
general compatible && name
general compatible
type && name
type
name

Return

0 for no match, and a positive integer on match. The return value is a relative score with larger values indicating better matches. The score is weighted for the most specific compatible value to get the highest score. Matching type is next, followed by matching name. Practically speaking, this results in the following priority order for matches:

boolof_device_is_available(conststructdevice_node *np): check if a device is available for use

Parameters

const struct device_node *np: Pointer to device node to check for availability

Return

true if the status property is absent or set to "okay", false otherwise

structdevice_node *of_get_parent(conststructdevice_node *np): Get a node’s parent, if any

Parameters

const struct device_node *np: Pointer to device node to check

Return

a node pointer, or NULL if none

structdevice_node *of_find_node_opts_by_path(structdevice_node *root, constchar*path, constchar**opts): Find a node matching a full OF path

Parameters

struct device_node *root: Root node of the tree to use. If this is NULL, then gd->of_root is used
const char *path: Either the full path to match, or if the path does not start with ‘/’, the name of a property of the /aliases node (an alias). In the case of an alias, the node matching the alias’ value will be returned.
const char **opts: Address of a pointer into which to store the start of an options string appended to the end of the path with a ‘:’ separator. Can be NULL

Description

Note that alias processing is only available on the control FDT (gd->of_root). For other trees it is skipped, so any attempt to obtain an alias will result in returning NULL.

Valid paths:: /foo/bar Full path foo Valid alias foo/bar Valid alias + relative path

Return

a node pointer or NULL if not found

structdevice_node *of_find_compatible_node(structdevice_node *from, constchar*type, constchar*compatible): find a node based on its compatible string

Parameters

struct device_node *from: Node to start searching from or NULL. the node you pass will not be searched, only the next one will; typically, you pass what the previous call returned.
const char *type: The type string to match "device_type" or NULL to ignore
const char *compatible: The string to match to one of the tokens in the device "compatible" list.

Description

Find a node based on type and one of the tokens in its "compatible" property

Return

node pointer or NULL if not found

structdevice_node *of_find_node_by_prop_value(structdevice_node *from, constchar*propname, constvoid*propval, intproplen): find a node with a given property value

Parameters

struct device_node *from: Node to start searching from or NULL. the node you pass will not be searched, only the next one will; typically, you pass what the previous call returned.
const char *propname: property name to check
const void *propval: property value to search for
int proplen: length of the value in propval

Description

Find a node based on a property value.

Return

node pointer or NULL if not found

structdevice_node *of_find_node_by_phandle(structdevice_node *root, phandlehandle): Find a node given a phandle

Parameters

struct device_node *root: root node to start from (NULL for default device tree)
phandle handle: phandle of the node to find

Return

node pointer, or NULL if not found

intof_read_u8(conststructdevice_node *np, constchar*propname, u8*outp): Find and read a 8-bit integer from a property

Parameters

const struct device_node *np: device node from which the property value is to be read.
const char *propname: name of the property to be searched.
u8 *outp: pointer to return value, modified only if return value is 0.

Description

Search for a property in a device node and read a 8-bit value from it.

Return

0 on success, -EINVAL if the property does not exist, -ENODATA if property does not have a value, and -EOVERFLOW if the property data isn’t large enough.

intof_read_u16(conststructdevice_node *np, constchar*propname, u16*outp): Find and read a 16-bit integer from a property

Parameters

const struct device_node *np: device node from which the property value is to be read.
const char *propname: name of the property to be searched.
u16 *outp: pointer to return value, modified only if return value is 0.

Description

Search for a property in a device node and read a 16-bit value from it.

Return

0 on success, -EINVAL if the property does not exist, -ENODATA if property does not have a value, and -EOVERFLOW if the property data isn’t large enough.

intof_read_u32(conststructdevice_node *np, constchar*propname, u32*outp): Find and read a 32-bit integer from a property

Parameters

const struct device_node *np: device node from which the property value is to be read.
const char *propname: name of the property to be searched.
u32 *outp: pointer to return value, modified only if return value is 0.

Description

Search for a property in a device node and read a 32-bit value from it.

Return

0 on success, -EINVAL if the property does not exist, -ENODATA if property does not have a value, and -EOVERFLOW if the property data isn’t large enough.

intof_read_u32_index(conststructdevice_node *np, constchar*propname, intindex, u32*outp): Find and read a 32-bit value from a multi-value property

Parameters

const struct device_node *np: device node from which the property value is to be read.
const char *propname: name of the property to be searched.
int index: index of the u32 in the list of values
u32 *outp: pointer to return value, modified only if return value is 0.

Description

Search for a property in a device node and read a 32-bit value from it.

Return

0 on success, -EINVAL if the property does not exist, or -EOVERFLOW if the property data isn’t large enough.

intof_read_u64_index(conststructdevice_node *np, constchar*propname, intindex, u64*outp): Find and read a 64-bit value from a multi-value property

Parameters

const struct device_node *np: device node from which the property value is to be read.
const char *propname: name of the property to be searched.
int index: index of the u32 in the list of values
u64 *outp: pointer to return value, modified only if return value is 0.

Description

Search for a property in a device node and read a 64-bit value from it.

Return

0 on success, -EINVAL if the property does not exist, or -EOVERFLOW if the property data isn’t large enough.

intof_read_u64(conststructdevice_node *np, constchar*propname, u64*outp): Find and read a 64-bit integer from a property

Parameters

const struct device_node *np: device node from which the property value is to be read.
const char *propname: name of the property to be searched.
u64 *outp: pointer to return value, modified only if return value is 0.

Description

Search for a property in a device node and read a 64-bit value from it.

Return

0 on success, -EINVAL if the property does not exist, or -EOVERFLOW if the property data isn’t large enough.

intof_read_u32_array(conststructdevice_node *np, constchar*propname, u32*out_values, size_tsz): Find and read an array of 32 bit integers

Parameters

const struct device_node *np: device node from which the property value is to be read.
const char *propname: name of the property to be searched.
u32 *out_values: pointer to return value, modified only if return value is 0.
size_t sz: number of array elements to read

Description

Search for a property in a device node and read 32-bit value(s) from it.

Return

0 on success, -EINVAL if the property does not exist, or -EOVERFLOW if longer than sz.

intof_property_match_string(conststructdevice_node *np, constchar*propname, constchar*string): Find string in a list and return index

Parameters

const struct device_node *np: pointer to node containing string list property
const char *propname: string list property name
const char *string: pointer to string to search for in string list

Description

This function searches a string list property and returns the index of a specific string value.

Return

0 on success, -EINVAL if the property does not exist, -ENODATA if property does not have a value, and -EOVERFLOW is longer than sz.

intof_property_read_string_index(conststructdevice_node *np, constchar*propname, intindex, constchar**output): Find and read a string from a multiple strings property.

Parameters

const struct device_node *np: device node from which the property value is to be read.
const char *propname: name of the property to be searched.
int index: index of the string in the list of strings
const char **output: pointer to null terminated return string, modified only if return value is 0.

Description

Search for a property in a device tree node and retrieve a null terminated string value (pointer to data, not a copy) in the list of strings contained in that property.

The out_string pointer is modified only if a valid string can be decoded.

Return

0 on success, -EINVAL if the property does not exist, -ENODATA if property does not have a value, and -EILSEQ if the string is not null-terminated within the length of the property data.

intof_property_count_strings(conststructdevice_node *np, constchar*propname): Find and return the number of strings from a multiple strings property.

Parameters

const struct device_node *np: device node from which the property value is to be read.
const char *propname: name of the property to be searched.

Description

Search for a property in a device tree node and retrieve the number of null terminated string contain in it.

Return

the number of strings on success, -EINVAL if the property does not exist, -ENODATA if property does not have a value, and -EILSEQ if the string is not null-terminated within the length of the property data.

structdevice_node *of_root_parse_phandle(structdevice_node *root, conststructdevice_node *np, constchar*phandle_name, intindex): Resolve a phandle property to a device_node pointer from a root node

Parameters

struct device_node *root: Pointer to root device tree node (default root node if NULL)
const struct device_node *np: Pointer to device node holding phandle property
const char *phandle_name: Name of property holding a phandle value
int index: For properties holding a table of phandles, this is the index into the table

Return

the device_node pointer with refcount incremented. Use of_node_put() on it when done.

intof_root_parse_phandle_with_args(structdevice_node *root, conststructdevice_node *np, constchar*list_name, constchar*cells_name, intcells_count, intindex, structof_phandle_args *out_args): Find a node pointed by phandle in a list from a root node

Parameters

struct device_node *root: pointer to root device tree node (default root node if NULL)
const struct device_node *np: pointer to a device tree node containing a list
const char *list_name: property name that contains a list
const char *cells_name: property name that specifies phandles’ arguments count
int cells_count: Cell count to use if cells_name is NULL
int index: index of a phandle to parse out
struct of_phandle_args *out_args: optional pointer to output arguments structure (will be filled)

Return

0 on success (with out_args filled out if not NULL), -ENOENT if list_name does not exist, -EINVAL if a phandle was not found, cells_name could not be found, the arguments were truncated or there were too many arguments.

Description

This function is useful to parse lists of phandles and their arguments. Returns 0 on success and fills out_args, on error returns appropriate errno value.

Caller is responsible to call of_node_put() on the returned out_args->np pointer.

phandle1: node1 {
 #list-cells = <2>;
};
phandle2: node2 {
 #list-cells = <1>;
};
node3 {
 list = <&phandle1 1 2 &phandle2 3>;
};

To get a device_node of the node2’ node you may call this: of_root_parse_phandle_with_args(node3, "list", "#list-cells", 1, :c:type:`args);

Example

intof_root_count_phandle_with_args(structdevice_node *root, conststructdevice_node *np, constchar*list_name, constchar*cells_name, intcells_count): Count the number of phandle in a list from a root node

Parameters

struct device_node *root: pointer to root device tree node (default root node if NULL)
const struct device_node *np: pointer to a device tree node containing a list
const char *list_name: property name that contains a list
const char *cells_name: property name that specifies phandles’ arguments count
int cells_count: Cell count to use if cells_name is NULL

Return

number of phandle found, -ENOENT if list_name does not exist, -EINVAL if a phandle was not found, cells_name could not be found, the arguments were truncated or there were too many arguments.

Description

Returns number of phandle found on success, on error returns appropriate errno value.

structdevice_node *of_parse_phandle(conststructdevice_node *np, constchar*phandle_name, intindex): Resolve a phandle property to a device_node pointer

Parameters

const struct device_node *np: Pointer to device node holding phandle property
const char *phandle_name: Name of property holding a phandle value
int index: For properties holding a table of phandles, this is the index into the table

Return

the device_node pointer with refcount incremented. Use of_node_put() on it when done.

intof_parse_phandle_with_args(conststructdevice_node *np, constchar*list_name, constchar*cells_name, intcells_count, intindex, structof_phandle_args *out_args): Find a node pointed by phandle in a list

Parameters

const struct device_node *np: pointer to a device tree node containing a list
const char *list_name: property name that contains a list
const char *cells_name: property name that specifies phandles’ arguments count
int cells_count: Cell count to use if cells_name is NULL
int index: index of a phandle to parse out
struct of_phandle_args *out_args: optional pointer to output arguments structure (will be filled)

Return

0 on success (with out_args filled out if not NULL), -ENOENT if list_name does not exist, -EINVAL if a phandle was not found, cells_name could not be found, the arguments were truncated or there were too many arguments.

Description

This function is useful to parse lists of phandles and their arguments. Returns 0 on success and fills out_args, on error returns appropriate errno value.

Caller is responsible to call of_node_put() on the returned out_args->np pointer.

phandle1: node1 {
 #list-cells = <2>;
};
phandle2: node2 {
 #list-cells = <1>;
};
node3 {
 list = <&phandle1 1 2 &phandle2 3>;
};

To get a device_node of the node2’ node you may call this: of_parse_phandle_with_args(node3, "list", "#list-cells", 1, :c:type:`args);

Example

intof_count_phandle_with_args(conststructdevice_node *np, constchar*list_name, constchar*cells_name, intcells_count): Count the number of phandle in a list

Parameters

const struct device_node *np: pointer to a device tree node containing a list
const char *list_name: property name that contains a list
const char *cells_name: property name that specifies phandles’ arguments count
int cells_count: Cell count to use if cells_name is NULL

Return

number of phandle found, -ENOENT if list_name does not exist, -EINVAL if a phandle was not found, cells_name could not be found, the arguments were truncated or there were too many arguments.

Description

Returns number of phandle found on success, on error returns appropriate errno value.

intof_alias_scan(void): Scan all properties of the ‘aliases’ node

Parameters

void: no arguments

Description

The function scans all the properties of the ‘aliases’ node and populates the lookup table with the properties. It returns the number of alias properties found, or an error code in case of failure.

Return

9 if OK, -ENOMEM if not enough memory

intof_alias_get_id(conststructdevice_node *np, constchar*stem): Get alias id for the given device_node

Parameters

const struct device_node *np: Pointer to the given device_node
const char *stem: Alias stem of the given device_node

Description

Travels the lookup table to get the alias id for the given device_node and alias stem.

Return

alias ID, if found, else -ENODEV

intof_alias_get_highest_id(constchar*stem): Get highest alias id for the given stem

Parameters

const char *stem: Alias stem to be examined

Description

The function travels the lookup table to get the highest alias id for the given alias stem.

Return

alias ID, if found, else -1

structdevice_node *of_get_stdout(void): Get node to use for stdout

Parameters

void: no arguments

Return

node referred to by stdout-path alias, or NULL if none

intof_write_prop(structdevice_node *np, constchar*propname, intlen, constvoid*value): Write a property to the device tree

Parameters

struct device_node *np: device node to which the property value is to be written
const char *propname: name of the property to write
int len: length of the property in bytes
const void *value: value of the property

Return

0 if OK, -ve on error

intof_add_subnode(structdevice_node *node, constchar*name, intlen, structdevice_node **subnodep): add a new subnode to a node

Parameters

struct device_node *node: parent node to add to
const char *name: name of subnode
int len: length of name (so the caller does not need to nul-terminate a partial string), or -1 for strlen(name)
struct device_node **subnodep: returns pointer to new subnode (valid if the function returns 0 or -EEXIST) Returns 0 if OK, -EEXIST if already exists, -ENOMEM if out of memory, other -ve on other error

intof_remove_property(structdevice_node *np, structproperty *prop): Remove a property from a node

Parameters

struct device_node *np: Node to remove from
struct property *prop: Pointer to property to remove Return 0 if OK, -ENODEV if the property could not be found in the node

intof_remove_node(structdevice_node *to_remove): Remove a node from the tree

Parameters

struct device_node *to_remove: Node to remove

Return

0 if OK, -EPERM if it is the root node (wWhich cannot be removed), -ENOENT if the tree is broken (to_remove is not a child of its parent)

u64of_translate_address(conststructdevice_node *np, const__be32*in_addr): translate a device-tree address to a CPU address

Parameters

const struct device_node *np: pointer to node to check
const __be32 *in_addr: pointer to input address

Description

Translate an address from the device-tree into a CPU physical address, this walks up the tree and applies the various bus mappings on the way.

Note

We consider that crossing any level with #size-cells == 0 to mean that translation is impossible (that is we are not dealing with a value that can be mapped to a cpu physical address). This is not really specified that way, but this is traditionally the way IBM at least do things

Return

translated address or OF_BAD_ADDR on error

u64of_translate_dma_address(conststructdevice_node *np, const__be32*in_addr): translate a device-tree DMA address to a CPU address

Parameters

const struct device_node *np: ne
const __be32 *in_addr: pointer to input DMA address

Description

Translate a DMA address from the device-tree into a CPU physical address, this walks up the tree and applies the various bus mappings on the way.

Note

Return

translated DMA address or OF_BAD_ADDR on error

intof_get_dma_range(conststructdevice_node *np, phys_addr_t*cpu, dma_addr_t*bus, u64*size): get dma-ranges for a specific DT node

Parameters

const struct device_node *np: Pointer to device tree blob
phys_addr_t *cpu: Pointer to variable storing the range’s cpu address
dma_addr_t *bus: Pointer to variable storing the range’s bus address
u64 *size: Pointer to variable storing the range’s size

Description

Get DMA ranges for a specifc node, this is useful to perform bus->cpu and cpu->bus address translations

Return

translated DMA address or OF_BAD_ADDR on error

const__be32*of_get_address(conststructdevice_node *np, intindex, u64*size, unsignedint*flags): obtain an address from a node

Parameters

const struct device_node *np: Node to check
int index: Index of address to read (0 = first)
u64 *size: place to put size on success
unsigned int *flags: place to put flags on success

Description

Extract an address from a node, returns the region size and the address space flags too. The PCI version uses a BAR number instead of an absolute index.

Return

pointer to address which can be read

intof_address_to_resource(conststructdevice_node *np, intindex, structresource*r): translate device tree address to resource

Parameters

const struct device_node *np: node to check
int index: index of address to read (0 = first)
struct resource *r: place to put resource information

Description

Note that if your address is a PIO address, the conversion will fail if the physical address can’t be internally converted to an IO token with pci_address_to_pio(), that is because it’s either called to early or it can’t be matched to any host bridge IO space

Return

0 if OK, -ve on error

fdt_addr_tdevfdt_get_addr(conststructudevice *dev): Get the reg property of a device

Parameters

const struct udevice *dev: Pointer to a device

Return

Address, or FDT_ADDR_T_NONE if there is no such property

void*devfdt_get_addr_ptr(conststructudevice *dev): Return pointer to the address of the reg property of a device

Parameters

const struct udevice *dev: Pointer to a device

Return

Pointer to addr, or NULL if there is no such property

void*devfdt_remap_addr(conststructudevice *dev): Return pointer to the memory-mapped I/O address of the reg property of a device

Parameters

const struct udevice *dev: Pointer to a device

Return

Pointer to addr, or NULL if there is no such property

void*devfdt_remap_addr_index(conststructudevice *dev, intindex): Return indexed pointer to the memory-mapped I/O address of the reg property of a device

Parameters

const struct udevice *dev: Pointer to a device
int index: the ‘reg’ property can hold a list of <addr, size> pairs and index is used to select which one is required

Return

Pointer to addr, or NULL if there is no such property

void*devfdt_remap_addr_name(conststructudevice *dev, constchar*name): Get the reg property of a device, indexed by name, as a memory-mapped I/O pointer

Parameters

const struct udevice *dev: Pointer to a device
const char *name: the ‘reg’ property can hold a list of <addr, size> pairs, with the ‘reg-names’ property providing named-based identification. name indicates the value to search for in ‘reg-names’.

Return

Pointer to addr, or NULL if there is no such property

void*devfdt_map_physmem(conststructudevice *dev, unsignedlongsize): Read device address from reg property of the device node and map the address into CPU address space.

Parameters

const struct udevice *dev: Pointer to device
unsigned long size: size of the memory to map

Return

mapped address, or NULL if the device does not have reg property.

fdt_addr_tdevfdt_get_addr_index(conststructudevice *dev, intindex): Get the indexed reg property of a device

Parameters

const struct udevice *dev: Pointer to a device
int index: the ‘reg’ property can hold a list of <addr, size> pairs and index is used to select which one is required

Return

Address, or FDT_ADDR_T_NONE if there is no such property

void*devfdt_get_addr_index_ptr(conststructudevice *dev, intindex): Return indexed pointer to the address of the reg property of a device

Parameters

const struct udevice *dev: Pointer to a device
int index: the ‘reg’ property can hold a list of <addr, size> pairs and index is used to select which one is required

Return

Pointer to addr, or NULL if there is no such property

fdt_addr_tdevfdt_get_addr_size_index(conststructudevice *dev, intindex, fdt_size_t*size): Get the indexed reg property of a device

Parameters

const struct udevice *dev: Pointer to a device
int index: the ‘reg’ property can hold a list of <addr, size> pairs and index is used to select which one is required
fdt_size_t *size: Pointer to size variable - this function returns the size specified in the ‘reg’ property here

Description

Returns the address and size specified in the ‘reg’ property of a device.

Return

Address, or FDT_ADDR_T_NONE if there is no such property

void*devfdt_get_addr_size_index_ptr(conststructudevice *dev, intindex, fdt_size_t*size): Return indexed pointer to the address of the reg property of a device

Parameters

const struct udevice *dev: Pointer to a device
int index: the ‘reg’ property can hold a list of <addr, size> pairs and index is used to select which one is required
fdt_size_t *size: Pointer to size variable - this function returns the size specified in the ‘reg’ property here

Return

Pointer to addr, or NULL if there is no such property

fdt_addr_tdevfdt_get_addr_name(conststructudevice *dev, constchar*name): Get the reg property of a device, indexed by name

Parameters

const struct udevice *dev: Pointer to a device
const char *name: the ‘reg’ property can hold a list of <addr, size> pairs, with the ‘reg-names’ property providing named-based identification. name indicates the value to search for in ‘reg-names’.

Return

Address, or FDT_ADDR_T_NONE if there is no such property

void*devfdt_get_addr_name_ptr(conststructudevice *dev, constchar*name): Get the reg property of a device as a pointer, indexed by name

Parameters

const struct udevice *dev: Pointer to a device
const char *name: the ‘reg’ property can hold a list of <addr, size> pairs, with the ‘reg-names’ property providing named-based identification. name indicates the value to search for in ‘reg-names’.

Return

Pointer to addr, or NULL if there is no such property

fdt_addr_tdevfdt_get_addr_size_name(conststructudevice *dev, constchar*name, fdt_size_t*size): Get the reg property and its size for a device, indexed by name

Parameters

const struct udevice *dev: Pointer to a device
const char *name: the ‘reg’ property can hold a list of <addr, size> pairs, with the ‘reg-names’ property providing named-based identification. name indicates the value to search for in ‘reg-names’.
fdt_size_t *size: Pointer to size variable - this function returns the size specified in the ‘reg’ property here

Description

Returns the address and size specified in the ‘reg’ property of a device.

Return

Address, or FDT_ADDR_T_NONE if there is no such property

void*devfdt_get_addr_size_name_ptr(conststructudevice *dev, constchar*name, fdt_size_t*size): Get the reg property for a device as a pointer, indexed by name

Parameters

const struct udevice *dev: Pointer to a device
const char *name: the ‘reg’ property can hold a list of <addr, size> pairs, with the ‘reg-names’ property providing named-based identification. name indicates the value to search for in ‘reg-names’.
fdt_size_t *size: Pointer to size variable - this function returns the size specified in the ‘reg’ property here

Description

Returns the address and size specified in the ‘reg’ property of a device.

Return

Pointer to addr, or NULL if there is no such property

fdt_addr_tdevfdt_get_addr_pci(conststructudevice *dev, fdt_size_t*sizep): Read an address and handle PCI address translation

Parameters

const struct udevice *dev: Device to read from
fdt_size_t *sizep: If non-NULL, returns size of address space

Return

address or FDT_ADDR_T_NONE if not found