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 ,
43 .Nd access properties of device tree node
46 .In dev/ofw/ofw_bus_subr.h
48 .Fn OF_getproplen "phandle_t node" "const char *propname"
50 .Fn OF_getprop "phandle_t node" "const char *propname" \
51 "void *buf" "size_t len"
53 .Fn OF_getencprop "phandle_t node" "const char *prop" \
54 "pcell_t *buf" "size_t len"
56 .Fn OF_hasprop "phandle_t node" "const char *propname"
58 .Fn OF_searchprop "phandle_t node" "const char *propname" \
59 "void *buf" "size_t len"
61 .Fn OF_searchencprop "phandle_t node" "const char *propname" \
62 "pcell_t *buf" "size_t len"
64 .Fn OF_getprop_alloc "phandle_t node" "const char *propname" \
67 .Fn OF_getencprop_alloc "phandle_t node" "const char *propname" \
70 .Fn OF_prop_free "void *buf"
72 .Fn OF_nextprop "phandle_t node" "const char *propname" \
73 "char *buf" "size_t len"
75 .Fn OF_setprop "phandle_t node" "const char *propname" \
76 "const void *buf" "size_t len"
79 Device nodes can have associated properties.
80 Properties consist of a name and a value.
81 A name is a human-readable string from 1 to 31 characters long.
82 A value is an array of zero or more bytes that encode certain
84 The meaning of that bytes depends on how drivers interpret them.
85 Properties can encode byte arrays, text strings, unsigned 32-bit
86 values or any combination of these types.
88 Property with a zero-length value usually represents boolean
90 If the property is present, it signifies true, otherwise false.
92 A byte array is encoded as a sequence of bytes and represents
93 values like MAC addresses.
95 A text string is a sequence of n printable characters.
96 It is encoded as a byte array of length n + 1 bytes with
97 characters represented as bytes plus a terminating null character.
99 Unsigned 32-bit values, also sometimes called cells, are
100 encoded as a sequence of 4 bytes in big-endian order.
103 returns either the length of the value associated with the property
105 in the node identified by
107 or 0 if the property exists but has no associated value.
110 does not exist, -1 is returned.
115 bytes from the value associated with the property
119 into the memory specified by
121 Returns the actual size of the value or -1 if the
122 property does not exist.
127 bytes into memory specified by
129 then converts cell values from big-endian to host byte order.
130 Returns the actual size of the value in bytes, or -1
131 if the property does not exist.
133 must be a multiple of 4.
136 returns 1 if the device node
138 has a property specified by
140 and zero if the property does not exist.
143 recursively looks for the property specified by
145 starting with the device node
147 followed by the parent node and up to the root node.
148 If the property is found, the function copies a maximum of
150 bytes of the value associated with the property
151 into the memory specified by
153 Returns the actual size in bytes of the value,
154 or -1 if the property does not exist.
157 recursively looks for the property specified by
159 starting with the device node
161 followed by the parent node and up to the root node.
162 If the property is found, the function copies a maximum of
164 bytes of the value associated with the property
165 into the memory specified by
167 then converts cell values from big-endian to host byte order.
168 Returns the actual size in bytes of the value,
169 or -1 if the property does not exist.
172 allocates memory large enough to hold the
173 value associated with the property
177 and copies the value into the newly allocated memory region.
178 Returns the actual size of the value and stores
179 the address of the allocated memory in
181 If the property has a zero-sized value
184 Returns -1 if the property does not exist or
185 memory allocation failed.
186 Allocated memory should be released when no longer required
189 The function might sleep when allocating memory.
191 .Fn OF_getencprop_alloc
192 allocates enough memory to hold the
193 value associated with the property
197 copies the value into the newly allocated memory region, and
198 then converts cell values from big-endian to host byte
200 The actual size of the value is returned and the
201 address of allocated memory is stored in
203 If the property has zero-length value,
206 Returns -1 if the property does not exist or
207 memory allocation failed.
208 Allocated memory should be released when no longer required
211 The function might sleep when allocating memory.
216 that was allocated by
219 .Fn OF_getencprop_alloc .
224 bytes of the name of the property following the
230 is NULL, the function copies the name of the first property of the
236 is invalid or there is an internal error, 0 if there are no more
242 sets the value of the property
246 to the value beginning at the address specified by
251 If the property does not exist, the function tries to create
254 returns the actual size of the new value, or -1 if the
255 property value cannot be changed or the new property
260 phandle_t hdmixref, hdminode;
266 * Get a byte array property
268 if (OF_getprop(node, "eth,hwaddr", mac, sizeof(mac)) != sizeof(mac))
272 * Get internal node reference and device associated with it
274 if (OF_getencprop(node, "hdmi", &hdmixref) <= 0)
276 hdmi = OF_device_from_xref(hdmixref);
279 * Get string value of model property of HDMI framer node
281 hdminode = OF_node_from_xref(hdmixref);
282 if (OF_getprop_alloc(hdminode, "model", (void **)&model) <= 0)
286 .Xr OF_device_from_xref 9
287 .Xr OF_node_from_xref 9
290 This manual page was written by
291 .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .