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