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:
718 .Bl -dash -offset indent
720 Host access to SoC address space is provided via a set of register windows
721 (e.g., a set of configurable windows into SoC address space mapped via PCI BARs)
723 DMA is supported by the bridge core's sparse mapping of host address space into
724 the backplane address space.
725 These address regions may be used as a target for the on-chip DMA engine.
727 Any backplane interrupt vectors routed to the bridge core may be mapped by the
728 bridge to host interrupts (e.g., PCI INTx/MSI/MSI-X).
733 driver programming interface \(em and
735 host bridge drivers \(em support the implementation of common drivers for
736 Broadcom IP cores, whether attached via a BHND host bridge, or via the native
739 .Ss "Bus Resource Functions"
740 The bhnd_resource functions are wrappers for the standard
741 .Vt "struct resource"
742 bus APIs, providing support for
746 bridged chipsets, may require on-demand remapping of address windows
747 prior to accessing bus memory.
749 These functions are primarily used in the implementation of BHND platform device
750 drivers that, on host-connected peripherals, must share a small set of register
751 windows during initial setup and teardown.
753 BHND peripherals are designed to not require register window remapping
754 during normal operation, and most drivers may safely use the standard
759 .Fn bhnd_activate_resource
760 function activates a previously allocated resource.
762 The arguments are as follows:
763 .Bl -tag -width indent
765 The device holding ownership of the allocated resource.
767 The type of the resource.
769 The bus-specific handle that identifies the resource being activated.
771 A pointer to the resource returned by
772 .Fn bhnd_alloc_resource .
776 .Fn bhnd_alloc_resource
777 function allocates a resource from a device's parent
781 The arguments are as follows:
782 .Bl -tag -width indent
784 The device requesting resource ownership.
786 The type of resource to allocate.
787 This may be any type supported by the standard
788 .Xr bus_alloc_resource 9
791 The bus-specific handle identifying the resource being allocated.
793 The start address of the resource.
795 The end address of the resource.
797 The size of the resource.
799 The flags for the resource to be allocated.
800 These may be any values supported by the standard
801 .Xr bus_alloc_resource 9
805 To request that the bus supply the resource's default
814 values of 0ul and ~0ul respectively, and a
819 .Fn bhnd_alloc_resource_any
820 function is a convenience wrapper for
821 .Fn bhnd_alloc_resource ,
822 using the resource's default
829 The arguments are as follows:
830 .Bl -tag -width indent
832 The device requesting resource ownership.
834 The type of resource to allocate.
835 This may be any type supported by the standard
836 .Xr bus_alloc_resource 9
839 The bus-specific handle identifying the resource being allocated.
841 The flags for the resource to be allocated.
842 These may be any values supported by the standard
843 .Xr bus_alloc_resource 9
848 .Fn bhnd_alloc_resources
849 function allocates resources defined in resource specification from a device's
854 The arguments are as follows:
855 .Bl -tag -width indent
857 The device requesting ownership of the resources.
859 A standard bus resource specification.
860 If all requested resources, are successfully allocated,
861 this will be updated with the allocated resource identifiers.
863 If all requested resources are successfully allocated, this will be populated
865 .Vt "struct bhnd_resource"
870 .Fn bhnd_deactivate_resource
871 function deactivates a resource previously activated by.
872 .Fn bhnd_activate_resource .
873 The arguments are as follows:
874 .Bl -tag -width indent
876 The device holding ownership of the activated resource.
878 The type of the resource.
880 The bus-specific handle identifying the resource.
882 A pointer to the resource returned by bhnd_alloc_resource.
886 .Fn bhnd_release_resource
887 function frees a resource previously returned by
888 .Fn bhnd_alloc_resource .
889 The arguments are as follows:
890 .Bl -tag -width indent
892 The device holding ownership of the resource.
894 The type of the resource.
896 The bus-specific handle identifying the resource.
898 A pointer to the resource returned by bhnd_alloc_resource.
902 .Fn bhnd_release_resources
903 function frees resources previously returned by
904 .Fn bhnd_alloc_resources .
905 The arguments are as follows:
906 .Bl -tag -width indent
908 The device that owns the resources.
910 A standard bus resource specification previously initialized by
911 .Fn bhnd_alloc_resources .
913 The resources to be released.
918 structure contains the following fields:
919 .Bl -tag -width "direct"
922 .Vt struct resource .
924 If true, the resource requires bus window remapping before it is MMIO
928 .Ss "Bus Space Functions"
929 The bhnd_bus_space functions wrap their equivalent
931 counterparts, and provide support for accessing bus memory via
932 .Vt "struct bhnd_resource".
934 .Bl -ohang -offset indent -compact
935 .It Fn bhnd_bus_barrier
936 .It Fn bhnd_bus_[read|write]_[1|2|4]
937 .It Fn bhnd_bus_[read_multi|write_multi]_[1|2|4]
938 .It Fn bhnd_bus_[read_multi_stream|write_multi_stream]_[1|2|4]
939 .It Fn bhnd_bus_[read_region|write_region]_[1|2|4]
940 .It Fn bhnd_bus_[read_region_stream|write_region_stream]_[1|2|4]
941 .It Fn bhnd_bus_[read_stream|write_stream]_[1|2|4]
942 .It Fn bhnd_bus_[set_multi|set_stream]_[1|2|4]
945 Drivers that do not rely on
946 .Vt "struct bhnd_resource"
947 should use the standard
953 .Ss "Device Configuration Functions"
956 function is used to read the I/O control register value of device
958 returning the current value in
963 function is used to modify the I/O control register of
965 The new value of the register is computed by updating any bits set in
969 The following I/O control flags are supported:
970 .Bl -tag -width ".Dv BHND_IOCTL_CLK_FORCE" -offset indent
971 .It Dv BHND_IOCTL_BIST
972 Initiate a built-in self-test (BIST).
973 Must be cleared after BIST results are read via the IOST (I/O Status) register.
974 .It Dv BHND_IOCTL_PME
975 Enable posting of power management events by the core.
976 .It Dv BHND_IOCTL_CLK_FORCE
977 Force disable of clock gating, resulting in all clocks being distributed within
979 Should be set when asserting/deasserting reset to ensure the reset signal fully
980 propagates to the entire core.
981 .It Dv BHND_IOCTL_CLK_EN
982 If cleared, the core clock will be disabled.
983 Should be set during normal operation, and cleared when the core is held in
985 .It Dv BHND_IOCTL_CFLAGS
986 The mask of IOCTL bits reserved for additional core-specific I/O control flags.
991 function is used to read the I/O status register of device
993 returning the current value in
995 The following I/O status flags are supported:
996 .Bl -tag -width ".Dv BHND_IOST_BIST_DONE" -offset indent
997 .It Dv BHND_IOST_BIST_DONE
998 Set upon BIST completion.
999 Will be cleared when the
1001 flag of the I/O control register is cleared using
1002 .Fn bhnd_write_ioctl .
1003 .It Dv BHND_IOST_BIST_FAIL
1004 Set upon detection of a BIST error; the value is unspecified if BIST has not
1006 .Dv BHND_IOST_BIST_DONE
1008 .It Dv BHND_IOST_CLK
1009 Set if the core has required that clocked be ungated, or cleared otherwise.
1010 The value is undefined if a core does not support clock gating.
1011 .It Dv BHND_IOST_DMA64
1012 Set if this core supports 64-bit DMA.
1013 .It Dv BHND_IOST_CFLAGS
1014 The mask of IOST bits reserved for additional core-specific I/O status flags.
1018 .Fn bhnd_read_config
1019 function is used to read a data item of
1023 from the backplane-specific agent/config space of the device
1027 .Fn bhnd_write_config
1028 function is used to write a data item of
1034 from the backplane-specific agent/config space of the device
1038 must be one of 1, 2, or 4 bytes.
1040 The agent/config space accessible via
1041 .Fn bhnd_read_config
1043 .Fn bhnd_write_config
1044 is backplane-specific, and these functions should only be used for functionality
1045 that is not available via another
1051 function transitions the device
1057 to the I/O control flags of
1059 The hardware may be brought out of this state using
1064 function first transitions the device
1066 to a low power RESET state, writing
1068 to the I/O control flags
1071 and then brings the device out of RESET, writing
1073 to the device's I/O control flags.
1076 .Fn bhnd_is_hw_suspended
1081 is currently held in a RESET state, or is otherwise not clocked.
1082 Otherwise, it returns
1085 Any outstanding per-device PMU requests made using
1086 .Fn bhnd_enable_clocks ,
1087 .Fn bhnd_request_clock ,
1089 .Fn bhnd_request_ext_rsrc
1090 will be released automatically upon placing a device into a RESET state.
1091 .Ss "Device Information Functions"
1093 .Fn bhnd_get_attach_type
1094 function returns the attachment type of the parent
1099 The following attachment types are supported:
1100 .Bl -hang -width ".Dv BHND_ATTACH_ADAPTER" -offset indent
1101 .It Dv BHND_ATTACH_ADAPTER
1102 The bus is resident on a bridged adapter, such as a PCI Wi-Fi device.
1103 .It Dv BHND_ATTACH_NATIVE
1104 The bus is resident on the native host, such as the primary or secondary bus of
1110 function returns chip information from the parent
1116 struct contains the following fields:
1117 .Bl -tag -width "enum_addr" -offset indent
1119 The chip identifier.
1121 The chip's hardware revision.
1123 The chip's semiconductor package identifier.
1125 Several different physical semiconductor package variants may exist for a given
1126 chip, each of which may require driver workarounds for hardware errata,
1127 unpopulated components, etc.
1129 The interconnect architecture used by this chip.
1133 capability flags supported by this chip.
1135 The backplane enumeration address.
1136 On SSB devices, this will be the base address of the first SSB core.
1137 On BCMA devices, this will be the address of the enumeration ROM (EROM) core.
1139 The number of cores on the chip backplane, or 0 if unknown.
1142 The following constants are defined for known
1145 .Bl -tag -width ".Dv BHND_CHIPTYPE_BCMA_ALT" -offset indent -compact
1146 .It Dv BHND_CHIPTYPE_SIBA
1148 .It Dv BHND_CHIPTYPE_BCMA
1150 .It Dv BHND_CHIPTYPE_BCMA_ALT
1151 BCMA-compatible variant found in Broadcom Northstar ARM SoCs.
1152 .It Dv BHND_CHIPTYPE_UBUS
1154 This BCMA-derived interconnect is found in Broadcom BCM33xx DOCSIS SoCs, and
1156 UBUS is not currently supported by
1162 flags are supported:
1163 .Bl -tag -width ".Dv BHND_CAP_BP64" -offset indent -compact
1164 .It Dv BHND_CAP_BP64
1165 The backplane supports 64-bit addressing.
1170 Additional symbolic constants for known
1175 values are defined in
1176 .In dev/bhnd/bhnd_ids.h .
1180 function returns the BHND class of device
1186 identifiers are recognized.
1188 .Dv BHND_DEVCLASS_OTHER .
1190 One of the following device classes will be returned:
1192 .Bl -tag -width ".Dv BHND_DEVCLASS_SOC_ROUTER" -offset indent -compact
1193 .It Dv BHND_DEVCLASS_CC
1194 ChipCommon I/O Controller
1195 .It Dv BHND_DEVCLASS_CC_B
1196 ChipCommon Auxiliary Controller
1197 .It Dv BHND_DEVCLASS_PMU
1199 .It Dv BHND_DEVCLASS_PCI
1200 PCI Host/Device Bridge
1201 .It Dv BHND_DEVCLASS_PCIE
1202 PCIe Host/Device Bridge
1203 .It Dv BHND_DEVCLASS_PCCARD
1204 PCMCIA Host/Device Bridge
1205 .It Dv BHND_DEVCLASS_RAM
1207 .It Dv BHND_DEVCLASS_MEMC
1209 .It Dv BHND_DEVCLASS_ENET
1211 .It Dv BHND_DEVCLASS_ENET_MAC
1213 .It Dv BHND_DEVCLASS_ENET_PHY
1215 .It Dv BHND_DEVCLASS_WLAN
1216 IEEE 802.11 MAC/PHY/Radio
1217 .It Dv BHND_DEVCLASS_WLAN_MAC
1219 .It Dv BHND_DEVCLASS_WLAN_PHY
1221 .It Dv BHND_DEVCLASS_CPU
1223 .It Dv BHND_DEVCLASS_SOC_ROUTER
1225 .It Dv BHND_DEVCLASS_SOC_BRIDGE
1226 Interconnect Host Bridge
1227 .It Dv BHND_DEVCLASS_EROM
1228 Device Enumeration ROM
1229 .It Dv BHND_DEVCLASS_NVRAM
1230 NVRAM/Flash Controller
1231 .It Dv BHND_DEVCLASS_SOFTMODEM
1232 Analog/PSTN SoftModem Codec
1233 .It Dv BHND_DEVCLASS_USB_HOST
1235 .It Dv BHND_DEVCLASS_USB_DEV
1236 USB Device Controller
1237 .It Dv BHND_DEVCLASS_USB_DUAL
1238 USB Host/Device Controller
1239 .It Dv BHND_DEVCLASS_OTHER
1241 .It Dv BHND_DEVCLASS_INVALID
1246 .Fn bhnd_get_core_info
1247 function returns the core information for device
1251 structure contains the following fields:
1253 .Bl -tag -width "core_idx" -offset indent -compact
1255 Vendor identifier (JEP-106, ARM 4-bit continuation encoded)
1266 Symbolic constants for common vendor and device identifiers are defined in
1267 .In dev/bhnd/bhnd_ids.h .
1268 Common vendor identifiers include:
1270 .Bl -tag -width ".Dv BHND_MFGID_MIPS" -offset indent -compact
1271 .It Dv BHND_MFGID_ARM
1273 .It Dv BHND_MFGID_BCM
1275 .It Dv BHND_MFGID_MIPS
1280 .Fn bhnd_get_core_index ,
1281 .Fn bhnd_get_core_unit ,
1282 .Fn bhnd_get_device ,
1283 .Fn bhnd_get_hwrev ,
1286 functions are convenience wrappers for
1287 .Fn bhnd_get_core_info ,
1288 returning, respect the
1300 .Fn bhnd_get_device_name
1301 function returns a human readable name for device
1305 .Fn bhnd_get_vendor_name
1306 function returns a human readable name for the vendor of device
1310 .Fn bhnd_read_board_info
1311 function attempts to read the board information for device
1313 The board information will be returned in the location pointed to by
1319 structure contains the following fields:
1320 .Bl -tag -width "board_srom_rev" -offset indent
1322 Vendor ID of the board manufacturer (PCI-SIG assigned).
1329 .It Fa board_srom_rev
1330 Board SROM format revision.
1341 field is the Broadcom PCI device ID that most closely matches the
1342 capabilities of the BHND device (if any).
1349 fields default to the PCI Subsystem Vendor ID, PCI Subsystem ID, and PCI
1350 device ID, unless overridden in device NVRAM.
1352 On other devices, including SoCs, the
1357 fields will be populated from device NVRAM.
1359 Symbolic constants for common board flags are defined in
1360 .In dev/bhnd/bhnd_ids.h .
1361 .Ss "Device Matching Functions"
1362 The bhnd device matching functions are used to match against core, chip, and
1363 board-level device attributes.
1364 Match requirements are specified using the
1365 .Vt "struct bhnd_board_match" ,
1366 .Vt "struct bhnd_chip_match" ,
1367 .Vt "struct bhnd_core_match" ,
1368 .Vt "struct bhnd_device_match" ,
1370 .Vt "struct bhnd_hwrev_match"
1371 match descriptor structures.
1374 .Fn bhnd_board_matches
1379 matches the board match descriptor
1381 Otherwise, it returns
1385 .Fn bhnd_chip_matches
1390 matches the chip match descriptor
1392 Otherwise, it returns
1396 .Fn bhnd_core_matches
1401 matches the core match descriptor
1403 Otherwise, it returns
1407 .Fn bhnd_device_matches
1412 matches the device match descriptor
1414 Otherwise, it returns
1418 .Fn bhnd_hwrev_matches
1423 matches the hwrev match descriptor
1425 Otherwise, it returns
1429 .Fn bhnd_bus_match_child
1430 function returns the first child device of
1432 that matches the device match descriptor
1434 If no matching child is found,
1439 .Fn bhnd_core_get_match_desc
1440 function returns an equality match descriptor for the core info in
1442 The returned descriptor will match only on core attributes identical to those
1447 .Fn bhnd_cores_equal
1448 function is a convenience wrapper for
1449 .Fn bhnd_core_matches
1451 .Fn bhnd_core_get_match_desc .
1452 This function returns
1461 Otherwise, it returns
1466 function returns a pointer to the first entry in the array
1472 If no matching core is found,
1477 .Vt bhnd_board_match
1478 match descriptor may be initialized using one or more of the following macros:
1479 .Bl -tag -width "Fn BHND_MATCH_BOARD_VENDOR vendor" -offset indent
1480 .It Fn BHND_MATCH_BOARD_VENDOR "vendor"
1481 Match on boards with a vendor equal to
1483 .It Fn BHND_MATCH_BOARD_TYPE "type"
1484 Match on boards with a type equal to
1485 .Dv "BHND_BOARD_ ##"
1487 .It Fn BHND_MATCH_SROMREV "sromrev"
1488 Match on boards with a sromrev that matches
1489 .Dv "BHND_HWREV_ ##"
1491 .It Fn BHND_MATCH_BOARD_REV "hwrev"
1492 Match on boards with hardware revisions that match
1495 .It Fn BHND_MATCH_BOARD "vendor" "type"
1496 A convenience wrapper for
1497 .Fn BHND_MATCH_BOARD_VENDOR
1499 .Fn BHND_MATCH_BOARD_TYPE .
1503 .Bd -literal -offset indent
1504 struct bhnd_board_match board_desc = {
1505 BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM),
1506 BHND_MATCH_BOARD_TYPE(BCM94360X52C),
1507 BHND_MATCH_BOARD_REV(HWREV_ANY),
1508 BHND_MATCH_SROMREV(RANGE(0, 10))
1514 match descriptor may be initialized using one or more of the following macros:
1515 .Bl -tag -width "Fn BHND_MATCH_CHIP_IPR id pkg hwrev" -offset indent
1516 .It Fn BHND_MATCH_CHIP_ID "id"
1517 Match on chips with an ID equal to
1518 .Dv "BHND_CHIPID_ ##"
1520 .It Fn BHND_MATCH_CHIP_REV "hwrev"
1521 Match on chips with hardware revisions that match
1524 .It Fn BHND_MATCH_CHIP_PKG "pkg"
1525 Match on chips with a package ID equal to
1526 .Dv "BHND_PKGID_ ##"
1528 .It Fn BHND_MATCH_CHIP_TYPE "type"
1529 Match on chips with a chip type equal to
1530 .Dv "BHND_CHIPTYPE_ ##"
1532 .It Fn BHND_MATCH_CHIP_IP "id" "pkg"
1533 A convenience wrapper for
1534 .Fn BHND_MATCH_CHIP_ID
1536 .Fn BHND_MATCH_CHIP_PKG .
1537 .It Fn BHND_MATCH_CHIP_IPR "id" "pkg" "hwrev"
1538 A convenience wrapper for
1539 .Fn BHND_MATCH_CHIP_ID ,
1540 .Fn BHND_MATCH_CHIP_PKG ,
1542 .Fn BHND_MATCH_CHIP_REV .
1543 .It Fn BHND_MATCH_CHIP_IR "id" "hwrev"
1544 A convenience wrapper for
1545 .Fn BHND_MATCH_CHIP_ID
1547 .Fn BHND_MATCH_CHIP_REV .
1551 .Bd -literal -offset indent
1552 struct bhnd_chip_match chip_desc = {
1553 BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN),
1554 BHND_MATCH_CHIP_TYPE(SIBA)
1560 match descriptor may be initialized using one or more of the following macros:
1561 .Bl -tag -width "Fn BHND_MATCH_CORE_VENDOR vendor" -offset indent
1562 .It Fn BHND_MATCH_CORE_VENDOR "vendor"
1563 Match on cores with a vendor ID equal to
1565 .It Fn BHND_MATCH_CORE_ID "id"
1566 Match on cores with a device ID equal to
1568 .It Fn BHND_MATCH_CORE_REV "hwrev"
1569 Match on cores with hardware revisions that match
1572 .It Fn BHND_MATCH_CORE_CLASS "class"
1573 Match on cores with a core device class equal to
1575 .It Fn BHND_MATCH_CORE_IDX "idx"
1576 Match on cores with a core index equal to
1578 .It Fn BHND_MATCH_CORE_UNIT "unit"
1579 Match on cores with a core unit equal to
1581 .It Fn BHND_MATCH_CORE "vendor" "id"
1582 A convenience wrapper for
1583 .Fn BHND_MATCH_CORE_VENDOR
1585 .Fn BHND_MATCH_CORE_ID .
1589 .Bd -literal -offset indent
1590 struct bhnd_core_match core_desc = {
1591 BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC),
1592 BHND_MATCH_CORE_REV(HWREV_RANGE(0, 10))
1597 .Vt bhnd_device_match
1598 match descriptor supports matching on all board, chip, and core attributes,
1599 and may be initialized using any of the
1600 .Vt bhnd_board_match ,
1601 .Vt bhnd_chip_match ,
1607 .Bd -literal -offset indent
1608 struct bhnd_device_match device_desc = {
1609 BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN),
1610 BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM),
1611 BHND_MATCH_BOARD_TYPE(BCM94329AGB),
1612 BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC),
1617 .Vt bhnd_hwrev_match
1618 match descriptor may be initialized using one of the following macros:
1620 .Bl -tag -width "Fn BHND_HWREV_RANGE start end" -offset indent -compact
1621 .It Dv BHND_HWREV_ANY
1622 Matches any hardware revision.
1623 .It Fn BHND_HWREV_EQ "hwrev"
1624 Matches any hardware revision equal to
1626 .It Fn BHND_HWREV_GTE "hwrev"
1627 Matches any hardware revision greater than or equal to
1629 .It Fn BHND_HWREV_LTE "hwrev"
1630 Matches any hardware revision less than or equal to
1632 .It Fn BHND_HWREV_RANGE "start" "end"
1633 Matches any hardware revision within an inclusive range.
1635 .Dv BHND_HWREV_INVALID
1638 value, will match on any revision equal to or greater than
1642 .Ss "Device Table Functions"
1643 The bhnd device table functions are used to query device and
1647 .Fn bhnd_device_lookup
1648 function returns a pointer to the first entry in device table
1650 that matches the device
1652 The table entry size is specified by
1656 .Fn bhnd_device_quirks
1657 function scan the device table
1659 for all quirk entries that match the device
1661 returning the bitwise OR of all matching quirk flags.
1662 The table entry size is specified by
1667 structure contains the following fields:
1668 .Bl -tag -width "quirks_table" -offset indent -compact
1671 .Vt bhnd_device_match
1674 A verbose device description suitable for use with
1675 .Xr device_set_desc 9 ,
1679 The quirks table for this device, or
1682 The device flags required when matching this entry.
1685 The following device flags are supported:
1686 .Bl -tag -width ".Dv BHND_DF_ADAPTER" -offset indent -compact
1688 Match on any device.
1689 .It Dv BHND_DF_HOSTB
1690 Match only if the device is the
1694 .Dv BHND_DF_ADAPTER .
1696 Match only if the device is attached to a native SoC backplane.
1697 .It Dv BHND_DF_ADAPTER
1698 Match only if the device is attached to a
1705 table entry may be initialized using one of the following macros:
1706 .Bl -ohang -offset indent
1707 .It Fn BHND_DEVICE "vendor" "device" "desc" "quirks" "flags"
1708 Match on devices with a vendor ID equal to
1711 and a core device ID equal to
1715 The device's verbose description is specified by the
1717 argument, a pointer to the device-specific quirks table is specified by the
1719 argument, and any required device flags may be provided in
1723 argument defaults to
1726 .It Dv BHND_DEVICE_END
1733 .Bd -literal -offset indent
1734 struct bhnd_device bhnd_usb11_devices[] = {
1735 BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller",
1742 .Vt bhnd_device_quirk
1743 structure contains the following fields:
1744 .Bl -tag -width "quirks_table" -offset indent -compact
1747 .Vt bhnd_device_match
1750 Applicable quirk flags.
1753 A bhnd_device_quirk table entry may be initialized using one of the following
1755 .Bl -tag -width "Fn BHND_CHIP_QUIRK chip hwrev flags" -offset indent
1756 .It Fn BHND_BOARD_QUIRK "board" "flags"
1759 on devices with a board type equal to
1762 .It Fn BHND_CHIP_QUIRK "chip" "hwrev" "flags"
1765 on devices with a chip ID equal to
1766 .Dv BHND_CHIPID_BCM ##
1768 and chip hardware revision that matches
1771 .It Fn BHND_PKG_QUIRK "chip" "pkg" flags"
1774 on devices with a chip ID equal to
1775 .Dv BHND_CHIPID_BCM ##
1777 and chip package equal to
1778 .Dv BHND_ ## chip ##
1780 .It Fn BHND_CORE_QUIRK "hwrev" flags"
1783 on devices with a core hardware revision that matches
1788 .Bd -literal -offset indent
1789 struct bhnd_device_quirk bhnd_usb11_quirks[] = {
1790 BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller",
1795 .Ss "DMA Address Translation Functions"
1797 .Fn bhnd_get_dma_translation
1798 function is used to request a DMA address translation descriptor suitable
1799 for use with a maximum DMA address width of
1801 with support for the requested translation
1804 If a suitable DMA address translation descriptor is found, it will be stored in
1806 and a bus DMA tag specifying the DMA translation's address restrictions will
1815 if the translation descriptor or DMA tag are not desired.
1817 The following DMA translation flags are supported:
1818 .Bl -ohang -width ".Dv BHND_DMA_TRANSLATION_BYTESWAPPED" -offset indent
1819 .It Dv BHND_DMA_TRANSLATION_PHYSMAP
1820 The translation remaps the device's physical address space.
1822 This is used in conjunction with
1823 .Dv BHND_DMA_TRANSLATION_BYTESWAPPED
1824 to define a DMA translation that provides byteswapped access to physical memory
1825 on big-endian MIPS SoCs.
1826 .It Dv BHND_DMA_TRANSLATION_BYTESWAPPED
1827 The translation provides a byte-swapped mapping; write requests will be
1828 byte-swapped before being written to memory, and read requests will be
1829 byte-swapped before being returned.
1831 This is primarily used to perform efficient byte swapping of DMA data on
1832 embedded MIPS SoCs executing in big-endian mode.
1835 The following symbolic constants are defined for common DMA address widths:
1837 .Bl -tag -width ".Dv BHND_DMA_ADDR_64BIT" -offset indent -compact
1838 .It Dv BHND_DMA_ADDR_30BIT
1840 .It Dv BHND_DMA_ADDR_32BIT
1842 .It Dv BHND_DMA_ADDR_64BIT
1847 .Vt bhnd_dma_translation
1848 structure contains the following fields:
1849 .Bl -tag -width "addrext_mask"
1851 Host-to-device physical address translation.
1852 This may be added to a host physical address to produce a device DMA address.
1854 Device-addressable address mask.
1855 This defines the device DMA address range, and excludes any bits reserved for
1856 mapping the address within the translation window at
1859 Device-addressable extended address mask.
1860 If a the per-core BHND DMA engine supports the 'addrext' control field, it can
1861 be used to provide address bits excluded by
1864 Support for DMA extended address changes \(em including coordination with the
1865 core providing device-to-host DMA address translation \(em is handled
1866 transparently by the DMA engine.
1868 For example, on PCI Wi-Fi devices, the Wi-Fi core's DMA engine will (in effect)
1869 update the PCI host bridge core's DMA
1870 .Dv sbtopcitranslation
1871 base address to map the target address prior to performing a DMA transaction.
1876 .Ss "Interrupt Functions"
1878 .Fn bhnd_get_intr_count
1879 function is used to determine the number of backplane interrupt lines assigned
1882 Interrupt line identifiers are allocated in monotonically increasing order,
1886 .Fn bhnd_get_intr_ivec
1887 function is used to determine the backplane interrupt vector assigned to
1892 writing the result to
1894 Interrupt vector assignments are backplane-specific: On BCMA devices, this
1895 function returns the OOB bus line assigned to the interrupt.
1896 On SIBA devices, it returns the target OCP slave flag number assigned to the
1901 function is used to map interrupt line
1905 to an IRQ number, writing the result to
1907 Until unmapped, this IRQ may be used when allocating a resource of type
1910 Ownership of the interrupt mapping is assumed by the caller, and must be
1911 explicitly released using
1912 .Fa bhnd_unmap_intr .
1916 function is used to unmap bus IRQ
1918 previously mapped using
1923 .Ss "NVRAM Functions"
1925 .Fn bhnd_nvram_getvar
1926 function is used to read the value of NVRAM variable
1928 from the NVRAM provider(s) registered with the parent
1932 coerced to the desired data representation
1934 written to the buffer specified by
1937 Before the call, the maximum capacity of
1941 After a successful call \(em or if
1943 is returned \(em the size of the available data will be written to
1945 The size of the desired data representation can be determined by calling
1946 .Fn bhnd_nvram_getvar
1952 The following NVRAM data types are supported:
1954 .Bl -tag -width ".Dv BHND_NVRAM_TYPE_UINT64_ARRAY" -offset indent -compact
1955 .It Dv BHND_NVRAM_TYPE_UINT8
1956 unsigned 8-bit integer
1957 .It Dv BHND_NVRAM_TYPE_UINT16
1958 unsigned 16-bit integer
1959 .It Dv BHND_NVRAM_TYPE_UINT32
1960 unsigned 32-bit integer
1961 .It Dv BHND_NVRAM_TYPE_UINT64
1962 signed 64-bit integer
1963 .It Dv BHND_NVRAM_TYPE_INT8
1964 signed 8-bit integer
1965 .It Dv BHND_NVRAM_TYPE_INT16
1966 signed 16-bit integer
1967 .It Dv BHND_NVRAM_TYPE_INT32
1968 signed 32-bit integer
1969 .It Dv BHND_NVRAM_TYPE_INT64
1970 signed 64-bit integer
1971 .It Dv BHND_NVRAM_TYPE_CHAR
1973 .It Dv BHND_NVRAM_TYPE_STRING
1974 UTF-8 NUL-terminated string
1975 .It Dv BHND_NVRAM_TYPE_BOOL
1977 .It Dv BHND_NVRAM_TYPE_NULL
1979 .It Dv BHND_NVRAM_TYPE_DATA
1981 .It Dv BHND_NVRAM_TYPE_UINT8_ARRAY
1982 array of uint8 integers
1983 .It Dv BHND_NVRAM_TYPE_UINT16_ARRAY
1984 array of uint16 integers
1985 .It Dv BHND_NVRAM_TYPE_UINT32_ARRAY
1986 array of uint32 integers
1987 .It Dv BHND_NVRAM_TYPE_UINT64_ARRAY
1988 array of uint64 integers
1989 .It Dv BHND_NVRAM_TYPE_INT8_ARRAY
1990 array of int8 integers
1991 .It Dv BHND_NVRAM_TYPE_INT16_ARRAY
1992 array of int16 integers
1993 .It Dv BHND_NVRAM_TYPE_INT32_ARRAY
1994 array of int32 integers
1995 .It Dv BHND_NVRAM_TYPE_INT64_ARRAY
1996 array of int64 integers
1997 .It Dv BHND_NVRAM_TYPE_CHAR_ARRAY
1998 array of UTF-8 characters
1999 .It Dv BHND_NVRAM_TYPE_STRING_ARRAY
2000 array of UTF-8 NUL-terminated strings
2001 .It Dv BHND_NVRAM_TYPE_BOOL_ARRAY
2002 array of uint8 boolean values
2006 .Fn bhnd_nvram_getvar_array ,
2007 .Fn bhnd_nvram_getvar_int ,
2008 .Fn bhnd_nvram_getvar_int8 ,
2009 .Fn bhnd_nvram_getvar_int16 ,
2010 .Fn bhnd_nvram_getvar_int32 ,
2011 .Fn bhnd_nvram_getvar_uint ,
2012 .Fn bhnd_nvram_getvar_uint8 ,
2013 .Fn bhnd_nvram_getvar_uint16 ,
2014 .Fn bhnd_nvram_getvar_uint32 ,
2016 .Fn bhnd_nvram_getvar_str
2017 functions are convenience wrappers for
2018 .Fn bhnd_nvram_getvar .
2021 .Fn bhnd_nvram_getvar_array
2022 function returns either a value of exactly
2026 or returns an error code of
2028 if the data representation is not exactly
2033 .Fn bhnd_nvram_getvar_int
2035 .Fn bhnd_nvram_getvar_uint
2036 functions return the value of NVRAM variable
2038 coerced to a signed or unsigned integer
2044 .Fn bhnd_nvram_getvar_int8 ,
2045 .Fn bhnd_nvram_getvar_int16 ,
2046 .Fn bhnd_nvram_getvar_int32 ,
2047 .Fn bhnd_nvram_getvar_uint ,
2048 .Fn bhnd_nvram_getvar_uint8 ,
2049 .Fn bhnd_nvram_getvar_uint16 ,
2051 .Fn bhnd_nvram_getvar_uint32
2052 functions return the value of NVRAM variable
2054 coerced to a signed or unsigned 8, 16, or 32-bit integer type.
2057 .Fn bhnd_nvram_getvar_str
2058 functions return the value of NVRAM variable
2060 coerced to a NUL-terminated string.
2063 .Fn bhnd_nvram_string_array_next
2064 function iterates over all strings in the
2066 .Dv BHND_NVRAM_TYPE_STRING_ARRAY
2070 including any terminating NUL character(s), is specified using the
2075 argument should be either a string pointer previously returned by
2076 .Fn bhnd_nvram_string_array_next ,
2085 argument must be a pointer to the length previously returned by
2086 .Fn bhnd_nvram_string_array_next .
2087 On success, the next string element's length will be written to this pointer.
2089 .Ss "Port/Region Functions"
2090 Per-device interconnect memory mappings are identified by a combination of
2095 Port and memory region identifiers are allocated in monotonically increasing
2100 The following port types are supported:
2101 .Bl -tag -width ".Dv BHND_PORT_DEVICE" -offset indent
2102 .It Dv BHND_PORT_DEVICE
2104 The device's control/status registers are always mapped by the first device port
2105 and region, and will be assigned a
2108 .It Dv BHND_PORT_BRIDGE
2110 .It Dv BHND_PORT_AGENT
2111 Interconnect agent/wrapper.
2115 .Fn bhnd_decode_port_rid
2116 function is used to decode the resource ID
2122 writing the port type to
2131 .Fn bhnd_get_port_count
2132 function returns the number of ports of type
2138 .Fn bhnd_get_port_rid
2139 function returns the resource ID for the
2141 resource mapping the
2149 or -1 if the port or region are invalid, or do not have an assigned resource ID.
2152 .Fn bhnd_get_region_addr
2153 function is used to determine the base address and size of the memory
2161 The region's base device address will be written to
2163 and the region size to
2167 .Fn bhnd_get_region_count
2168 function returns the number of memory regions mapped to
2176 .Fn bhnd_is_region_valid
2181 is a valid region mapped by
2188 .Ss "Power Management Functions"
2189 Drivers must ask the parent
2191 bus to allocate device PMU state using
2193 before calling any another bhnd PMU functions.
2197 function is used to allocate per-device PMU state and enable PMU request
2200 The memory region containing the device's PMU register block must be allocated
2202 .Xr bus_alloc_resource 9
2204 .Fn bhnd_alloc_resource
2206 .Fn bhnd_alloc_pmu ,
2207 and must not be released until after calling
2208 .Fn bhnd_release_pmu .
2210 On all supported BHND hardware, the PMU register block is mapped by the device's
2211 control/status registers in the first device port and region.
2214 .Fn bhnd_release_pmu
2215 function releases the per-device PMU state previously allocated for device
2218 .Fn bhnd_alloc_pmu .
2219 Any outstanding clock and external resource requests will be discarded upon
2220 release of the device PMU state.
2223 .Fn bhnd_enable_clocks
2224 function is used to request that
2226 be powered up and routed to the backplane on behalf of device
2228 This will power any clock sources required (e.g., XTAL, PLL, etc) and wait until
2229 the requested clocks are stable.
2230 If the request succeeds, any previous clock requests issued by
2234 The following clocks are supported, and may be combined using bitwise OR to
2235 request multiple clocks:
2236 .Bl -tag -width ".Dv BHND_CLOCK_DYN" -offset indent
2238 Dynamically select an appropriate clock source based on all outstanding clock
2239 requests by any device attached to the parent
2243 Idle Low-Power (ILP) Clock.
2244 May be used if no register access is required, or long request latency is
2247 Active Low-Power (ALP) Clock.
2248 Supports low-latency register access and low-rate DMA.
2250 High Throughput (HT) Clock.
2251 Supports high bus throughput and lowest-latency register access.
2255 .Fn bhnd_request_clock
2256 function is used to request that
2258 (or faster) be powered up and routed to device
2262 .Fn bhnd_get_clock_freq
2263 function is used to request the current clock frequency of
2265 writing the frequency in Hz to
2269 .Fn bhnd_get_clock_latency
2270 function is used to determine the transition latency required for
2272 writing the latency in microseconds to
2276 latency value is suitable for use as the D11 Wi-Fi core
2281 .Fn bhnd_request_ext_rsrc
2282 function is used to request that the external PMU-managed resource assigned to
2285 identified by device-specific identifier
2290 .Fn bhnd_release_ext_rsrc
2291 function releases any outstanding requests by device
2293 for the PMU-managed resource identified by device-specific identifier
2295 If an external resource is shared by multiple devices, it will not be powered
2296 down until all device requests are released.
2298 .Ss "Service Provider Functions"
2300 .Fn bhnd_register_provider
2301 function is used to register device
2303 as a provider for platform
2309 The following service types are supported:
2310 .Bl -tag -width ".Dv BHND_SERVICE_INVALID" -offset indent
2311 .It Dv BHND_SERVICE_CHIPC
2313 The providing device must implement the bhnd_chipc interface.
2314 .It Dv BHND_SERVICE_PWRCTL
2315 Legacy PWRCTL service.
2316 The providing device must implement the bhnd_pwrctl interface.
2317 .It Dv BHND_SERVICE_PMU
2319 The providing device must implement the bhnd_pmu interface.
2320 .It Dv BHND_SERVICE_NVRAM
2322 The providing device must implement the bhnd_nvram interface.
2323 .It Dv BHND_SERVICE_GPIO
2325 The providing device must implement the standard
2328 .It Dv BHND_SERVICE_ANY
2329 Matches on any service type.
2331 .Fn bhnd_deregister_provider
2332 to remove all service provider registrations for a device.
2336 .Fn bhnd_deregister_provider
2337 function attempts to remove provider registration for the device
2344 .Dv BHND_SERVICE_ANY
2345 is specified, this function will attempt to remove
2346 .Em all service provider registrations for
2350 .Fn bhnd_retain_provider
2351 function retains and returns a reference to the provider registered for
2358 On success, the caller is responsible for releasing this provider reference
2360 .Fn bhnd_release_provider .
2361 The service provider is guaranteed to remain available until the provider
2362 reference is released.
2365 .Fn bhnd_release_provider
2366 function releases a reference to a
2370 previously retained by device
2373 .Fn bhnd_retain_provider .
2375 .Ss "Utility Functions"
2377 .Fn bhnd_driver_get_erom_class
2378 function returns the
2380 class for the device enumeration table format used by
2384 If the driver does not support
2391 .Fn bhnd_find_core_class
2392 function looks up the BHND class, if known, for the BHND vendor ID
2398 .Fn bhnd_find_core_name
2399 function is used to fetch the human-readable name, if known, for the BHND core
2409 functions are convenience wrappers for
2410 .Fn bhnd_find_core_class
2412 .Fn bhnd_find_core_name ,
2417 fields of the core info structure
2421 .Fn bhnd_format_chip_id
2422 function writes a NUL-terminated human-readable representation of the BHND
2424 value to the specified
2430 characters will be written, with the
2432 character set to '\\0'.
2434 .Dv BHND_CHIPID_MAX_NAMELEN
2435 is sufficient for any string representation produced using
2436 .Fn bhnd_format_chip_id .
2439 .Fn bhnd_set_custom_core_desc
2442 device identification of
2444 overriding the core name with the specified
2446 to populate the device's verbose description using
2447 .Xr device_set_desc 9 .
2450 .Fn bhnd_set_default_core_desc
2453 device identification of
2455 to populate the device's verbose description using
2456 .Xr device_set_desc 9 .
2459 .Fn bhnd_vendor_name
2460 function returns the human-readable name for the JEP-106, ARM 4-bit
2461 continuation encoded manufacturer ID
2466 .Ss Bus Resource Functions
2468 .Fn bhnd_activate_resource ,
2469 .Fn bhnd_alloc_resources ,
2470 .Fn bhnd_deactivate_resource ,
2472 .Fn bhnd_release_resource
2473 functions return 0 on success, otherwise an appropriate error code is returned.
2476 .Fn bhnd_alloc_resource
2478 .Fn bhnd_alloc_resource_any
2479 functions return a pointer to
2480 .Vt "struct resource"
2481 on success, a null pointer otherwise.
2483 .Ss "Device Configuration Functions"
2485 .Fn bhnd_read_config
2487 .Fn bhnd_write_config
2488 functions return 0 on success, or one of the following values on error:
2491 The device is not a direct child of the
2495 The requested width is not one of 1, 2, or 4 bytes.
2497 Accessing agent/config space for the device is unsupported.
2499 The requested offset or width exceeds the bounds of the mapped agent/config
2504 .Fn bhnd_read_ioctl ,
2505 .Fn bhnd_write_ioctl ,
2506 .Fn bhnd_read_iost ,
2510 functions return 0 on success, otherwise an appropriate error code is returned.
2512 .Ss "Device Information Functions"
2514 .Fn bhnd_read_board_info
2515 function returns 0 on success, otherwise an appropriate error code is returned.
2517 .Ss "DMA Address Translation Functions"
2519 .Fn bhnd_get_dma_translation
2520 function returns 0 on success, or one of the following values on error:
2523 DMA is not supported.
2525 No DMA translation matching the requested address width and translation flags
2529 If fetching the requested DMA address translation otherwise fails, an
2530 appropriate error code will be returned.
2532 .Ss "Interrupt Functions"
2534 .Fn bhnd_get_intr_ivec
2538 if the requested interrupt line exceeds the number of interrupt lines assigned
2543 function returns 0 on success, otherwise an appropriate error code is returned.
2545 .Ss "NVRAM Functions"
2547 .Fn bhnd_nvram_getvar ,
2548 .Fn bhnd_nvram_getvar_array ,
2549 .Fn bhnd_nvram_getvar_int ,
2550 .Fn bhnd_nvram_getvar_int8 ,
2551 .Fn bhnd_nvram_getvar_int16 ,
2552 .Fn bhnd_nvram_getvar_int32 ,
2553 .Fn bhnd_nvram_getvar_uint ,
2554 .Fn bhnd_nvram_getvar_uint8 ,
2555 .Fn bhnd_nvram_getvar_uint16 ,
2557 .Fn bhnd_nvram_getvar_uint32
2558 functions return 0 on success, or one of the following values on error:
2561 If an NVRAM provider has not been registered with the bus.
2563 The requested variable was not found.
2565 If the buffer of size is too small to hold the requested value.
2566 .It Bq Er EOPNOTSUPP
2567 If the value's native type is incompatible with and cannot be coerced to the
2570 If value coercion would overflow (or underflow) the requested type
2573 If reading the variable otherwise fails, an appropriate error code will be
2576 .Ss "Port/Region Functions"
2578 .Fn bhnd_decode_port_rid
2580 0 on success, or an appropriate error code if no matching port/region is found.
2583 .Fn bhnd_get_port_rid
2584 function returns the resource ID for the requested port and region,
2585 or -1 if the port or region are invalid, or do not have an assigned resource ID.
2588 .Fn bhnd_get_region_addr
2590 0 on success, or an appropriate error code if no matching port/region is found.
2595 function returns 0 on success, otherwise an appropriate error code is returned.
2598 .Fn bhnd_release_pmu
2599 function returns 0 on success, otherwise an appropriate error code is returned,
2600 and the core state will be left unmodified.
2603 .Fn bhnd_enable_clocks
2605 .Fn bhnd_request_clock
2606 functions return 0 on success, or one of the following values on error:
2609 An unsupported clock was requested.
2611 No PMU or PWRCTL provider has been registered with the bus.
2615 .Fn bhnd_get_clock_freq
2616 function returns 0 on success, or
2618 if the frequency for the specified clock is not available.
2621 .Fn bhnd_get_clock_latency
2622 function returns 0 on success, or
2624 if the transition latency for the specified clock is not available.
2627 .Fn bhnd_request_ext_rsrc
2629 .Fn bhnd_release_ext_rsrc
2630 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"
2654 .Fn bhnd_format_chip_id
2655 function returns the total number of bytes written on success, or a negative
2665 driver programming interface and this manual page were written by
2666 .An Landon Fuller Aq Mt landonf@FreeBSD.org .