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