share/man/man9/OF_getprop.9

   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
  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
  91 information.
  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.
  95 .Pp
  96 Property with a zero-length value usually represents boolean
  97 information.
  98 If the property is present, it signifies true, otherwise false.
  99 .Pp
 100 A byte array is encoded as a sequence of bytes and represents
 101 values like MAC addresses.
 102 .Pp
 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.
 106 .Pp
 107 Unsigned 32-bit values, also sometimes called cells, are
 108 encoded as a sequence of 4 bytes in big-endian order.
 109 .Pp
 110 .Fn OF_getproplen
 111 returns either the length of the value associated with the property
 112 .Fa propname
 113 in the node identified by
 114 .Fa node ,
 115 or 0 if the property exists but has no associated value.
 116 If
 117 .Fa propname
 118 does not exist, -1 is returned.
 119 .Pp
 120 .Fn OF_getprop
 121 copies a maximum of
 122 .Fa len
 123 bytes from the value associated with the property
 124 .Fa propname
 125 of the device node
 126 .Fa node
 127 into the memory specified by
 128 .Fa buf .
 129 Returns the actual size of the value or -1 if the
 130 property does not exist.
 131 .Pp
 132 .Fn OF_getencprop
 133 copies a maximum of
 134 .Fa len
 135 bytes into memory specified by
 136 .Fa buf ,
 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.
 140 .Fa len
 141 must be a multiple of 4.
 142 .Pp
 143 .Fn OF_hasprop
 144 returns 1 if the device node
 145 .Fa node
 146 has a property specified by
 147 .Fa propname ,
 148 and zero if the property does not exist.
 149 .Pp
 150 .Fn OF_searchprop
 151 recursively looks for the property specified by
 152 .Fa propname
 153 starting with the device node
 154 .Fa 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
 157 .Fa len
 158 bytes of the value associated with the property
 159 into the memory specified by
 160 .Fa buf .
 161 Returns the actual size in bytes of the value,
 162 or -1 if the property does not exist.
 163 .Pp
 164 .Fn OF_searchencprop
 165 recursively looks for the property specified by
 166 .Fa propname
 167 starting with the device node
 168 .Fa 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
 171 .Fa len
 172 bytes of the value associated with the property
 173 into the memory specified by
 174 .Fa buf ,
 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.
 178 .Pp
 179 .Fn OF_getprop_alloc
 180 allocates memory large enough to hold the
 181 value associated with the property
 182 .Fa propname
 183 of the device node
 184 .Fa node
 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
 188 .Fa *buf .
 189 If the property has a zero-sized value
 190 .Fa *buf
 191 is set NULL.
 192 Returns -1 if the property does not exist or
 193 memory allocation failed.
 194 Allocated memory should be released when no longer required
 195 by calling
 196 .Fn OF_prop_free .
 197 The function might sleep when allocating memory.
 198 .Pp
 199 .Fn OF_getencprop_alloc
 200 allocates enough memory to hold the
 201 value associated with the property
 202 .Fa propname
 203 of the device node
 204 .Fa node ,
 205 copies the value into the newly allocated memory region, and
 206 then converts cell values from big-endian to host byte
 207 order.
 208 The actual size of the value is returned and the
 209 address of allocated memory is stored in
 210 .Fa *buf .
 211 If the property has zero-length value,
 212 .Fa *buf
 213 is set to NULL.
 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
 218 by calling
 219 .Fn OF_prop_free .
 220 The function might sleep when allocating memory.
 221 .Pp
 222 .Fn OF_getprop_alloc_multi
 223 allocates memory large enough to hold the
 224 value associated with the property
 225 .Fa propname
 226 of the device node
 227 .Fa node
 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
 230 .Fa elsz
 231 bytes long.
 232 Returns the number of elements in the value and stores
 233 the address of the allocated memory in
 234 .Fa *buf .
 235 If the property has a zero-sized value
 236 .Fa *buf
 237 is set NULL.
 238 Returns -1 if the property does not exist or
 239 memory allocation failed or the size of the value is not
 240 divisible by
 241 .Fa elsz .
 242 Allocated memory should be released when no longer required
 243 by calling
 244 .Fn OF_prop_free .
 245 The function might sleep when allocating memory.
 246 .Pp
 247 .Fn OF_getencprop_alloc_multi
 248 allocates memory large enough to hold the
 249 value associated with the property
 250 .Fa propname
 251 of the device node
 252 .Fa node
 253 and copies the value into the newly allocated memory region, and
 254 then converts cell values from big-endian to host byte
 255 order.
 256 The value is expected to be an array of zero or more elements
 257 .Fa elsz
 258 bytes long.
 259 Returns the number of elements in the value and stores
 260 the address of the allocated memory in
 261 .Fa *buf .
 262 If the property has a zero-sized value
 263 .Fa *buf
 264 is set NULL.
 265 Returns -1 if the property does not exist or
 266 memory allocation failed or the size of the value is not
 267 divisible by
 268 .Fa elsz .
 269 Allocated memory should be released when no longer required
 270 by calling
 271 .Fn OF_prop_free .
 272 The function might sleep when allocating memory.
 273 .Pp
 274 .Fn OF_prop_free
 275 releases memory at
 276 .Fa buf
 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 .
 282 .Pp
 283 .Fn OF_nextprop
 284 copies a maximum of
 285 .Fa size
 286 bytes of the name of the property following the
 287 .Fa propname
 288 property into
 289 .Fa buf .
 290 If
 291 .Fa propname
 292 is NULL, the function copies the name of the first property of the
 293 device node
 294 .Fa node .
 295 .Fn OF_nextprop
 296 returns -1 if
 297 .Fa propname
 298 is invalid or there is an internal error, 0 if there are no more
 299 properties after
 300 .Fa propname ,
 301 or 1 otherwise.
 302 .Pp
 303 .Fn OF_setprop
 304 sets the value of the property
 305 .Fa propname
 306 in the device node
 307 .Fa node
 308 to the value beginning at the address specified by
 309 .Fa buf
 310 and running for
 311 .Fa len
 312 bytes.
 313 If the property does not exist, the function tries to create
 314 it.
 315 .Fn OF_setprop
 316 returns the actual size of the new value, or -1 if the
 317 property value cannot be changed or the new property
 318 cannot 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
 352 This manual page was written by
 353 .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .