xref: /freebsd/share/man/man9/OF_getprop.9 (revision 716fd348) 
1.\"
2.\" Copyright (c) 2018 Oleksandr Tymoshenko <gonzo@FreeBSD.org>
3.\"
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd June 23, 2018
29.Dt OF_GETPROP 9
30.Os
31.Sh NAME
32.Nm OF_getprop ,
33.Nm OF_getproplen ,
34.Nm OF_getencprop ,
35.Nm OF_hasprop ,
36.Nm OF_searchprop ,
37.Nm OF_searchencprop ,
38.Nm OF_getprop_alloc ,
39.Nm OF_getencprop_alloc ,
40.Nm OF_getprop_alloc_multi ,
41.Nm OF_getencprop_alloc_multi ,
42.Nm OF_prop_free ,
43.Nm OF_nextprop ,
44.Nm OF_setprop
45.Nd access properties of device tree node
46.Sh SYNOPSIS
47.In dev/ofw/ofw_bus.h
48.In dev/ofw/ofw_bus_subr.h
49.Ft ssize_t
50.Fn OF_getproplen "phandle_t node" "const char *propname"
51.Ft ssize_t
52.Fn OF_getprop "phandle_t node" "const char *propname" \
53"void *buf" "size_t len"
54.Ft ssize_t
55.Fn OF_getencprop "phandle_t node" "const char *prop" \
56"pcell_t *buf" "size_t len"
57.Ft int
58.Fn OF_hasprop "phandle_t node" "const char *propname"
59.Ft ssize_t
60.Fn OF_searchprop "phandle_t node" "const char *propname" \
61"void *buf" "size_t len"
62.Ft ssize_t
63.Fn OF_searchencprop "phandle_t node" "const char *propname" \
64"pcell_t *buf" "size_t len"
65.Ft ssize_t
66.Fn OF_getprop_alloc "phandle_t node" "const char *propname" \
67"void **buf"
68.Ft ssize_t
69.Fn OF_getencprop_alloc "phandle_t node" "const char *propname" \
70"pcell_t **buf"
71.Ft ssize_t
72.Fn OF_getprop_alloc_multi "phandle_t node" "const char *propname" \
73"int elsz" "void **buf"
74.Ft ssize_t
75.Fn OF_getencprop_alloc_multi "phandle_t node" "const char *propname" \
76"int elsz" "pcell_t **buf"
77.Ft void
78.Fn OF_prop_free "void *buf"
79.Ft int
80.Fn OF_nextprop "phandle_t node" "const char *propname" \
81"char *buf" "size_t len"
82.Ft int
83.Fn OF_setprop "phandle_t node" "const char *propname" \
84"const void *buf" "size_t len"
85.Sh DESCRIPTION
86Device nodes can have associated properties.
87Properties consist of a name and a value.
88A name is a human-readable string from 1 to 31 characters long.
89A value is an array of zero or more bytes that encode certain
90information.
91The meaning of that bytes depends on how drivers interpret them.
92Properties can encode byte arrays, text strings, unsigned 32-bit
93values or any combination of these types.
94.Pp
95Property with a zero-length value usually represents boolean
96information.
97If the property is present, it signifies true, otherwise false.
98.Pp
99A byte array is encoded as a sequence of bytes and represents
100values like MAC addresses.
101.Pp
102A text string is a sequence of n printable characters.
103It is encoded as a byte array of length n + 1 bytes with
104characters represented as bytes plus a terminating null character.
105.Pp
106Unsigned 32-bit values, also sometimes called cells, are
107encoded as a sequence of 4 bytes in big-endian order.
108.Pp
109.Fn OF_getproplen
110returns either the length of the value associated with the property
111.Fa propname
112in the node identified by
113.Fa node ,
114or 0 if the property exists but has no associated value.
115If
116.Fa propname
117does not exist, -1 is returned.
118.Pp
119.Fn OF_getprop
120copies a maximum of
121.Fa len
122bytes from the value associated with the property
123.Fa propname
124of the device node
125.Fa node
126into the memory specified by
127.Fa buf .
128Returns the actual size of the value or -1 if the
129property does not exist.
130.Pp
131.Fn OF_getencprop
132copies a maximum of
133.Fa len
134bytes into memory specified by
135.Fa buf ,
136then converts cell values from big-endian to host byte order.
137Returns the actual size of the value in bytes, or -1
138if the property does not exist.
139.Fa len
140must be a multiple of 4.
141.Pp
142.Fn OF_hasprop
143returns 1 if the device node
144.Fa node
145has a property specified by
146.Fa propname ,
147and zero if the property does not exist.
148.Pp
149.Fn OF_searchprop
150recursively looks for the property specified by
151.Fa propname
152starting with the device node
153.Fa node
154followed by the parent node and up to the root node.
155If the property is found, the function copies a maximum of
156.Fa len
157bytes of the value associated with the property
158into the memory specified by
159.Fa buf .
160Returns the actual size in bytes of the value,
161or -1 if the property does not exist.
162.Pp
163.Fn OF_searchencprop
164recursively looks for the property specified by
165.Fa propname
166starting with the device node
167.Fa node
168followed by the parent node and up to the root node.
169If the property is found, the function copies a maximum of
170.Fa len
171bytes of the value associated with the property
172into the memory specified by
173.Fa buf ,
174then converts cell values from big-endian to host byte order.
175Returns the actual size in bytes of the value,
176or -1 if the property does not exist.
177.Pp
178.Fn OF_getprop_alloc
179allocates memory large enough to hold the
180value associated with the property
181.Fa propname
182of the device node
183.Fa node
184and copies the value into the newly allocated memory region.
185Returns the actual size of the value and stores
186the address of the allocated memory in
187.Fa *buf .
188If the property has a zero-sized value
189.Fa *buf
190is set NULL.
191Returns -1 if the property does not exist or
192memory allocation failed.
193Allocated memory should be released when no longer required
194by calling
195.Fn OF_prop_free .
196The function might sleep when allocating memory.
197.Pp
198.Fn OF_getencprop_alloc
199allocates enough memory to hold the
200value associated with the property
201.Fa propname
202of the device node
203.Fa node ,
204copies the value into the newly allocated memory region, and
205then converts cell values from big-endian to host byte
206order.
207The actual size of the value is returned and the
208address of allocated memory is stored in
209.Fa *buf .
210If the property has zero-length value,
211.Fa *buf
212is set to NULL.
213Returns -1 if the property does not exist or
214memory allocation failed or the size of the value is not
215divisible by a cell size (4 bytes).
216Allocated memory should be released when no longer required
217by calling
218.Fn OF_prop_free .
219The function might sleep when allocating memory.
220.Pp
221.Fn OF_getprop_alloc_multi
222allocates memory large enough to hold the
223value associated with the property
224.Fa propname
225of the device node
226.Fa node
227and copies the value into the newly allocated memory region.
228The value is expected to be an array of zero or more elements
229.Fa elsz
230bytes long.
231Returns the number of elements in the value and stores
232the address of the allocated memory in
233.Fa *buf .
234If the property has a zero-sized value
235.Fa *buf
236is set NULL.
237Returns -1 if the property does not exist or
238memory allocation failed or the size of the value is not
239divisible by
240.Fa elsz .
241Allocated memory should be released when no longer required
242by calling
243.Fn OF_prop_free .
244The function might sleep when allocating memory.
245.Pp
246.Fn OF_getencprop_alloc_multi
247allocates memory large enough to hold the
248value associated with the property
249.Fa propname
250of the device node
251.Fa node
252and copies the value into the newly allocated memory region, and
253then converts cell values from big-endian to host byte
254order.
255The value is expected to be an array of zero or more elements
256.Fa elsz
257bytes long.
258Returns the number of elements in the value and stores
259the address of the allocated memory in
260.Fa *buf .
261If the property has a zero-sized value
262.Fa *buf
263is set NULL.
264Returns -1 if the property does not exist or
265memory allocation failed or the size of the value is not
266divisible by
267.Fa elsz .
268Allocated memory should be released when no longer required
269by calling
270.Fn OF_prop_free .
271The function might sleep when allocating memory.
272.Pp
273.Fn OF_prop_free
274releases memory at
275.Fa buf
276that was allocated by
277.Fn OF_getprop_alloc ,
278.Fn OF_getencprop_alloc ,
279.Fn OF_getprop_alloc_multi ,
280.Fn OF_getencprop_alloc_multi .
281.Pp
282.Fn OF_nextprop
283copies a maximum of
284.Fa size
285bytes of the name of the property following the
286.Fa propname
287property into
288.Fa buf .
289If
290.Fa propname
291is NULL, the function copies the name of the first property of the
292device node
293.Fa node .
294.Fn OF_nextprop
295returns -1 if
296.Fa propname
297is invalid or there is an internal error, 0 if there are no more
298properties after
299.Fa propname ,
300or 1 otherwise.
301.Pp
302.Fn OF_setprop
303sets the value of the property
304.Fa propname
305in the device node
306.Fa node
307to the value beginning at the address specified by
308.Fa buf
309and running for
310.Fa len
311bytes.
312If the property does not exist, the function tries to create
313it.
314.Fn OF_setprop
315returns the actual size of the new value, or -1 if the
316property value cannot be changed or the new property
317cannot be created.
318.Sh EXAMPLES
319.Bd -literal
320    phandle_t node;
321    phandle_t hdmixref, hdminode;
322    device_t hdmi;
323    uint8_t mac[6];
324    char *model;
325
326    /*
327     * Get a byte array property
328     */
329    if (OF_getprop(node, "eth,hwaddr", mac, sizeof(mac)) != sizeof(mac))
330        return;
331
332    /*
333     * Get internal node reference and device associated with it
334     */
335    if (OF_getencprop(node, "hdmi", &hdmixref) <= 0)
336        return;
337    hdmi = OF_device_from_xref(hdmixref);
338
339    /*
340     * Get string value of model property of HDMI framer node
341     */
342    hdminode = OF_node_from_xref(hdmixref);
343    if (OF_getprop_alloc(hdminode, "model", (void **)&model) <= 0)
344        return;
345.Ed
346.Sh SEE ALSO
347.Xr OF_device_from_xref 9 ,
348.Xr OF_node_from_xref 9
349.Sh AUTHORS
350.An -nosplit
351This manual page was written by
352.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .
353