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 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
  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
  83 information.
  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.
  87 .Pp
  88 Property with a zero-length value usually represents boolean
  89 information.
  90 If the property is present, it signifies true, otherwise false.
  91 .Pp
  92 A byte array is encoded as a sequence of bytes and represents
  93 values like MAC addresses.
  94 .Pp
  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.
  98 .Pp
  99 Unsigned 32-bit values, also sometimes called cells, are
 100 encoded as a sequence of 4 bytes in big-endian order.
 101 .Pp
 102 .Fn OF_getproplen
 103 returns either the length of the value associated with the property
 104 .Fa propname
 105 in the node identified by
 106 .Fa node ,
 107 or 0 if the property exists but has no associated value.
 108 If
 109 .Fa propname
 110 does not exist, -1 is returned.
 111 .Pp
 112 .Fn OF_getprop
 113 copies a maximum of
 114 .Fa len
 115 bytes from the value associated with the property
 116 .Fa propname
 117 of the device node
 118 .Fa node
 119 into the memory specified by
 120 .Fa buf .
 121 Returns the actual size of the value or -1 if the
 122 property does not exist.
 123 .Pp
 124 .Fn OF_getencprop
 125 copies a maximum of
 126 .Fa len
 127 bytes into memory specified by
 128 .Fa buf ,
 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.
 132 .Fa len
 133 must be a multiple of 4.
 134 .Pp
 135 .Fn OF_hasprop
 136 returns 1 if the device node
 137 .Fa node
 138 has a property specified by
 139 .Fa propname ,
 140 and zero if the property does not exist.
 141 .Pp
 142 .Fn OF_searchprop
 143 recursively looks for the property specified by
 144 .Fa propname
 145 starting with the device node
 146 .Fa 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
 149 .Fa len
 150 bytes of the value associated with the property
 151 into the memory specified by
 152 .Fa buf .
 153 Returns the actual size in bytes of the value,
 154 or -1 if the property does not exist.
 155 .Pp
 156 .Fn OF_searchencprop
 157 recursively looks for the property specified by
 158 .Fa propname
 159 starting with the device node
 160 .Fa 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
 163 .Fa len
 164 bytes of the value associated with the property
 165 into the memory specified by
 166 .Fa buf ,
 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.
 170 .Pp
 171 .Fn OF_getprop_alloc
 172 allocates memory large enough to hold the
 173 value associated with the property
 174 .Fa propname
 175 of the device node
 176 .Fa node
 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
 180 .Fa *buf .
 181 If the property has a zero-sized value
 182 .Fa *buf
 183 is set NULL.
 184 Returns -1 if the property does not exist or
 185 memory allocation failed.
 186 Allocated memory should be released when no longer required
 187 by calling
 188 .Fn OF_prop_free .
 189 The function might sleep when allocating memory.
 190 .Pp
 191 .Fn OF_getencprop_alloc
 192 allocates enough memory to hold the
 193 value associated with the property
 194 .Fa propname
 195 of the device node
 196 .Fa node ,
 197 copies the value into the newly allocated memory region, and
 198 then converts cell values from big-endian to host byte
 199 order.
 200 The actual size of the value is returned and the
 201 address of allocated memory is stored in
 202 .Fa *buf .
 203 If the property has zero-length value,
 204 .Fa *buf
 205 is set to NULL.
 206 Returns -1 if the property does not exist or
 207 memory allocation failed.
 208 Allocated memory should be released when no longer required
 209 by calling
 210 .Fn OF_prop_free .
 211 The function might sleep when allocating memory.
 212 .Pp
 213 .Fn OF_prop_free
 214 releases memory at
 215 .Fa buf
 216 that was allocated by
 217 .Fn OF_getprop_alloc
 218 or
 219 .Fn OF_getencprop_alloc .
 220 .Pp
 221 .Fn OF_nextprop
 222 copies a maximum of
 223 .Fa size
 224 bytes of the name of the property following the
 225 .Fa propname
 226 property into
 227 .Fa buf .
 228 If
 229 .Fa propname
 230 is NULL, the function copies the name of the first property of the
 231 device node
 232 .Fa node .
 233 .Fn OF_nextprop
 234 returns -1 if
 235 .Fa propname
 236 is invalid or there is an internal error, 0 if there are no more
 237 properties after
 238 .Fa propname ,
 239 or 1 otherwise.
 240 .Pp
 241 .Fn OF_setprop
 242 sets the value of the property
 243 .Fa propname
 244 in the device node
 245 .Fa node
 246 to the value beginning at the address specified by
 247 .Fa buf
 248 and running for
 249 .Fa len
 250 bytes.
 251 If the property does not exist, the function tries to create
 252 it.
 253 .Fn OF_setprop
 254 returns the actual size of the new value, or -1 if the
 255 property value cannot be changed or the new property
 256 cannot 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
 290 This manual page was written by
 291 .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .