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
36 .Nd BHND driver programming interface
40 .Ss Bus Resource Functions
42 .Fo bhnd_activate_resource
43 .Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r"
45 .Ft "struct bhnd_resource *"
46 .Fo bhnd_alloc_resource
47 .Fa "device_t dev" "int type" "int *rid" "rman_res_t start" "rman_res_t end"
48 .Fa "rman_res_t count" "u_int flags"
50 .Ft "struct bhnd_resource *"
51 .Fo bhnd_alloc_resource_any
52 .Fa "device_t dev" "int type" "int *rid" "u_int flags"
55 .Fo bhnd_alloc_resources
56 .Fa "device_t dev" "struct resource_spec *rs" "struct bhnd_resource **res"
59 .Fo bhnd_deactivate_resource
60 .Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r"
63 .Fo bhnd_release_resource
64 .Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r"
67 .Fo bhnd_release_resources
68 .Fa "device_t dev" "const struct resource_spec *rs"
69 .Fa "struct bhnd_resource **res"
72 .Ss "Bus Space Functions"
75 .Fa "struct bhnd_resource *r" "bus_size_t offset"
76 .Fa "bus_size_t length" "int flags"
79 .Fn bhnd_bus_read_1 "struct bhnd_resource *r" "bus_size_t offset"
81 .Fn bhnd_bus_read_2 "struct bhnd_resource *r" "bus_size_t offset"
83 .Fn bhnd_bus_read_4 "struct bhnd_resource *r" "bus_size_t offset"
85 .Fo bhnd_bus_read_multi_1
86 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
87 .Fa "bus_size_t count"
90 .Fo bhnd_bus_read_multi_2
91 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
92 .Fa "bus_size_t count"
95 .Fo bhnd_bus_read_multi_4
96 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
97 .Fa "bus_size_t count"
100 .Fo bhnd_bus_read_multi_stream_1
101 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
102 .Fa "bus_size_t count"
105 .Fo bhnd_bus_read_multi_stream_2
106 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
107 .Fa "bus_size_t count"
110 .Fo bhnd_bus_read_multi_stream_4
111 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
112 .Fa "bus_size_t count"
115 .Fo bhnd_bus_read_region_1
116 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
117 .Fa "bus_size_t count"
120 .Fo bhnd_bus_read_region_2
121 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
122 .Fa "bus_size_t count"
125 .Fo bhnd_bus_read_region_4
126 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
127 .Fa "bus_size_t count"
130 .Fo bhnd_bus_read_region_stream_1
131 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
132 .Fa "bus_size_t count"
135 .Fo bhnd_bus_read_region_stream_2
136 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
137 .Fa "bus_size_t count"
140 .Fo bhnd_bus_read_region_stream_4
141 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
142 .Fa "bus_size_t count"
145 .Fn bhnd_bus_read_stream_1 "struct bhnd_resource *r" "bus_size_t offset"
147 .Fn bhnd_bus_read_stream_2 "struct bhnd_resource *r" "bus_size_t offset"
149 .Fn bhnd_bus_read_stream_4 "struct bhnd_resource *r" "bus_size_t offset"
151 .Fo bhnd_bus_set_multi_1
152 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t value"
153 .Fa "bus_size_t count"
156 .Fo bhnd_bus_set_multi_2
157 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t value"
158 .Fa "bus_size_t count"
161 .Fo bhnd_bus_set_multi_4
162 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t value"
163 .Fa "bus_size_t count"
166 .Fo bhnd_bus_set_region_1
167 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t value"
168 .Fa "bus_size_t count"
171 .Fo bhnd_bus_set_region_2
172 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t value"
173 .Fa "bus_size_t count"
176 .Fo bhnd_bus_set_region_4
177 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t value"
178 .Fa "bus_size_t count"
181 .Fn bhnd_bus_write_1 "struct bhnd_resource *r" "uint8_t value"
183 .Fn bhnd_bus_write_2 "struct bhnd_resource *r" "uint16_t value"
185 .Fn bhnd_bus_write_4 "struct bhnd_resource *r" "uint32_t value"
187 .Fo bhnd_bus_write_multi_1
188 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
189 .Fa "bus_size_t count"
192 .Fo bhnd_bus_write_multi_2
193 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
194 .Fa "bus_size_t count"
197 .Fo bhnd_bus_write_multi_4
198 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
199 .Fa "bus_size_t count"
202 .Fo bhnd_bus_write_multi_stream_1
203 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
204 .Fa "bus_size_t count"
207 .Fo bhnd_bus_write_multi_stream_2
208 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
209 .Fa "bus_size_t count"
212 .Fo bhnd_bus_write_multi_stream_4
213 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
214 .Fa "bus_size_t count"
217 .Fo bhnd_bus_write_region_1
218 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
219 .Fa "bus_size_t count"
222 .Fo bhnd_bus_write_region_2
223 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
224 .Fa "bus_size_t count"
227 .Fo bhnd_bus_write_region_4
228 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
229 .Fa "bus_size_t count"
232 .Fo bhnd_bus_write_region_stream_1
233 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap"
234 .Fa "bus_size_t count"
237 .Fo bhnd_bus_write_region_stream_2
238 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap"
239 .Fa "bus_size_t count"
242 .Fo bhnd_bus_write_region_stream_4
243 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap"
244 .Fa "bus_size_t count"
247 .Fn bhnd_bus_write_stream_1 "struct bhnd_resource *r" "uint8_t value"
249 .Fn bhnd_bus_write_stream_2 "struct bhnd_resource *r" "uint16_t value"
251 .Fn bhnd_bus_write_stream_4 "struct bhnd_resource *r" "uint32_t value"
253 .Ss "Device Configuration Functions"
255 .Fn bhnd_read_ioctl "device_t dev" "uint16_t *ioctl"
257 .Fn bhnd_write_ioctl "device_t dev" "uint16_t value" "uint16_t mask"
259 .Fn bhnd_read_iost "device_t dev" "uint16_t *iost"
262 .Fa "device_t dev" "bus_size_t offset" "void *value" "u_int width"
265 .Fo bhnd_write_config
266 .Fa "device_t dev" "bus_size_t offset" "const void *value" "u_int width"
269 .Fn bhnd_reset_hw "device_t dev" "uint16_t ioctl" "uint16_t reset_ioctl"
271 .Fn bhnd_suspend_hw "device_t dev" "uint16_t ioctl"
273 .Fn bhnd_is_hw_suspended "device_t dev"
275 .Ss "Device Information Functions"
277 .Fo bhnd_get_attach_type
280 .Ft "const struct bhnd_chipid *"
289 .Fo bhnd_get_core_index
292 .Ft "struct bhnd_core_info"
293 .Fo bhnd_get_core_info
297 .Fo bhnd_get_core_unit
305 .Fo bhnd_get_device_name
317 .Fo bhnd_get_vendor_name
321 .Fo bhnd_read_board_info
322 .Fa "device_t dev" "struct bhnd_board_info *info"
325 .Ss "Device Matching Functions"
327 .Fo bhnd_board_matches
328 .Fa "const struct bhnd_board_info *board" "const struct bhnd_board_match *desc"
331 .Fo bhnd_bus_match_child
332 .Fa "device_t bus" "const struct bhnd_core_match *desc"
335 .Fo bhnd_chip_matches
336 .Fa "const struct bhnd_chipid *chip" "const struct bhnd_chip_match *desc"
338 .Ft "struct bhnd_core_match"
339 .Fo bhnd_core_get_match_desc
340 .Fa "const struct bhnd_core_info *core"
343 .Fo bhnd_core_matches
344 .Fa "const struct bhnd_core_info *core" "const struct bhnd_core_match *desc"
348 .Fa "const struct bhnd_core_info *lhs" "const struct bhnd_core_info *rhs"
351 .Fo bhnd_hwrev_matches
352 .Fa "uint16_t hwrev" "const struct bhnd_hwrev_match *desc"
354 .Ft "const struct bhnd_core_info *"
356 .Fa "const struct bhnd_core_info *cores" "u_int num_cores"
357 .Fa "const struct bhnd_core_match *desc"
360 .Ss "Device Table Functions"
361 .Ft "const struct bhnd_device *"
362 .Fo bhnd_device_lookup
363 .Fa "device_t dev" "const struct bhnd_device *table" "size_t entry_size"
366 .Fo bhnd_device_matches
367 .Fa "device_t dev" "const struct bhnd_device_match *desc"
370 .Fo bhnd_device_quirks
371 .Fa "device_t dev" "const struct bhnd_device *table" "size_t entry_size"
377 .Fa "chip" "hwrev" "flags"
383 .Fa "vendor" "device" "desc" "quirks" "..."
385 .Fo BHND_DEVICE_IS_END
386 .Fa "struct bhnd_device *d"
388 .Fo BHND_DEVICE_QUIRK_IS_END
389 .Fa "struct bhnd_device_quirk *q"
392 .Fa "chip" "pkg" "flags"
395 struct bhnd_device_quirk {
396 struct bhnd_device_match desc;
402 const struct bhnd_device_match core;
404 const struct bhnd_device_quirk *quirks_table;
405 uint32_t device_flags;
411 BHND_DF_HOSTB = (1 << 0),
412 BHND_DF_SOC = (1 << 1),
413 BHND_DF_ADAPTER = (1 << 2)
417 #define BHND_DEVICE_END { { BHND_MATCH_ANY }, NULL, NULL, 0 }
420 #define BHND_DEVICE_QUIRK_END { { BHND_MATCH_ANY }, 0 }
423 .Ss "DMA Address Translation Functions"
425 .Fo bhnd_get_dma_translation
426 .Fa "device_t dev" "u_int width" "uint32_t flags" "bus_dma_tag_t *dmat"
427 .Fa "struct bhnd_dma_translation *translation"
430 struct bhnd_dma_translation {
431 bhnd_addr_t base_addr;
432 bhnd_addr_t addr_mask;
433 bhnd_addr_t addrext_mask;
439 BHND_DMA_ADDR_30BIT = 30,
440 BHND_DMA_ADDR_32BIT = 32,
441 BHND_DMA_ADDR_64BIT = 64
442 } bhnd_dma_addrwidth;
445 enum bhnd_dma_translation_flags {
446 BHND_DMA_TRANSLATION_PHYSMAP = (1<<0),
447 BHND_DMA_TRANSLATION_BYTESWAPPED = (1<<1)
451 .Ss "Interrupt Functions"
453 .Fo bhnd_get_intr_count
457 .Fo bhnd_get_intr_ivec
458 .Fa "device_t dev" "u_int intr" "u_int *ivec"
462 .Fa "device_t dev" "u_int intr" "rman_res_t *irq"
466 .Fa "device_t dev" "rman_res_t irq"
469 .Ss "NVRAM Functions"
471 .Fo bhnd_nvram_getvar
472 .Fa "device_t dev" "const char *name" "void *buf" "size_t *len"
473 .Fa "bhnd_nvram_type type"
476 .Fo bhnd_nvram_getvar_array
477 .Fa "device_t dev" "const char *name" "void *buf" "size_t size"
478 .Fa "bhnd_nvram_type type"
481 .Fo bhnd_nvram_getvar_int
482 .Fa "device_t dev" "const char *name" "void *value" "int width"
485 .Fn bhnd_nvram_getvar_int8 "device_t dev" "const char *name" "int8_t *value"
487 .Fn bhnd_nvram_getvar_int16 "device_t dev" "const char *name" "int16_t *value"
489 .Fn bhnd_nvram_getvar_int32 "device_t dev" "const char *name" "int32_t *value"
491 .Fo bhnd_nvram_getvar_uint
492 .Fa "device_t dev" "const char *name" "void *value" "int width"
495 .Fo bhnd_nvram_getvar_uint8
496 .Fa "device_t dev" "const char *name" "uint8_t *value"
499 .Fo bhnd_nvram_getvar_uint16
500 .Fa "device_t dev" "const char *name" "uint16_t *value"
503 .Fo bhnd_nvram_getvar_uint32
504 .Fa "device_t dev" "const char *name" "uint32_t *value"
507 .Fo bhnd_nvram_getvar_str
508 .Fa "device_t dev" "const char *name" "char *buf" "size_t len" "size_t *rlen"
511 .Fo bhnd_nvram_string_array_next
512 .Fa "const char *inp" "size_t ilen" "const char *prev" "size_t *olen"
516 BHND_NVRAM_TYPE_UINT8 = 0,
517 BHND_NVRAM_TYPE_UINT16 = 1,
518 BHND_NVRAM_TYPE_UINT32 = 2,
519 BHND_NVRAM_TYPE_UINT64 = 3,
520 BHND_NVRAM_TYPE_INT8 = 4,
521 BHND_NVRAM_TYPE_INT16 = 5,
522 BHND_NVRAM_TYPE_INT32 = 6,
523 BHND_NVRAM_TYPE_INT64 = 7,
524 BHND_NVRAM_TYPE_CHAR = 8,
525 BHND_NVRAM_TYPE_STRING = 9,
526 BHND_NVRAM_TYPE_BOOL = 10,
527 BHND_NVRAM_TYPE_NULL = 11,
528 BHND_NVRAM_TYPE_DATA = 12
529 BHND_NVRAM_TYPE_UINT8_ARRAY = 16,
530 BHND_NVRAM_TYPE_UINT16_ARRAY = 17,
531 BHND_NVRAM_TYPE_UINT32_ARRAY = 18,
532 BHND_NVRAM_TYPE_UINT64_ARRAY = 19,
533 BHND_NVRAM_TYPE_INT8_ARRAY = 20,
534 BHND_NVRAM_TYPE_INT16_ARRAY = 21,
535 BHND_NVRAM_TYPE_INT32_ARRAY = 22,
536 BHND_NVRAM_TYPE_INT64_ARRAY = 23,
537 BHND_NVRAM_TYPE_CHAR_ARRAY = 24,
538 BHND_NVRAM_TYPE_STRING_ARRAY = 25,
539 BHND_NVRAM_TYPE_BOOL_ARRAY = 26
543 .Ss "Port/Region Functions"
545 .Fo bhnd_decode_port_rid
546 .Fa "device_t dev" "int type" "int rid" "bhnd_port_type *port_type"
547 .Fa "u_int *port" "u_int *region"
550 .Fo bhnd_get_port_count
551 .Fa "device_t dev" "bhnd_port_type type"
554 .Fo bhnd_get_port_rid
555 .Fa "device_t dev" "bhnd_port_type type" "u_int port" "u_int region"
558 .Fo bhnd_get_region_addr
559 .Fa "device_t dev" "bhnd_port_type port_type" "u_int port" "u_int region"
560 .Fa "bhnd_addr_t *region_addr" "bhnd_size_t *region_size"
563 .Fo bhnd_get_region_count
564 .Fa "device_t dev" "bhnd_port_type type" "u_int port"
567 .Fo bhnd_is_region_valid
568 .Fa "device_t dev" "bhnd_port_type type" "u_int port" "u_int region"
572 BHND_PORT_DEVICE = 0,
573 BHND_PORT_BRIDGE = 1,
578 .Ss "Power Management Functions"
588 .Fo bhnd_enable_clocks
589 .Fa "device_t dev" "uint32_t clocks"
592 .Fo bhnd_request_clock
593 .Fa "device_t dev" "bhnd_clock clock"
596 .Fo bhnd_get_clock_freq
597 .Fa "device_t dev" "bhnd_clock clock" "u_int *freq"
600 .Fo bhnd_get_clock_latency
601 .Fa "device_t dev" "bhnd_clock clock" "u_int *latency"
604 .Fo bhnd_request_ext_rsrc
605 .Fa "device_t dev" "u_int rsrc"
608 .Fo bhnd_release_ext_rsrc
609 .Fa "device_t dev" "u_int rsrc"
613 BHND_CLOCK_DYN = (1 << 0),
614 BHND_CLOCK_ILP = (1 << 1),
615 BHND_CLOCK_ALP = (1 << 2),
616 BHND_CLOCK_HT = (1 << 3)
620 .Ss "Service Provider Functions"
622 .Fo bhnd_register_provider
623 .Fa "device_t dev" "bhnd_service_t service"
626 .Fo bhnd_deregister_provider
627 .Fa "device_t dev" "bhnd_service_t service"
630 .Fo bhnd_retain_provider
631 .Fa "device_t dev" "bhnd_service_t service"
634 .Fo bhnd_release_provider
635 .Fa "device_t dev" "device_t provider" "bhnd_service_t service"
644 BHND_SERVICE_ANY = 1000
648 .Ss "Utility Functions"
649 .Ft "bhnd_erom_class_t *"
650 .Fo bhnd_driver_get_erom_class
651 .Fa "driver_t *driver"
654 .Fo bhnd_find_core_class
655 .Fa "uint16_t vendor" "uint16_t device"
658 .Fo bhnd_find_core_name
659 .Fa "uint16_t vendor" "uint16_t device"
663 .Fa "const struct bhnd_core_info *ci"
667 .Fa "const struct bhnd_core_info *ci"
670 .Fo bhnd_format_chip_id
671 .Fa "char *buffer" "size_t size" "uint16_t chip_id"
674 .Fo bhnd_set_custom_core_desc
675 .Fa "device_t dev" "const char *dev_name"
678 .Fo bhnd_set_default_core_desc
683 .Fa "uint16_t vendor"
686 #define BHND_CHIPID_MAX_NAMELEN 32
691 provides a unified bus and driver programming interface for the
692 on-chip interconnects and IP cores found in Broadcom Home Networking Division
695 The BHND device family consists of MIPS/ARM SoCs (System On a Chip) and
696 host-connected chipsets based on a common library of Broadcom IP cores,
697 connected via one of two on-chip backplane (hardware bus) architectures.
699 Hardware designed prior to 2009 used Broadcom's
701 backplane architecture, based on Sonics Silicon's interconnect IP.
702 Each core on the Sonics backplane vends a 4 KiB register block, containing both
703 device-specific CSRs, and SSB-specific per-core device management
704 (enable/reset/etc) registers.
706 Subsequent hardware is based on Broadcom's
708 backplane, based on ARM's AMBA IP.
709 The IP cores used in earlier SSB-based devices were adapted for compatibility
710 with the new backplane, with additional
712 cores providing per-core device management functions in place of the SSB
713 per-core management registers.
715 When BHND hardware is used as a host-connected peripheral (e.g., in a PCI Wi-Fi
716 card), the on-chip peripheral controller core is configured to operate as
717 an endpoint device, bridging access to the SoC hardware:
719 .Bl -dash -offset indent
721 Host access to SoC address space is provided via a set of register windows
722 (e.g., a set of configurable windows into SoC address space mapped via PCI BARs)
724 DMA is supported by the bridge core's sparse mapping of host address space into
725 the backplane address space.
726 These address regions may be used as a target for the on-chip DMA engine.
728 Any backplane interrupt vectors routed to the bridge core may be mapped by the
729 bridge to host interrupts (e.g., PCI INTx/MSI/MSI-X).
734 driver programming interface \(em and
736 host bridge drivers \(em support the implementation of common drivers for
737 Broadcom IP cores, whether attached via a BHND host bridge, or via the native
740 .Ss "Bus Resource Functions"
741 The bhnd_resource functions are wrappers for the standard
742 .Vt "struct resource"
743 bus APIs, providing support for
747 bridged chipsets, may require on-demand remapping of address windows
748 prior to accessing bus memory.
750 These functions are primarily used in the implementation of BHND platform device
751 drivers that, on host-connected peripherals, must share a small set of register
752 windows during initial setup and teardown.
754 BHND peripherals are designed to not require register window remapping
755 during normal operation, and most drivers may safely use the standard
760 .Fn bhnd_activate_resource
761 function activates a previously allocated resource.
763 The arguments are as follows:
764 .Bl -tag -width indent
766 The device holding ownership of the allocated resource.
768 The type of the resource.
770 The bus-specific handle that identifies the resource being activated.
772 A pointer to the resource returned by
773 .Fn bhnd_alloc_resource .
777 .Fn bhnd_alloc_resource
778 function allocates a resource from a device's parent
782 The arguments are as follows:
783 .Bl -tag -width indent
785 The device requesting resource ownership.
787 The type of resource to allocate.
788 This may be any type supported by the standard
789 .Xr bus_alloc_resource 9
792 The bus-specific handle identifying the resource being allocated.
794 The start address of the resource.
796 The end address of the resource.
798 The size of the resource.
800 The flags for the resource to be allocated.
801 These may be any values supported by the standard
802 .Xr bus_alloc_resource 9
806 To request that the bus supply the resource's default
815 values of 0ul and ~0ul respectively, and a
820 .Fn bhnd_alloc_resource_any
821 function is a convenience wrapper for
822 .Fn bhnd_alloc_resource ,
823 using the resource's default
830 The arguments are as follows:
831 .Bl -tag -width indent
833 The device requesting resource ownership.
835 The type of resource to allocate.
836 This may be any type supported by the standard
837 .Xr bus_alloc_resource 9
840 The bus-specific handle identifying the resource being allocated.
842 The flags for the resource to be allocated.
843 These may be any values supported by the standard
844 .Xr bus_alloc_resource 9
849 .Fn bhnd_alloc_resources
850 function allocates resources defined in resource specification from a device's
855 The arguments are as follows:
856 .Bl -tag -width indent
858 The device requesting ownership of the resources.
860 A standard bus resource specification. If all requested resources, are
861 successfully allocated, this will be updated with the allocated resource
864 If all requested resources are successfully allocated, this will be populated
866 .Vt "struct bhnd_resource"
871 .Fn bhnd_deactivate_resource
872 function deactivates a resource previously activated by.
873 .Fn bhnd_activate_resource .
874 The arguments are as follows:
875 .Bl -tag -width indent
877 The device holding ownership of the activated resource.
879 The type of the resource.
881 The bus-specific handle identifying the resource.
883 A pointer to the resource returned by bhnd_alloc_resource.
887 .Fn bhnd_release_resource
888 function frees a resource previously returned by
889 .Fn bhnd_alloc_resource .
890 The arguments are as follows:
891 .Bl -tag -width indent
893 The device holding ownership of the resource.
895 The type of the resource.
897 The bus-specific handle identifying the resource.
899 A pointer to the resource returned by bhnd_alloc_resource.
903 .Fn bhnd_release_resources
904 function frees resources previously returned by
905 .Fn bhnd_alloc_resources .
906 The arguments are as follows:
907 .Bl -tag -width indent
909 The device that owns the resources.
911 A standard bus resource specification previously initialized by
912 .Fn bhnd_alloc_resources .
914 The resources to be released.
919 structure contains the following fields:
920 .Bl -tag -width "direct"
923 .Vt struct resource .
925 If true, the resource requires bus window remapping before it is MMIO
930 .Ss "Bus Space Functions"
931 The bhnd_bus_space functions wrap their equivalent
933 counterparts, and provide support for accessing bus memory via
934 .Vt "struct bhnd_resource".
936 .Bl -ohang -offset indent -compact
937 .It Fn bhnd_bus_barrier
938 .It Fn bhnd_bus_[read|write]_[1|2|4]
939 .It Fn bhnd_bus_[read_multi|write_multi]_[1|2|4]
940 .It Fn bhnd_bus_[read_multi_stream|write_multi_stream]_[1|2|4]
941 .It Fn bhnd_bus_[read_region|write_region]_[1|2|4]
942 .It Fn bhnd_bus_[read_region_stream|write_region_stream]_[1|2|4]
943 .It Fn bhnd_bus_[read_stream|write_stream]_[1|2|4]
944 .It Fn bhnd_bus_[set_multi|set_stream]_[1|2|4]
947 Drivers that do not rely on
948 .Vt "struct bhnd_resource"
949 should use the standard
955 .Ss "Device Configuration Functions"
958 function is used to read the I/O control register value of device
960 returning the current value in
965 function is used to modify the I/O control register of
967 The new value of the register is computed by updating any bits set in
971 The following I/O control flags are supported:
972 .Bl -tag -width ".Dv BHND_IOCTL_CLK_FORCE" -offset indent
973 .It Dv BHND_IOCTL_BIST
974 Initiate a built-in self-test (BIST).
975 Must be cleared after BIST results are read via the IOST (I/O Status) register.
976 .It Dv BHND_IOCTL_PME
977 Enable posting of power management events by the core.
978 .It Dv BHND_IOCTL_CLK_FORCE
979 Force disable of clock gating, resulting in all clocks being distributed within
981 Should be set when asserting/deasserting reset to ensure the reset signal fully
982 propagates to the entire core.
983 .It Dv BHND_IOCTL_CLK_EN
984 If cleared, the core clock will be disabled.
985 Should be set during normal operation, and cleared when the core is held in
987 .It Dv BHND_IOCTL_CFLAGS
988 The mask of IOCTL bits reserved for additional core-specific I/O control flags.
993 function is used to read the I/O status register of device
995 returning the current value in
997 The following I/O status flags are supported:
998 .Bl -tag -width ".Dv BHND_IOST_BIST_DONE" -offset indent
999 .It Dv BHND_IOST_BIST_DONE
1000 Set upon BIST completion.
1001 Will be cleared when the
1003 flag of the I/O control register is cleared using
1004 .Fn bhnd_write_ioctl .
1005 .It Dv BHND_IOST_BIST_FAIL
1006 Set upon detection of a BIST error; the value is unspecified if BIST has not
1008 .Dv BHND_IOST_BIST_DONE
1010 .It Dv BHND_IOST_CLK
1011 Set if the core has required that clocked be ungated, or cleared otherwise.
1012 The value is undefined if a core does not support clock gating.
1013 .It Dv BHND_IOST_DMA64
1014 Set if this core supports 64-bit DMA.
1015 .It Dv BHND_IOST_CFLAGS
1016 The mask of IOST bits reserved for additional core-specific I/O status flags.
1020 .Fn bhnd_read_config
1021 function is used to read a data item of
1025 from the backplane-specific agent/config space of the device
1029 .Fn bhnd_write_config
1030 function is used to write a data item of
1036 from the backplane-specific agent/config space of the device
1040 must be one of 1, 2, or 4 bytes.
1042 The agent/config space accessible via
1043 .Fn bhnd_read_config
1045 .Fn bhnd_write_config
1046 is backplane-specific, and these functions should only be used for functionality
1047 that is not available via another
1053 function transitions the device
1059 to the I/O control flags of
1061 The hardware may be brought out of this state using
1066 function first transitions the device
1068 to a low power RESET state, writing
1070 to the I/O control flags
1073 and then brings the device out of RESET, writing
1075 to the device's I/O control flags.
1078 .Fn bhnd_is_hw_suspended
1083 is currently held in a RESET state, or is otherwise not clocked.
1084 Otherwise, it returns
1087 Any outstanding per-device PMU requests made using
1088 .Fn bhnd_enable_clocks ,
1089 .Fn bhnd_request_clock ,
1091 .Fn bhnd_request_ext_rsrc
1092 will be released automatically upon placing a device into a RESET state.
1093 .Ss "Device Information Functions"
1095 .Fn bhnd_get_attach_type
1096 function returns the attachment type of the parent
1101 The following attachment types are supported:
1102 .Bl -hang -width ".Dv BHND_ATTACH_ADAPTER" -offset indent
1103 .It Dv BHND_ATTACH_ADAPTER
1104 The bus is resident on a bridged adapter, such as a PCI Wi-Fi device.
1105 .It Dv BHND_ATTACH_NATIVE
1106 The bus is resident on the native host, such as the primary or secondary bus of
1112 function returns chip information from the parent
1118 struct contains the following fields:
1120 .Bl -tag -width "enum_addr" -offset indent
1122 The chip identifier.
1124 The chip's hardware revision.
1126 The chip's semiconductor package identifier.
1128 Several different physical semiconductor package variants may exist for a given
1129 chip, each of which may require driver workarounds for hardware errata,
1130 unpopulated components, etc.
1132 The interconnect architecture used by this chip.
1134 The backplane enumeration address.
1135 On SSB devices, this will be the base address of the first SSB core.
1136 On BCMA devices, this will be the address of the enumeration ROM (EROM) core.
1138 The number of cores on the chip backplane, or 0 if unknown.
1141 The following constants are defined for known
1144 .Bl -tag -width ".Dv BHND_CHIPTYPE_BCMA_ALT" -offset indent -compact
1145 .It Dv BHND_CHIPTYPE_SIBA
1147 .It Dv BHND_CHIPTYPE_BCMA
1149 .It Dv BHND_CHIPTYPE_BCMA_ALT
1150 BCMA-compatible variant found in Broadcom Northstar ARM SoCs.
1151 .It Dv BHND_CHIPTYPE_UBUS
1153 This BCMA-derived interconnect is found in Broadcom BCM33xx DOCSIS SoCs, and
1155 UBUS is not currently supported by
1159 Additional symbolic constants for known
1164 values are defined in
1165 .In dev/bhnd/bhnd_ids.h .
1169 function returns the BHND class of device
1175 identifiers are recognized.
1177 .Dv BHND_DEVCLASS_OTHER .
1179 One of the following device classes will be returned:
1181 .Bl -tag -width ".Dv BHND_DEVCLASS_SOC_ROUTER" -offset indent -compact
1182 .It Dv BHND_DEVCLASS_CC
1183 ChipCommon I/O Controller
1184 .It Dv BHND_DEVCLASS_CC_B
1185 ChipCommon Auxiliary Controller
1186 .It Dv BHND_DEVCLASS_PMU
1188 .It Dv BHND_DEVCLASS_PCI
1189 PCI Host/Device Bridge
1190 .It Dv BHND_DEVCLASS_PCIE
1191 PCIe Host/Device Bridge
1192 .It Dv BHND_DEVCLASS_PCCARD
1193 PCMCIA Host/Device Bridge
1194 .It Dv BHND_DEVCLASS_RAM
1196 .It Dv BHND_DEVCLASS_MEMC
1198 .It Dv BHND_DEVCLASS_ENET
1200 .It Dv BHND_DEVCLASS_ENET_MAC
1202 .It Dv BHND_DEVCLASS_ENET_PHY
1204 .It Dv BHND_DEVCLASS_WLAN
1205 IEEE 802.11 MAC/PHY/Radio
1206 .It Dv BHND_DEVCLASS_WLAN_MAC
1208 .It Dv BHND_DEVCLASS_WLAN_PHY
1210 .It Dv BHND_DEVCLASS_CPU
1212 .It Dv BHND_DEVCLASS_SOC_ROUTER
1214 .It Dv BHND_DEVCLASS_SOC_BRIDGE
1215 Interconnect Host Bridge
1216 .It Dv BHND_DEVCLASS_EROM
1217 Device Enumeration ROM
1218 .It Dv BHND_DEVCLASS_NVRAM
1219 NVRAM/Flash Controller
1220 .It Dv BHND_DEVCLASS_SOFTMODEM
1221 Analog/PSTN SoftModem Codec
1222 .It Dv BHND_DEVCLASS_USB_HOST
1224 .It Dv BHND_DEVCLASS_USB_DEV
1225 USB Device Controller
1226 .It Dv BHND_DEVCLASS_USB_DUAL
1227 USB Host/Device Controller
1228 .It Dv BHND_DEVCLASS_OTHER
1230 .It Dv BHND_DEVCLASS_INVALID
1235 .Fn bhnd_get_core_info
1236 function returns the core information for device
1240 structure contains the following fields:
1242 .Bl -tag -width "core_idx" -offset indent -compact
1244 Vendor identifier (JEP-106, ARM 4-bit continuation encoded)
1255 Symbolic constants for common vendor and device identifiers are defined in
1256 .In dev/bhnd/bhnd_ids.h .
1257 Common vendor identifiers include:
1259 .Bl -tag -width ".Dv BHND_MFGID_MIPS" -offset indent -compact
1260 .It Dv BHND_MFGID_ARM
1262 .It Dv BHND_MFGID_BCM
1264 .It Dv BHND_MFGID_MIPS
1269 .Fn bhnd_get_core_index ,
1270 .Fn bhnd_get_core_unit ,
1271 .Fn bhnd_get_device ,
1272 .Fn bhnd_get_hwrev ,
1275 functions are convenience wrappers for
1276 .Fn bhnd_get_core_info ,
1277 returning, respect the
1289 .Fn bhnd_get_device_name
1290 function returns a human readable name for device
1294 .Fn bhnd_get_vendor_name
1295 function returns a human readable name for the vendor of device
1299 .Fn bhnd_read_board_info
1300 function attempts to read the board information for device
1302 The board information will be returned in the location pointed to by
1308 structure contains the following fields:
1310 .Bl -tag -width "board_srom_rev" -offset indent
1312 Vendor ID of the board manufacturer (PCI-SIG assigned).
1319 .It Fa board_srom_rev
1320 Board SROM format revision.
1331 field is the Broadcom PCI device ID that most closely matches the
1332 capabilities of the BHND device (if any).
1339 fields default to the PCI Subsystem Vendor ID, PCI Subsystem ID, and PCI
1340 device ID, unless overridden in device NVRAM.
1342 On other devices, including SoCs, the
1347 fields will be populated from device NVRAM.
1349 Symbolic constants for common board flags are defined in
1350 .In dev/bhnd/bhnd_ids.h .
1352 .Ss "Device Matching Functions"
1353 The bhnd device matching functions are used to match against core, chip, and
1354 board-level device attributes.
1355 Match requirements are specified using the
1356 .Vt "struct bhnd_board_match" ,
1357 .Vt "struct bhnd_chip_match" ,
1358 .Vt "struct bhnd_core_match" ,
1359 .Vt "struct bhnd_device_match" ,
1361 .Vt "struct bhnd_hwrev_match"
1362 match descriptor structures.
1365 .Fn bhnd_board_matches
1370 matches the board match descriptor
1372 Otherwise, it returns
1376 .Fn bhnd_chip_matches
1381 matches the chip match descriptor
1383 Otherwise, it returns
1387 .Fn bhnd_core_matches
1392 matches the core match descriptor
1394 Otherwise, it returns
1398 .Fn bhnd_device_matches
1403 matches the device match descriptor
1405 Otherwise, it returns
1409 .Fn bhnd_hwrev_matches
1414 matches the hwrev match descriptor
1416 Otherwise, it returns
1420 .Fn bhnd_bus_match_child
1421 function returns the first child device of
1423 that matches the device match descriptor
1425 If no matching child is found,
1430 .Fn bhnd_core_get_match_desc
1431 function returns an equality match descriptor for the core info in
1433 The returned descriptor will match only on core attributes identical to those
1438 .Fn bhnd_cores_equal
1439 function is a convenience wrapper for
1440 .Fn bhnd_core_matches
1442 .Fn bhnd_core_get_match_desc .
1443 This function returns
1452 Otherwise, it returns
1457 function returns a pointer to the first entry in the array
1463 If no matching core is found,
1468 .Vt bhnd_board_match
1469 match descriptor may be initialized using one or more of the following macros:
1471 .Bl -tag -width "Fn BHND_MATCH_BOARD_VENDOR vendor" -offset indent
1472 .It Fn BHND_MATCH_BOARD_VENDOR "vendor"
1473 Match on boards with a vendor equal to
1475 .It Fn BHND_MATCH_BOARD_TYPE "type"
1476 Match on boards with a type equal to
1477 .Dv "BHND_BOARD_ ##"
1479 .It Fn BHND_MATCH_SROMREV "sromrev"
1480 Match on boards with a sromrev that matches
1481 .Dv "BHND_HWREV_ ##"
1483 .It Fn BHND_MATCH_BOARD_REV "hwrev"
1484 Match on boards with hardware revisions that match
1487 .It Fn BHND_MATCH_BOARD "vendor" "type"
1488 A convenience wrapper for
1489 .Fn BHND_MATCH_BOARD_VENDOR
1491 .Fn BHND_MATCH_BOARD_TYPE .
1495 .Bd -literal -offset indent
1496 struct bhnd_board_match board_desc = {
1497 BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM),
1498 BHND_MATCH_BOARD_TYPE(BCM94360X52C),
1499 BHND_MATCH_BOARD_REV(HWREV_ANY),
1500 BHND_MATCH_SROMREV(RANGE(0, 10))
1506 match descriptor may be initialized using one or more of the following macros:
1508 .Bl -tag -width "Fn BHND_MATCH_CHIP_IPR id pkg hwrev" -offset indent
1509 .It Fn BHND_MATCH_CHIP_ID "id"
1510 Match on chips with an ID equal to
1511 .Dv "BHND_CHIPID_ ##"
1513 .It Fn BHND_MATCH_CHIP_REV "hwrev"
1514 Match on chips with hardware revisions that match
1517 .It Fn BHND_MATCH_CHIP_PKG "pkg"
1518 Match on chips with a package ID equal to
1519 .Dv "BHND_PKGID_ ##"
1521 .It Fn BHND_MATCH_CHIP_TYPE "type"
1522 Match on chips with a chip type equal to
1523 .Dv "BHND_CHIPTYPE_ ##"
1525 .It Fn BHND_MATCH_CHIP_IP "id" "pkg"
1526 A convenience wrapper for
1527 .Fn BHND_MATCH_CHIP_ID
1529 .Fn BHND_MATCH_CHIP_PKG .
1530 .It Fn BHND_MATCH_CHIP_IPR "id" "pkg" "hwrev"
1531 A convenience wrapper for
1532 .Fn BHND_MATCH_CHIP_ID ,
1533 .Fn BHND_MATCH_CHIP_PKG ,
1535 .Fn BHND_MATCH_CHIP_REV .
1536 .It Fn BHND_MATCH_CHIP_IR "id" "hwrev"
1537 A convenience wrapper for
1538 .Fn BHND_MATCH_CHIP_ID
1540 .Fn BHND_MATCH_CHIP_REV .
1544 .Bd -literal -offset indent
1545 struct bhnd_chip_match chip_desc = {
1546 BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN),
1547 BHND_MATCH_CHIP_TYPE(SIBA)
1553 match descriptor may be initialized using one or more of the following macros:
1555 .Bl -tag -width "Fn BHND_MATCH_CORE_VENDOR vendor" -offset indent
1556 .It Fn BHND_MATCH_CORE_VENDOR "vendor"
1557 Match on cores with a vendor ID equal to
1559 .It Fn BHND_MATCH_CORE_ID "id"
1560 Match on cores with a device ID equal to
1562 .It Fn BHND_MATCH_CORE_REV "hwrev"
1563 Match on cores with hardware revisions that match
1566 .It Fn BHND_MATCH_CORE_CLASS "class"
1567 Match on cores with a core device class equal to
1569 .It Fn BHND_MATCH_CORE_IDX "idx"
1570 Match on cores with a core index equal to
1572 .It Fn BHND_MATCH_CORE_UNIT "unit"
1573 Match on cores with a core unit equal to
1575 .It Fn BHND_MATCH_CORE "vendor" "id"
1576 A convenience wrapper for
1577 .Fn BHND_MATCH_CORE_VENDOR
1579 .Fn BHND_MATCH_CORE_ID .
1583 .Bd -literal -offset indent
1584 struct bhnd_core_match core_desc = {
1585 BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC),
1586 BHND_MATCH_CORE_REV(HWREV_RANGE(0, 10))
1591 .Vt bhnd_device_match
1592 match descriptor supports matching on all board, chip, and core attributes,
1593 and may be initialized using any of the
1594 .Vt bhnd_board_match ,
1595 .Vt bhnd_chip_match ,
1601 .Bd -literal -offset indent
1602 struct bhnd_device_match device_desc = {
1603 BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN),
1604 BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM),
1605 BHND_MATCH_BOARD_TYPE(BCM94329AGB),
1606 BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC),
1611 .Vt bhnd_hwrev_match
1612 match descriptor may be initialized using one of the following macros:
1614 .Bl -tag -width "Fn BHND_HWREV_RANGE start end" -offset indent -compact
1615 .It Dv BHND_HWREV_ANY
1616 Matches any hardware revision.
1617 .It Fn BHND_HWREV_EQ "hwrev"
1618 Matches any hardware revision equal to
1620 .It Fn BHND_HWREV_GTE "hwrev"
1621 Matches any hardware revision greater than or equal to
1623 .It Fn BHND_HWREV_LTE "hwrev"
1624 Matches any hardware revision less than or equal to
1626 .It Fn BHND_HWREV_RANGE "start" "end"
1627 Matches any hardware revision within an inclusive range.
1629 .Dv BHND_HWREV_INVALID
1632 value, will match on any revision equal to or greater than
1636 .Ss "Device Table Functions"
1637 The bhnd device table functions are used to query device and
1641 .Fn bhnd_device_lookup
1642 function returns a pointer to the first entry in device table
1644 that matches the device
1646 The table entry size is specified by
1650 .Fn bhnd_device_quirks
1651 function scan the device table
1653 for all quirk entries that match the device
1655 returning the bitwise OR of all matching quirk flags.
1656 The table entry size is specified by
1661 structure contains the following fields:
1662 .Bl -tag -width "quirks_table" -offset indent -compact
1665 .Vt bhnd_device_match
1668 A verbose device description suitable for use with
1669 .Xr device_set_desc 9 ,
1673 The quirks table for this device, or
1676 The device flags required when matching this entry.
1679 The following device flags are supported:
1680 .Bl -tag -width ".Dv BHND_DF_ADAPTER" -offset indent -compact
1682 Match on any device.
1683 .It Dv BHND_DF_HOSTB
1684 Match only if the device is the
1688 .Dv BHND_DF_ADAPTER .
1690 Match only if the device is attached to a native SoC backplane.
1691 .It Dv BHND_DF_ADAPTER
1692 Match only if the device is attached to a
1699 table entry may be initialized using one of the following macros:
1701 .Bl -ohang -offset indent
1702 .It Fn BHND_DEVICE "vendor" "device" "desc" "quirks" "flags"
1703 Match on devices with a vendor ID equal to
1706 and a core device ID equal to
1710 The device's verbose description is specified by the
1712 argument, a pointer to the device-specific quirks table is specified by the
1714 argument, and any required device flags may be provided in
1718 argument defaults to
1721 .It Dv BHND_DEVICE_END
1728 .Bd -literal -offset indent
1729 struct bhnd_device bhnd_usb11_devices[] = {
1730 BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller",
1737 .Vt bhnd_device_quirk
1738 structure contains the following fields:
1739 .Bl -tag -width "quirks_table" -offset indent -compact
1742 .Vt bhnd_device_match
1745 Applicable quirk flags.
1748 A bhnd_device_quirk table entry may be initialized using one of the following
1750 .Bl -tag -width "Fn BHND_CHIP_QUIRK chip hwrev flags" -offset indent
1751 .It Fn BHND_BOARD_QUIRK "board" "flags"
1754 on devices with a board type equal to
1757 .It Fn BHND_CHIP_QUIRK "chip" "hwrev" "flags"
1760 on devices with a chip ID equal to
1761 .Dv BHND_CHIPID_BCM ##
1763 and chip hardware revision that matches
1766 .It Fn BHND_PKG_QUIRK "chip" "pkg" flags"
1769 on devices with a chip ID equal to
1770 .Dv BHND_CHIPID_BCM ##
1772 and chip package equal to
1773 .Dv BHND_ ## chip ##
1775 .It Fn BHND_CORE_QUIRK "hwrev" flags"
1778 on devices with a core hardware revision that matches
1783 .Bd -literal -offset indent
1784 struct bhnd_device_quirk bhnd_usb11_quirks[] = {
1785 BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller",
1790 .Ss "DMA Address Translation Functions"
1792 .Fn bhnd_get_dma_translation
1793 function is used to request a DMA address translation descriptor suitable
1794 for use with a maximum DMA address width of
1796 with support for the requested translation
1799 If a suitable DMA address translation descriptor is found, it will be stored in
1801 and a bus DMA tag specifying the DMA translation's address restrictions will
1810 if the translation descriptor or DMA tag are not desired.
1812 The following DMA translation flags are supported:
1813 .Bl -ohang -width ".Dv BHND_DMA_TRANSLATION_BYTESWAPPED" -offset indent
1814 .It Dv BHND_DMA_TRANSLATION_PHYSMAP
1815 The translation remaps the device's physical address space.
1817 This is used in conjunction with
1818 .Dv BHND_DMA_TRANSLATION_BYTESWAPPED
1819 to define a DMA translation that provides byteswapped access to physical memory
1820 on big-endian MIPS SoCs.
1821 .It Dv BHND_DMA_TRANSLATION_BYTESWAPPED
1822 The translation provides a byte-swapped mapping; write requests will be
1823 byte-swapped before being written to memory, and read requests will be
1824 byte-swapped before being returned.
1826 This is primarily used to perform efficient byte swapping of DMA data on
1827 embedded MIPS SoCs executing in big-endian mode.
1830 The following symbolic constants are defined for common DMA address widths:
1832 .Bl -tag -width ".Dv BHND_DMA_ADDR_64BIT" -offset indent -compact
1833 .It Dv BHND_DMA_ADDR_30BIT
1835 .It Dv BHND_DMA_ADDR_32BIT
1837 .It Dv BHND_DMA_ADDR_64BIT
1842 .Vt bhnd_dma_translation
1843 structure contains the following fields:
1844 .Bl -tag -width "addrext_mask"
1846 Host-to-device physical address translation.
1847 This may be added to a host physical address to produce a device DMA address.
1849 Device-addressable address mask.
1850 This defines the device DMA address range, and excludes any bits reserved for
1851 mapping the address within the translation window at
1854 Device-addressable extended address mask.
1855 If a the per-core BHND DMA engine supports the 'addrext' control field, it can
1856 be used to provide address bits excluded by
1859 Support for DMA extended address changes \(em including coordination with the
1860 core providing device-to-host DMA address translation \(em is handled
1861 transparently by the DMA engine.
1863 For example, on PCI Wi-Fi devices, the Wi-Fi core's DMA engine will (in effect)
1864 update the PCI host bridge core's DMA
1865 .Dv sbtopcitranslation
1866 base address to map the target address prior to performing a DMA transaction.
1871 .Ss "Interrupt Functions"
1873 .Fn bhnd_get_intr_count
1874 function is used to determine the number of backplane interrupt lines assigned
1877 Interrupt line identifiers are allocated in monotonically increasing order,
1881 .Fn bhnd_get_intr_ivec
1882 function is used to determine the backplane interrupt vector assigned to
1887 writing the result to
1889 Interrupt vector assignments are backplane-specific: On BCMA devices, this
1890 function returns the OOB bus line assigned to the interrupt.
1891 On SIBA devices, it returns the target OCP slave flag number assigned to the
1896 function is used to map interrupt line
1900 to an IRQ number, writing the result to
1902 Until unmapped, this IRQ may be used when allocating a resource of type
1905 Ownership of the interrupt mapping is assumed by the caller, and must be
1906 explicitly released using
1907 .Fa bhnd_unmap_intr .
1911 function is used to unmap bus IRQ
1913 previously mapped using
1918 .Ss "NVRAM Functions"
1920 .Fn bhnd_nvram_getvar
1921 function is used to read the value of NVRAM variable
1923 from the NVRAM provider(s) registered with the parent
1927 coerced to the desired data representation
1929 written to the buffer specified by
1932 Before the call, the maximum capacity of
1936 After a successful call \(em or if
1938 is returned \(em the size of the available data will be written to
1940 The size of the desired data representation can be determined by calling
1941 .Fn bhnd_nvram_getvar
1947 The following NVRAM data types are supported:
1949 .Bl -tag -width ".Dv BHND_NVRAM_TYPE_UINT64_ARRAY" -offset indent -compact
1950 .It Dv BHND_NVRAM_TYPE_UINT8
1951 unsigned 8-bit integer
1952 .It Dv BHND_NVRAM_TYPE_UINT16
1953 unsigned 16-bit integer
1954 .It Dv BHND_NVRAM_TYPE_UINT32
1955 unsigned 32-bit integer
1956 .It Dv BHND_NVRAM_TYPE_UINT64
1957 signed 64-bit integer
1958 .It Dv BHND_NVRAM_TYPE_INT8
1959 signed 8-bit integer
1960 .It Dv BHND_NVRAM_TYPE_INT16
1961 signed 16-bit integer
1962 .It Dv BHND_NVRAM_TYPE_INT32
1963 signed 32-bit integer
1964 .It Dv BHND_NVRAM_TYPE_INT64
1965 signed 64-bit integer
1966 .It Dv BHND_NVRAM_TYPE_CHAR
1968 .It Dv BHND_NVRAM_TYPE_STRING
1969 UTF-8 NUL-terminated string
1970 .It Dv BHND_NVRAM_TYPE_BOOL
1972 .It Dv BHND_NVRAM_TYPE_NULL
1974 .It Dv BHND_NVRAM_TYPE_DATA
1976 .It Dv BHND_NVRAM_TYPE_UINT8_ARRAY
1977 array of uint8 integers
1978 .It Dv BHND_NVRAM_TYPE_UINT16_ARRAY
1979 array of uint16 integers
1980 .It Dv BHND_NVRAM_TYPE_UINT32_ARRAY
1981 array of uint32 integers
1982 .It Dv BHND_NVRAM_TYPE_UINT64_ARRAY
1983 array of uint64 integers
1984 .It Dv BHND_NVRAM_TYPE_INT8_ARRAY
1985 array of int8 integers
1986 .It Dv BHND_NVRAM_TYPE_INT16_ARRAY
1987 array of int16 integers
1988 .It Dv BHND_NVRAM_TYPE_INT32_ARRAY
1989 array of int32 integers
1990 .It Dv BHND_NVRAM_TYPE_INT64_ARRAY
1991 array of int64 integers
1992 .It Dv BHND_NVRAM_TYPE_CHAR_ARRAY
1993 array of UTF-8 characters
1994 .It Dv BHND_NVRAM_TYPE_STRING_ARRAY
1995 array of UTF-8 NUL-terminated strings
1996 .It Dv BHND_NVRAM_TYPE_BOOL_ARRAY
1997 array of uint8 boolean values
2001 .Fn bhnd_nvram_getvar_array ,
2002 .Fn bhnd_nvram_getvar_int ,
2003 .Fn bhnd_nvram_getvar_int8 ,
2004 .Fn bhnd_nvram_getvar_int16 ,
2005 .Fn bhnd_nvram_getvar_int32 ,
2006 .Fn bhnd_nvram_getvar_uint ,
2007 .Fn bhnd_nvram_getvar_uint8 ,
2008 .Fn bhnd_nvram_getvar_uint16 ,
2009 .Fn bhnd_nvram_getvar_uint32 ,
2011 .Fn bhnd_nvram_getvar_str
2012 functions are convenience wrappers for
2013 .Fn bhnd_nvram_getvar .
2016 .Fn bhnd_nvram_getvar_array
2017 function returns either a value of exactly
2021 or returns an error code of
2023 if the data representation is not exactly
2028 .Fn bhnd_nvram_getvar_int
2030 .Fn bhnd_nvram_getvar_uint
2031 functions return the value of NVRAM variable
2033 coerced to a signed or unsigned integer
2039 .Fn bhnd_nvram_getvar_int8 ,
2040 .Fn bhnd_nvram_getvar_int16 ,
2041 .Fn bhnd_nvram_getvar_int32 ,
2042 .Fn bhnd_nvram_getvar_uint ,
2043 .Fn bhnd_nvram_getvar_uint8 ,
2044 .Fn bhnd_nvram_getvar_uint16 ,
2046 .Fn bhnd_nvram_getvar_uint32
2047 functions return the value of NVRAM variable
2049 coerced to a signed or unsigned 8, 16, or 32-bit integer type.
2052 .Fn bhnd_nvram_getvar_str
2053 functions return the value of NVRAM variable
2055 coerced to a NUL-terminated string.
2058 .Fn bhnd_nvram_string_array_next
2059 function iterates over all strings in the
2061 .Dv BHND_NVRAM_TYPE_STRING_ARRAY
2065 including any terminating NUL character(s), is specified using the
2070 argument should be either a string pointer previously returned by
2071 .Fn bhnd_nvram_string_array_next ,
2080 argument must be a pointer to the length previously returned by
2081 .Fn bhnd_nvram_string_array_next .
2082 On success, the next string element's length will be written to this pointer.
2084 .Ss "Port/Region Functions"
2085 Per-device interconnect memory mappings are identified by a combination of
2090 Port and memory region identifiers are allocated in monotonically increasing
2095 The following port types are supported:
2096 .Bl -tag -width ".Dv BHND_PORT_DEVICE" -offset indent
2097 .It Dv BHND_PORT_DEVICE
2099 The device's control/status registers are always mapped by the first device port
2100 and region, and will be assigned a
2103 .It Dv BHND_PORT_BRIDGE
2105 .It Dv BHND_PORT_AGENT
2106 Interconnect agent/wrapper.
2110 .Fn bhnd_decode_port_rid
2111 function is used to decode the resource ID
2117 writing the port type to
2126 .Fn bhnd_get_port_count
2127 function returns the number of ports of type
2133 .Fn bhnd_get_port_rid
2134 function returns the resource ID for the
2136 resource mapping the
2144 or -1 if the port or region are invalid, or do not have an assigned resource ID.
2147 .Fn bhnd_get_region_addr
2148 function is used to determine the base address and size of the memory
2156 The region's base device address will be written to
2158 and the region size to
2162 .Fn bhnd_get_region_count
2163 function returns the number of memory regions mapped to
2171 .Fn bhnd_is_region_valid
2176 is a valid region mapped by
2183 .Ss "Power Management Functions"
2184 Drivers must ask the parent
2186 bus to allocate device PMU state using
2188 before calling any another bhnd PMU functions.
2192 function is used to allocate per-device PMU state and enable PMU request
2195 The memory region containing the device's PMU register block must be allocated
2197 .Xr bus_alloc_resource 9
2199 .Fn bhnd_alloc_resource
2201 .Fn bhnd_alloc_pmu ,
2202 and must not be released until after calling
2203 .Fn bhnd_release_pmu .
2205 On all supported BHND hardware, the PMU register block is mapped by the device's
2206 control/status registers in the first device port and region.
2209 .Fn bhnd_release_pmu
2210 function releases the per-device PMU state previously allocated for device
2213 .Fn bhnd_alloc_pmu .
2214 Any outstanding clock and external resource requests will be discarded upon
2215 release of the device PMU state.
2218 .Fn bhnd_enable_clocks
2219 function is used to request that
2221 be powered up and routed to the backplane on behalf of device
2223 This will power any clock sources required (e.g., XTAL, PLL, etc) and wait until
2224 the requested clocks are stable.
2225 If the request succeeds, any previous clock requests issued by
2229 The following clocks are supported, and may be combined using bitwise OR to
2230 request multiple clocks:
2232 .Bl -tag -width ".Dv BHND_CLOCK_DYN" -offset indent
2234 Dynamically select an appropriate clock source based on all outstanding clock
2235 requests by any device attached to the parent
2239 Idle Low-Power (ILP) Clock.
2240 May be used if no register access is required, or long request latency is
2243 Active Low-Power (ALP) Clock.
2244 Supports low-latency register access and low-rate DMA.
2246 High Throughput (HT) Clock.
2247 Supports high bus throughput and lowest-latency register access.
2251 .Fn bhnd_request_clock
2252 function is used to request that
2254 (or faster) be powered up and routed to device
2258 .Fn bhnd_get_clock_freq
2259 function is used to request the current clock frequency of
2261 writing the frequency in Hz to
2265 .Fn bhnd_get_clock_latency
2266 function is used to determine the transition latency required for
2268 writing the latency in microseconds to
2272 latency value is suitable for use as the D11 Wi-Fi core
2277 .Fn bhnd_request_ext_rsrc
2278 function is used to request that the external PMU-managed resource assigned to
2281 identified by device-specific identifier
2286 .Fn bhnd_release_ext_rsrc
2287 function releases any outstanding requests by device
2289 for the PMU-managed resource identified by device-specific identifier
2291 If an external resource is shared by multiple devices, it will not be powered
2292 down until all device requests are released.
2294 .Ss "Service Provider Functions"
2296 .Fn bhnd_register_provider
2297 function is used to register device
2299 as a provider for platform
2305 The following service types are supported:
2306 .Bl -tag -width ".Dv BHND_SERVICE_INVALID" -offset indent
2307 .It Dv BHND_SERVICE_CHIPC
2309 The providing device must implement the bhnd_chipc interface.
2310 .It Dv BHND_SERVICE_PWRCTL
2311 Legacy PWRCTL service.
2312 The providing device must implement the bhnd_pwrctl interface.
2313 .It Dv BHND_SERVICE_PMU
2315 The providing device must implement the bhnd_pmu interface.
2316 .It Dv BHND_SERVICE_NVRAM
2318 The providing device must implement the bhnd_nvram interface.
2319 .It Dv BHND_SERVICE_GPIO
2321 The providing device must implement the standard
2324 .It Dv BHND_SERVICE_ANY
2325 Matches on any service type.
2327 .Fn bhnd_deregister_provider
2328 to remove all service provider registrations for a device.
2332 .Fn bhnd_deregister_provider
2333 function attempts to remove provider registration for the device
2340 .Dv BHND_SERVICE_ANY
2341 is specified, this function will attempt to remove
2342 .Em all service provider registrations for
2346 .Fn bhnd_retain_provider
2347 function retains and returns a reference to the provider registered for
2354 On success, the caller is responsible for releasing this provider reference
2356 .Fn bhnd_release_provider .
2357 The service provider is guaranteed to remain available until the provider
2358 reference is released.
2361 .Fn bhnd_release_provider
2362 function releases a reference to a
2366 previously retained by device
2369 .Fn bhnd_retain_provider .
2371 .Ss "Utility Functions"
2373 .Fn bhnd_driver_get_erom_class
2374 function returns the
2376 class for the device enumeration table format used by
2380 If the driver does not support
2387 .Fn bhnd_find_core_class
2388 function looks up the BHND class, if known, for the BHND vendor ID
2394 .Fn bhnd_find_core_name
2395 function is used to fetch the human-readable name, if known, for the BHND core
2405 functions are convenience wrappers for
2406 .Fn bhnd_find_core_class
2408 .Fn bhnd_find_core_name ,
2413 fields of the core info structure
2417 .Fn bhnd_format_chip_id
2418 function writes a NUL-terminated human-readable representation of the BHND
2420 value to the specified
2426 characters will be written, with the
2428 character set to '\\0'.
2430 .Dv BHND_CHIPID_MAX_NAMELEN
2431 is sufficient for any string representation produced using
2432 .Fn bhnd_format_chip_id .
2435 .Fn bhnd_set_custom_core_desc
2438 device identification of
2440 overriding the core name with the specified
2442 to populate the device's verbose description using
2443 .Xr device_set_desc .
2446 .Fn bhnd_set_default_core_desc
2449 device identification of
2451 to populate the device's verbose description using
2452 .Xr device_set_desc .
2455 .Fn bhnd_vendor_name
2456 function returns the human-readable name for the JEP-106, ARM 4-bit
2457 continuation encoded manufacturer ID
2462 .Ss Bus Resource Functions
2464 .Fn bhnd_activate_resource ,
2465 .Fn bhnd_alloc_resources ,
2466 .Fn bhnd_deactivate_resource ,
2468 .Fn bhnd_release_resource
2469 functions return 0 on success, otherwise an appropriate error code is returned.
2472 .Fn bhnd_alloc_resource
2474 .Fn bhnd_alloc_resource_any
2475 functions return a pointer to
2476 .Vt "struct resource"
2477 on success, a null pointer otherwise.
2479 .Ss "Device Configuration Functions"
2482 .Fn bhnd_read_config
2484 .Fn bhnd_write_config
2485 functions return 0 on success, or one of the following values on error:
2488 The device is not a direct child of the
2492 The requested width is not one of 1, 2, or 4 bytes.
2494 Accessing agent/config space for the device is unsupported.
2496 The requested offset or width exceeds the bounds of the mapped agent/config
2501 .Fn bhnd_read_ioctl ,
2502 .Fn bhnd_write_ioctl ,
2503 .Fn bhnd_read_iost ,
2507 functions return 0 on success, otherwise an appropriate error code is returned.
2509 .Ss "Device Information Functions"
2512 .Fn bhnd_read_board_info
2513 function returns 0 on success, otherwise an appropriate error code is returned.
2515 .Ss "DMA Address Translation Functions"
2517 .Fn bhnd_get_dma_translation
2518 function returns 0 on success, or one of the following values on error:
2521 DMA is not supported.
2523 No DMA translation matching the requested address width and translation flags
2527 If fetching the requested DMA address translation otherwise fails, an
2528 appropriate error code will be returned.
2530 .Ss "Interrupt Functions"
2533 .Fn bhnd_get_intr_ivec
2537 if the requested interrupt line exceeds the number of interrupt lines assigned
2542 function returns 0 on success, otherwise an appropriate error code is returned.
2544 .Ss "NVRAM Functions"
2546 .Fn bhnd_nvram_getvar ,
2547 .Fn bhnd_nvram_getvar_array ,
2548 .Fn bhnd_nvram_getvar_int ,
2549 .Fn bhnd_nvram_getvar_int8 ,
2550 .Fn bhnd_nvram_getvar_int16 ,
2551 .Fn bhnd_nvram_getvar_int32 ,
2552 .Fn bhnd_nvram_getvar_uint ,
2553 .Fn bhnd_nvram_getvar_uint8 ,
2554 .Fn bhnd_nvram_getvar_uint16 ,
2556 .Fn bhnd_nvram_getvar_uint32
2557 functions return 0 on success, or one of the following values on error:
2560 If an NVRAM provider has not been registered with the bus.
2562 The requested variable was not found.
2564 If the buffer of size is too small to hold the requested value.
2565 .It Bq Er EOPNOTSUPP
2566 If the value's native type is incompatible with and cannot be coerced to the
2569 If value coercion would overflow (or underflow) the requested type
2572 If reading the variable otherwise fails, an appropriate error code will be
2575 .Ss "Port/Region Functions"
2577 .Fn bhnd_decode_port_rid
2579 0 on success, or an appropriate error code if no matching port/region is found.
2582 .Fn bhnd_get_port_rid
2583 function returns the resource ID for the requested port and region,
2584 or -1 if the port or region are invalid, or do not have an assigned resource ID.
2587 .Fn bhnd_get_region_addr
2589 0 on success, or an appropriate error code if no matching port/region is found.
2594 function returns 0 on success, otherwise an appropriate error code is returned.
2597 .Fn bhnd_release_pmu
2598 function returns 0 on success, otherwise an appropriate error code is returned,
2599 and the core state will be left unmodified.
2602 .Fn bhnd_enable_clocks
2604 .Fn bhnd_request_clock
2605 functions return 0 on success, or one of the following values on error:
2608 An unsupported clock was requested.
2610 No PMU or PWRCTL provider has been registered with the bus.
2614 .Fn bhnd_get_clock_freq
2615 function returns 0 on success, or
2617 if the frequency for the specified clock is not available.
2620 .Fn bhnd_get_clock_latency
2621 function returns 0 on success, or
2623 if the transition latency for the specified clock is not available.
2626 .Fn bhnd_request_ext_rsrc
2628 .Fn bhnd_release_ext_rsrc
2629 functions return 0 on success, otherwise an appropriate error code is returned.
2632 .Ss "Service Provider Functions"
2634 .Fn bhnd_register_provider
2635 function returns 0 on success,
2637 if an entry for service already exists, or an appropriate error code if
2638 service registration otherwise fails.
2641 .Fn bhnd_deregister_provider
2642 function returns 0 on success, or
2644 if active references to the service provider exist.
2647 .Fn bhnd_retain_provider
2648 function returns a pointer to
2650 on success, a null pointer if the requested provider is not registered.
2652 .Ss "Utility Functions"
2655 .Fn bhnd_format_chip_id
2656 function returns the total number of bytes written on success, or a negative
2666 driver programming interface and this manual page were written by
2667 .An Landon Fuller Aq Mt landonf@FreeBSD.org .