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