share/man/man9/bhnd_erom.9

   1 .\" Copyright (c) 2015-2016 Landon Fuller <landonf@FreeBSD.org>
   2 .\" Copyright (c) 2017 The FreeBSD Foundation
   3 .\" All rights reserved.
   4 .\"
   5 .\" Portions of this documentation were written by Landon Fuller
   6 .\" under sponsorship from the FreeBSD Foundation.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd November 9, 2017
  32 .Dt BHND_EROM 9
  33 .Os
  34 .Sh NAME
  35 .Nm bhnd_erom ,
  36 .Nm bhnd_erom_alloc ,
  37 .Nm bhnd_erom_dump ,
  38 .Nm bhnd_erom_fini_static ,
  39 .Nm bhnd_erom_free ,
  40 .Nm bhnd_erom_free_core_table ,
  41 .Nm bhnd_erom_get_core_table ,
  42 .Nm bhnd_erom_init_static ,
  43 .Nm bhnd_erom_io ,
  44 .Nm bhnd_erom_io_fini ,
  45 .Nm bhnd_erom_io_map ,
  46 .Nm bhnd_erom_io_read ,
  47 .Nm bhnd_erom_iobus_init ,
  48 .Nm bhnd_erom_iores_new ,
  49 .Nm bhnd_erom_lookup_core ,
  50 .Nm bhnd_erom_lookup_core_addr ,
  51 .Nm bhnd_erom_probe ,
  52 .Nm bhnd_erom_probe_driver_classes
  53 .Nd BHND device enumeration table parsing
  54 .Sh SYNOPSIS
  55 .In dev/bhnd/bhnd.h
  56 .In dev/bhnd/bhnd_erom.h
  57 .\"
  58 .Vt typedef struct bhnd_erom bhnd_erom_t ;
  59 .Vt typedef struct kobj_class bhnd_erom_class_t ;
  60 .Vt typedef struct bhnd_erom_static bhnd_erom_static_t ;
  61 .Ft int
  62 .Fo bhnd_erom_probe
  63 .Fa "bhnd_erom_class_t *cls"
  64 .Fa "struct bhnd_erom_io *eio"
  65 .Fa "const struct bhnd_chipid *hint"
  66 .Fa "struct bhnd_chipid *cid"
  67 .Fc
  68 .Ft bhnd_erom_class_t *
  69 .Fo bhnd_erom_probe_driver_classes
  70 .Fa "devclass_t bus_devclass"
  71 .Fa "struct bhnd_erom_io *eio"
  72 .Fa "const struct bhnd_chipid *hint"
  73 .Fa "struct bhnd_chipid *cid"
  74 .Fc
  75 .Ft bhnd_erom_t *
  76 .Fo bhnd_erom_alloc
  77 .Fa "bhnd_erom_class_t *cls"
  78 .Fa "const struct bhnd_chipid *cid"
  79 .Fa "struct bhnd_erom_io *eio"
  80 .Fc
  81 .Ft void
  82 .Fo bhnd_erom_free
  83 .Fa "bhnd_erom_t *erom"
  84 .Fc
  85 .Ft int
  86 .Fo bhnd_erom_init_static
  87 .Fa "bhnd_erom_class_t *cls"
  88 .Fa "bhnd_erom_t *erom"
  89 .Fa "size_t esize"
  90 .Fa "const struct bhnd_chipid *cid"
  91 .Fa "struct bhnd_erom_io *eio"
  92 .Fc
  93 .Ft void
  94 .Fo bhnd_erom_fini_static
  95 .Fa "bhnd_erom_t *erom"
  96 .Fc
  97 .Ft int
  98 .Fo bhnd_erom_dump
  99 .Fa "bhnd_erom_t *erom"
 100 .Fc
 101 .Ft int
 102 .Fo bhnd_erom_get_core_table
 103 .Fa "bhnd_erom_t *erom"
 104 .Fa "struct bhnd_core_info **cores"
 105 .Fa "u_int *num_cores"
 106 .Fc
 107 .Ft void
 108 .Fo bhnd_erom_free_core_table
 109 .Fa "bhnd_erom_t *erom"
 110 .Fa "struct bhnd_core_info *cores"
 111 .Fc
 112 .Ft int
 113 .Fo bhnd_erom_lookup_core
 114 .Fa "bhnd_erom_t *erom"
 115 .Fa "const struct bhnd_core_match *desc"
 116 .Fa "struct bhnd_core_info *core"
 117 .Fc
 118 .Ft int
 119 .Fo bhnd_erom_lookup_core_addr
 120 .Fa "bhnd_erom_t *erom"
 121 .Fa "const struct bhnd_core_match *desc"
 122 .Fa "bhnd_port_type type"
 123 .Fa "u_int port"
 124 .Fa "u_int region"
 125 .Fa "struct bhnd_core_info *core"
 126 .Fa "bhnd_addr_t *addr"
 127 .Fa "bhnd_size_t *size"
 128 .Fc
 129 .\"
 130 .Ss Bus Space I/O
 131 .Ft struct bhnd_erom_io *
 132 .Fo bhnd_erom_iores_new
 133 .Fa "device_t dev"
 134 .Fa "int rid"
 135 .Fc
 136 .Ft int
 137 .Fo bhnd_erom_iobus_init
 138 .Fa "struct bhnd_erom_iobus *iobus"
 139 .Fa "bhnd_addr_t addr"
 140 .Fa "bhnd_size_t size"
 141 .Fa "bus_space_tag_t bst"
 142 .Fa "bus_space_handle_t bsh"
 143 .Fc
 144 .Ft void
 145 .Fo bhnd_erom_io_fini
 146 .Fa "struct bhnd_erom_io *eio"
 147 .Fc
 148 .Ft int
 149 .Fo bhnd_erom_io_map
 150 .Fa "struct bhnd_erom_io *eio"
 151 .Fa "bhnd_addr_t addr"
 152 .Fa "bhnd_size_t size"
 153 .Fc
 154 .Ft uint32_t
 155 .Fo bhnd_erom_io_read
 156 .Fa "struct bhnd_erom_io *eio"
 157 .Fa "bhnd_size_t offset"
 158 .Fa "u_int width"
 159 .Fc
 160 .In dev/bhnd/bhnd_eromvar.h
 161 .Bd -literal
 162 struct bhnd_erom_io {
 163         bhnd_erom_io_map_t      *map;
 164         bhnd_erom_io_read_t     *read;
 165         bhnd_erom_io_fini_t     *fini;
 166 };
 167 .Ed
 168 .Ft typedef int
 169 .Fo \*(lpbhnd_erom_io_map_t\*(rp
 170 .Fa "struct bhnd_erom_io *eio"
 171 .Fa "bhnd_addr_t addr"
 172 .Fa "bhnd_size_t size"
 173 .Fc
 174 .Ft typedef uint32_t
 175 .Fo \*(lpbhnd_erom_io_read_t\*(rp
 176 .Fa "struct bhnd_erom_io *eio"
 177 .Fa "bhnd_size_t offset"
 178 .Fa "u_int width"
 179 .Fc
 180 .Ft typedef void
 181 .Fo "\*(lpbhnd_erom_io_fini_t\*(rp
 182 .Fa "struct bhnd_erom_io *eio"
 183 .Fc
 184 .\"
 185 .Sh DESCRIPTION
 186 The
 187 .Nm
 188 framework provides a common parser interface to the BHND device enumeration
 189 table formats supported by
 190 .Xr bhnd 4
 191 bus drivers.
 192 .Pp
 193 The
 194 .Fn bhnd_erom_probe
 195 function is used to identify a
 196 .Xr bhnd 4
 197 bus device and determine whether the erom class
 198 .Fa cls
 199 is capable of parsing its device enumeration table.
 200 If successful, the probed chip identification is written to the location
 201 pointed to by
 202 .Fa cid .
 203 .Pp
 204 A pointer to a bus I/O instance mapping the device registers of the first
 205 hardware core must be provided using the
 206 .Fa eio
 207 argument.
 208 The registers can be mapped using
 209 .Xr bhnd_erom_io_map 9 .
 210 .Pp
 211 On devices that do not provide standard
 212 .Xr bhnd_chipc 4
 213 chip identification registers via the first hardware core, a pointer to chip
 214 information for the device must be specified using the
 215 .Fa hint
 216 argument.
 217 Otherwise, the
 218 .Fa hint
 219 argument should be
 220 .Dv NULL .
 221 .Pp
 222 The
 223 .Fn bhnd_erom_probe_driver_classes
 224 function is a convenience wrapper for
 225 .Fn bhnd_erom_probe .
 226 This function will iterate over all drivers instances in the device class
 227 .Fa bus_devclass ,
 228 using
 229 .Xr bhnd_driver_get_erom_class 9
 230 to fetch each driver's erom class and probe the hardware core mapped by
 231 .Fa eio .
 232 A pointer to the erom class with the highest probe priority is returned on
 233 success.
 234 If there are no successful probe results from the erom classes,
 235 .Dv NULL
 236 is returned.
 237 .Pp
 238 The
 239 .Fn bhnd_erom_alloc
 240 function allocates and returns a new parser instance of the device enumeration
 241 class
 242 .Fa cls
 243 for the chip identified by
 244 .Fa cid ,
 245 using the bus I/O instance
 246 .Fa eio
 247 to map and read the device table.
 248 On success, the returned
 249 .Vt bhnd_erom_t
 250 assumes ownership of
 251 .Fa eio .
 252 .Pp
 253 The
 254 .Fn bhnd_erom_free
 255 function releases all resources held by an erom parser successfully allocated
 256 using
 257 .Fn bhnd_erom_alloc .
 258 .Pp
 259 Clients can manage the allocation of memory themselves with
 260 .Fn bhnd_erom_init_static .
 261 This is useful in cases like performing device enumeration before
 262 .Xr malloc 9
 263 initialization.
 264 .Fn bhnd_erom_init_static
 265 is called with
 266 .Fa erom
 267 set to a pointer to the memory for the instance, and the total available bytes
 268 in
 269 .Fa esize .
 270 .Pp
 271 The
 272 .Vt bhnd_erom_static
 273 structure is large enough to statically allocate any supported parser class
 274 instance state.
 275 Pointers to a
 276 .Vt bhnd_erom_static
 277 structure can be cast to
 278 .Vt bhnd_erom_t .
 279 .Pp
 280 The
 281 .Fn bhnd_erom_fini_static
 282 function releases all resources held by an erom parser successfully
 283 initialized using
 284 .Fn bhnd_erom_init_static .
 285 .Pp
 286 The
 287 .Fn bhnd_erom_dump
 288 function enumerates and prints all device table entries in
 289 .Fa erom .
 290 .Pp
 291 The
 292 .Fn bhnd_erom_get_core_table
 293 function enumerates all device table entries in
 294 .Fa erom ,
 295 returning a table of core information structures in
 296 .Fa cores
 297 and the count in
 298 .Fa num_cores .
 299 The memory allocated for the table must be freed using
 300 .Fn bhnd_erom_free_core_table .
 301 .Pp
 302 The
 303 .Fn bhnd_erom_free_core_table
 304 function frees any memory allocated in a previous call to
 305 .Fn bhnd_erom_get_core_table .
 306 .Pp
 307 The
 308 .Fn bhnd_erom_lookup_core
 309 function locates the first device table entry in
 310 .Fa erom
 311 that matches core match descriptor
 312 .Fa desc ,
 313 writing the core information of the matching entry to
 314 .Fa core .
 315 .Pp
 316 The
 317 .Fn bhnd_erom_lookup_core_addr
 318 function locates the first device table entry in
 319 .Fa erom
 320 that matches core match descriptor
 321 .Fa desc ,
 322 fetching the base address and size of the memory region
 323 .Fa region
 324 mapped to the port
 325 .Fa port
 326 of type
 327 .Fa type .
 328 On success, the core information of the matching entry is written to
 329 .Fa core ,
 330 the base address of the port region is written to
 331 .Fa addr ,
 332 and the total size of the port region is written to
 333 .Fa size .
 334 If the core information is not desired, set
 335 .Fa core
 336 to
 337 .Dv NULL .
 338 .Ss Bus Space I/O
 339 The
 340 .Vt bhnd_erom_io
 341 structure provides a set of I/O callbacks used by
 342 .Nm
 343 to map and read the device enumeration table.
 344 Clients may either use the existing
 345 .Fn bhnd_erom_iores_new
 346 or
 347 .Fn bhnd_erom_iobus_init
 348 functions to allocate a bus I/O instance, or implement the
 349 .Vt bhnd_erom_io
 350 callbacks directly.
 351 .Pp
 352 The
 353 .Vt bhnd_erom_io
 354 structure contains these required fields:
 355 .Bl -tag -width "read" -offset indent
 356 .It Fa map
 357 A function implementing
 358 .Fn bhnd_erom_io_map .
 359 .It Fa read
 360 A function implementing
 361 .Fn bhnd_erom_io_read .
 362 .It Fa fini
 363 A function implementing
 364 .Fn bhnd_erom_io_fini .
 365 .El
 366 .Pp
 367 The
 368 .Fn bhnd_erom_iores_new
 369 function allocates and returns a new bus I/O instance that will perform mapping
 370 by using
 371 .Xr bhnd_alloc_resource 9
 372 to allocate
 373 .Dv SYS_RES_MEMORY
 374 bus resources on demand from the device
 375 .Fa dev
 376 using a resource ID of
 377 .Fa rid .
 378 .Pp
 379 The
 380 .Fn bhnd_erom_iobus_init
 381 function initializes a caller-allocated bus I/O instance
 382 .Fa iobus
 383 that will perform bus I/O using the bus space tag
 384 .Fa bst
 385 and handle
 386 .Fa bsh .
 387 The base address and total size mapped by
 388 .Fa bsh
 389 should be specified using the
 390 .Fa addr
 391 and
 392 .Fa size
 393 arguments.
 394 .Pp
 395 The
 396 .Fn bhnd_erom_io_fini
 397 function frees all resources held by the bus I/O instance
 398 .Fa eio .
 399 .Pp
 400 The
 401 .Fn bhnd_erom_io_map
 402 function is used to request that the bus I/O instance
 403 .Fa eio
 404 map
 405 .Xr bhnd 4
 406 bus space at bus address
 407 .Fa addr
 408 with a mapping of size
 409 .Fa size .
 410 .Pp
 411 The
 412 .Fn bhnd_erom_io_read
 413 function is used to read a data item of
 414 .Fa width
 415 bytes from the bus I/O instance
 416 .Fa eio
 417 at
 418 .Fa offset ,
 419 relative to the bus address previously mapped using
 420 .Fn bhnd_erom_io_map .
 421 .Pp
 422 The
 423 .Fa width
 424 must be one of 1, 2, or 4 bytes.
 425 .Sh RETURN VALUES
 426 The
 427 .Fn bhnd_erom_probe
 428 function returns a standard
 429 .Xr DEVICE_PROBE 9
 430 result.
 431 .Pp
 432 A return value equal to or less than zero indicates success.
 433 Values greater than zero indicates an error, and will be an appropriate error
 434 code.
 435 For values less than or equal to zero, the erom class returning the highest
 436 value should be used to parse the erom table.
 437 .Er ENXIO
 438 is returned if the device is not supported by the parser.
 439 .Pp
 440 The
 441 .Fn bhnd_erom_probe_driver_classes
 442 function returns a pointer to the probed
 443 .Vt bhnd_erom_class_t
 444 instance on success, a null pointer otherwise.
 445 .Pp
 446 The
 447 .Fn bhnd_erom_alloc
 448 function returns a pointer to
 449 .Vt bhnd_erom_t
 450 on success, or
 451 .Dv NULL
 452 if an error occurred allocating or initializing the EROM parser.
 453 .Pp
 454 The
 455 .Fn bhnd_erom_init_static
 456 function returns 0 on success,
 457 .Er ENOMEM
 458 if the allocation size is smaller than required by the erom class, or
 459 an appropriate error code if initialization otherwise fails.
 460 .Pp
 461 The
 462 .Fn bhnd_erom_lookup_core
 463 function returns 0 on success,
 464 .Er ENOENT
 465 if no matching core is found, or an appropriate error code if parsing the device
 466 table otherwise fails.
 467 .Pp
 468 The
 469 .Fn bhnd_erom_dump ,
 470 .Fn bhnd_erom_get_core_table ,
 471 .Fn bhnd_erom_iobus_init ,
 472 .Fn bhnd_erom_io_map ,
 473 functions return 0 on success, otherwise an appropriate error code is returned.
 474 .Sh SEE ALSO
 475 .Xr bhnd 4 ,
 476 .Xr bhnd 9 ,
 477 .Xr bhnd_alloc_resource 9 ,
 478 .Xr bhnd_driver_get_erom_class 9 ,
 479 .Xr bus_space 9
 480 .Sh AUTHORS
 481 .An -nosplit
 482 The
 483 .Nm
 484 framework and this manual page were written by
 485 .An Landon Fuller Aq Mt landonf@FreeBSD.org .