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 162struct 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 186The 187.Nm 188framework provides a common parser interface to the BHND device enumeration 189table formats supported by 190.Xr bhnd 4 191bus drivers. 192.Pp 193The 194.Fn bhnd_erom_probe 195function is used to identify a 196.Xr bhnd 4 197bus device and determine whether the erom class 198.Fa cls 199is capable of parsing its device enumeration table. 200If successful, the probed chip identification is written to the location 201pointed to by 202.Fa cid . 203.Pp 204A pointer to a bus I/O instance mapping the device registers of the first 205hardware core must be provided using the 206.Fa eio 207argument. 208The registers can be mapped using 209.Xr bhnd_erom_io_map 9 . 210.Pp 211On devices that do not provide standard 212.Xr bhnd_chipc 4 213chip identification registers via the first hardware core, a pointer to chip 214information for the device must be specified using the 215.Fa hint 216argument. 217Otherwise, the 218.Fa hint 219argument should be 220.Dv NULL . 221.Pp 222The 223.Fn bhnd_erom_probe_driver_classes 224function is a convenience wrapper for 225.Fn bhnd_erom_probe . 226This function will iterate over all drivers instances in the device class 227.Fa bus_devclass , 228using 229.Xr bhnd_driver_get_erom_class 9 230to fetch each driver's erom class and probe the hardware core mapped by 231.Fa eio . 232A pointer to the erom class with the highest probe priority is returned on 233success. 234If there are no successful probe results from the erom classes, 235.Dv NULL 236is returned. 237.Pp 238The 239.Fn bhnd_erom_alloc 240function allocates and returns a new parser instance of the device enumeration 241class 242.Fa cls 243for the chip identified by 244.Fa cid , 245using the bus I/O instance 246.Fa eio 247to map and read the device table. 248On success, the returned 249.Vt bhnd_erom_t 250assumes ownership of 251.Fa eio . 252.Pp 253The 254.Fn bhnd_erom_free 255function releases all resources held by an erom parser successfully allocated 256using 257.Fn bhnd_erom_alloc . 258.Pp 259Clients can manage the allocation of memory themselves with 260.Fn bhnd_erom_init_static . 261This is useful in cases like performing device enumeration before 262.Xr malloc 9 263initialization. 264.Fn bhnd_erom_init_static 265is called with 266.Fa erom 267set to a pointer to the memory for the instance, and the total available bytes 268in 269.Fa esize . 270.Pp 271The 272.Vt bhnd_erom_static 273structure is large enough to statically allocate any supported parser class 274instance state. 275Pointers to a 276.Vt bhnd_erom_static 277structure can be cast to 278.Vt bhnd_erom_t . 279.Pp 280The 281.Fn bhnd_erom_fini_static 282function releases all resources held by an erom parser successfully 283initialized using 284.Fn bhnd_erom_init_static . 285.Pp 286The 287.Fn bhnd_erom_dump 288function enumerates and prints all device table entries in 289.Fa erom . 290.Pp 291The 292.Fn bhnd_erom_get_core_table 293function enumerates all device table entries in 294.Fa erom , 295returning a table of core information structures in 296.Fa cores 297and the count in 298.Fa num_cores . 299The memory allocated for the table must be freed using 300.Fn bhnd_erom_free_core_table . 301.Pp 302The 303.Fn bhnd_erom_free_core_table 304function frees any memory allocated in a previous call to 305.Fn bhnd_erom_get_core_table . 306.Pp 307The 308.Fn bhnd_erom_lookup_core 309function locates the first device table entry in 310.Fa erom 311that matches core match descriptor 312.Fa desc , 313writing the core information of the matching entry to 314.Fa core . 315.Pp 316The 317.Fn bhnd_erom_lookup_core_addr 318function locates the first device table entry in 319.Fa erom 320that matches core match descriptor 321.Fa desc , 322fetching the base address and size of the memory region 323.Fa region 324mapped to the port 325.Fa port 326of type 327.Fa type . 328On success, the core information of the matching entry is written to 329.Fa core , 330the base address of the port region is written to 331.Fa addr , 332and the total size of the port region is written to 333.Fa size . 334If the core information is not desired, set 335.Fa core 336to 337.Dv NULL . 338.Ss Bus Space I/O 339.Pp 340The 341.Vt bhnd_erom_io 342structure provides a set of I/O callbacks used by 343.Nm 344to map and read the device enumeration table. 345Clients may either use the existing 346.Fn bhnd_erom_iores_new 347or 348.Fn bhnd_erom_iobus_init 349functions to allocate a bus I/O instance, or implement the 350.Vt bhnd_erom_io 351callbacks directly. 352.Pp 353The 354.Vt bhnd_erom_io 355structure contains these required fields: 356.Pp 357.Bl -tag -width "read" -offset indent 358.It Fa map 359A function implementing 360.Fn bhnd_erom_io_map . 361.It Fa read 362A function implementing 363.Fn bhnd_erom_io_read . 364.It Fa fini 365A function implementing 366.Fn bhnd_erom_io_fini . 367.El 368.Pp 369The 370.Fn bhnd_erom_iores_new 371function allocates and returns a new bus I/O instance that will perform mapping 372by using 373.Xr bhnd_alloc_resource 9 374to allocate 375.Dv SYS_RES_MEMORY 376bus resources on demand from the device 377.Fa dev 378using a resource ID of 379.Fa rid . 380.Pp 381The 382.Fn bhnd_erom_iobus_init 383function initializes a caller-allocated bus I/O instance 384.Fa iobus 385that will perform bus I/O using the bus space tag 386.Fa bst 387and handle 388.Fa bsh . 389The base address and total size mapped by 390.Fa bsh 391should be specified using the 392.Fa addr 393and 394.Fa size 395arguments. 396.Pp 397The 398.Fn bhnd_erom_io_fini 399function frees all resources held by the bus I/O instance 400.Fa eio . 401.Pp 402The 403.Fn bhnd_erom_io_map 404function is used to request that the bus I/O instance 405.Fa eio 406map 407.Xr bhnd 4 408bus space at bus address 409.Fa addr 410with a mapping of size 411.Fa size . 412.Pp 413The 414.Fn bhnd_erom_io_read 415function is used to read a data item of 416.Fa width 417bytes from the bus I/O instance 418.Fa eio 419at 420.Fa offset , 421relative to the bus address previously mapped using 422.Fn bhnd_erom_io_map . 423.Pp 424The 425.Fa width 426must be one of 1, 2, or 4 bytes. 427.Pp 428.Sh RETURN VALUES 429The 430.Fn bhnd_erom_probe 431function returns a standard 432.Xr DEVICE_PROBE 9 433result. 434.Pp 435A return value equal to or less than zero indicates success. 436Values greater than zero indicates an error, and will be an appropriate error 437code. 438For values less than or equal to zero, the erom class returning the highest 439value should be used to parse the erom table. 440.Er ENXIO 441is returned if the device is not supported by the parser. 442.Pp 443The 444.Fn bhnd_erom_probe_driver_classes 445function returns a pointer to the probed 446.Vt bhnd_erom_class_t 447instance on success, a null pointer otherwise. 448.Pp 449The 450.Fn bhnd_erom_alloc 451function returns a pointer to 452.Vt bhnd_erom_t 453on success, or 454.Dv NULL 455if an error occurred allocating or initializing the EROM parser. 456.Pp 457The 458.Fn bhnd_erom_init_static 459function returns 0 on success, 460.Er ENOMEM 461if the allocation size is smaller than required by the erom class, or 462an appropriate error code if initialization otherwise fails. 463.Pp 464The 465.Fn bhnd_erom_lookup_core 466function returns 0 on success, 467.Er ENOENT 468if no matching core is found, or an appropriate error code if parsing the device 469table otherwise fails. 470.Pp 471The 472.Fn bhnd_erom_dump , 473.Fn bhnd_erom_get_core_table , 474.Fn bhnd_erom_iobus_init , 475.Fn bhnd_erom_io_map , 476functions return 0 on success, otherwise an appropriate error code is returned. 477.Sh SEE ALSO 478.Xr bhnd 4 , 479.Xr bhnd 9 , 480.Xr bhnd_alloc_resource 9 481.Xr bhnd_driver_get_erom_class 9 482.Xr bus_space 9 483.Sh AUTHORS 484.An -nosplit 485The 486.Nm 487framework and this manual page were written by 488.An Landon Fuller Aq Mt landonf@FreeBSD.org . 489