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.
861 If all requested resources, are successfully allocated,
862 this will be updated with the allocated resource identifiers.
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.
1136 capability flags supported by this chip.
1138 The backplane enumeration address.
1139 On SSB devices, this will be the base address of the first SSB core.
1140 On BCMA devices, this will be the address of the enumeration ROM (EROM) core.
1142 The number of cores on the chip backplane, or 0 if unknown.
1145 The following constants are defined for known
1148 .Bl -tag -width ".Dv BHND_CHIPTYPE_BCMA_ALT" -offset indent -compact
1149 .It Dv BHND_CHIPTYPE_SIBA
1151 .It Dv BHND_CHIPTYPE_BCMA
1153 .It Dv BHND_CHIPTYPE_BCMA_ALT
1154 BCMA-compatible variant found in Broadcom Northstar ARM SoCs.
1155 .It Dv BHND_CHIPTYPE_UBUS
1157 This BCMA-derived interconnect is found in Broadcom BCM33xx DOCSIS SoCs, and
1159 UBUS is not currently supported by
1165 flags are supported:
1166 .Bl -tag -width ".Dv BHND_CAP_BP64" -offset indent -compact
1167 .It Dv BHND_CAP_BP64
1168 The backplane supports 64-bit addressing.
1173 Additional symbolic constants for known
1178 values are defined in
1179 .In dev/bhnd/bhnd_ids.h .
1183 function returns the BHND class of device
1189 identifiers are recognized.
1191 .Dv BHND_DEVCLASS_OTHER .
1193 One of the following device classes will be returned:
1195 .Bl -tag -width ".Dv BHND_DEVCLASS_SOC_ROUTER" -offset indent -compact
1196 .It Dv BHND_DEVCLASS_CC
1197 ChipCommon I/O Controller
1198 .It Dv BHND_DEVCLASS_CC_B
1199 ChipCommon Auxiliary Controller
1200 .It Dv BHND_DEVCLASS_PMU
1202 .It Dv BHND_DEVCLASS_PCI
1203 PCI Host/Device Bridge
1204 .It Dv BHND_DEVCLASS_PCIE
1205 PCIe Host/Device Bridge
1206 .It Dv BHND_DEVCLASS_PCCARD
1207 PCMCIA Host/Device Bridge
1208 .It Dv BHND_DEVCLASS_RAM
1210 .It Dv BHND_DEVCLASS_MEMC
1212 .It Dv BHND_DEVCLASS_ENET
1214 .It Dv BHND_DEVCLASS_ENET_MAC
1216 .It Dv BHND_DEVCLASS_ENET_PHY
1218 .It Dv BHND_DEVCLASS_WLAN
1219 IEEE 802.11 MAC/PHY/Radio
1220 .It Dv BHND_DEVCLASS_WLAN_MAC
1222 .It Dv BHND_DEVCLASS_WLAN_PHY
1224 .It Dv BHND_DEVCLASS_CPU
1226 .It Dv BHND_DEVCLASS_SOC_ROUTER
1228 .It Dv BHND_DEVCLASS_SOC_BRIDGE
1229 Interconnect Host Bridge
1230 .It Dv BHND_DEVCLASS_EROM
1231 Device Enumeration ROM
1232 .It Dv BHND_DEVCLASS_NVRAM
1233 NVRAM/Flash Controller
1234 .It Dv BHND_DEVCLASS_SOFTMODEM
1235 Analog/PSTN SoftModem Codec
1236 .It Dv BHND_DEVCLASS_USB_HOST
1238 .It Dv BHND_DEVCLASS_USB_DEV
1239 USB Device Controller
1240 .It Dv BHND_DEVCLASS_USB_DUAL
1241 USB Host/Device Controller
1242 .It Dv BHND_DEVCLASS_OTHER
1244 .It Dv BHND_DEVCLASS_INVALID
1249 .Fn bhnd_get_core_info
1250 function returns the core information for device
1254 structure contains the following fields:
1256 .Bl -tag -width "core_idx" -offset indent -compact
1258 Vendor identifier (JEP-106, ARM 4-bit continuation encoded)
1269 Symbolic constants for common vendor and device identifiers are defined in
1270 .In dev/bhnd/bhnd_ids.h .
1271 Common vendor identifiers include:
1273 .Bl -tag -width ".Dv BHND_MFGID_MIPS" -offset indent -compact
1274 .It Dv BHND_MFGID_ARM
1276 .It Dv BHND_MFGID_BCM
1278 .It Dv BHND_MFGID_MIPS
1283 .Fn bhnd_get_core_index ,
1284 .Fn bhnd_get_core_unit ,
1285 .Fn bhnd_get_device ,
1286 .Fn bhnd_get_hwrev ,
1289 functions are convenience wrappers for
1290 .Fn bhnd_get_core_info ,
1291 returning, respect the
1303 .Fn bhnd_get_device_name
1304 function returns a human readable name for device
1308 .Fn bhnd_get_vendor_name
1309 function returns a human readable name for the vendor of device
1313 .Fn bhnd_read_board_info
1314 function attempts to read the board information for device
1316 The board information will be returned in the location pointed to by
1322 structure contains the following fields:
1324 .Bl -tag -width "board_srom_rev" -offset indent
1326 Vendor ID of the board manufacturer (PCI-SIG assigned).
1333 .It Fa board_srom_rev
1334 Board SROM format revision.
1345 field is the Broadcom PCI device ID that most closely matches the
1346 capabilities of the BHND device (if any).
1353 fields default to the PCI Subsystem Vendor ID, PCI Subsystem ID, and PCI
1354 device ID, unless overridden in device NVRAM.
1356 On other devices, including SoCs, the
1361 fields will be populated from device NVRAM.
1363 Symbolic constants for common board flags are defined in
1364 .In dev/bhnd/bhnd_ids.h .
1366 .Ss "Device Matching Functions"
1367 The bhnd device matching functions are used to match against core, chip, and
1368 board-level device attributes.
1369 Match requirements are specified using the
1370 .Vt "struct bhnd_board_match" ,
1371 .Vt "struct bhnd_chip_match" ,
1372 .Vt "struct bhnd_core_match" ,
1373 .Vt "struct bhnd_device_match" ,
1375 .Vt "struct bhnd_hwrev_match"
1376 match descriptor structures.
1379 .Fn bhnd_board_matches
1384 matches the board match descriptor
1386 Otherwise, it returns
1390 .Fn bhnd_chip_matches
1395 matches the chip match descriptor
1397 Otherwise, it returns
1401 .Fn bhnd_core_matches
1406 matches the core match descriptor
1408 Otherwise, it returns
1412 .Fn bhnd_device_matches
1417 matches the device match descriptor
1419 Otherwise, it returns
1423 .Fn bhnd_hwrev_matches
1428 matches the hwrev match descriptor
1430 Otherwise, it returns
1434 .Fn bhnd_bus_match_child
1435 function returns the first child device of
1437 that matches the device match descriptor
1439 If no matching child is found,
1444 .Fn bhnd_core_get_match_desc
1445 function returns an equality match descriptor for the core info in
1447 The returned descriptor will match only on core attributes identical to those
1452 .Fn bhnd_cores_equal
1453 function is a convenience wrapper for
1454 .Fn bhnd_core_matches
1456 .Fn bhnd_core_get_match_desc .
1457 This function returns
1466 Otherwise, it returns
1471 function returns a pointer to the first entry in the array
1477 If no matching core is found,
1482 .Vt bhnd_board_match
1483 match descriptor may be initialized using one or more of the following macros:
1485 .Bl -tag -width "Fn BHND_MATCH_BOARD_VENDOR vendor" -offset indent
1486 .It Fn BHND_MATCH_BOARD_VENDOR "vendor"
1487 Match on boards with a vendor equal to
1489 .It Fn BHND_MATCH_BOARD_TYPE "type"
1490 Match on boards with a type equal to
1491 .Dv "BHND_BOARD_ ##"
1493 .It Fn BHND_MATCH_SROMREV "sromrev"
1494 Match on boards with a sromrev that matches
1495 .Dv "BHND_HWREV_ ##"
1497 .It Fn BHND_MATCH_BOARD_REV "hwrev"
1498 Match on boards with hardware revisions that match
1501 .It Fn BHND_MATCH_BOARD "vendor" "type"
1502 A convenience wrapper for
1503 .Fn BHND_MATCH_BOARD_VENDOR
1505 .Fn BHND_MATCH_BOARD_TYPE .
1509 .Bd -literal -offset indent
1510 struct bhnd_board_match board_desc = {
1511 BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM),
1512 BHND_MATCH_BOARD_TYPE(BCM94360X52C),
1513 BHND_MATCH_BOARD_REV(HWREV_ANY),
1514 BHND_MATCH_SROMREV(RANGE(0, 10))
1520 match descriptor may be initialized using one or more of the following macros:
1522 .Bl -tag -width "Fn BHND_MATCH_CHIP_IPR id pkg hwrev" -offset indent
1523 .It Fn BHND_MATCH_CHIP_ID "id"
1524 Match on chips with an ID equal to
1525 .Dv "BHND_CHIPID_ ##"
1527 .It Fn BHND_MATCH_CHIP_REV "hwrev"
1528 Match on chips with hardware revisions that match
1531 .It Fn BHND_MATCH_CHIP_PKG "pkg"
1532 Match on chips with a package ID equal to
1533 .Dv "BHND_PKGID_ ##"
1535 .It Fn BHND_MATCH_CHIP_TYPE "type"
1536 Match on chips with a chip type equal to
1537 .Dv "BHND_CHIPTYPE_ ##"
1539 .It Fn BHND_MATCH_CHIP_IP "id" "pkg"
1540 A convenience wrapper for
1541 .Fn BHND_MATCH_CHIP_ID
1543 .Fn BHND_MATCH_CHIP_PKG .
1544 .It Fn BHND_MATCH_CHIP_IPR "id" "pkg" "hwrev"
1545 A convenience wrapper for
1546 .Fn BHND_MATCH_CHIP_ID ,
1547 .Fn BHND_MATCH_CHIP_PKG ,
1549 .Fn BHND_MATCH_CHIP_REV .
1550 .It Fn BHND_MATCH_CHIP_IR "id" "hwrev"
1551 A convenience wrapper for
1552 .Fn BHND_MATCH_CHIP_ID
1554 .Fn BHND_MATCH_CHIP_REV .
1558 .Bd -literal -offset indent
1559 struct bhnd_chip_match chip_desc = {
1560 BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN),
1561 BHND_MATCH_CHIP_TYPE(SIBA)
1567 match descriptor may be initialized using one or more of the following macros:
1569 .Bl -tag -width "Fn BHND_MATCH_CORE_VENDOR vendor" -offset indent
1570 .It Fn BHND_MATCH_CORE_VENDOR "vendor"
1571 Match on cores with a vendor ID equal to
1573 .It Fn BHND_MATCH_CORE_ID "id"
1574 Match on cores with a device ID equal to
1576 .It Fn BHND_MATCH_CORE_REV "hwrev"
1577 Match on cores with hardware revisions that match
1580 .It Fn BHND_MATCH_CORE_CLASS "class"
1581 Match on cores with a core device class equal to
1583 .It Fn BHND_MATCH_CORE_IDX "idx"
1584 Match on cores with a core index equal to
1586 .It Fn BHND_MATCH_CORE_UNIT "unit"
1587 Match on cores with a core unit equal to
1589 .It Fn BHND_MATCH_CORE "vendor" "id"
1590 A convenience wrapper for
1591 .Fn BHND_MATCH_CORE_VENDOR
1593 .Fn BHND_MATCH_CORE_ID .
1597 .Bd -literal -offset indent
1598 struct bhnd_core_match core_desc = {
1599 BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC),
1600 BHND_MATCH_CORE_REV(HWREV_RANGE(0, 10))
1605 .Vt bhnd_device_match
1606 match descriptor supports matching on all board, chip, and core attributes,
1607 and may be initialized using any of the
1608 .Vt bhnd_board_match ,
1609 .Vt bhnd_chip_match ,
1615 .Bd -literal -offset indent
1616 struct bhnd_device_match device_desc = {
1617 BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN),
1618 BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM),
1619 BHND_MATCH_BOARD_TYPE(BCM94329AGB),
1620 BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC),
1625 .Vt bhnd_hwrev_match
1626 match descriptor may be initialized using one of the following macros:
1628 .Bl -tag -width "Fn BHND_HWREV_RANGE start end" -offset indent -compact
1629 .It Dv BHND_HWREV_ANY
1630 Matches any hardware revision.
1631 .It Fn BHND_HWREV_EQ "hwrev"
1632 Matches any hardware revision equal to
1634 .It Fn BHND_HWREV_GTE "hwrev"
1635 Matches any hardware revision greater than or equal to
1637 .It Fn BHND_HWREV_LTE "hwrev"
1638 Matches any hardware revision less than or equal to
1640 .It Fn BHND_HWREV_RANGE "start" "end"
1641 Matches any hardware revision within an inclusive range.
1643 .Dv BHND_HWREV_INVALID
1646 value, will match on any revision equal to or greater than
1650 .Ss "Device Table Functions"
1651 The bhnd device table functions are used to query device and
1655 .Fn bhnd_device_lookup
1656 function returns a pointer to the first entry in device table
1658 that matches the device
1660 The table entry size is specified by
1664 .Fn bhnd_device_quirks
1665 function scan the device table
1667 for all quirk entries that match the device
1669 returning the bitwise OR of all matching quirk flags.
1670 The table entry size is specified by
1675 structure contains the following fields:
1676 .Bl -tag -width "quirks_table" -offset indent -compact
1679 .Vt bhnd_device_match
1682 A verbose device description suitable for use with
1683 .Xr device_set_desc 9 ,
1687 The quirks table for this device, or
1690 The device flags required when matching this entry.
1693 The following device flags are supported:
1694 .Bl -tag -width ".Dv BHND_DF_ADAPTER" -offset indent -compact
1696 Match on any device.
1697 .It Dv BHND_DF_HOSTB
1698 Match only if the device is the
1702 .Dv BHND_DF_ADAPTER .
1704 Match only if the device is attached to a native SoC backplane.
1705 .It Dv BHND_DF_ADAPTER
1706 Match only if the device is attached to a
1713 table entry may be initialized using one of the following macros:
1715 .Bl -ohang -offset indent
1716 .It Fn BHND_DEVICE "vendor" "device" "desc" "quirks" "flags"
1717 Match on devices with a vendor ID equal to
1720 and a core device ID equal to
1724 The device's verbose description is specified by the
1726 argument, a pointer to the device-specific quirks table is specified by the
1728 argument, and any required device flags may be provided in
1732 argument defaults to
1735 .It Dv BHND_DEVICE_END
1742 .Bd -literal -offset indent
1743 struct bhnd_device bhnd_usb11_devices[] = {
1744 BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller",
1751 .Vt bhnd_device_quirk
1752 structure contains the following fields:
1753 .Bl -tag -width "quirks_table" -offset indent -compact
1756 .Vt bhnd_device_match
1759 Applicable quirk flags.
1762 A bhnd_device_quirk table entry may be initialized using one of the following
1764 .Bl -tag -width "Fn BHND_CHIP_QUIRK chip hwrev flags" -offset indent
1765 .It Fn BHND_BOARD_QUIRK "board" "flags"
1768 on devices with a board type equal to
1771 .It Fn BHND_CHIP_QUIRK "chip" "hwrev" "flags"
1774 on devices with a chip ID equal to
1775 .Dv BHND_CHIPID_BCM ##
1777 and chip hardware revision that matches
1780 .It Fn BHND_PKG_QUIRK "chip" "pkg" flags"
1783 on devices with a chip ID equal to
1784 .Dv BHND_CHIPID_BCM ##
1786 and chip package equal to
1787 .Dv BHND_ ## chip ##
1789 .It Fn BHND_CORE_QUIRK "hwrev" flags"
1792 on devices with a core hardware revision that matches
1797 .Bd -literal -offset indent
1798 struct bhnd_device_quirk bhnd_usb11_quirks[] = {
1799 BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller",
1804 .Ss "DMA Address Translation Functions"
1806 .Fn bhnd_get_dma_translation
1807 function is used to request a DMA address translation descriptor suitable
1808 for use with a maximum DMA address width of
1810 with support for the requested translation
1813 If a suitable DMA address translation descriptor is found, it will be stored in
1815 and a bus DMA tag specifying the DMA translation's address restrictions will
1824 if the translation descriptor or DMA tag are not desired.
1826 The following DMA translation flags are supported:
1827 .Bl -ohang -width ".Dv BHND_DMA_TRANSLATION_BYTESWAPPED" -offset indent
1828 .It Dv BHND_DMA_TRANSLATION_PHYSMAP
1829 The translation remaps the device's physical address space.
1831 This is used in conjunction with
1832 .Dv BHND_DMA_TRANSLATION_BYTESWAPPED
1833 to define a DMA translation that provides byteswapped access to physical memory
1834 on big-endian MIPS SoCs.
1835 .It Dv BHND_DMA_TRANSLATION_BYTESWAPPED
1836 The translation provides a byte-swapped mapping; write requests will be
1837 byte-swapped before being written to memory, and read requests will be
1838 byte-swapped before being returned.
1840 This is primarily used to perform efficient byte swapping of DMA data on
1841 embedded MIPS SoCs executing in big-endian mode.
1844 The following symbolic constants are defined for common DMA address widths:
1846 .Bl -tag -width ".Dv BHND_DMA_ADDR_64BIT" -offset indent -compact
1847 .It Dv BHND_DMA_ADDR_30BIT
1849 .It Dv BHND_DMA_ADDR_32BIT
1851 .It Dv BHND_DMA_ADDR_64BIT
1856 .Vt bhnd_dma_translation
1857 structure contains the following fields:
1858 .Bl -tag -width "addrext_mask"
1860 Host-to-device physical address translation.
1861 This may be added to a host physical address to produce a device DMA address.
1863 Device-addressable address mask.
1864 This defines the device DMA address range, and excludes any bits reserved for
1865 mapping the address within the translation window at
1868 Device-addressable extended address mask.
1869 If a the per-core BHND DMA engine supports the 'addrext' control field, it can
1870 be used to provide address bits excluded by
1873 Support for DMA extended address changes \(em including coordination with the
1874 core providing device-to-host DMA address translation \(em is handled
1875 transparently by the DMA engine.
1877 For example, on PCI Wi-Fi devices, the Wi-Fi core's DMA engine will (in effect)
1878 update the PCI host bridge core's DMA
1879 .Dv sbtopcitranslation
1880 base address to map the target address prior to performing a DMA transaction.
1885 .Ss "Interrupt Functions"
1887 .Fn bhnd_get_intr_count
1888 function is used to determine the number of backplane interrupt lines assigned
1891 Interrupt line identifiers are allocated in monotonically increasing order,
1895 .Fn bhnd_get_intr_ivec
1896 function is used to determine the backplane interrupt vector assigned to
1901 writing the result to
1903 Interrupt vector assignments are backplane-specific: On BCMA devices, this
1904 function returns the OOB bus line assigned to the interrupt.
1905 On SIBA devices, it returns the target OCP slave flag number assigned to the
1910 function is used to map interrupt line
1914 to an IRQ number, writing the result to
1916 Until unmapped, this IRQ may be used when allocating a resource of type
1919 Ownership of the interrupt mapping is assumed by the caller, and must be
1920 explicitly released using
1921 .Fa bhnd_unmap_intr .
1925 function is used to unmap bus IRQ
1927 previously mapped using
1932 .Ss "NVRAM Functions"
1934 .Fn bhnd_nvram_getvar
1935 function is used to read the value of NVRAM variable
1937 from the NVRAM provider(s) registered with the parent
1941 coerced to the desired data representation
1943 written to the buffer specified by
1946 Before the call, the maximum capacity of
1950 After a successful call \(em or if
1952 is returned \(em the size of the available data will be written to
1954 The size of the desired data representation can be determined by calling
1955 .Fn bhnd_nvram_getvar
1961 The following NVRAM data types are supported:
1963 .Bl -tag -width ".Dv BHND_NVRAM_TYPE_UINT64_ARRAY" -offset indent -compact
1964 .It Dv BHND_NVRAM_TYPE_UINT8
1965 unsigned 8-bit integer
1966 .It Dv BHND_NVRAM_TYPE_UINT16
1967 unsigned 16-bit integer
1968 .It Dv BHND_NVRAM_TYPE_UINT32
1969 unsigned 32-bit integer
1970 .It Dv BHND_NVRAM_TYPE_UINT64
1971 signed 64-bit integer
1972 .It Dv BHND_NVRAM_TYPE_INT8
1973 signed 8-bit integer
1974 .It Dv BHND_NVRAM_TYPE_INT16
1975 signed 16-bit integer
1976 .It Dv BHND_NVRAM_TYPE_INT32
1977 signed 32-bit integer
1978 .It Dv BHND_NVRAM_TYPE_INT64
1979 signed 64-bit integer
1980 .It Dv BHND_NVRAM_TYPE_CHAR
1982 .It Dv BHND_NVRAM_TYPE_STRING
1983 UTF-8 NUL-terminated string
1984 .It Dv BHND_NVRAM_TYPE_BOOL
1986 .It Dv BHND_NVRAM_TYPE_NULL
1988 .It Dv BHND_NVRAM_TYPE_DATA
1990 .It Dv BHND_NVRAM_TYPE_UINT8_ARRAY
1991 array of uint8 integers
1992 .It Dv BHND_NVRAM_TYPE_UINT16_ARRAY
1993 array of uint16 integers
1994 .It Dv BHND_NVRAM_TYPE_UINT32_ARRAY
1995 array of uint32 integers
1996 .It Dv BHND_NVRAM_TYPE_UINT64_ARRAY
1997 array of uint64 integers
1998 .It Dv BHND_NVRAM_TYPE_INT8_ARRAY
1999 array of int8 integers
2000 .It Dv BHND_NVRAM_TYPE_INT16_ARRAY
2001 array of int16 integers
2002 .It Dv BHND_NVRAM_TYPE_INT32_ARRAY
2003 array of int32 integers
2004 .It Dv BHND_NVRAM_TYPE_INT64_ARRAY
2005 array of int64 integers
2006 .It Dv BHND_NVRAM_TYPE_CHAR_ARRAY
2007 array of UTF-8 characters
2008 .It Dv BHND_NVRAM_TYPE_STRING_ARRAY
2009 array of UTF-8 NUL-terminated strings
2010 .It Dv BHND_NVRAM_TYPE_BOOL_ARRAY
2011 array of uint8 boolean values
2015 .Fn bhnd_nvram_getvar_array ,
2016 .Fn bhnd_nvram_getvar_int ,
2017 .Fn bhnd_nvram_getvar_int8 ,
2018 .Fn bhnd_nvram_getvar_int16 ,
2019 .Fn bhnd_nvram_getvar_int32 ,
2020 .Fn bhnd_nvram_getvar_uint ,
2021 .Fn bhnd_nvram_getvar_uint8 ,
2022 .Fn bhnd_nvram_getvar_uint16 ,
2023 .Fn bhnd_nvram_getvar_uint32 ,
2025 .Fn bhnd_nvram_getvar_str
2026 functions are convenience wrappers for
2027 .Fn bhnd_nvram_getvar .
2030 .Fn bhnd_nvram_getvar_array
2031 function returns either a value of exactly
2035 or returns an error code of
2037 if the data representation is not exactly
2042 .Fn bhnd_nvram_getvar_int
2044 .Fn bhnd_nvram_getvar_uint
2045 functions return the value of NVRAM variable
2047 coerced to a signed or unsigned integer
2053 .Fn bhnd_nvram_getvar_int8 ,
2054 .Fn bhnd_nvram_getvar_int16 ,
2055 .Fn bhnd_nvram_getvar_int32 ,
2056 .Fn bhnd_nvram_getvar_uint ,
2057 .Fn bhnd_nvram_getvar_uint8 ,
2058 .Fn bhnd_nvram_getvar_uint16 ,
2060 .Fn bhnd_nvram_getvar_uint32
2061 functions return the value of NVRAM variable
2063 coerced to a signed or unsigned 8, 16, or 32-bit integer type.
2066 .Fn bhnd_nvram_getvar_str
2067 functions return the value of NVRAM variable
2069 coerced to a NUL-terminated string.
2072 .Fn bhnd_nvram_string_array_next
2073 function iterates over all strings in the
2075 .Dv BHND_NVRAM_TYPE_STRING_ARRAY
2079 including any terminating NUL character(s), is specified using the
2084 argument should be either a string pointer previously returned by
2085 .Fn bhnd_nvram_string_array_next ,
2094 argument must be a pointer to the length previously returned by
2095 .Fn bhnd_nvram_string_array_next .
2096 On success, the next string element's length will be written to this pointer.
2098 .Ss "Port/Region Functions"
2099 Per-device interconnect memory mappings are identified by a combination of
2104 Port and memory region identifiers are allocated in monotonically increasing
2109 The following port types are supported:
2110 .Bl -tag -width ".Dv BHND_PORT_DEVICE" -offset indent
2111 .It Dv BHND_PORT_DEVICE
2113 The device's control/status registers are always mapped by the first device port
2114 and region, and will be assigned a
2117 .It Dv BHND_PORT_BRIDGE
2119 .It Dv BHND_PORT_AGENT
2120 Interconnect agent/wrapper.
2124 .Fn bhnd_decode_port_rid
2125 function is used to decode the resource ID
2131 writing the port type to
2140 .Fn bhnd_get_port_count
2141 function returns the number of ports of type
2147 .Fn bhnd_get_port_rid
2148 function returns the resource ID for the
2150 resource mapping the
2158 or -1 if the port or region are invalid, or do not have an assigned resource ID.
2161 .Fn bhnd_get_region_addr
2162 function is used to determine the base address and size of the memory
2170 The region's base device address will be written to
2172 and the region size to
2176 .Fn bhnd_get_region_count
2177 function returns the number of memory regions mapped to
2185 .Fn bhnd_is_region_valid
2190 is a valid region mapped by
2197 .Ss "Power Management Functions"
2198 Drivers must ask the parent
2200 bus to allocate device PMU state using
2202 before calling any another bhnd PMU functions.
2206 function is used to allocate per-device PMU state and enable PMU request
2209 The memory region containing the device's PMU register block must be allocated
2211 .Xr bus_alloc_resource 9
2213 .Fn bhnd_alloc_resource
2215 .Fn bhnd_alloc_pmu ,
2216 and must not be released until after calling
2217 .Fn bhnd_release_pmu .
2219 On all supported BHND hardware, the PMU register block is mapped by the device's
2220 control/status registers in the first device port and region.
2223 .Fn bhnd_release_pmu
2224 function releases the per-device PMU state previously allocated for device
2227 .Fn bhnd_alloc_pmu .
2228 Any outstanding clock and external resource requests will be discarded upon
2229 release of the device PMU state.
2232 .Fn bhnd_enable_clocks
2233 function is used to request that
2235 be powered up and routed to the backplane on behalf of device
2237 This will power any clock sources required (e.g., XTAL, PLL, etc) and wait until
2238 the requested clocks are stable.
2239 If the request succeeds, any previous clock requests issued by
2243 The following clocks are supported, and may be combined using bitwise OR to
2244 request multiple clocks:
2246 .Bl -tag -width ".Dv BHND_CLOCK_DYN" -offset indent
2248 Dynamically select an appropriate clock source based on all outstanding clock
2249 requests by any device attached to the parent
2253 Idle Low-Power (ILP) Clock.
2254 May be used if no register access is required, or long request latency is
2257 Active Low-Power (ALP) Clock.
2258 Supports low-latency register access and low-rate DMA.
2260 High Throughput (HT) Clock.
2261 Supports high bus throughput and lowest-latency register access.
2265 .Fn bhnd_request_clock
2266 function is used to request that
2268 (or faster) be powered up and routed to device
2272 .Fn bhnd_get_clock_freq
2273 function is used to request the current clock frequency of
2275 writing the frequency in Hz to
2279 .Fn bhnd_get_clock_latency
2280 function is used to determine the transition latency required for
2282 writing the latency in microseconds to
2286 latency value is suitable for use as the D11 Wi-Fi core
2291 .Fn bhnd_request_ext_rsrc
2292 function is used to request that the external PMU-managed resource assigned to
2295 identified by device-specific identifier
2300 .Fn bhnd_release_ext_rsrc
2301 function releases any outstanding requests by device
2303 for the PMU-managed resource identified by device-specific identifier
2305 If an external resource is shared by multiple devices, it will not be powered
2306 down until all device requests are released.
2308 .Ss "Service Provider Functions"
2310 .Fn bhnd_register_provider
2311 function is used to register device
2313 as a provider for platform
2319 The following service types are supported:
2320 .Bl -tag -width ".Dv BHND_SERVICE_INVALID" -offset indent
2321 .It Dv BHND_SERVICE_CHIPC
2323 The providing device must implement the bhnd_chipc interface.
2324 .It Dv BHND_SERVICE_PWRCTL
2325 Legacy PWRCTL service.
2326 The providing device must implement the bhnd_pwrctl interface.
2327 .It Dv BHND_SERVICE_PMU
2329 The providing device must implement the bhnd_pmu interface.
2330 .It Dv BHND_SERVICE_NVRAM
2332 The providing device must implement the bhnd_nvram interface.
2333 .It Dv BHND_SERVICE_GPIO
2335 The providing device must implement the standard
2338 .It Dv BHND_SERVICE_ANY
2339 Matches on any service type.
2341 .Fn bhnd_deregister_provider
2342 to remove all service provider registrations for a device.
2346 .Fn bhnd_deregister_provider
2347 function attempts to remove provider registration for the device
2354 .Dv BHND_SERVICE_ANY
2355 is specified, this function will attempt to remove
2356 .Em all service provider registrations for
2360 .Fn bhnd_retain_provider
2361 function retains and returns a reference to the provider registered for
2368 On success, the caller is responsible for releasing this provider reference
2370 .Fn bhnd_release_provider .
2371 The service provider is guaranteed to remain available until the provider
2372 reference is released.
2375 .Fn bhnd_release_provider
2376 function releases a reference to a
2380 previously retained by device
2383 .Fn bhnd_retain_provider .
2385 .Ss "Utility Functions"
2387 .Fn bhnd_driver_get_erom_class
2388 function returns the
2390 class for the device enumeration table format used by
2394 If the driver does not support
2401 .Fn bhnd_find_core_class
2402 function looks up the BHND class, if known, for the BHND vendor ID
2408 .Fn bhnd_find_core_name
2409 function is used to fetch the human-readable name, if known, for the BHND core
2419 functions are convenience wrappers for
2420 .Fn bhnd_find_core_class
2422 .Fn bhnd_find_core_name ,
2427 fields of the core info structure
2431 .Fn bhnd_format_chip_id
2432 function writes a NUL-terminated human-readable representation of the BHND
2434 value to the specified
2440 characters will be written, with the
2442 character set to '\\0'.
2444 .Dv BHND_CHIPID_MAX_NAMELEN
2445 is sufficient for any string representation produced using
2446 .Fn bhnd_format_chip_id .
2449 .Fn bhnd_set_custom_core_desc
2452 device identification of
2454 overriding the core name with the specified
2456 to populate the device's verbose description using
2457 .Xr device_set_desc .
2460 .Fn bhnd_set_default_core_desc
2463 device identification of
2465 to populate the device's verbose description using
2466 .Xr device_set_desc .
2469 .Fn bhnd_vendor_name
2470 function returns the human-readable name for the JEP-106, ARM 4-bit
2471 continuation encoded manufacturer ID
2476 .Ss Bus Resource Functions
2478 .Fn bhnd_activate_resource ,
2479 .Fn bhnd_alloc_resources ,
2480 .Fn bhnd_deactivate_resource ,
2482 .Fn bhnd_release_resource
2483 functions return 0 on success, otherwise an appropriate error code is returned.
2486 .Fn bhnd_alloc_resource
2488 .Fn bhnd_alloc_resource_any
2489 functions return a pointer to
2490 .Vt "struct resource"
2491 on success, a null pointer otherwise.
2493 .Ss "Device Configuration Functions"
2496 .Fn bhnd_read_config
2498 .Fn bhnd_write_config
2499 functions return 0 on success, or one of the following values on error:
2502 The device is not a direct child of the
2506 The requested width is not one of 1, 2, or 4 bytes.
2508 Accessing agent/config space for the device is unsupported.
2510 The requested offset or width exceeds the bounds of the mapped agent/config
2515 .Fn bhnd_read_ioctl ,
2516 .Fn bhnd_write_ioctl ,
2517 .Fn bhnd_read_iost ,
2521 functions return 0 on success, otherwise an appropriate error code is returned.
2523 .Ss "Device Information Functions"
2526 .Fn bhnd_read_board_info
2527 function returns 0 on success, otherwise an appropriate error code is returned.
2529 .Ss "DMA Address Translation Functions"
2531 .Fn bhnd_get_dma_translation
2532 function returns 0 on success, or one of the following values on error:
2535 DMA is not supported.
2537 No DMA translation matching the requested address width and translation flags
2541 If fetching the requested DMA address translation otherwise fails, an
2542 appropriate error code will be returned.
2544 .Ss "Interrupt Functions"
2547 .Fn bhnd_get_intr_ivec
2551 if the requested interrupt line exceeds the number of interrupt lines assigned
2556 function returns 0 on success, otherwise an appropriate error code is returned.
2558 .Ss "NVRAM Functions"
2560 .Fn bhnd_nvram_getvar ,
2561 .Fn bhnd_nvram_getvar_array ,
2562 .Fn bhnd_nvram_getvar_int ,
2563 .Fn bhnd_nvram_getvar_int8 ,
2564 .Fn bhnd_nvram_getvar_int16 ,
2565 .Fn bhnd_nvram_getvar_int32 ,
2566 .Fn bhnd_nvram_getvar_uint ,
2567 .Fn bhnd_nvram_getvar_uint8 ,
2568 .Fn bhnd_nvram_getvar_uint16 ,
2570 .Fn bhnd_nvram_getvar_uint32
2571 functions return 0 on success, or one of the following values on error:
2574 If an NVRAM provider has not been registered with the bus.
2576 The requested variable was not found.
2578 If the buffer of size is too small to hold the requested value.
2579 .It Bq Er EOPNOTSUPP
2580 If the value's native type is incompatible with and cannot be coerced to the
2583 If value coercion would overflow (or underflow) the requested type
2586 If reading the variable otherwise fails, an appropriate error code will be
2589 .Ss "Port/Region Functions"
2591 .Fn bhnd_decode_port_rid
2593 0 on success, or an appropriate error code if no matching port/region is found.
2596 .Fn bhnd_get_port_rid
2597 function returns the resource ID for the requested port and region,
2598 or -1 if the port or region are invalid, or do not have an assigned resource ID.
2601 .Fn bhnd_get_region_addr
2603 0 on success, or an appropriate error code if no matching port/region is found.
2608 function returns 0 on success, otherwise an appropriate error code is returned.
2611 .Fn bhnd_release_pmu
2612 function returns 0 on success, otherwise an appropriate error code is returned,
2613 and the core state will be left unmodified.
2616 .Fn bhnd_enable_clocks
2618 .Fn bhnd_request_clock
2619 functions return 0 on success, or one of the following values on error:
2622 An unsupported clock was requested.
2624 No PMU or PWRCTL provider has been registered with the bus.
2628 .Fn bhnd_get_clock_freq
2629 function returns 0 on success, or
2631 if the frequency for the specified clock is not available.
2634 .Fn bhnd_get_clock_latency
2635 function returns 0 on success, or
2637 if the transition latency for the specified clock is not available.
2640 .Fn bhnd_request_ext_rsrc
2642 .Fn bhnd_release_ext_rsrc
2643 functions return 0 on success, otherwise an appropriate error code is returned.
2646 .Ss "Service Provider Functions"
2648 .Fn bhnd_register_provider
2649 function returns 0 on success,
2651 if an entry for service already exists, or an appropriate error code if
2652 service registration otherwise fails.
2655 .Fn bhnd_deregister_provider
2656 function returns 0 on success, or
2658 if active references to the service provider exist.
2661 .Fn bhnd_retain_provider
2662 function returns a pointer to
2664 on success, a null pointer if the requested provider is not registered.
2666 .Ss "Utility Functions"
2669 .Fn bhnd_format_chip_id
2670 function returns the total number of bytes written on success, or a negative
2680 driver programming interface and this manual page were written by
2681 .An Landon Fuller Aq Mt landonf@FreeBSD.org .