Differential D14511 Diff 39726 share/man/man9/OF_getprop.9

Changeset View

Standalone View

share/man/man9/OF_getprop.9

This file was added.

				.\"
				.\" Copyright (c) 2018 Oleksandr Tymoshenko <gonzo@FreeBSD.org>
				.\"
				.\" All rights reserved.
				.\"
				.\" Redistribution and use in source and binary forms, with or without
				.\" modification, are permitted provided that the following conditions
				.\" are met:
				.\" 1. Redistributions of source code must retain the above copyright
				.\" notice, this list of conditions and the following disclaimer.
				.\" 2. Redistributions in binary form must reproduce the above copyright
				.\" notice, this list of conditions and the following disclaimer in the
				.\" documentation and/or other materials provided with the distribution.
				.\"
				.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
				.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
				.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
				.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
				.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
				.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
				.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
				.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
				.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
				.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
				.\"
				.\" $FreeBSD$
				.\"
				.Dd February 25, 2018
				.Dt OF_CHILD 9
				.Os
				.Sh NAME
				.Nm OF_getprop ,
				.Nm OF_getproplen ,
				.Nm OF_getencprop ,
				.Nm OF_hasprop ,
				.Nm OF_searchprop ,
				.Nm OF_searchencprop ,
				.Nm OF_getprop_alloc ,
				.Nm OF_getencprop_alloc ,
				.Nm OF_prop_free ,
				.Nm OF_nextprop ,
				.Nm OF_setprop
				.Nd access properties of device tree node
				.Sh SYNOPSIS
				.In dev/ofw/ofw_bus.h
				.In dev/ofw/ofw_bus_subr.h
				.Ft ssize_t
				.Fn OF_getproplen "phandle_t node" "const char *propname"
				.Ft ssize_t
				.Fn OF_getprop "phandle_t node" "const char *propname" \
				"void *buf" "size_t len"
				.Ft ssize_t
				.Fn OF_getencprop "phandle_t node" "const char *prop" \
				"pcell_t *buf" "size_t len"
				.Ft int
				.Fn OF_hasprop "phandle_t node" "const char *propname"
				.Ft ssize_t
				.Fn OF_searchprop "phandle_t node" "const char *propname" \
				"void *buf" "size_t len"
				.Ft ssize_t
				.Fn OF_searchencprop "phandle_t node" "const char *propname" \
				"pcell_t *buf" "size_t len"
				.Ft ssize_t
				.Fn OF_getprop_alloc "phandle_t node" "const char *propname" \
				"void **buf"
				.Ft ssize_t
				.Fn OF_getencprop_alloc "phandle_t node" "const char *propname" \
				"pcell_t **buf"
				.Ft void
				.Fn OF_prop_free "void *buf"
				.Ft int
				.Fn OF_nextprop "phandle_t node" "const char *propname" \
				"char *buf" "size_t len"
				.Ft int
				.Fn OF_setprop "phandle_t node" "const char *propname" \
				"const void *buf" "size_t len"
				.Sh DESCRIPTION
				.Pp
				Device nodes can have properties associated with them.
				wblockUnsubmitted Done Inline Actions Device nodes can have associated properties. wblock: ```Device nodes can have associated properties.```
				Properties consist of name and value.
				wblockUnsubmitted Done Inline Actions Properties consist of a name and a value. wblock: ```Properties consist of a name and a value.```
				A name is a human-readable string from 1 to 31 characters long.
				Value is an array of zero or more bytes that encode certain
				wblockUnsubmitted Done Inline Actions A value is an array of zero or more bytes that encode certain wblock: ```A value is an array of zero or more bytes that encode certain```
				information.
				The meaning of that bytes depends on how drivers interpret them.
				Properties can encode byte arrays, text strings, unsigned 32-bit
				values or combination of any of these types.
				wblockUnsubmitted Done Inline Actions values or any combination of these types. wblock: ```values or any combination of these types.```
				.Pp
				Property with zero bytes long value usually represents boolean
				wblockUnsubmitted Done Inline Actions Properties with a zero-byte length value usually represent boolean Is the length being a byte value relevant if it is zero? Could we just say Properties with a zero-length value usually represent boolean wblock: ```Properties with a zero-byte length value usually represent boolean``` Is the length being a…
				information.
				If the property is present, it signifies true, otherwise false.
				.Pp
				A byte array is encoded as a sequence of its bytes and represents
				wblockUnsubmitted Done Inline Actions Possessive adds no value here: A byte array is encoded as a sequence of bytes and represents wblock: Possessive adds no value here: ```A byte array is encoded as a sequence of bytes and…
				values like MAC addresses.
				.Pp
				A text string is a sequence of n printable characters. It is
				wblockUnsubmitted Done Inline Actions A text string is a sequence of n printable characters. It is wblock: ```A text string is a sequence of n printable characters. It is```
				encoded as a byte array of length n + 1 bytes with
				characters represented as bytes plus terminating null character.
				wblockUnsubmitted Done Inline Actions characters represented as bytes plus a terminating null character. wblock: ```characters represented as bytes plus a terminating null character.```
				.Pp
				Unsigned 32-bit values, also sometimes called cells, are
				encoded as a sequence of 4 bytes in big-endian order.
				.Pp
				.Fn OF_getproplen
				returns either the length of the value associated with the property
				.Fa propname
				in the node identified by
				.Fa node ,
				or 0 if the property exists but has no value associated with it
				wblockUnsubmitted Done Inline Actions or 0 if the property exists but has no associated value. wblock: ```or 0 if the property exists but has no associated value.```
				or -1 if the property
				wblockUnsubmitted Done Inline Actions If .Fa propname does not exist, -1 is returned. wblock: ```If .Fa propname does not exist, -1 is returned.```
				.Fa propname
				does not exist.
				.Pp
				.Fn OF_getprop
				copies maximum of
				wblockUnsubmitted Done Inline Actions copies a maximum of wblock: ```copies a maximum of```
				.Fa len
				bytes from the value associated with the property
				.Fa propname
				of the device node
				.Fa node
				into the memory specified by
				.Fa buf .
				The function returns actual size of the value or -1 if the
				wblockUnsubmitted Done Inline Actions The function returns the actual size of the value or -1 if the wblock: ```The function returns the actual size of the value or -1 if the```
				property does not exist.
				.Pp
				.Fn OF_getencprop
				copies maximum of
				wblockUnsubmitted Done Inline Actions copies a maximum of wblock: ```copies a maximum of```
				.Fa len
				bytes into memory specified by
				.Fa buf ,
				and then converts cell values from big-endian to host byte order.
				wblockUnsubmitted Done Inline Actions then converts cell values from big-endian to host byte order. wblock: ```then converts cell values from big-endian to host byte order.```
				The function returns actual size of the value in bytes or -1
				wblockUnsubmitted Done Inline Actions The function returns the actual size of the value in bytes, or -1 wblock: ```The function returns the actual size of the value in bytes, or -1```
				if the property does not exist.
				.Fa len
				should be multiply of 4.
				wblockUnsubmitted Done Inline Actions Spelling, but also unclear. Will it still work if len is not a multiple of 4? If not, this should say "must". must be a multiple of 4. wblock: Spelling, but also unclear. Will it still work if len is not a multiple of 4? If not, this…
				.Pp
				.Fn OF_hasprop
				returns 1 if the device node
				.Fa node
				has property specified by
				wblockUnsubmitted Done Inline Actions has a property specified by wblock: ```has a property specified by```
				.Fa propname ,
				and zero if there is the property does not exist.
				wblockUnsubmitted Done Inline Actions or zero if the property does not exist. wblock: ```or zero if the property does not exist.```
				.Pp
				.Fn OF_searchprop
				recursively looks for the property specified by
				.Fa propname
				starting with the device node
				.Fa node
				followed by the parent node and up to the root node.
				If the property is found the function copies max
				wblockUnsubmitted Done Inline Actions If the property is found, the function copies a maximum of wblock: ```If the property is found, the function copies a maximum of```
				.Fa len
				bytes of the value associated with the property
				into the memory specified by
				.Fa buf .
				The function returns actual size in bytes of the value,
				wblockUnsubmitted Done Inline Actions The function returns the actual size in bytes of the value, wblock: ```The function returns the actual size in bytes of the value,```
				and -1 if the property does not exist.
				wblockUnsubmitted Done Inline Actions or -1 if the property does not exist. wblock: ```or -1 if the property does not exist.```
				.Pp
				.Fn OF_searchencprop
				recursively looks for the property specified by
				.Fa propname
				starting with the device node
				.Fa node
				followed by the parent node and up to the root node.
				If the property is found the function copies max
				wblockUnsubmitted Done Inline Actions If the property is found, the function copies a maximum of wblock: ```If the property is found, the function copies a maximum of```
				.Fa len
				bytes of the value associated with the property
				into the memory specified by
				.Fa buf ,
				and then converts cell values from big-endian to host byte order.
				wblockUnsubmitted Done Inline Actions then converts cell values from big-endian to host byte order. wblock: ```then converts cell values from big-endian to host byte order.```
				The function returns actual size in bytes of the value,
				wblockUnsubmitted Done Inline Actions The function returns the actual size in bytes of the value, wblock: ```The function returns the actual size in bytes of the value,```
				and -1 if the property does not exist.
				wblockUnsubmitted Done Inline Actions or -1 if the property does not exist. wblock: ```or -1 if the property does not exist.```
				.Pp
				.Fn OF_getprop_alloc
				allocates the amount of memory large enough to fit the
				wblockUnsubmitted Done Inline Actions allocates memory large enough to hold the wblock: ```allocates memory large enough to hold the```
				value associated with the property
				.Fa propname
				of the device node
				.Fa node
				and copies the value into the newly allocated memory region.
				The function returns actual size of the value and stores
				wblockUnsubmitted Done Inline Actions The function returns the actual size of the value and stores the wblock: ```The function returns the actual size of the value and stores the```
				address of allocated memory in
				wblockUnsubmitted Done Inline Actions address of the allocated memory in wblock: ```address of the allocated memory in
				.Fa *buf .
				If the property has zero-sized value
				wblockUnsubmitted Done Inline Actions If the property has a zero-sized value, wblock: ```If the property has a zero-sized value,```
				.Fa *buf
				is set NULL.
				The function return -1 if the property does not exist or
				wblockUnsubmitted Done Inline Actions The function returns -1 if the property does not exist or wblock: ```The function returns -1 if the property does not exist or```
				memory allocation failed.
				Allocated memory should be released when no longer required
				by calling
				.Fn OF_prop_free .
				The function may sleep when allocating memory.
				wblockUnsubmitted Done Inline Actions Does "may sleep" mean I have permission to sleep while waiting for the memory allocation, or does it mean that the memory allocation might cause me to sleep? I suspect it's the second. So: The function might sleep when allocating memory. wblock: Does "may sleep" mean I have permission to sleep while waiting for the memory allocation, or…
				gonzoAuthorUnsubmitted Not Done Inline Actions It's the second. gonzo: It's the second.
				.Pp
				.Fn OF_getencprop_alloc
				allocates the amount of memory large enough to fit the
				wblockUnsubmitted Done Inline Actions allocates enough memory to hold the wblock: ```allocates enough memory to hold the```
				value associated with the property
				.Fa propname
				of the device node
				.Fa node ,
				copies the value into the newly allocated memory region, and
				then converts cell values from big-endian to host byte
				order.
				The function returns actual size of the value and stores
				wblockUnsubmitted Done Inline Actions The actual size of the value is returned and the wblock: ```The actual size of the value is returned and the```
				address of allocated memory in
				wblockUnsubmitted Not Done Inline Actions address of allocated memory is stored in Note: many of the previous sections had this copy/paste "The function returns", which is redundant and can be shortened this way. wblock: ```address of allocated memory is stored in``` Note: many of the previous sections had this…
				.Fa *buf .
				If the property has zero-sized value
				wblockUnsubmitted Done Inline Actions If the property has a zero-length value, wblock: ```If the property has a zero-length value,```
				.Fa *buf
				is set NULL.
				wblockUnsubmitted Done Inline Actions is set to NULL. wblock: ```is set to NULL.```
				The function return -1 if the property does not exist or
				wblockUnsubmitted Done Inline Actions The function returns -1 if the property does not exist or wblock: ```The function returns -1 if the property does not exist or```
				memory allocation failed.
				Allocated memory should be released when no longer required
				by calling
				.Fn OF_prop_free .
				The function may sleep when allocating memory.
				wblockUnsubmitted Done Inline Actions The function might sleep when allocating memory. wblock: ```The function might sleep when allocating memory.```
				.Pp
				.Fn OF_prop_free
				releases memory at
				.Fa buf
				allocated by
				wblockUnsubmitted Done Inline Actions Should this be that was allocated by wblock: Should this be ```that was allocated by```
				.Fn OF_getprop_alloc
				and
				wblockUnsubmitted Done Inline Actions or wblock: ```or```
				.Fn OF_getencprop_alloc .
				.Pp
				.Fn OF_nextprop
				copies maximum of
				wblockUnsubmitted Done Inline Actions copies a maximum of wblock: ```copies a maximum of```
				.Fa size
				bytes of the name of the property following the
				wblockUnsubmitted Not Done Inline Actions Not clear. Maybe: .Fn OF_nextprop copies .Fa size bytes of the name of the property following .Fa propname wblock: Not clear. Maybe: ```.Fn OF_nextprop copies .Fa size bytes of the name of the property…
				gonzoAuthorUnsubmitted Not Done Inline Actions I don't think it's the right description. Function copies name to buf, if the name length is larger than size, it copies only size bytes. gonzo: I don't think it's the right description. Function copies name to buf, if the name length is…
				.Fa propname
				property into
				.Fa buf .
				If
				.Fa propname
				is NULL, the function copies the name of the first property of the
				device node
				.Fa node .
				.Fn OF_nextprop
				returns -1 if
				.Fa propname
				is invalid or there is an internal error, 0 if there are no more
				properties after
				.Fa propname ,
				or 1 otherwise.
				.Pp
				.Fn OF_setprop
				sets the value of the property
				.Fa propname
				in the device node
				.Fa node
				to the value beginning at the address specified by
				.Fa buf
				and running for
				.Fa len
				bytes.
				If the property does not exist the function tries to create
				wblockUnsubmitted Done Inline Actions If the property does not exist, the function tries to create wblock: ```If the property does not exist, the function tries to create```
				it.
				.Fn OF_setprop
				returns the actual size of the new value, or -1 if the
				property value cannot be changed or the new property
				cannot be created.
				.Sh EXAMPLES
				.Bd -literal
				phandle_t node;
				phandle_t hdmixref, hdminode;
				device_t hdmi;
				uint8_t mac[6];
				char *model;

				/*
				* Get a byte array property
				*/
				if (OF_getprop(node, "eth,hwaddr", mac, sizeof(mac)) != sizeof(mac))
				return;

				/*
				* Get internal node reference and device associated with it
				*/
				if (OF_getencprop(node, "hdmi", &hdmixref) <= 0)
				return;
				hdmi = OF_device_from_xref(hdmixref);

				/*
				* Get string value of model property of HDMI framer node
				*/
				hdminode = OF_node_from_xref(hdmixref);
				if (OF_getprop_alloc(hdminode, "model", (void **)&model) <= 0)
				return;
				.Ed
				.Sh SEE ALSO
				.Xr OF_device_from_xref 9
				.Xr OF_node_from_xref 9
				.Sh AUTHORS
				.An -nosplit
				This manual page was written by
				.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .