Driver Model

Uclass and Driver

struct uclass

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.

struct uclass_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(const struct uclass *uc)

Get the private data for a uclass

Parameters

const struct uclass *uc

Uclass to check

Return

private data, or NULL if none

int uclass_get(enum uclass_id key, struct uclass **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

const char *uclass_get_name(enum uclass_id id)

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

enum uclass_id uclass_get_by_namelen(const char *name, int len)

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

enum uclass_id uclass_get_by_name(const char *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

int uclass_get_device(enum uclass_id id, int index, struct udevice **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

int uclass_get_device_by_name(enum uclass_id id, const char *name, struct udevice **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

int uclass_get_device_by_seq(enum uclass_id id, int seq, struct udevice **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

int uclass_get_device_by_of_offset(enum uclass_id id, int node, struct udevice **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

int uclass_get_device_by_ofnode(enum uclass_id id, ofnode node, struct udevice **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

int uclass_get_device_by_phandle_id(enum uclass_id id, uint phandle_id, struct udevice **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

int uclass_get_device_by_phandle(enum uclass_id id, struct udevice *parent, const char *name, struct udevice **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

int uclass_get_device_by_driver(enum uclass_id id, const struct driver *drv, struct udevice **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

void uclass_first_device(enum uclass_id id, struct udevice **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.

void uclass_next_device(struct udevice **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.

int uclass_first_device_err(enum uclass_id id, struct udevice **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

int uclass_next_device_err(struct udevice **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

int uclass_first_device_check(enum uclass_id id, struct udevice **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.

int uclass_next_device_check(struct udevice **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.

int uclass_first_device_drvdata(enum uclass_id id, ulong driver_data, struct udevice **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

int uclass_probe_all(enum uclass_id id)

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

int uclass_id_count(enum uclass_id id)

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.

struct dm_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

struct udevice *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

void dm_fixup_for_gd_move(struct global_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.

int dm_scan_plat(bool pre_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

int dm_scan_fdt(bool pre_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

int dm_extended_scan(bool pre_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

int dm_scan_other(bool pre_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

int dm_init_and_scan(bool pre_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

int dm_init(bool of_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

int dm_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

int dm_remove_devices_flags(uint flags)

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

void dm_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

void dm_get_mem(struct dm_stats *stats)

Get stats on memory usage in driver model

Parameters

struct dm_stats *stats

Place to put the information

struct driver *lists_driver_lookup_name(const char *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

struct uclass_driver *lists_uclass_lookup(enum uclass_id id)

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.

int lists_bind_drivers(struct udevice *parent, bool pre_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.

int lists_bind_fdt(struct udevice *parent, ofnode node, struct udevice **devp, struct driver *drv, bool pre_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

int device_bind_driver(struct udevice *parent, const char *drv_name, const char *dev_name, struct udevice **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

int device_bind_driver_to_node(struct udevice *parent, const char *drv_name, const char *dev_name, ofnode node, struct udevice **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

struct driver_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.

struct driver_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

struct udevice

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.

struct udevice_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__ ofnode dev_ofnode(const struct udevice *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

struct udevice_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

struct driver

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_FLAGS_…

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(const struct udevice *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(const struct udevice *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(const struct udevice *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(const struct udevice *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(const struct udevice *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(const struct udevice *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(const struct udevice *dev, enum dm_tag_t tag)

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

int dev_get_attach_size(const struct udevice *dev, enum dm_tag_t tag)

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

struct udevice *dev_get_parent(const struct udevice *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

ulong dev_get_driver_data(const struct udevice *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)

const void *dev_get_driver_ops(const struct udevice *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

enum uclass_id device_get_uclass_id(const struct udevice *dev)

return the uclass ID of a device

Parameters

const struct udevice *dev

Device to check

Return

uclass ID for the device

const char *dev_get_uclass_name(const struct udevice *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

int device_get_child(const struct udevice *parent, int index, struct udevice **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

int device_get_child_count(const struct udevice *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.

int device_get_decendent_count(const struct udevice *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

int device_find_child_by_seq(const struct udevice *parent, int seq, struct udevice **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

int device_get_child_by_seq(const struct udevice *parent, int seq, struct udevice **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

int device_find_child_by_of_offset(const struct udevice *parent, int of_offset, struct udevice **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

int device_get_child_by_of_offset(const struct udevice *parent, int of_offset, struct udevice **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

int device_find_global_by_ofnode(ofnode node, struct udevice **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

int device_get_global_by_ofnode(ofnode node, struct udevice **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

int device_get_by_ofplat_idx(uint idx, struct udevice **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

int device_find_first_child(const struct udevice *parent, struct udevice **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

0

int device_find_next_child(struct udevice **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

0

int device_find_first_inactive_child(const struct udevice *parent, enum uclass_id uclass_id, struct udevice **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

int device_find_first_child_by_uclass(const struct udevice *parent, enum uclass_id uclass_id, struct udevice **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

int device_find_child_by_namelen(const struct udevice *parent, const char *name, int len, struct udevice **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

int device_find_child_by_name(const struct udevice *parent, const char *name, struct udevice **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

int device_first_child_ofdata_err(struct udevice *parent, struct udevice **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

int device_first_child_err(struct udevice *parent, struct udevice **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

int device_next_child_err(struct udevice **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

bool device_has_children(const struct udevice *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

bool device_has_active_children(const struct udevice *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).

bool device_is_last_sibling(const struct udevice *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.

int device_set_name(struct udevice *dev, const char *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

void device_set_name_alloced(struct udevice *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.

bool device_is_compatible(const struct udevice *dev, const char *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

bool of_machine_is_compatible(const char *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

int dev_disable_by_path(const char *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

int dev_enable_by_path(const char *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

bool device_is_on_pci_bus(const struct udevice *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

int dm_scan_fdt_dev(struct udevice *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 u-boot,dm-pre-reloc 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

struct devres_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.

void devres_free(void *res)

Free device resource data

Parameters

void *res

Pointer to devres data to free

Description

Free devres created with devres_alloc().

void devres_add(struct udevice *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(struct udevice *dev, dr_release_t release, dr_match_t match, 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(struct udevice *dev, void *new_res, dr_match_t match, 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(struct udevice *dev, dr_release_t release, dr_match_t match, 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.

int devres_destroy(struct udevice *dev, dr_release_t release, dr_match_t match, 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

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 freed.

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.

int devres_release(struct udevice *dev, dr_release_t release, dr_match_t match, 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

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, the release function called and the resource freed.

Return

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

void *devm_kmalloc(struct udevice *dev, size_t size, gfp_t gfp)

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.

void devm_kfree(struct udevice *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().

int dev_read_u8(const struct udevice *dev, const char *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

u8 dev_read_u8_default(const struct udevice *dev, const char *propname, u8 def)

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

int dev_read_u16(const struct udevice *dev, const char *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

u16 dev_read_u16_default(const struct udevice *dev, const char *propname, u16 def)

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

int dev_read_u32(const struct udevice *dev, const char *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

int dev_read_u32_default(const struct udevice *dev, const char *propname, int def)

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

int dev_read_u32_index(struct udevice *dev, const char *propname, int index, 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

u32 dev_read_u32_index_default(struct udevice *dev, const char *propname, int index, u32 def)

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

int dev_read_s32(const struct udevice *dev, const char *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

int dev_read_s32_default(const struct udevice *dev, const char *propname, int def)

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

int dev_read_u32u(const struct udevice *dev, const char *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

int dev_read_u64(const struct udevice *dev, const char *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

u64 dev_read_u64_default(const struct udevice *dev, const char *propname, u64 def)

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

const char *dev_read_string(const struct udevice *dev, const char *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

bool dev_read_bool(const struct udevice *dev, const char *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

ofnode dev_read_subnode(const struct udevice *dev, const char *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)

int dev_read_size(const struct udevice *dev, const char *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_t dev_read_addr_index(const struct udevice *dev, int index)

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(const struct udevice *dev, int index)

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_t dev_read_addr_size_index(const struct udevice *dev, int index, 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_remap_addr_index(const struct udevice *dev, int index)

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_t dev_read_addr_name(const struct udevice *dev, const char *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. index indicates the value to search for in ‘reg-names’.

Return

address or FDT_ADDR_T_NONE if not found

fdt_addr_t dev_read_addr_size_name(const struct udevice *dev, const char *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. index 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_remap_addr_name(const struct udevice *dev, const char *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. index indicates the value to search for in ‘reg-names’.

Return

pointer or NULL if not found

fdt_addr_t dev_read_addr(const struct udevice *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(const struct udevice *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_t dev_read_addr_pci(const struct udevice *dev)

Read an address and handle PCI address translation

Parameters

const struct udevice *dev

Device to read from

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:

  1. PCI address translation is added; and either

  2. 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(const struct udevice *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_t dev_read_addr_size(const struct udevice *dev, const char *propname, fdt_size_t *sizep)

get address and size from a device property

Parameters

const struct udevice *dev

Device 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

const char *dev_read_name(const struct udevice *dev)

get the name of a device’s node

Parameters

const struct udevice *dev

Device to read from

Return

name of node

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

int dev_read_string_index(const struct udevice *dev, const char *propname, int index, const char **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

int dev_read_string_count(const struct udevice *dev, const char *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

int dev_read_string_list(const struct udevice *dev, const char *propname, const char ***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

int dev_read_phandle_with_args(const struct udevice *dev, const char *list_name, const char *cells_name, int cell_count, int index, struct ofnode_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.

int dev_count_phandle_with_args(const struct udevice *dev, const char *list_name, const char *cells_name, int cell_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.

int dev_read_addr_cells(const struct udevice *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

int dev_read_size_cells(const struct udevice *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

int dev_read_simple_addr_cells(const struct udevice *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

int dev_read_simple_size_cells(const struct udevice *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

int dev_read_phandle(const struct udevice *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

const void *dev_read_prop(const struct udevice *dev, const char *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

int dev_read_first_prop(const struct udevice *dev, struct ofprop *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

int dev_read_next_prop(struct ofprop *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

const void *dev_read_prop_by_prop(struct ofprop *prop, const char **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

int dev_read_alias_seq(const struct udevice *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

int dev_read_u32_array(const struct udevice *dev, const char *propname, u32 *out_values, size_t sz)

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.

ofnode dev_read_first_subnode(const struct udevice *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)

ofnode dev_read_next_subnode(ofnode node)

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)

const uint8_t *dev_read_u8_array_ptr(const struct udevice *dev, const char *propname, size_t sz)

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

int dev_read_enabled(const struct udevice *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)

int dev_read_resource(const struct udevice *dev, uint index, struct resource *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

int dev_read_resource_byname(const struct udevice *dev, const char *name, struct resource *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

u64 dev_translate_address(const struct udevice *dev, const fdt32_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

u64 dev_translate_dma_address(const struct udevice *dev, const fdt32_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

int dev_get_dma_range(const struct udevice *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

int dev_read_alias_highest_id(const char *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

int dev_get_child_count(const struct udevice *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

int dev_read_pci_bus_range(const struct udevice *dev, struct resource *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

int dev_decode_display_timing(const struct udevice *dev, int index, struct display_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

int dev_decode_panel_timing(const struct udevice *dev, struct display_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

ofnode dev_get_phy_node(const struct udevice *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_t dev_read_phy_mode(const struct udevice *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

struct property

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

struct device_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.

struct of_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.

bool of_live_active(void)

check if livetree is active

Parameters

void

no arguments

Description

returns true if livetree is active, false it not

void oftree_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(ofnode node)

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__ int ofnode_to_offset(ofnode node)

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)

oftree oftree_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

ofnode noffset_to_ofnode(ofnode other_node, int of_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

struct device_node *ofnode_to_np(ofnode node)

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)

bool ofnode_valid(ofnode node)

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(oftree tree)

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

ofnode offset_to_ofnode(int of_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

ofnode np_to_ofnode(struct device_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

bool ofnode_is_np(ofnode node)

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

bool ofnode_equal(ofnode ref1, ofnode ref2)

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

bool oftree_valid(oftree tree)

check if an oftree is valid

Parameters

oftree tree

Reference containing oftree

Return

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

oftree oftree_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.

ofnode ofnode_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.

bool ofprop_valid(struct ofprop *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

oftree oftree_default(void)

Returns the default device tree (U-Boot’s control FDT)

Parameters

void

no arguments

Return

reference to the control FDT

oftree oftree_from_np(struct device_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

bool ofnode_name_eq(ofnode node, const char *name)

Check if the node name is equivalent to a given name ignoring the unit address

Parameters

ofnode node

valid node reference that has to be compared

const char *name

name that has to be compared with the node name

Return

true if matches, false if it doesn’t match

int ofnode_read_u8(ofnode node, const char *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

u8 ofnode_read_u8_default(ofnode node, const char *propname, u8 def)

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

int ofnode_read_u16(ofnode node, const char *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

u16 ofnode_read_u16_default(ofnode node, const char *propname, u16 def)

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

int ofnode_read_u32(ofnode node, const char *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

int ofnode_read_u32_index(ofnode node, const char *propname, int index, 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

int ofnode_read_s32(ofnode node, const char *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

u32 ofnode_read_u32_default(ofnode node, const char *propname, u32 def)

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

u32 ofnode_read_u32_index_default(ofnode node, const char *propname, int index, u32 def)

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

int ofnode_read_s32_default(ofnode node, const char *propname, s32 def)

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

int ofnode_read_u64(ofnode node, const char *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

u64 ofnode_read_u64_default(ofnode node, const char *propname, u64 def)

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

const void *ofnode_read_prop(ofnode node, const char *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

const char *ofnode_read_string(ofnode node, const char *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

int ofnode_read_u32_array(ofnode node, const char *propname, u32 *out_values, size_t sz)

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.

bool ofnode_read_bool(ofnode node, const char *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

ofnode ofnode_find_subnode(ofnode node, const char *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)

bool ofnode_is_enabled(ofnode node)

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)

ofnode ofnode_first_subnode(ofnode node)

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)

ofnode ofnode_next_subnode(ofnode node)

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)

ofnode ofnode_get_parent(ofnode node)

get the ofnode’s parent (enclosing ofnode)

Parameters

ofnode node

valid node to look up

Return

ofnode reference of the parent node

const char *ofnode_get_name(ofnode node)

get the name of a node

Parameters

ofnode node

valid node to look up

Return

name of node (for the root node this is “”)

int ofnode_get_path(ofnode node, char *buf, int buflen)

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

ofnode ofnode_get_by_phandle(uint phandle)

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

ofnode oftree_get_by_phandle(oftree tree, uint phandle)

get ofnode from phandle

Parameters

oftree tree

tree to use

uint phandle

phandle to look up

Return

ofnode reference to the phandle

int ofnode_read_size(ofnode node, const char *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

phys_addr_t ofnode_get_addr_size_index(ofnode node, int index, 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

phys_addr_t ofnode_get_addr_size_index_notrans(ofnode node, int index, 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

phys_addr_t ofnode_get_addr_index(ofnode node, int index)

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

phys_addr_t ofnode_get_addr(ofnode node)

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_t ofnode_get_size(ofnode node)

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

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

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

int ofnode_read_string_index(ofnode node, const char *propname, int index, const char **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

int ofnode_read_string_count(ofnode node, const char *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

int ofnode_read_string_list(ofnode node, const char *property, const char ***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}.

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, -EINVAL if no such property, -EENODATA if property is empty

int ofnode_parse_phandle_with_args(ofnode node, const char *list_name, const char *cells_name, int cell_count, int index, struct ofnode_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.

int ofnode_count_phandle_with_args(ofnode node, const char *list_name, const char *cells_name, int cell_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.

ofnode ofnode_path(const char *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

ofnode oftree_path(oftree tree, const char *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

ofnode oftree_root(oftree tree)

get the root node of a tree

Parameters

oftree tree

Device tree to use

Return

reference to the root node

const void *ofnode_read_chosen_prop(const char *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

const char *ofnode_read_chosen_string(const char *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

ofnode ofnode_get_chosen_node(const char *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()

const void *ofnode_read_aliases_prop(const char *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

This only works with the control FDT.

Return

property value if found, else NULL

ofnode ofnode_get_aliases_node(const char *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()

int ofnode_decode_display_timing(ofnode node, int index, struct display_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

int ofnode_decode_panel_timing(ofnode node, struct display_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

const void *ofnode_get_property(ofnode node, const char *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, or NULL if not found

int ofnode_first_property(ofnode node, struct ofprop *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

int ofnode_next_property(struct ofprop *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.

const void *ofprop_get_property(const struct ofprop *prop, const char **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

phys_addr_t ofnode_get_addr_size(ofnode node, const char *propname, phys_size_t *sizep)

get address and size from a property

Parameters

ofnode node

node to read from

const char *propname

property to read

phys_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

const uint8_t *ofnode_read_u8_array_ptr(ofnode node, const char *propname, size_t sz)

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

int ofnode_read_pci_addr(ofnode node, enum fdt_pci_space type, const char *propname, struct fdt_pci_addr *addr)

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

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

int ofnode_read_pci_vendev(ofnode node, 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

int ofnode_read_eth_phy_id(ofnode node, 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

int ofnode_read_addr_cells(ofnode node)

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

int ofnode_read_size_cells(ofnode node)

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

int ofnode_read_simple_addr_cells(ofnode node)

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

int ofnode_read_simple_size_cells(ofnode node)

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

bool ofnode_pre_reloc(ofnode node)

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 - u-boot,dm-pre-proper: U-Boot proper pre-relocation only - u-boot,dm-pre-reloc: legacy and indicates any of TPL or SPL Existing platforms only use it to indicate nodes needed in SPL. Should probably be replaced by u-boot,dm-spl for new platforms. - u-boot,dm-spl: SPL and U-Boot pre-relocation - u-boot,dm-tpl: TPL and U-Boot pre-relocation

Return

true if node is needed in SPL/TL, false otherwise

int ofnode_read_resource(ofnode node, uint index, struct resource *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

int ofnode_read_resource_byname(ofnode node, const char *name, struct resource *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

ofnode ofnode_by_compatible(ofnode from, const char *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

ofnode ofnode_by_prop_value(ofnode from, const char *propname, const void *propval, int proplen)

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.

int ofnode_get_child_count(ofnode parent)

get the child count of a ofnode

Parameters

ofnode parent

valid node to get its child count

Return

the number of subnodes

u64 ofnode_translate_address(ofnode node, const fdt32_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

u64 ofnode_translate_dma_address(ofnode node, const fdt32_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

int ofnode_get_dma_range(ofnode node, 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

int ofnode_device_is_compatible(ofnode node, const char *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

int ofnode_write_prop(ofnode node, const char *propname, const void *value, int len, bool copy)

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

int ofnode_write_string(ofnode node, const char *propname, const char *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

int ofnode_write_u32(ofnode node, const char *propname, u32 value)

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

int ofnode_set_enabled(ofnode node, bool value)

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

ofnode ofnode_get_phy_node(ofnode eth_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_t ofnode_read_phy_mode(ofnode mac_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

bool ofnode_conf_read_bool(const char *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

int ofnode_conf_read_int(const char *prop_name, int default_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

const char *ofnode_conf_read_str(const char *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

int ofnode_add_subnode(ofnode parent, const char *name, ofnode *nodep)

add a new subnode to a node

Parameters

ofnode parent

parent node to add to

const char *name

name of subnode

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

int ofnode_copy_props(ofnode src, ofnode dst)

copy all properties from one node to another

Parameters

ofnode src

Source node to read properties from

ofnode dst

Destination node to write properties too

Description

Makes a copy of all properties from the source note in 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.

int ofnode_read_fmap_entry(ofnode node, struct fmap_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

int ofnode_decode_region(ofnode node, const char *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)

int ofnode_decode_memory_region(ofnode config_node, const char *mem_type, const char *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

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

bool ofnode_eth_uses_inband_aneg(ofnode eth_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

struct device_node *of_find_all_nodes(struct device_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.

int of_n_addr_cells(const struct device_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

int of_n_size_cells(const struct device_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

int of_simple_addr_cells(const struct device_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

int of_simple_size_cells(const struct device_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

struct property *of_find_property(const struct device_node *np, const char *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

const void *of_get_property(const struct device_node *np, const char *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

const struct property *of_get_first_property(const struct device_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

const struct property *of_get_next_property(const struct device_node *np, const struct property *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

const void *of_get_property_by_prop(const struct device_node *np, const struct property *property, const char **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

int of_device_is_compatible(const struct device_node *np, const char *compat, const char *type, const char *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.

  1. specific compatible && type && name

  2. specific compatible && type

  3. specific compatible && name

  4. specific compatible

  5. general compatible && type && name

  6. general compatible && type

  7. general compatible && name

  8. general compatible

  9. type && name

  10. type

  11. 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:

bool of_device_is_available(const struct device_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

struct device_node *of_get_parent(const struct device_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

struct device_node *of_find_node_opts_by_path(struct device_node *root, const char *path, const char **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

struct device_node *of_find_compatible_node(struct device_node *from, const char *type, const char *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

struct device_node *of_find_node_by_prop_value(struct device_node *from, const char *propname, const void *propval, int proplen)

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

struct device_node *of_find_node_by_phandle(struct device_node *root, phandle handle)

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

int of_read_u8(const struct device_node *np, const char *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.

int of_read_u16(const struct device_node *np, const char *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.

int of_read_u32(const struct device_node *np, const char *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.

int of_read_u32_index(const struct device_node *np, const char *propname, int index, 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.

int of_read_u64(const struct device_node *np, const char *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.

int of_read_u32_array(const struct device_node *np, const char *propname, u32 *out_values, size_t sz)

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.

int of_property_match_string(const struct device_node *np, const char *propname, const char *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.

int of_property_read_string_index(const struct device_node *np, const char *propname, int index, const char **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.

int of_property_count_strings(const struct device_node *np, const char *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.

struct device_node *of_parse_phandle(const struct device_node *np, const char *phandle_name, int index)

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.

int of_parse_phandle_with_args(const struct device_node *np, const char *list_name, const char *cells_name, int cells_count, int index, struct of_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

int of_count_phandle_with_args(const struct device_node *np, const char *list_name, const char *cells_name, int cells_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.

int of_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

int of_alias_get_id(const struct device_node *np, const char *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

int of_alias_get_highest_id(const char *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

struct device_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

int of_write_prop(struct device_node *np, const char *propname, int len, const void *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

int of_add_subnode(struct device_node *node, const char *name, int len, struct device_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

u64 of_translate_address(const struct device_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

u64 of_translate_dma_address(const struct device_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

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 DMA address or OF_BAD_ADDR on error

int of_get_dma_range(const struct device_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(const struct device_node *np, int index, u64 *size, unsigned int *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

int of_address_to_resource(const struct device_node *np, int index, struct resource *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_t devfdt_get_addr(const struct udevice *dev)

Get the reg property of a device

Parameters

const struct udevice *dev

Pointer to a device

Return

addr

void *devfdt_get_addr_ptr(const struct udevice *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(const struct udevice *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(const struct udevice *dev, int index)

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(const struct udevice *dev, const char *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. index 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(const struct udevice *dev, unsigned long size)

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_t devfdt_get_addr_index(const struct udevice *dev, int index)

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

addr

void *devfdt_get_addr_index_ptr(const struct udevice *dev, int index)

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_t devfdt_get_addr_size_index(const struct udevice *dev, int index, 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 varible - 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

addr

fdt_addr_t devfdt_get_addr_name(const struct udevice *dev, const char *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. index indicates the value to search for in ‘reg-names’.

Return

addr

fdt_addr_t devfdt_get_addr_size_name(const struct udevice *dev, const char *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. index 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

addr

fdt_addr_t devfdt_get_addr_pci(const struct udevice *dev)

Read an address and handle PCI address translation

Parameters

const struct udevice *dev

Device to read from

Return

address or FDT_ADDR_T_NONE if not found