1 .\" Copyright (c) 2015-2016 Landon Fuller <landonf@FreeBSD.org>
2 .\" Copyright (c) 2017 The FreeBSD Foundation
3 .\" All rights reserved.
5 .\" Portions of this documentation were written by Landon Fuller
6 .\" under sponsorship from the FreeBSD Foundation.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
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.
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
38 .Nm bhnd_erom_fini_static ,
40 .Nm bhnd_erom_free_core_table ,
41 .Nm bhnd_erom_get_core_table ,
42 .Nm bhnd_erom_init_static ,
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 ,
52 .Nm bhnd_erom_probe_driver_classes
53 .Nd BHND device enumeration table parsing
56 .In dev/bhnd/bhnd_erom.h
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 ;
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"
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"
77 .Fa "bhnd_erom_class_t *cls"
78 .Fa "const struct bhnd_chipid *cid"
79 .Fa "struct bhnd_erom_io *eio"
83 .Fa "bhnd_erom_t *erom"
86 .Fo bhnd_erom_init_static
87 .Fa "bhnd_erom_class_t *cls"
88 .Fa "bhnd_erom_t *erom"
90 .Fa "const struct bhnd_chipid *cid"
91 .Fa "struct bhnd_erom_io *eio"
94 .Fo bhnd_erom_fini_static
95 .Fa "bhnd_erom_t *erom"
99 .Fa "bhnd_erom_t *erom"
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"
108 .Fo bhnd_erom_free_core_table
109 .Fa "bhnd_erom_t *erom"
110 .Fa "struct bhnd_core_info *cores"
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"
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"
125 .Fa "struct bhnd_core_info *core"
126 .Fa "bhnd_addr_t *addr"
127 .Fa "bhnd_size_t *size"
131 .Ft struct bhnd_erom_io *
132 .Fo bhnd_erom_iores_new
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"
145 .Fo bhnd_erom_io_fini
146 .Fa "struct bhnd_erom_io *eio"
150 .Fa "struct bhnd_erom_io *eio"
151 .Fa "bhnd_addr_t addr"
152 .Fa "bhnd_size_t size"
155 .Fo bhnd_erom_io_read
156 .Fa "struct bhnd_erom_io *eio"
157 .Fa "bhnd_size_t offset"
160 .In dev/bhnd/bhnd_eromvar.h
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;
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"
175 .Fo \*(lpbhnd_erom_io_read_t\*(rp
176 .Fa "struct bhnd_erom_io *eio"
177 .Fa "bhnd_size_t offset"
181 .Fo "\*(lpbhnd_erom_io_fini_t\*(rp
182 .Fa "struct bhnd_erom_io *eio"
188 framework provides a common parser interface to the BHND device enumeration
189 table formats supported by
195 function is used to identify a
197 bus device and determine whether the erom class
199 is capable of parsing its device enumeration table.
200 If successful, the probed chip identification is written to the location
204 A pointer to a bus I/O instance mapping the device registers of the first
205 hardware core must be provided using the
208 The registers can be mapped using
209 .Xr bhnd_erom_io_map 9 .
211 On devices that do not provide standard
213 chip identification registers via the first hardware core, a pointer to chip
214 information for the device must be specified using 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
229 .Xr bhnd_driver_get_erom_class 9
230 to fetch each driver's erom class and probe the hardware core mapped by
232 A pointer to the erom class with the highest probe priority is returned on
234 If there are no successful probe results from the erom classes,
240 function allocates and returns a new parser instance of the device enumeration
243 for the chip identified by
245 using the bus I/O instance
247 to map and read the device table.
248 On success, the returned
255 function releases all resources held by an erom parser successfully allocated
257 .Fn bhnd_erom_alloc .
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
264 .Fn bhnd_erom_init_static
267 set to a pointer to the memory for the instance, and the total available bytes
273 structure is large enough to statically allocate any supported parser class
277 structure can be cast to
281 .Fn bhnd_erom_fini_static
282 function releases all resources held by an erom parser successfully
284 .Fn bhnd_erom_init_static .
288 function enumerates and prints all device table entries in
292 .Fn bhnd_erom_get_core_table
293 function enumerates all device table entries in
295 returning a table of core information structures in
299 The memory allocated for the table must be freed using
300 .Fn bhnd_erom_free_core_table .
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 .
308 .Fn bhnd_erom_lookup_core
309 function locates the first device table entry in
311 that matches core match descriptor
313 writing the core information of the matching entry to
317 .Fn bhnd_erom_lookup_core_addr
318 function locates the first device table entry in
320 that matches core match descriptor
322 fetching the base address and size of the memory region
328 On success, the core information of the matching entry is written to
330 the base address of the port region is written to
332 and the total size of the port region is written to
334 If the core information is not desired, set
341 structure provides a set of I/O callbacks used by
343 to map and read the device enumeration table.
344 Clients may either use the existing
345 .Fn bhnd_erom_iores_new
347 .Fn bhnd_erom_iobus_init
348 functions to allocate a bus I/O instance, or implement the
354 structure contains these required fields:
355 .Bl -tag -width "read" -offset indent
357 A function implementing
358 .Fn bhnd_erom_io_map .
360 A function implementing
361 .Fn bhnd_erom_io_read .
363 A function implementing
364 .Fn bhnd_erom_io_fini .
368 .Fn bhnd_erom_iores_new
369 function allocates and returns a new bus I/O instance that will perform mapping
371 .Xr bhnd_alloc_resource 9
374 bus resources on demand from the device
376 using a resource ID of
380 .Fn bhnd_erom_iobus_init
381 function initializes a caller-allocated bus I/O instance
383 that will perform bus I/O using the bus space tag
387 The base address and total size mapped by
389 should be specified using the
396 .Fn bhnd_erom_io_fini
397 function frees all resources held by the bus I/O instance
402 function is used to request that the bus I/O instance
406 bus space at bus address
408 with a mapping of size
412 .Fn bhnd_erom_io_read
413 function is used to read a data item of
415 bytes from the bus I/O instance
419 relative to the bus address previously mapped using
420 .Fn bhnd_erom_io_map .
424 must be one of 1, 2, or 4 bytes.
428 function returns a standard
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
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.
438 is returned if the device is not supported by the parser.
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.
448 function returns a pointer to
452 if an error occurred allocating or initializing the EROM parser.
455 .Fn bhnd_erom_init_static
456 function returns 0 on success,
458 if the allocation size is smaller than required by the erom class, or
459 an appropriate error code if initialization otherwise fails.
462 .Fn bhnd_erom_lookup_core
463 function returns 0 on success,
465 if no matching core is found, or an appropriate error code if parsing the device
466 table otherwise fails.
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.
477 .Xr bhnd_alloc_resource 9 ,
478 .Xr bhnd_driver_get_erom_class 9 ,
484 framework and this manual page were written by
485 .An Landon Fuller Aq Mt landonf@FreeBSD.org .