2 .\" Copyright (c) 2018 Oleksandr Tymoshenko <gonzo@FreeBSD.org>
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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.
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 ,
45 .Nd access properties of device tree node
48 .In dev/ofw/ofw_bus_subr.h
50 .Fn OF_getproplen "phandle_t node" "const char *propname"
52 .Fn OF_getprop "phandle_t node" "const char *propname" \
53 "void *buf" "size_t len"
55 .Fn OF_getencprop "phandle_t node" "const char *prop" \
56 "pcell_t *buf" "size_t len"
58 .Fn OF_hasprop "phandle_t node" "const char *propname"
60 .Fn OF_searchprop "phandle_t node" "const char *propname" \
61 "void *buf" "size_t len"
63 .Fn OF_searchencprop "phandle_t node" "const char *propname" \
64 "pcell_t *buf" "size_t len"
66 .Fn OF_getprop_alloc "phandle_t node" "const char *propname" \
69 .Fn OF_getencprop_alloc "phandle_t node" "const char *propname" \
72 .Fn OF_getprop_alloc_multi "phandle_t node" "const char *propname" \
73 "int elsz" "void **buf"
75 .Fn OF_getencprop_alloc_multi "phandle_t node" "const char *propname" \
76 "int elsz" "pcell_t **buf"
78 .Fn OF_prop_free "void *buf"
80 .Fn OF_nextprop "phandle_t node" "const char *propname" \
81 "char *buf" "size_t len"
83 .Fn OF_setprop "phandle_t node" "const char *propname" \
84 "const void *buf" "size_t len"
87 Device nodes can have associated properties.
88 Properties consist of a name and a value.
89 A name is a human-readable string from 1 to 31 characters long.
90 A value is an array of zero or more bytes that encode certain
92 The meaning of that bytes depends on how drivers interpret them.
93 Properties can encode byte arrays, text strings, unsigned 32-bit
94 values or any combination of these types.
96 Property with a zero-length value usually represents boolean
98 If the property is present, it signifies true, otherwise false.
100 A byte array is encoded as a sequence of bytes and represents
101 values like MAC addresses.
103 A text string is a sequence of n printable characters.
104 It is encoded as a byte array of length n + 1 bytes with
105 characters represented as bytes plus a terminating null character.
107 Unsigned 32-bit values, also sometimes called cells, are
108 encoded as a sequence of 4 bytes in big-endian order.
111 returns either the length of the value associated with the property
113 in the node identified by
115 or 0 if the property exists but has no associated value.
118 does not exist, -1 is returned.
123 bytes from the value associated with the property
127 into the memory specified by
129 Returns the actual size of the value or -1 if the
130 property does not exist.
135 bytes into memory specified by
137 then converts cell values from big-endian to host byte order.
138 Returns the actual size of the value in bytes, or -1
139 if the property does not exist.
141 must be a multiple of 4.
144 returns 1 if the device node
146 has a property specified by
148 and zero if the property does not exist.
151 recursively looks for the property specified by
153 starting with the device node
155 followed by the parent node and up to the root node.
156 If the property is found, the function copies a maximum of
158 bytes of the value associated with the property
159 into the memory specified by
161 Returns the actual size in bytes of the value,
162 or -1 if the property does not exist.
165 recursively looks for the property specified by
167 starting with the device node
169 followed by the parent node and up to the root node.
170 If the property is found, the function copies a maximum of
172 bytes of the value associated with the property
173 into the memory specified by
175 then converts cell values from big-endian to host byte order.
176 Returns the actual size in bytes of the value,
177 or -1 if the property does not exist.
180 allocates memory large enough to hold the
181 value associated with the property
185 and copies the value into the newly allocated memory region.
186 Returns the actual size of the value and stores
187 the address of the allocated memory in
189 If the property has a zero-sized value
192 Returns -1 if the property does not exist or
193 memory allocation failed.
194 Allocated memory should be released when no longer required
197 The function might sleep when allocating memory.
199 .Fn OF_getencprop_alloc
200 allocates enough memory to hold the
201 value associated with the property
205 copies the value into the newly allocated memory region, and
206 then converts cell values from big-endian to host byte
208 The actual size of the value is returned and the
209 address of allocated memory is stored in
211 If the property has zero-length value,
214 Returns -1 if the property does not exist or
215 memory allocation failed or the size of the value is not
216 divisible by a cell size (4 bytes).
217 Allocated memory should be released when no longer required
220 The function might sleep when allocating memory.
222 .Fn OF_getprop_alloc_multi
223 allocates memory large enough to hold the
224 value associated with the property
228 and copies the value into the newly allocated memory region.
229 The value is expected to be an array of zero or more elements
232 Returns the number of elements in the value and stores
233 the address of the allocated memory in
235 If the property has a zero-sized value
238 Returns -1 if the property does not exist or
239 memory allocation failed or the size of the value is not
242 Allocated memory should be released when no longer required
245 The function might sleep when allocating memory.
247 .Fn OF_getencprop_alloc_multi
248 allocates memory large enough to hold the
249 value associated with the property
253 and copies the value into the newly allocated memory region, and
254 then converts cell values from big-endian to host byte
256 The value is expected to be an array of zero or more elements
259 Returns the number of elements in the value and stores
260 the address of the allocated memory in
262 If the property has a zero-sized value
265 Returns -1 if the property does not exist or
266 memory allocation failed or the size of the value is not
269 Allocated memory should be released when no longer required
272 The function might sleep when allocating memory.
277 that 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 .
286 bytes of the name of the property following the
292 is NULL, the function copies the name of the first property of the
298 is invalid or there is an internal error, 0 if there are no more
304 sets the value of the property
308 to the value beginning at the address specified by
313 If the property does not exist, the function tries to create
316 returns the actual size of the new value, or -1 if the
317 property value cannot be changed or the new property
322 phandle_t hdmixref, hdminode;
328 * Get a byte array property
330 if (OF_getprop(node, "eth,hwaddr", mac, sizeof(mac)) != sizeof(mac))
334 * Get internal node reference and device associated with it
336 if (OF_getencprop(node, "hdmi", &hdmixref) <= 0)
338 hdmi = OF_device_from_xref(hdmixref);
341 * Get string value of model property of HDMI framer node
343 hdminode = OF_node_from_xref(hdmixref);
344 if (OF_getprop_alloc(hdminode, "model", (void **)&model) <= 0)
348 .Xr OF_device_from_xref 9
349 .Xr OF_node_from_xref 9
352 This manual page was written by
353 .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .