xref: /freebsd/share/man/man9/OF_getprop.9 (revision 0957b409) 
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
86.Pp
87Device nodes can have associated properties.
88Properties consist of a name and a value.
89A name is a human-readable string from 1 to 31 characters long.
90A value is an array of zero or more bytes that encode certain
91information.
92The meaning of that bytes depends on how drivers interpret them.
93Properties can encode byte arrays, text strings, unsigned 32-bit
94values or any combination of these types.
95.Pp
96Property with a zero-length value usually represents boolean
97information.
98If the property is present, it signifies true, otherwise false.
99.Pp
100A byte array is encoded as a sequence of bytes and represents
101values like MAC addresses.
102.Pp
103A text string is a sequence of n printable characters.
104It is encoded as a byte array of length n + 1 bytes with
105characters represented as bytes plus a terminating null character.
106.Pp
107Unsigned 32-bit values, also sometimes called cells, are
108encoded as a sequence of 4 bytes in big-endian order.
109.Pp
110.Fn OF_getproplen
111returns either the length of the value associated with the property
112.Fa propname
113in the node identified by
114.Fa node ,
115or 0 if the property exists but has no associated value.
116If
117.Fa propname
118does not exist, -1 is returned.
119.Pp
120.Fn OF_getprop
121copies a maximum of
122.Fa len
123bytes from the value associated with the property
124.Fa propname
125of the device node
126.Fa node
127into the memory specified by
128.Fa buf .
129Returns the actual size of the value or -1 if the
130property does not exist.
131.Pp
132.Fn OF_getencprop
133copies a maximum of
134.Fa len
135bytes into memory specified by
136.Fa buf ,
137then converts cell values from big-endian to host byte order.
138Returns the actual size of the value in bytes, or -1
139if the property does not exist.
140.Fa len
141must be a multiple of 4.
142.Pp
143.Fn OF_hasprop
144returns 1 if the device node
145.Fa node
146has a property specified by
147.Fa propname ,
148and zero if the property does not exist.
149.Pp
150.Fn OF_searchprop
151recursively looks for the property specified by
152.Fa propname
153starting with the device node
154.Fa node
155followed by the parent node and up to the root node.
156If the property is found, the function copies a maximum of
157.Fa len
158bytes of the value associated with the property
159into the memory specified by
160.Fa buf .
161Returns the actual size in bytes of the value,
162or -1 if the property does not exist.
163.Pp
164.Fn OF_searchencprop
165recursively looks for the property specified by
166.Fa propname
167starting with the device node
168.Fa node
169followed by the parent node and up to the root node.
170If the property is found, the function copies a maximum of
171.Fa len
172bytes of the value associated with the property
173into the memory specified by
174.Fa buf ,
175then converts cell values from big-endian to host byte order.
176Returns the actual size in bytes of the value,
177or -1 if the property does not exist.
178.Pp
179.Fn OF_getprop_alloc
180allocates memory large enough to hold the
181value associated with the property
182.Fa propname
183of the device node
184.Fa node
185and copies the value into the newly allocated memory region.
186Returns the actual size of the value and stores
187the address of the allocated memory in
188.Fa *buf .
189If the property has a zero-sized value
190.Fa *buf
191is set NULL.
192Returns -1 if the property does not exist or
193memory allocation failed.
194Allocated memory should be released when no longer required
195by calling
196.Fn OF_prop_free .
197The function might sleep when allocating memory.
198.Pp
199.Fn OF_getencprop_alloc
200allocates enough memory to hold the
201value associated with the property
202.Fa propname
203of the device node
204.Fa node ,
205copies the value into the newly allocated memory region, and
206then converts cell values from big-endian to host byte
207order.
208The actual size of the value is returned and the
209address of allocated memory is stored in
210.Fa *buf .
211If the property has zero-length value,
212.Fa *buf
213is set to NULL.
214Returns -1 if the property does not exist or
215memory allocation failed or the size of the value is not
216divisible by a cell size (4 bytes).
217Allocated memory should be released when no longer required
218by calling
219.Fn OF_prop_free .
220The function might sleep when allocating memory.
221.Pp
222.Fn OF_getprop_alloc_multi
223allocates memory large enough to hold the
224value associated with the property
225.Fa propname
226of the device node
227.Fa node
228and copies the value into the newly allocated memory region.
229The value is expected to be an array of zero or more elements
230.Fa elsz
231bytes long.
232Returns the number of elements in the value and stores
233the address of the allocated memory in
234.Fa *buf .
235If the property has a zero-sized value
236.Fa *buf
237is set NULL.
238Returns -1 if the property does not exist or
239memory allocation failed or the size of the value is not
240divisible by
241.Fa elsz .
242Allocated memory should be released when no longer required
243by calling
244.Fn OF_prop_free .
245The function might sleep when allocating memory.
246.Pp
247.Fn OF_getencprop_alloc_multi
248allocates memory large enough to hold the
249value associated with the property
250.Fa propname
251of the device node
252.Fa node
253and copies the value into the newly allocated memory region, and
254then converts cell values from big-endian to host byte
255order.
256The value is expected to be an array of zero or more elements
257.Fa elsz
258bytes long.
259Returns the number of elements in the value and stores
260the address of the allocated memory in
261.Fa *buf .
262If the property has a zero-sized value
263.Fa *buf
264is set NULL.
265Returns -1 if the property does not exist or
266memory allocation failed or the size of the value is not
267divisible by
268.Fa elsz .
269Allocated memory should be released when no longer required
270by calling
271.Fn OF_prop_free .
272The function might sleep when allocating memory.
273.Pp
274.Fn OF_prop_free
275releases memory at
276.Fa buf
277that was allocated by
278.Fn OF_getprop_alloc ,
279.Fn OF_getencprop_alloc ,
280.Fn OF_getprop_alloc_multi ,
281.Fn OF_getencprop_alloc_multi .
282.Pp
283.Fn OF_nextprop
284copies a maximum of
285.Fa size
286bytes of the name of the property following the
287.Fa propname
288property into
289.Fa buf .
290If
291.Fa propname
292is NULL, the function copies the name of the first property of the
293device node
294.Fa node .
295.Fn OF_nextprop
296returns -1 if
297.Fa propname
298is invalid or there is an internal error, 0 if there are no more
299properties after
300.Fa propname ,
301or 1 otherwise.
302.Pp
303.Fn OF_setprop
304sets the value of the property
305.Fa propname
306in the device node
307.Fa node
308to the value beginning at the address specified by
309.Fa buf
310and running for
311.Fa len
312bytes.
313If the property does not exist, the function tries to create
314it.
315.Fn OF_setprop
316returns the actual size of the new value, or -1 if the
317property value cannot be changed or the new property
318cannot be created.
319.Sh EXAMPLES
320.Bd -literal
321    phandle_t node;
322    phandle_t hdmixref, hdminode;
323    device_t hdmi;
324    uint8_t mac[6];
325    char *model;
326
327    /*
328     * Get a byte array property
329     */
330    if (OF_getprop(node, "eth,hwaddr", mac, sizeof(mac)) != sizeof(mac))
331        return;
332
333    /*
334     * Get internal node reference and device associated with it
335     */
336    if (OF_getencprop(node, "hdmi", &hdmixref) <= 0)
337        return;
338    hdmi = OF_device_from_xref(hdmixref);
339
340    /*
341     * Get string value of model property of HDMI framer node
342     */
343    hdminode = OF_node_from_xref(hdmixref);
344    if (OF_getprop_alloc(hdminode, "model", (void **)&model) <= 0)
345        return;
346.Ed
347.Sh SEE ALSO
348.Xr OF_device_from_xref 9
349.Xr OF_node_from_xref 9
350.Sh AUTHORS
351.An -nosplit
352This manual page was written by
353.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .
354