ofw.h File Reference

#include <rtems.h>
#include <stdint.h>
#include <sys/types.h>

Go to the source code of this file.

Data Structures
struct	rtems_ofw_memory_area
struct	rtems_ofw_ranges

Typedefs
typedef uint32_t	phandle_t
typedef uint32_t	ihandle_t
typedef uint32_t	pcell_t

Functions
phandle_t	rtems_ofw_peer (phandle_t node)
	Gets the node that is next to node.
phandle_t	rtems_ofw_child (phandle_t node)
	Gets the node that is the child of node.
phandle_t	rtems_ofw_parent (phandle_t node)
	Gets the node that is the parent of node.
ssize_t	rtems_ofw_get_prop_len (phandle_t node, const char *propname)
	Gets the length of the property mentioned in propname.
ssize_t	rtems_ofw_get_prop (phandle_t node, const char *propname, void *buf, size_t len)
	Gets the value of property mentioned in propname.
ssize_t	rtems_ofw_get_enc_prop (phandle_t node, const char *prop, pcell_t *buf, size_t len)
	Gets the value of property mentioned in prop.
int	rtems_ofw_has_prop (phandle_t node, const char *propname)
	Checks if the property propname is present in node.
ssize_t	rtems_ofw_search_prop (phandle_t node, const char *propname, void *buf, size_t len)
	Searches for property propname in node.
ssize_t	rtems_ofw_search_enc_prop (phandle_t node, const char *propname, pcell_t *buf, size_t len)
	Searches for property propname in node.
ssize_t	rtems_ofw_get_prop_alloc (phandle_t node, const char *propname, void **buf)
	Gets the value of property mentioned in propname.
ssize_t	rtems_ofw_get_prop_alloc_multi (phandle_t node, const char *propname, int elsz, void **buf)
	Gets multiple values of the property propname.
ssize_t	rtems_ofw_get_enc_prop_alloc (phandle_t node, const char *propname, void **buf)
	Gets the value of property mentioned in propname.
ssize_t	rtems_ofw_get_enc_prop_alloc_multi (phandle_t node, const char *propname, int elsz, void **buf)
	Gets multiple values of the property propname.
void	rtems_ofw_free (void *buf)
	Free's the buffers allocated by the rtems_ofw_*_alloc functions.
int	rtems_ofw_next_prop (phandle_t node, const char *previous, char *buf, size_t len)
	Finds the next property of node.
of @a node to @a buf.
Sets the property Parameters [in] node Node offset [in] name Property name [in] buf Buffer contains the value to be set. [in] len Length of the buffer Return values -1 node does not exist 0 on success libFDT error codes on unsuccessful setting operation
int	rtems_ofw_set_prop (phandle_t node, const char *name, const void *buf, size_t len)
ssize_t	rtems_ofw_canon (const char *dev, char *buf, size_t len)
	Converts a device specifier to a fully qualified path name.
phandle_t	rtems_ofw_find_device (const char *path)
	Finds the node at the given path.
phandle_t	rtems_ofw_node_from_xref (phandle_t xref)
	This routine converts effective phandle xref to node offset.
phandle_t	rtems_ofw_xref_from_node (phandle_t node)
	This routine converts node offset to effective phandle of node.
phandle_t	rtems_ofw_instance_to_package (ihandle_t instance)
	Converts instance handle to phandle.
ssize_t	rtems_ofw_package_to_path (phandle_t node, char *buf, size_t len)
	Find the node's path from phandle.
ssize_t	rtems_ofw_instance_to_path (ihandle_t instance, char *buf, size_t len)
	Find the node's path from ihandle.
int	rtems_ofw_get_reg (phandle_t node, rtems_ofw_memory_area *buf, size_t size)
	Queries the node's reg value.
int	rtems_ofw_get_interrupts (phandle_t node, rtems_vector_number *buf, size_t size)
	Queries the node's interrupt value.
bool	rtems_ofw_node_status (phandle_t node)
	Queries the node's status.
phandle_t	rtems_ofw_find_device_by_compat (const char *compat)
	Gets node phandle from compatible property.
bool	rtems_ofw_is_node_compatible (phandle_t node, const char *compat)
	check a nodes compatible property.

Detailed Description

RTEMS FDT implementation of OpenFirmWare Interface.

RTEMS OFW is a FDT only implementation of the OpenFirmWare interface. This API is created to be compatible with FreeBSD OpenFirmWare interface. The main intention is to make porting of FreeBSD drivers to RTEMS easier.

Typedef Documentation

ihandle_t

typedef uint32_t ihandle_t

Represents the effective phandle of the node.

pcell_t

typedef uint32_t pcell_t

Represents the data type of the buffer.

phandle_t

typedef uint32_t phandle_t

Represents a node in the device tree. The offset from fdtp to node is used instead of fdt offset to make sure this is compatible with OF interface in FreeBSD.

Function Documentation

rtems_ofw_canon()

ssize_t rtems_ofw_canon	(	const char *	dev,
		char *	buf,
		size_t	len
	)

Converts a device specifier to a fully qualified path name.

Parameters

[in]	dev	device specifier
[out]	buf	The path is filled into the buffer(Pre-allocated)
[in]	length	of the buffer

Return values

-1	always. Unimplemented.

rtems_ofw_child()

phandle_t rtems_ofw_child

(

phandle_t

node

)

Gets the node that is the child of node.

Parameters

[in]

node

Node offset

Return values

child	node offset Successful operation.
0	No child node or invalid node handle

rtems_ofw_find_device()

phandle_t rtems_ofw_find_device

(

const char *

path

)

Finds the node at the given path.

Parameters

[in]

path

to the node from root

Return values

-1	node does not exist
node	handle on success

rtems_ofw_find_device_by_compat()

phandle_t rtems_ofw_find_device_by_compat

(

const char *

compat

)

Gets node phandle from compatible property.

This routine is local to RTEMS OFW and does not have an corresponding FreeBSD OFW pair.

Parameters

[in]

compat

Compatible string

Return values

0	Node with compat as compatible string not found
Node	phandle on success.

rtems_ofw_free()

void rtems_ofw_free

(

void *

buf

)

Free's the buffers allocated by the rtems_ofw_*_alloc functions.

Parameters

[in]

buf

Buffer to be freed

rtems_ofw_get_enc_prop()

ssize_t rtems_ofw_get_enc_prop	(	phandle_t	node,
		const char *	prop,
		pcell_t *	buf,
		size_t	len
	)

Gets the value of property mentioned in prop.

Gets the value of property of node and converts the value into the host's endianness.

Parameters

[in]	node	Node offset
[in]	prop	Property name
[out]	buf	The property value gets stored in this buffer(Pre-allocated) after converted to the host's endianness
[in]	len	Length of the buffer

Return values

-1	Invalid node or property
Length	of property on successful operation

rtems_ofw_get_enc_prop_alloc()

ssize_t rtems_ofw_get_enc_prop_alloc	(	phandle_t	node,
		const char *	propname,
		void **	buf
	)

Gets the value of property mentioned in propname.

Same as rtems_ofw_getprop_alloc but the value stored in the buffer is converted into the host's endianness.

Parameters

[in]	node	Node offset
[in]	propname	Property name
[out]	buf	The buffer is allocated in this routine and user is responsible for freeing.

Return values

-1	Property is not found.
Length	of the property if property is found.

rtems_ofw_get_enc_prop_alloc_multi()

ssize_t rtems_ofw_get_enc_prop_alloc_multi	(	phandle_t	node,
		const char *	propname,
		int	elsz,
		void **	buf
	)

Gets multiple values of the property propname.

Same as rtems_ofw_getprop_alloc_multi but the values stored in the buffer are converted to the host's endianness.

Parameters

[in]	node	Node offset
[in]	propname	Property name
[in]	elsz	Size of the single value
[out]	buf	The buffer is allocated in this routine and user is responsible for freeing.

Return values

-1	Property is not found.
Number	of values read.

rtems_ofw_get_interrupts()

int rtems_ofw_get_interrupts	(	phandle_t	node,
		rtems_vector_number *	buf,
		size_t	size
	)

Queries the node's interrupt value.

This routine fills the buffer buf with the interrupt number. In case of multiple numbers it fills the buffer to its full extent. This routine is local to RTEMS OFW and does not have an corresponding FreeBSD OFW pair.

Parameters

[in]	node	Node offset
[out]	buf	Interrupt values are stored in this buffer(Pre-allocated).
[in]	size	Length of the buffer.

Return values

-1	If interrupts property is missing.
The	number of interrupt numbers read.

rtems_ofw_get_prop()

ssize_t rtems_ofw_get_prop	(	phandle_t	node,
		const char *	propname,
		void *	buf,
		size_t	len
	)

Gets the value of property mentioned in propname.

Parameters

[in]	node	Node offset
[in]	prop	Property name
[out]	buf	The property value gets stored in this buffer (Pre-allocated)
[in]	len	Length of the buffer

Return values

-1	Invalid node or property
Length	of property on successful operation

rtems_ofw_get_prop_alloc()

ssize_t rtems_ofw_get_prop_alloc	(	phandle_t	node,
		const char *	propname,
		void **	buf
	)

Gets the value of property mentioned in propname.

Same as rtems_ofw_getprop, but the buf is allocated in this routine and the user is responsible for freeing it.

Parameters

[in]	node	Node offset
[in]	propname	Property name
[out]	buf	The buffer is allocated in this routine and user is responsible for freeing.

Return values

-1	Property is not found.
Length	of the property if property is found.

rtems_ofw_get_prop_alloc_multi()

ssize_t rtems_ofw_get_prop_alloc_multi	(	phandle_t	node,
		const char *	propname,
		int	elsz,
		void **	buf
	)

Gets multiple values of the property propname.

Same as rtems_ofw_getprop_alloc but it can read properties with multiple values. For eg: reg = <0x1000 0x10 0x2000 0x20>

Parameters

[in]	node	Node offset
[in]	propname	Property name
[in]	elsz	Size of the single value
[out]	buf	The buffer is allocated in this routine and user is responsible for freeing.

Return values

-1	Property is not found.
Number	of values read.

rtems_ofw_get_prop_len()

ssize_t rtems_ofw_get_prop_len	(	phandle_t	node,
		const char *	propname
	)

Gets the length of the property mentioned in propname.

Parameters

[in]	node	Node offset
[in]	prop	Property name

Return values

-1	Invalid node or property
Length	of property on successful operation

rtems_ofw_get_reg()

int rtems_ofw_get_reg	(	phandle_t	node,
		rtems_ofw_memory_area *	buf,
		size_t	size
	)

Queries the node's reg value.

This routine fills the buffer buf with the values in reg property of node node. It reads all the values of the property and fills the buffer to max size. This routine is local to RTEMS OFW and does not have an corresponding FreeBSD OFW pair.

Parameters

[in]	node	Node offset
[out]	buf	Register values are stored in this buffer(Pre-allocated).
[in]	size	Length of the buffer.

Return values

-1	If reg property is missing.
Length	of the reg property in bytes.

(buf + size - (sizeof(buf[0]) - 1) is the last valid address for buf[i]. If buf[i] points to any address larger than this, it will be an out of bound access

rtems_ofw_has_prop()

int rtems_ofw_has_prop	(	phandle_t	node,
		const char *	propname
	)

Checks if the property propname is present in node.

Parameters

[in]	node	Node offset
[in]	propname	Property name

Return values

0	Property not present.
1	Property is present.

rtems_ofw_instance_to_package()

phandle_t rtems_ofw_instance_to_package

(

ihandle_t

instance

)

Converts instance handle to phandle.

instance are same as node offsets in FDT.

Parameters

[in]

instance

Node offset

Return values

phandle	of node on success.
instance	of node on failure.

rtems_ofw_instance_to_path()

ssize_t rtems_ofw_instance_to_path	(	ihandle_t	instance,
		char *	buf,
		size_t	len
	)

Find the node's path from ihandle.

Parameters

[in]	instance	Node offset
[out]	buf	Path is filled into this buffer(Pre-allocated).
[in]	len	Length of the buffer.

Return values

-1	always. Unimplemented.

rtems_ofw_is_node_compatible()

bool rtems_ofw_is_node_compatible	(	phandle_t	node,
		const char *	compat
	)

check a nodes compatible property.

This routine is local to RTEMS OFW and does not have an corresponding FreeBSD OFW pair.

Return true if compat equals node compatible property

Parameters

[in]	node	phandle of node
[in]	compat	Compatible string

Return values

1	If node contains the compat as a element in compatible property.
0	Otherwise.

rtems_ofw_next_prop()

int rtems_ofw_next_prop	(	phandle_t	node,
		const char *	previous,
		char *	buf,
		size_t	len
	)

Finds the next property of node.

Finds the next property of the node and when propname is NULL it returns the value in the first property.

Parameters

[in]	node	Node offset
[in]	previous	Previous property name
[out]	buf	The value of the next property gets stored in this buffer (Pre-allocated)
[in]	len	Length of the buffer

Return values

-1	node or previous property does not exist
0	no more properties
1	success

rtems_ofw_node_from_xref()

phandle_t rtems_ofw_node_from_xref

(

phandle_t

xref

)

This routine converts effective phandle xref to node offset.

Parameters

[in]

xref

Node phandle

Return values

Node	offset on success
Node	phandle on failure

rtems_ofw_node_status()

bool rtems_ofw_node_status

(

phandle_t

node

)

Queries the node's status.

This routine is local to RTEMS OFW and does not have an corresponding FreeBSD OFW pair.

Parameters

[in]

node

Node offset

Return values

true	Status is OK or empty.
false	Status is not OK or missing.

rtems_ofw_package_to_path()

ssize_t rtems_ofw_package_to_path	(	phandle_t	node,
		char *	buf,
		size_t	len
	)

Find the node's path from phandle.

Parameters

[in]	node	Node offset
[out]	buf	Path is filled into this buffer(Pre-allocated).
[in]	len	Length of the buffer.

Return values

-1	always. Unimplemented.

rtems_ofw_parent()

phandle_t rtems_ofw_parent

(

phandle_t

node

)

Gets the node that is the parent of node.

Parameters

[in]

node

Node offset

Return values

child	node offset Successful operation.
0	No child node or invalid node handle

rtems_ofw_peer()

phandle_t rtems_ofw_peer

(

phandle_t

node

)

Gets the node that is next to node.

Parameters

[in]

node

Node offset

Return values

Peer	node offset Successful operation.
0	No peer node or invalid node handle

rtems_ofw_search_enc_prop()

ssize_t rtems_ofw_search_enc_prop	(	phandle_t	node,
		const char *	propname,
		pcell_t *	buf,
		size_t	len
	)

Searches for property propname in node.

Searches the node and its parent recursively for the property and fills the buffer with the first value found after converting it to the endianness of the host.

Parameters

[in]	node	Node offset
[in]	propname	Property name
[out]	buf	The property value gets stored in this buffer(Pre-allocated) after converted to the host's endianness
[in]	len	Length of the buffer

Return values

Length	of the property if property is found.
-1	Property is not found.

rtems_ofw_search_prop()

ssize_t rtems_ofw_search_prop	(	phandle_t	node,
		const char *	propname,
		void *	buf,
		size_t	len
	)

Searches for property propname in node.

Searches the node and its parent recursively for the property and fills the buffer with the first found value.

Parameters

[in]	node	Node offset
[in]	propname	Property name
[out]	buf	The property value gets stored in this buffer (Pre-allocated)
[in]	len	Length of the buffer

Return values

Length	of the property if property is found.
-1	Property is not found.

rtems_ofw_xref_from_node()

phandle_t rtems_ofw_xref_from_node

(

phandle_t

node

)

This routine converts node offset to effective phandle of node.

Return values

Node	phandle on success
Node	offset on failure