1.\" Copyright (c) 2015-2016 Landon Fuller <landonf@FreeBSD.org> 2.\" Copyright (c) 2017 The FreeBSD Foundation 3.\" All rights reserved. 4.\" 5.\" Portions of this documentation were written by Landon Fuller 6.\" under sponsorship from the FreeBSD Foundation. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd March 26, 2018 30.Dt BHND 9 31.Os 32.Sh NAME 33.Nm bhnd 34.Nd BHND driver programming interface 35.Sh SYNOPSIS 36.In dev/bhnd/bhnd.h 37.\" 38.Ss Bus Resource Functions 39.Ft int 40.Fo bhnd_activate_resource 41.Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r" 42.Fc 43.Ft "struct bhnd_resource *" 44.Fo bhnd_alloc_resource 45.Fa "device_t dev" "int type" "int *rid" "rman_res_t start" "rman_res_t end" 46.Fa "rman_res_t count" "u_int flags" 47.Fc 48.Ft "struct bhnd_resource *" 49.Fo bhnd_alloc_resource_any 50.Fa "device_t dev" "int type" "int *rid" "u_int flags" 51.Fc 52.Ft int 53.Fo bhnd_alloc_resources 54.Fa "device_t dev" "struct resource_spec *rs" "struct bhnd_resource **res" 55.Fc 56.Ft int 57.Fo bhnd_deactivate_resource 58.Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r" 59.Fc 60.Ft int 61.Fo bhnd_release_resource 62.Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r" 63.Fc 64.Ft void 65.Fo bhnd_release_resources 66.Fa "device_t dev" "const struct resource_spec *rs" 67.Fa "struct bhnd_resource **res" 68.Fc 69.\" 70.Ss "Bus Space Functions" 71.Ft void 72.Fo bhnd_bus_barrier 73.Fa "struct bhnd_resource *r" "bus_size_t offset" 74.Fa "bus_size_t length" "int flags" 75.Fc 76.Ft uint8_t 77.Fn bhnd_bus_read_1 "struct bhnd_resource *r" "bus_size_t offset" 78.Ft uint16_t 79.Fn bhnd_bus_read_2 "struct bhnd_resource *r" "bus_size_t offset" 80.Ft uint32_t 81.Fn bhnd_bus_read_4 "struct bhnd_resource *r" "bus_size_t offset" 82.Ft void 83.Fo bhnd_bus_read_multi_1 84.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" 85.Fa "bus_size_t count" 86.Fc 87.Ft void 88.Fo bhnd_bus_read_multi_2 89.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" 90.Fa "bus_size_t count" 91.Fc 92.Ft void 93.Fo bhnd_bus_read_multi_4 94.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" 95.Fa "bus_size_t count" 96.Fc 97.Ft void 98.Fo bhnd_bus_read_multi_stream_1 99.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" 100.Fa "bus_size_t count" 101.Fc 102.Ft void 103.Fo bhnd_bus_read_multi_stream_2 104.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" 105.Fa "bus_size_t count" 106.Fc 107.Ft void 108.Fo bhnd_bus_read_multi_stream_4 109.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" 110.Fa "bus_size_t count" 111.Fc 112.Ft void 113.Fo bhnd_bus_read_region_1 114.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" 115.Fa "bus_size_t count" 116.Fc 117.Ft void 118.Fo bhnd_bus_read_region_2 119.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" 120.Fa "bus_size_t count" 121.Fc 122.Ft void 123.Fo bhnd_bus_read_region_4 124.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" 125.Fa "bus_size_t count" 126.Fc 127.Ft void 128.Fo bhnd_bus_read_region_stream_1 129.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" 130.Fa "bus_size_t count" 131.Fc 132.Ft void 133.Fo bhnd_bus_read_region_stream_2 134.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" 135.Fa "bus_size_t count" 136.Fc 137.Ft void 138.Fo bhnd_bus_read_region_stream_4 139.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" 140.Fa "bus_size_t count" 141.Fc 142.Ft void 143.Fn bhnd_bus_read_stream_1 "struct bhnd_resource *r" "bus_size_t offset" 144.Ft void 145.Fn bhnd_bus_read_stream_2 "struct bhnd_resource *r" "bus_size_t offset" 146.Ft uint32_t 147.Fn bhnd_bus_read_stream_4 "struct bhnd_resource *r" "bus_size_t offset" 148.Ft void 149.Fo bhnd_bus_set_multi_1 150.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t value" 151.Fa "bus_size_t count" 152.Fc 153.Ft void 154.Fo bhnd_bus_set_multi_2 155.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t value" 156.Fa "bus_size_t count" 157.Fc 158.Ft void 159.Fo bhnd_bus_set_multi_4 160.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t value" 161.Fa "bus_size_t count" 162.Fc 163.Ft void 164.Fo bhnd_bus_set_region_1 165.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t value" 166.Fa "bus_size_t count" 167.Fc 168.Ft void 169.Fo bhnd_bus_set_region_2 170.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t value" 171.Fa "bus_size_t count" 172.Fc 173.Ft void 174.Fo bhnd_bus_set_region_4 175.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t value" 176.Fa "bus_size_t count" 177.Fc 178.Ft void 179.Fn bhnd_bus_write_1 "struct bhnd_resource *r" "uint8_t value" 180.Ft void 181.Fn bhnd_bus_write_2 "struct bhnd_resource *r" "uint16_t value" 182.Ft void 183.Fn bhnd_bus_write_4 "struct bhnd_resource *r" "uint32_t value" 184.Ft void 185.Fo bhnd_bus_write_multi_1 186.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" 187.Fa "bus_size_t count" 188.Fc 189.Ft void 190.Fo bhnd_bus_write_multi_2 191.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" 192.Fa "bus_size_t count" 193.Fc 194.Ft void 195.Fo bhnd_bus_write_multi_4 196.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" 197.Fa "bus_size_t count" 198.Fc 199.Ft void 200.Fo bhnd_bus_write_multi_stream_1 201.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" 202.Fa "bus_size_t count" 203.Fc 204.Ft void 205.Fo bhnd_bus_write_multi_stream_2 206.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" 207.Fa "bus_size_t count" 208.Fc 209.Ft void 210.Fo bhnd_bus_write_multi_stream_4 211.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" 212.Fa "bus_size_t count" 213.Fc 214.Ft void 215.Fo bhnd_bus_write_region_1 216.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" 217.Fa "bus_size_t count" 218.Fc 219.Ft void 220.Fo bhnd_bus_write_region_2 221.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" 222.Fa "bus_size_t count" 223.Fc 224.Ft void 225.Fo bhnd_bus_write_region_4 226.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" 227.Fa "bus_size_t count" 228.Fc 229.Ft void 230.Fo bhnd_bus_write_region_stream_1 231.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" 232.Fa "bus_size_t count" 233.Fc 234.Ft void 235.Fo bhnd_bus_write_region_stream_2 236.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" 237.Fa "bus_size_t count" 238.Fc 239.Ft void 240.Fo bhnd_bus_write_region_stream_4 241.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" 242.Fa "bus_size_t count" 243.Fc 244.Ft void 245.Fn bhnd_bus_write_stream_1 "struct bhnd_resource *r" "uint8_t value" 246.Ft void 247.Fn bhnd_bus_write_stream_2 "struct bhnd_resource *r" "uint16_t value" 248.Ft void 249.Fn bhnd_bus_write_stream_4 "struct bhnd_resource *r" "uint32_t value" 250.\" 251.Ss "Device Configuration Functions" 252.Ft int 253.Fn bhnd_read_ioctl "device_t dev" "uint16_t *ioctl" 254.Ft int 255.Fn bhnd_write_ioctl "device_t dev" "uint16_t value" "uint16_t mask" 256.Ft int 257.Fn bhnd_read_iost "device_t dev" "uint16_t *iost" 258.Ft uint32_t 259.Fo bhnd_read_config 260.Fa "device_t dev" "bus_size_t offset" "void *value" "u_int width" 261.Fc 262.Ft int 263.Fo bhnd_write_config 264.Fa "device_t dev" "bus_size_t offset" "const void *value" "u_int width" 265.Fc 266.Ft int 267.Fn bhnd_reset_hw "device_t dev" "uint16_t ioctl" "uint16_t reset_ioctl" 268.Ft int 269.Fn bhnd_suspend_hw "device_t dev" "uint16_t ioctl" 270.Ft bool 271.Fn bhnd_is_hw_suspended "device_t dev" 272.\" 273.Ss "Device Information Functions" 274.Ft bhnd_attach_type 275.Fo bhnd_get_attach_type 276.Fa "device_t dev" 277.Fc 278.Ft "const struct bhnd_chipid *" 279.Fo bhnd_get_chipid 280.Fa "device_t dev" 281.Fc 282.Ft bhnd_devclass_t 283.Fo bhnd_get_class 284.Fa "device_t dev" 285.Fc 286.Ft u_int 287.Fo bhnd_get_core_index 288.Fa "device_t dev" 289.Fc 290.Ft "struct bhnd_core_info" 291.Fo bhnd_get_core_info 292.Fa "device_t dev" 293.Fc 294.Ft int 295.Fo bhnd_get_core_unit 296.Fa "device_t dev" 297.Fc 298.Ft uint16_t 299.Fo bhnd_get_device 300.Fa "device_t dev" 301.Fc 302.Ft const char * 303.Fo bhnd_get_device_name 304.Fa "device_t dev" 305.Fc 306.Ft uint8_t 307.Fo bhnd_get_hwrev 308.Fa "device_t dev" 309.Fc 310.Ft uint16_t 311.Fo bhnd_get_vendor 312.Fa "device_t dev" 313.Fc 314.Ft const char * 315.Fo bhnd_get_vendor_name 316.Fa "device_t dev" 317.Fc 318.Ft int 319.Fo bhnd_read_board_info 320.Fa "device_t dev" "struct bhnd_board_info *info" 321.Fc 322.\" 323.Ss "Device Matching Functions" 324.Ft bool 325.Fo bhnd_board_matches 326.Fa "const struct bhnd_board_info *board" "const struct bhnd_board_match *desc" 327.Fc 328.Ft device_t 329.Fo bhnd_bus_match_child 330.Fa "device_t bus" "const struct bhnd_core_match *desc" 331.Fc 332.Ft bool 333.Fo bhnd_chip_matches 334.Fa "const struct bhnd_chipid *chip" "const struct bhnd_chip_match *desc" 335.Fc 336.Ft "struct bhnd_core_match" 337.Fo bhnd_core_get_match_desc 338.Fa "const struct bhnd_core_info *core" 339.Fc 340.Ft bool 341.Fo bhnd_core_matches 342.Fa "const struct bhnd_core_info *core" "const struct bhnd_core_match *desc" 343.Fc 344.Ft bool 345.Fo bhnd_cores_equal 346.Fa "const struct bhnd_core_info *lhs" "const struct bhnd_core_info *rhs" 347.Fc 348.Ft bool 349.Fo bhnd_hwrev_matches 350.Fa "uint16_t hwrev" "const struct bhnd_hwrev_match *desc" 351.Fc 352.Ft "const struct bhnd_core_info *" 353.Fo bhnd_match_core 354.Fa "const struct bhnd_core_info *cores" "u_int num_cores" 355.Fa "const struct bhnd_core_match *desc" 356.Fc 357.\" 358.Ss "Device Table Functions" 359.Ft "const struct bhnd_device *" 360.Fo bhnd_device_lookup 361.Fa "device_t dev" "const struct bhnd_device *table" "size_t entry_size" 362.Fc 363.Ft bool 364.Fo bhnd_device_matches 365.Fa "device_t dev" "const struct bhnd_device_match *desc" 366.Fc 367.Ft uint32_t 368.Fo bhnd_device_quirks 369.Fa "device_t dev" "const struct bhnd_device *table" "size_t entry_size" 370.Fc 371.Fo BHND_BOARD_QUIRK 372.Fa "board" "flags" 373.Fc 374.Fo BHND_CHIP_QUIRK 375.Fa "chip" "hwrev" "flags" 376.Fc 377.Fo BHND_CORE_QUIRK 378.Fa "hwrev" "flags" 379.Fc 380.Fo BHND_DEVICE 381.Fa "vendor" "device" "desc" "quirks" "..." 382.Fc 383.Fo BHND_DEVICE_IS_END 384.Fa "struct bhnd_device *d" 385.Fc 386.Fo BHND_DEVICE_QUIRK_IS_END 387.Fa "struct bhnd_device_quirk *q" 388.Fc 389.Fo BHND_PKG_QUIRK 390.Fa "chip" "pkg" "flags" 391.Fc 392.Bd -literal 393struct bhnd_device_quirk { 394 struct bhnd_device_match desc; 395 uint32_t quirks; 396}; 397.Ed 398.Bd -literal 399struct bhnd_device { 400 const struct bhnd_device_match core; 401 const char *desc; 402 const struct bhnd_device_quirk *quirks_table; 403 uint32_t device_flags; 404}; 405.Ed 406.Bd -literal 407enum { 408 BHND_DF_ANY = 0, 409 BHND_DF_HOSTB = (1 << 0), 410 BHND_DF_SOC = (1 << 1), 411 BHND_DF_ADAPTER = (1 << 2) 412}; 413.Ed 414.Bd -literal 415#define BHND_DEVICE_END { { BHND_MATCH_ANY }, NULL, NULL, 0 } 416.Ed 417.Bd -literal 418#define BHND_DEVICE_QUIRK_END { { BHND_MATCH_ANY }, 0 } 419.Ed 420.\" 421.Ss "DMA Address Translation Functions" 422.Ft int 423.Fo bhnd_get_dma_translation 424.Fa "device_t dev" "u_int width" "uint32_t flags" "bus_dma_tag_t *dmat" 425.Fa "struct bhnd_dma_translation *translation" 426.Fc 427.Bd -literal 428struct bhnd_dma_translation { 429 bhnd_addr_t base_addr; 430 bhnd_addr_t addr_mask; 431 bhnd_addr_t addrext_mask; 432 uint32_t flags; 433}; 434.Ed 435.Bd -literal 436typedef enum { 437 BHND_DMA_ADDR_30BIT = 30, 438 BHND_DMA_ADDR_32BIT = 32, 439 BHND_DMA_ADDR_64BIT = 64 440} bhnd_dma_addrwidth; 441.Ed 442.Bd -literal 443enum bhnd_dma_translation_flags { 444 BHND_DMA_TRANSLATION_PHYSMAP = (1<<0), 445 BHND_DMA_TRANSLATION_BYTESWAPPED = (1<<1) 446}; 447.Ed 448.\" 449.Ss "Interrupt Functions" 450.Ft u_int 451.Fo bhnd_get_intr_count 452.Fa "device_t dev" 453.Fc 454.Ft int 455.Fo bhnd_get_intr_ivec 456.Fa "device_t dev" "u_int intr" "u_int *ivec" 457.Fc 458.Ft int 459.Fo bhnd_map_intr 460.Fa "device_t dev" "u_int intr" "rman_res_t *irq" 461.Fc 462.Ft void 463.Fo bhnd_unmap_intr 464.Fa "device_t dev" "rman_res_t irq" 465.Fc 466.\" 467.Ss "NVRAM Functions" 468.Ft int 469.Fo bhnd_nvram_getvar 470.Fa "device_t dev" "const char *name" "void *buf" "size_t *len" 471.Fa "bhnd_nvram_type type" 472.Fc 473.Ft int 474.Fo bhnd_nvram_getvar_array 475.Fa "device_t dev" "const char *name" "void *buf" "size_t size" 476.Fa "bhnd_nvram_type type" 477.Fc 478.Ft int 479.Fo bhnd_nvram_getvar_int 480.Fa "device_t dev" "const char *name" "void *value" "int width" 481.Fc 482.Ft int 483.Fn bhnd_nvram_getvar_int8 "device_t dev" "const char *name" "int8_t *value" 484.Ft int 485.Fn bhnd_nvram_getvar_int16 "device_t dev" "const char *name" "int16_t *value" 486.Ft int 487.Fn bhnd_nvram_getvar_int32 "device_t dev" "const char *name" "int32_t *value" 488.Ft int 489.Fo bhnd_nvram_getvar_uint 490.Fa "device_t dev" "const char *name" "void *value" "int width" 491.Fc 492.Ft int 493.Fo bhnd_nvram_getvar_uint8 494.Fa "device_t dev" "const char *name" "uint8_t *value" 495.Fc 496.Ft int 497.Fo bhnd_nvram_getvar_uint16 498.Fa "device_t dev" "const char *name" "uint16_t *value" 499.Fc 500.Ft int 501.Fo bhnd_nvram_getvar_uint32 502.Fa "device_t dev" "const char *name" "uint32_t *value" 503.Fc 504.Ft int 505.Fo bhnd_nvram_getvar_str 506.Fa "device_t dev" "const char *name" "char *buf" "size_t len" "size_t *rlen" 507.Fc 508.Ft "const char *" 509.Fo bhnd_nvram_string_array_next 510.Fa "const char *inp" "size_t ilen" "const char *prev" "size_t *olen" 511.Fc 512.Bd -literal 513typedef enum { 514 BHND_NVRAM_TYPE_UINT8 = 0, 515 BHND_NVRAM_TYPE_UINT16 = 1, 516 BHND_NVRAM_TYPE_UINT32 = 2, 517 BHND_NVRAM_TYPE_UINT64 = 3, 518 BHND_NVRAM_TYPE_INT8 = 4, 519 BHND_NVRAM_TYPE_INT16 = 5, 520 BHND_NVRAM_TYPE_INT32 = 6, 521 BHND_NVRAM_TYPE_INT64 = 7, 522 BHND_NVRAM_TYPE_CHAR = 8, 523 BHND_NVRAM_TYPE_STRING = 9, 524 BHND_NVRAM_TYPE_BOOL = 10, 525 BHND_NVRAM_TYPE_NULL = 11, 526 BHND_NVRAM_TYPE_DATA = 12 527 BHND_NVRAM_TYPE_UINT8_ARRAY = 16, 528 BHND_NVRAM_TYPE_UINT16_ARRAY = 17, 529 BHND_NVRAM_TYPE_UINT32_ARRAY = 18, 530 BHND_NVRAM_TYPE_UINT64_ARRAY = 19, 531 BHND_NVRAM_TYPE_INT8_ARRAY = 20, 532 BHND_NVRAM_TYPE_INT16_ARRAY = 21, 533 BHND_NVRAM_TYPE_INT32_ARRAY = 22, 534 BHND_NVRAM_TYPE_INT64_ARRAY = 23, 535 BHND_NVRAM_TYPE_CHAR_ARRAY = 24, 536 BHND_NVRAM_TYPE_STRING_ARRAY = 25, 537 BHND_NVRAM_TYPE_BOOL_ARRAY = 26 538} bhnd_nvram_type; 539.Ed 540.\" 541.Ss "Port/Region Functions" 542.Ft int 543.Fo bhnd_decode_port_rid 544.Fa "device_t dev" "int type" "int rid" "bhnd_port_type *port_type" 545.Fa "u_int *port" "u_int *region" 546.Fc 547.Ft u_int 548.Fo bhnd_get_port_count 549.Fa "device_t dev" "bhnd_port_type type" 550.Fc 551.Ft int 552.Fo bhnd_get_port_rid 553.Fa "device_t dev" "bhnd_port_type type" "u_int port" "u_int region" 554.Fc 555.Ft int 556.Fo bhnd_get_region_addr 557.Fa "device_t dev" "bhnd_port_type port_type" "u_int port" "u_int region" 558.Fa "bhnd_addr_t *region_addr" "bhnd_size_t *region_size" 559.Fc 560.Ft u_int 561.Fo bhnd_get_region_count 562.Fa "device_t dev" "bhnd_port_type type" "u_int port" 563.Fc 564.Ft bool 565.Fo bhnd_is_region_valid 566.Fa "device_t dev" "bhnd_port_type type" "u_int port" "u_int region" 567.Fc 568.Bd -literal 569typedef enum { 570 BHND_PORT_DEVICE = 0, 571 BHND_PORT_BRIDGE = 1, 572 BHND_PORT_AGENT = 2 573} bhnd_port_type; 574.Ed 575.\" 576.Ss "Power Management Functions" 577.Ft int 578.Fo bhnd_alloc_pmu 579.Fa "device_t dev" 580.Fc 581.Ft int 582.Fo bhnd_release_pmu 583.Fa "device_t dev" 584.Fc 585.Ft int 586.Fo bhnd_enable_clocks 587.Fa "device_t dev" "uint32_t clocks" 588.Fc 589.Ft int 590.Fo bhnd_request_clock 591.Fa "device_t dev" "bhnd_clock clock" 592.Fc 593.Ft int 594.Fo bhnd_get_clock_freq 595.Fa "device_t dev" "bhnd_clock clock" "u_int *freq" 596.Fc 597.Ft int 598.Fo bhnd_get_clock_latency 599.Fa "device_t dev" "bhnd_clock clock" "u_int *latency" 600.Fc 601.Ft int 602.Fo bhnd_request_ext_rsrc 603.Fa "device_t dev" "u_int rsrc" 604.Fc 605.Ft int 606.Fo bhnd_release_ext_rsrc 607.Fa "device_t dev" "u_int rsrc" 608.Fc 609.Bd -literal 610typedef enum { 611 BHND_CLOCK_DYN = (1 << 0), 612 BHND_CLOCK_ILP = (1 << 1), 613 BHND_CLOCK_ALP = (1 << 2), 614 BHND_CLOCK_HT = (1 << 3) 615} bhnd_clock; 616.Ed 617.\" 618.Ss "Service Provider Functions" 619.Ft int 620.Fo bhnd_register_provider 621.Fa "device_t dev" "bhnd_service_t service" 622.Fc 623.Ft int 624.Fo bhnd_deregister_provider 625.Fa "device_t dev" "bhnd_service_t service" 626.Fc 627.Ft device_t 628.Fo bhnd_retain_provider 629.Fa "device_t dev" "bhnd_service_t service" 630.Fc 631.Ft void 632.Fo bhnd_release_provider 633.Fa "device_t dev" "device_t provider" "bhnd_service_t service" 634.Fc 635.Bd -literal 636typedef enum { 637 BHND_SERVICE_CHIPC, 638 BHND_SERVICE_PWRCTL, 639 BHND_SERVICE_PMU, 640 BHND_SERVICE_NVRAM, 641 BHND_SERVICE_GPIO, 642 BHND_SERVICE_ANY = 1000 643} bhnd_service_t; 644.Ed 645.\" 646.Ss "Utility Functions" 647.Ft "bhnd_erom_class_t *" 648.Fo bhnd_driver_get_erom_class 649.Fa "driver_t *driver" 650.Fc 651.Ft bhnd_devclass_t 652.Fo bhnd_find_core_class 653.Fa "uint16_t vendor" "uint16_t device" 654.Fc 655.Ft "const char *" 656.Fo bhnd_find_core_name 657.Fa "uint16_t vendor" "uint16_t device" 658.Fc 659.Ft bhnd_devclass_t 660.Fo bhnd_core_class 661.Fa "const struct bhnd_core_info *ci" 662.Fc 663.Ft "const char *" 664.Fo bhnd_core_name 665.Fa "const struct bhnd_core_info *ci" 666.Fc 667.Ft int 668.Fo bhnd_format_chip_id 669.Fa "char *buffer" "size_t size" "uint16_t chip_id" 670.Fc 671.Ft void 672.Fo bhnd_set_custom_core_desc 673.Fa "device_t dev" "const char *dev_name" 674.Fc 675.Ft void 676.Fo bhnd_set_default_core_desc 677.Fa "device_t dev" 678.Fc 679.Ft "const char *" 680.Fo bhnd_vendor_name 681.Fa "uint16_t vendor" 682.Fc 683.Bd -literal 684#define BHND_CHIPID_MAX_NAMELEN 32 685.Ed 686.\" 687.Sh DESCRIPTION 688.Nm 689provides a unified bus and driver programming interface for the 690on-chip interconnects and IP cores found in Broadcom Home Networking Division 691(BHND) devices. 692.Pp 693The BHND device family consists of MIPS/ARM SoCs (System On a Chip) and 694host-connected chipsets based on a common library of Broadcom IP cores, 695connected via one of two on-chip backplane (hardware bus) architectures. 696.Pp 697Hardware designed prior to 2009 used Broadcom's 698.Dq SSB 699backplane architecture, based on Sonics Silicon's interconnect IP. 700Each core on the Sonics backplane vends a 4 KiB register block, containing both 701device-specific CSRs, and SSB-specific per-core device management 702(enable/reset/etc) registers. 703.Pp 704Subsequent hardware is based on Broadcom's 705.Dq BCMA 706backplane, based on ARM's AMBA IP. 707The IP cores used in earlier SSB-based devices were adapted for compatibility 708with the new backplane, with additional 709.Dq wrapper 710cores providing per-core device management functions in place of the SSB 711per-core management registers. 712.Pp 713When BHND hardware is used as a host-connected peripheral (e.g., in a PCI Wi-Fi 714card), the on-chip peripheral controller core is configured to operate as 715an endpoint device, bridging access to the SoC hardware: 716.Bl -dash -offset indent 717.It 718Host access to SoC address space is provided via a set of register windows 719(e.g., a set of configurable windows into SoC address space mapped via PCI BARs) 720.It 721DMA is supported by the bridge core's sparse mapping of host address space into 722the backplane address space. 723These address regions may be used as a target for the on-chip DMA engine. 724.It 725Any backplane interrupt vectors routed to the bridge core may be mapped by the 726bridge to host interrupts (e.g., PCI INTx/MSI/MSI-X). 727.El 728.Pp 729The 730.Nm 731driver programming interface \(em and 732.Xr bhndb 4 733host bridge drivers \(em support the implementation of common drivers for 734Broadcom IP cores, whether attached via a BHND host bridge, or via the native 735SoC backplane. 736.\" 737.Ss "Bus Resource Functions" 738The bhnd_resource functions are wrappers for the standard 739.Vt "struct resource" 740bus APIs, providing support for 741.Vt SYS_RES_MEMORY 742resources that, on 743.Xr bhndb 4 744bridged chipsets, may require on-demand remapping of address windows 745prior to accessing bus memory. 746.Pp 747These functions are primarily used in the implementation of BHND platform device 748drivers that, on host-connected peripherals, must share a small set of register 749windows during initial setup and teardown. 750.Pp 751BHND peripherals are designed to not require register window remapping 752during normal operation, and most drivers may safely use the standard 753.Vt struct resource 754APIs directly. 755.Pp 756The 757.Fn bhnd_activate_resource 758function activates a previously allocated resource. 759.Pp 760The arguments are as follows: 761.Bl -tag -width indent 762.It Fa dev 763The device holding ownership of the allocated resource. 764.It Fa type 765The type of the resource. 766.It Fa rid 767The bus-specific handle that identifies the resource being activated. 768.It Fa r 769A pointer to the resource returned by 770.Fn bhnd_alloc_resource . 771.El 772.Pp 773The 774.Fn bhnd_alloc_resource 775function allocates a resource from a device's parent 776.Xr bhnd 4 777bus. 778.Pp 779The arguments are as follows: 780.Bl -tag -width indent 781.It Fa dev 782The device requesting resource ownership. 783.It Fa type 784The type of resource to allocate. 785This may be any type supported by the standard 786.Xr bus_alloc_resource 9 787function. 788.It Fa rid 789The bus-specific handle identifying the resource being allocated. 790.It Fa start 791The start address of the resource. 792.It Fa end 793The end address of the resource. 794.It Fa count 795The size of the resource. 796.It Fa flags 797The flags for the resource to be allocated. 798These may be any values supported by the standard 799.Xr bus_alloc_resource 9 800function. 801.El 802.Pp 803To request that the bus supply the resource's default 804.Fa start , 805.Fa end , 806and 807.Fa count 808values, pass 809.Fa start 810and 811.Fa end 812values of 0ul and ~0ul respectively, and a 813.Fa count 814of 1. 815.Pp 816The 817.Fn bhnd_alloc_resource_any 818function is a convenience wrapper for 819.Fn bhnd_alloc_resource , 820using the resource's default 821.Fa start , 822.Fa end , 823and 824.Fa count 825values. 826.Pp 827The arguments are as follows: 828.Bl -tag -width indent 829.It Fa dev 830The device requesting resource ownership. 831.It Fa type 832The type of resource to allocate. 833This may be any type supported by the standard 834.Xr bus_alloc_resource 9 835function. 836.It Fa rid 837The bus-specific handle identifying the resource being allocated. 838.It Fa flags 839The flags for the resource to be allocated. 840These may be any values supported by the standard 841.Xr bus_alloc_resource 9 842function. 843.El 844.Pp 845The 846.Fn bhnd_alloc_resources 847function allocates resources defined in resource specification from a device's 848parent 849.Xr bhnd 4 850bus. 851.Pp 852The arguments are as follows: 853.Bl -tag -width indent 854.It Fa dev 855The device requesting ownership of the resources. 856.It Fa rs 857A standard bus resource specification. 858If all requested resources, are successfully allocated, 859this will be updated with the allocated resource identifiers. 860.It Fa res 861If all requested resources are successfully allocated, this will be populated 862with the allocated 863.Vt "struct bhnd_resource" 864instances. 865.El 866.Pp 867The 868.Fn bhnd_deactivate_resource 869function deactivates a resource previously activated by. 870.Fn bhnd_activate_resource . 871The arguments are as follows: 872.Bl -tag -width indent 873.It Fa dev 874The device holding ownership of the activated resource. 875.It Fa type 876The type of the resource. 877.It Fa rid 878The bus-specific handle identifying the resource. 879.It Fa r 880A pointer to the resource returned by bhnd_alloc_resource. 881.El 882.Pp 883The 884.Fn bhnd_release_resource 885function frees a resource previously returned by 886.Fn bhnd_alloc_resource . 887The arguments are as follows: 888.Bl -tag -width indent 889.It Fa dev 890The device holding ownership of the resource. 891.It Fa type 892The type of the resource. 893.It Fa rid 894The bus-specific handle identifying the resource. 895.It Fa r 896A pointer to the resource returned by bhnd_alloc_resource. 897.El 898.Pp 899The 900.Fn bhnd_release_resources 901function frees resources previously returned by 902.Fn bhnd_alloc_resources . 903The arguments are as follows: 904.Bl -tag -width indent 905.It Fa dev 906The device that owns the resources. 907.It Fa rs 908A standard bus resource specification previously initialized by 909.Fn bhnd_alloc_resources . 910.It Fa res 911The resources to be released. 912.El 913.Pp 914The 915.Vt bhnd_resource 916structure contains the following fields: 917.Bl -tag -width "direct" 918.It Fa res 919A pointer to the bus 920.Vt struct resource . 921.It Fa direct 922If true, the resource requires bus window remapping before it is MMIO 923accessible. 924.El 925.\" 926.Ss "Bus Space Functions" 927The bhnd_bus_space functions wrap their equivalent 928.Xr bus_space 9 929counterparts, and provide support for accessing bus memory via 930.Vt "struct bhnd_resource". 931.Pp 932.Bl -ohang -offset indent -compact 933.It Fn bhnd_bus_barrier 934.It Fn bhnd_bus_[read|write]_[1|2|4] 935.It Fn bhnd_bus_[read_multi|write_multi]_[1|2|4] 936.It Fn bhnd_bus_[read_multi_stream|write_multi_stream]_[1|2|4] 937.It Fn bhnd_bus_[read_region|write_region]_[1|2|4] 938.It Fn bhnd_bus_[read_region_stream|write_region_stream]_[1|2|4] 939.It Fn bhnd_bus_[read_stream|write_stream]_[1|2|4] 940.It Fn bhnd_bus_[set_multi|set_stream]_[1|2|4] 941.El 942.Pp 943Drivers that do not rely on 944.Vt "struct bhnd_resource" 945should use the standard 946.Vt struct resource 947and 948.Xr bus_space 9 949APIs directly. 950.\" 951.Ss "Device Configuration Functions" 952The 953.Fn bhnd_read_ioctl 954function is used to read the I/O control register value of device 955.Fa dev , 956returning the current value in 957.Fa ioctl . 958.Pp 959The 960.Fn bhnd_write_ioctl 961function is used to modify the I/O control register of 962.Fa dev . 963The new value of the register is computed by updating any bits set in 964.Fa mask 965to 966.Fa value . 967The following I/O control flags are supported: 968.Bl -tag -width ".Dv BHND_IOCTL_CLK_FORCE" -offset indent 969.It Dv BHND_IOCTL_BIST 970Initiate a built-in self-test (BIST). 971Must be cleared after BIST results are read via the IOST (I/O Status) register. 972.It Dv BHND_IOCTL_PME 973Enable posting of power management events by the core. 974.It Dv BHND_IOCTL_CLK_FORCE 975Force disable of clock gating, resulting in all clocks being distributed within 976the core. 977Should be set when asserting/deasserting reset to ensure the reset signal fully 978propagates to the entire core. 979.It Dv BHND_IOCTL_CLK_EN 980If cleared, the core clock will be disabled. 981Should be set during normal operation, and cleared when the core is held in 982reset. 983.It Dv BHND_IOCTL_CFLAGS 984The mask of IOCTL bits reserved for additional core-specific I/O control flags. 985.El 986.Pp 987The 988.Fn bhnd_read_iost 989function is used to read the I/O status register of device 990.Fa dev , 991returning the current value in 992.Fa iost . 993The following I/O status flags are supported: 994.Bl -tag -width ".Dv BHND_IOST_BIST_DONE" -offset indent 995.It Dv BHND_IOST_BIST_DONE 996Set upon BIST completion. 997Will be cleared when the 998.Dv BHND_IOCTL_BIST 999flag of the I/O control register is cleared using 1000.Fn bhnd_write_ioctl . 1001.It Dv BHND_IOST_BIST_FAIL 1002Set upon detection of a BIST error; the value is unspecified if BIST has not 1003completed and 1004.Dv BHND_IOST_BIST_DONE 1005is not also set. 1006.It Dv BHND_IOST_CLK 1007Set if the core has required that clocked be ungated, or cleared otherwise. 1008The value is undefined if a core does not support clock gating. 1009.It Dv BHND_IOST_DMA64 1010Set if this core supports 64-bit DMA. 1011.It Dv BHND_IOST_CFLAGS 1012The mask of IOST bits reserved for additional core-specific I/O status flags. 1013.El 1014.Pp 1015The 1016.Fn bhnd_read_config 1017function is used to read a data item of 1018.Fa width 1019bytes at 1020.Fa offset 1021from the backplane-specific agent/config space of the device 1022.Fa dev . 1023.Pp 1024The 1025.Fn bhnd_write_config 1026function is used to write a data item of 1027.Fa width 1028bytes with 1029.Fa value 1030at 1031.Fa offset 1032from the backplane-specific agent/config space of the device 1033.Fa dev . 1034The requested 1035.Fa width 1036must be one of 1, 2, or 4 bytes. 1037.Pp 1038The agent/config space accessible via 1039.Fn bhnd_read_config 1040and 1041.Fn bhnd_write_config 1042is backplane-specific, and these functions should only be used for functionality 1043that is not available via another 1044.Nm 1045function. 1046.Pp 1047The 1048.Fn bhnd_suspend_hw 1049function transitions the device 1050.Fa dev 1051to a low power 1052.Dq RESET 1053state, writing 1054.Fa ioctl 1055to the I/O control flags of 1056.Fa dev . 1057The hardware may be brought out of this state using 1058.Fn bhnd_reset_hw . 1059.Pp 1060The 1061.Fn bhnd_reset_hw 1062function first transitions the device 1063.Fa dev 1064to a low power RESET state, writing 1065.Fa ioctl_reset 1066to the I/O control flags 1067of 1068.Fa dev , 1069and then brings the device out of RESET, writing 1070.Fa ioctl 1071to the device's I/O control flags. 1072.Pp 1073The 1074.Fn bhnd_is_hw_suspended 1075function returns 1076.Dv true 1077if the device 1078.Fa dev 1079is currently held in a RESET state, or is otherwise not clocked. 1080Otherwise, it returns 1081.Dv false . 1082.Pp 1083Any outstanding per-device PMU requests made using 1084.Fn bhnd_enable_clocks , 1085.Fn bhnd_request_clock , 1086or 1087.Fn bhnd_request_ext_rsrc 1088will be released automatically upon placing a device into a RESET state. 1089.Ss "Device Information Functions" 1090The 1091.Fn bhnd_get_attach_type 1092function returns the attachment type of the parent 1093.Xr bhnd 4 1094bus of device 1095.Fa dev . 1096.Pp 1097The following attachment types are supported: 1098.Bl -hang -width ".Dv BHND_ATTACH_ADAPTER" -offset indent 1099.It Dv BHND_ATTACH_ADAPTER 1100The bus is resident on a bridged adapter, such as a PCI Wi-Fi device. 1101.It Dv BHND_ATTACH_NATIVE 1102The bus is resident on the native host, such as the primary or secondary bus of 1103an embedded SoC. 1104.El 1105.Pp 1106The 1107.Fn bhnd_get_chipid 1108function returns chip information from the parent 1109.Xr bhnd 4 1110bus of device 1111.Fa dev . 1112The returned 1113.Vt bhnd_chipid 1114struct contains the following fields: 1115.Bl -tag -width "enum_addr" -offset indent 1116.It Fa chip_id 1117The chip identifier. 1118.It Fa chip_rev 1119The chip's hardware revision. 1120.It Fa chip_pkg 1121The chip's semiconductor package identifier. 1122.Pp 1123Several different physical semiconductor package variants may exist for a given 1124chip, each of which may require driver workarounds for hardware errata, 1125unpopulated components, etc. 1126.It Fa chip_type 1127The interconnect architecture used by this chip. 1128.It Fa chip_caps 1129The 1130.Nm 1131capability flags supported by this chip. 1132.It Fa enum_addr 1133The backplane enumeration address. 1134On SSB devices, this will be the base address of the first SSB core. 1135On BCMA devices, this will be the address of the enumeration ROM (EROM) core. 1136.It Fa ncores 1137The number of cores on the chip backplane, or 0 if unknown. 1138.El 1139.Pp 1140The following constants are defined for known 1141.Fa chip_type 1142values: 1143.Bl -tag -width ".Dv BHND_CHIPTYPE_BCMA_ALT" -offset indent -compact 1144.It Dv BHND_CHIPTYPE_SIBA 1145SSB interconnect. 1146.It Dv BHND_CHIPTYPE_BCMA 1147BCMA interconnect. 1148.It Dv BHND_CHIPTYPE_BCMA_ALT 1149BCMA-compatible variant found in Broadcom Northstar ARM SoCs. 1150.It Dv BHND_CHIPTYPE_UBUS 1151UBUS interconnect. 1152This BCMA-derived interconnect is found in Broadcom BCM33xx DOCSIS SoCs, and 1153BCM63xx xDSL SoCs. 1154UBUS is not currently supported by 1155.Xr bhnd 4 . 1156.El 1157.Pp 1158The following 1159.Fa chip_caps 1160flags are supported: 1161.Bl -tag -width ".Dv BHND_CAP_BP64" -offset indent -compact 1162.It Dv BHND_CAP_BP64 1163The backplane supports 64-bit addressing. 1164.It Dv BHND_CAP_PMU 1165PMU is present. 1166.El 1167.Pp 1168Additional symbolic constants for known 1169.Fa chip_id , 1170.Fa chip_pkg , 1171and 1172.Fa chip_type 1173values are defined in 1174.In dev/bhnd/bhnd_ids.h . 1175.Pp 1176The 1177.Fn bhnd_get_class 1178function returns the BHND class of device 1179.Fa dev , 1180if the device's 1181.Em vendor 1182and 1183.Em device 1184identifiers are recognized. 1185Otherwise, returns 1186.Dv BHND_DEVCLASS_OTHER . 1187.Pp 1188One of the following device classes will be returned: 1189.Pp 1190.Bl -tag -width ".Dv BHND_DEVCLASS_SOC_ROUTER" -offset indent -compact 1191.It Dv BHND_DEVCLASS_CC 1192ChipCommon I/O Controller 1193.It Dv BHND_DEVCLASS_CC_B 1194ChipCommon Auxiliary Controller 1195.It Dv BHND_DEVCLASS_PMU 1196PMU Controller 1197.It Dv BHND_DEVCLASS_PCI 1198PCI Host/Device Bridge 1199.It Dv BHND_DEVCLASS_PCIE 1200PCIe Host/Device Bridge 1201.It Dv BHND_DEVCLASS_PCCARD 1202PCMCIA Host/Device Bridge 1203.It Dv BHND_DEVCLASS_RAM 1204Internal RAM/SRAM 1205.It Dv BHND_DEVCLASS_MEMC 1206Memory Controller 1207.It Dv BHND_DEVCLASS_ENET 1208IEEE 802.3 MAC/PHY 1209.It Dv BHND_DEVCLASS_ENET_MAC 1210IEEE 802.3 MAC 1211.It Dv BHND_DEVCLASS_ENET_PHY 1212IEEE 802.3 PHY 1213.It Dv BHND_DEVCLASS_WLAN 1214IEEE 802.11 MAC/PHY/Radio 1215.It Dv BHND_DEVCLASS_WLAN_MAC 1216IEEE 802.11 MAC 1217.It Dv BHND_DEVCLASS_WLAN_PHY 1218IEEE 802.11 PHY 1219.It Dv BHND_DEVCLASS_CPU 1220CPU Core 1221.It Dv BHND_DEVCLASS_SOC_ROUTER 1222Interconnect Router 1223.It Dv BHND_DEVCLASS_SOC_BRIDGE 1224Interconnect Host Bridge 1225.It Dv BHND_DEVCLASS_EROM 1226Device Enumeration ROM 1227.It Dv BHND_DEVCLASS_NVRAM 1228NVRAM/Flash Controller 1229.It Dv BHND_DEVCLASS_SOFTMODEM 1230Analog/PSTN SoftModem Codec 1231.It Dv BHND_DEVCLASS_USB_HOST 1232USB Host Controller 1233.It Dv BHND_DEVCLASS_USB_DEV 1234USB Device Controller 1235.It Dv BHND_DEVCLASS_USB_DUAL 1236USB Host/Device Controller 1237.It Dv BHND_DEVCLASS_OTHER 1238Other / Unknown 1239.It Dv BHND_DEVCLASS_INVALID 1240Invalid Class 1241.El 1242.Pp 1243The 1244.Fn bhnd_get_core_info 1245function returns the core information for device 1246.Fa dev . 1247The returned 1248.Vt bhnd_core_info 1249structure contains the following fields: 1250.Pp 1251.Bl -tag -width "core_idx" -offset indent -compact 1252.It Fa vendor 1253Vendor identifier (JEP-106, ARM 4-bit continuation encoded) 1254.It Fa device 1255Device identifier 1256.It Fa hwrev 1257Hardware revision 1258.It Fa core_idx 1259Core index 1260.It Fa unit 1261Core unit 1262.El 1263.Pp 1264Symbolic constants for common vendor and device identifiers are defined in 1265.In dev/bhnd/bhnd_ids.h . 1266Common vendor identifiers include: 1267.Pp 1268.Bl -tag -width ".Dv BHND_MFGID_MIPS" -offset indent -compact 1269.It Dv BHND_MFGID_ARM 1270ARM 1271.It Dv BHND_MFGID_BCM 1272Broadcom 1273.It Dv BHND_MFGID_MIPS 1274MIPS 1275.El 1276.Pp 1277The 1278.Fn bhnd_get_core_index , 1279.Fn bhnd_get_core_unit , 1280.Fn bhnd_get_device , 1281.Fn bhnd_get_hwrev , 1282and 1283.Fn bhnd_get_vendor 1284functions are convenience wrappers for 1285.Fn bhnd_get_core_info , 1286returning, respect the 1287.Fa core_idx , 1288.Fa core_unit , 1289.Fa device , 1290.Fa hwrev , 1291or 1292.Fa vendor 1293field from the 1294.Vt bhnd_core_info 1295structure. 1296.Pp 1297The 1298.Fn bhnd_get_device_name 1299function returns a human readable name for device 1300.Fa dev . 1301.Pp 1302The 1303.Fn bhnd_get_vendor_name 1304function returns a human readable name for the vendor of device 1305.Fa dev . 1306.Pp 1307The 1308.Fn bhnd_read_board_info 1309function attempts to read the board information for device 1310.Fa dev . 1311The board information will be returned in the location pointed to by 1312.Fa info 1313on success. 1314.Pp 1315The 1316.Vt bhnd_board_info 1317structure contains the following fields: 1318.Bl -tag -width "board_srom_rev" -offset indent 1319.It Fa board_vendor 1320Vendor ID of the board manufacturer (PCI-SIG assigned). 1321.It Fa board_type 1322Board ID. 1323.It Fa board_devid 1324Device ID. 1325.It Fa board_rev 1326Board revision. 1327.It Fa board_srom_rev 1328Board SROM format revision. 1329.It Fa board_flags 1330Board flags (1) 1331.It Fa board_flags2 1332Board flags (2) 1333.It Fa board_flags3 1334Board flags (3) 1335.El 1336.Pp 1337The 1338.Fa board_devid 1339field is the Broadcom PCI device ID that most closely matches the 1340capabilities of the BHND device (if any). 1341.Pp 1342On PCI devices, the 1343.Fa board_vendor , 1344.Fa board_type , 1345and 1346.Fa board_devid 1347fields default to the PCI Subsystem Vendor ID, PCI Subsystem ID, and PCI 1348device ID, unless overridden in device NVRAM. 1349.Pp 1350On other devices, including SoCs, the 1351.Fa board_vendor , 1352.Fa board_type , 1353and 1354.Fa board_devid 1355fields will be populated from device NVRAM. 1356.Pp 1357Symbolic constants for common board flags are defined in 1358.In dev/bhnd/bhnd_ids.h . 1359.Ss "Device Matching Functions" 1360The bhnd device matching functions are used to match against core, chip, and 1361board-level device attributes. 1362Match requirements are specified using the 1363.Vt "struct bhnd_board_match" , 1364.Vt "struct bhnd_chip_match" , 1365.Vt "struct bhnd_core_match" , 1366.Vt "struct bhnd_device_match" , 1367and 1368.Vt "struct bhnd_hwrev_match" 1369match descriptor structures. 1370.Pp 1371The 1372.Fn bhnd_board_matches 1373function returns 1374.Dv true 1375if 1376.Fa board 1377matches the board match descriptor 1378.Fa desc . 1379Otherwise, it returns 1380.Dv false . 1381.Pp 1382The 1383.Fn bhnd_chip_matches 1384function returns 1385.Dv true 1386if 1387.Fa chip 1388matches the chip match descriptor 1389.Fa desc . 1390Otherwise, it returns 1391.Dv false . 1392.Pp 1393The 1394.Fn bhnd_core_matches 1395function returns 1396.Dv true 1397if 1398.Fa core 1399matches the core match descriptor 1400.Fa desc . 1401Otherwise, it returns 1402.Dv false . 1403.Pp 1404The 1405.Fn bhnd_device_matches 1406function returns 1407.Dv true 1408if the device 1409.Fa dev 1410matches the device match descriptor 1411.Fa desc . 1412Otherwise, it returns 1413.Dv false . 1414.Pp 1415The 1416.Fn bhnd_hwrev_matches 1417function returns 1418.Dv true 1419if 1420.Fa hwrev 1421matches the hwrev match descriptor 1422.Fa desc . 1423Otherwise, it returns 1424.Dv false . 1425.Pp 1426The 1427.Fn bhnd_bus_match_child 1428function returns the first child device of 1429.Fa bus 1430that matches the device match descriptor 1431.Fa desc . 1432If no matching child is found, 1433.Dv NULL 1434is returned. 1435.Pp 1436The 1437.Fn bhnd_core_get_match_desc 1438function returns an equality match descriptor for the core info in 1439.Fa core . 1440The returned descriptor will match only on core attributes identical to those 1441defined by 1442.Fa core . 1443.Pp 1444The 1445.Fn bhnd_cores_equal 1446function is a convenience wrapper for 1447.Fn bhnd_core_matches 1448and 1449.Fn bhnd_core_get_match_desc . 1450This function returns 1451.Dv true 1452if the 1453.Vt bhnd_core_info 1454structures 1455.Fa lhs 1456and 1457.Fa rhs 1458are equal. 1459Otherwise, it returns 1460.Dv false . 1461.Pp 1462The 1463.Fn bhnd_match_core 1464function returns a pointer to the first entry in the array 1465.Fa cores 1466of length 1467.Fa num_cores 1468that matches 1469.Fa desc . 1470If no matching core is found, 1471.Dv NULL 1472is returned. 1473.Pp 1474A 1475.Vt bhnd_board_match 1476match descriptor may be initialized using one or more of the following macros: 1477.Bl -tag -width "Fn BHND_MATCH_BOARD_VENDOR vendor" -offset indent 1478.It Fn BHND_MATCH_BOARD_VENDOR "vendor" 1479Match on boards with a vendor equal to 1480.Fa vendor . 1481.It Fn BHND_MATCH_BOARD_TYPE "type" 1482Match on boards with a type equal to 1483.Dv "BHND_BOARD_ ##" 1484.Fa type 1485.It Fn BHND_MATCH_SROMREV "sromrev" 1486Match on boards with a sromrev that matches 1487.Dv "BHND_HWREV_ ##" 1488.Fa sromrev . 1489.It Fn BHND_MATCH_BOARD_REV "hwrev" 1490Match on boards with hardware revisions that match 1491.Dv "BHND_ ##" 1492.Fa hwrev . 1493.It Fn BHND_MATCH_BOARD "vendor" "type" 1494A convenience wrapper for 1495.Fn BHND_MATCH_BOARD_VENDOR 1496and 1497.Fn BHND_MATCH_BOARD_TYPE . 1498.El 1499.Pp 1500For example: 1501.Bd -literal -offset indent 1502struct bhnd_board_match board_desc = { 1503 BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM), 1504 BHND_MATCH_BOARD_TYPE(BCM94360X52C), 1505 BHND_MATCH_BOARD_REV(HWREV_ANY), 1506 BHND_MATCH_SROMREV(RANGE(0, 10)) 1507}; 1508.Ed 1509.Pp 1510A 1511.Vt bhnd_chip_match 1512match descriptor may be initialized using one or more of the following macros: 1513.Bl -tag -width "Fn BHND_MATCH_CHIP_IPR id pkg hwrev" -offset indent 1514.It Fn BHND_MATCH_CHIP_ID "id" 1515Match on chips with an ID equal to 1516.Dv "BHND_CHIPID_ ##" 1517.Fa id 1518.It Fn BHND_MATCH_CHIP_REV "hwrev" 1519Match on chips with hardware revisions that match 1520.Dv "BHND_ ##" 1521.Fa hwrev . 1522.It Fn BHND_MATCH_CHIP_PKG "pkg" 1523Match on chips with a package ID equal to 1524.Dv "BHND_PKGID_ ##" 1525.Fa pkg 1526.It Fn BHND_MATCH_CHIP_TYPE "type" 1527Match on chips with a chip type equal to 1528.Dv "BHND_CHIPTYPE_ ##" 1529.Fa type 1530.It Fn BHND_MATCH_CHIP_IP "id" "pkg" 1531A convenience wrapper for 1532.Fn BHND_MATCH_CHIP_ID 1533and 1534.Fn BHND_MATCH_CHIP_PKG . 1535.It Fn BHND_MATCH_CHIP_IPR "id" "pkg" "hwrev" 1536A convenience wrapper for 1537.Fn BHND_MATCH_CHIP_ID , 1538.Fn BHND_MATCH_CHIP_PKG , 1539and 1540.Fn BHND_MATCH_CHIP_REV . 1541.It Fn BHND_MATCH_CHIP_IR "id" "hwrev" 1542A convenience wrapper for 1543.Fn BHND_MATCH_CHIP_ID 1544and 1545.Fn BHND_MATCH_CHIP_REV . 1546.El 1547.Pp 1548For example: 1549.Bd -literal -offset indent 1550struct bhnd_chip_match chip_desc = { 1551 BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN), 1552 BHND_MATCH_CHIP_TYPE(SIBA) 1553}; 1554.Ed 1555.Pp 1556A 1557.Vt bhnd_core_match 1558match descriptor may be initialized using one or more of the following macros: 1559.Bl -tag -width "Fn BHND_MATCH_CORE_VENDOR vendor" -offset indent 1560.It Fn BHND_MATCH_CORE_VENDOR "vendor" 1561Match on cores with a vendor ID equal to 1562.Fa vendor 1563.It Fn BHND_MATCH_CORE_ID "id" 1564Match on cores with a device ID equal to 1565.Fa id 1566.It Fn BHND_MATCH_CORE_REV "hwrev" 1567Match on cores with hardware revisions that match 1568.Dv "BHND_ ##" 1569.Fa hwrev . 1570.It Fn BHND_MATCH_CORE_CLASS "class" 1571Match on cores with a core device class equal to 1572.Fa class 1573.It Fn BHND_MATCH_CORE_IDX "idx" 1574Match on cores with a core index equal to 1575.Fa idx 1576.It Fn BHND_MATCH_CORE_UNIT "unit" 1577Match on cores with a core unit equal to 1578.Fa unit 1579.It Fn BHND_MATCH_CORE "vendor" "id" 1580A convenience wrapper for 1581.Fn BHND_MATCH_CORE_VENDOR 1582and 1583.Fn BHND_MATCH_CORE_ID . 1584.El 1585.Pp 1586For example: 1587.Bd -literal -offset indent 1588struct bhnd_core_match core_desc = { 1589 BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC), 1590 BHND_MATCH_CORE_REV(HWREV_RANGE(0, 10)) 1591}; 1592.Ed 1593.Pp 1594The 1595.Vt bhnd_device_match 1596match descriptor supports matching on all board, chip, and core attributes, 1597and may be initialized using any of the 1598.Vt bhnd_board_match , 1599.Vt bhnd_chip_match , 1600or 1601.Vt bhnd_core_match 1602macros. 1603.Pp 1604For example: 1605.Bd -literal -offset indent 1606struct bhnd_device_match device_desc = { 1607 BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN), 1608 BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM), 1609 BHND_MATCH_BOARD_TYPE(BCM94329AGB), 1610 BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC), 1611}; 1612.Ed 1613.Pp 1614A 1615.Vt bhnd_hwrev_match 1616match descriptor may be initialized using one of the following macros: 1617.Pp 1618.Bl -tag -width "Fn BHND_HWREV_RANGE start end" -offset indent -compact 1619.It Dv BHND_HWREV_ANY 1620Matches any hardware revision. 1621.It Fn BHND_HWREV_EQ "hwrev" 1622Matches any hardware revision equal to 1623.Fa hwrev 1624.It Fn BHND_HWREV_GTE "hwrev" 1625Matches any hardware revision greater than or equal to 1626.Fa hwrev 1627.It Fn BHND_HWREV_LTE "hwrev" 1628Matches any hardware revision less than or equal to 1629.Fa hwrev 1630.It Fn BHND_HWREV_RANGE "start" "end" 1631Matches any hardware revision within an inclusive range. 1632If 1633.Dv BHND_HWREV_INVALID 1634is specified as the 1635.Fa end 1636value, will match on any revision equal to or greater than 1637.Fa start 1638.El 1639.\" 1640.Ss "Device Table Functions" 1641The bhnd device table functions are used to query device and 1642quirk tables. 1643.Pp 1644The 1645.Fn bhnd_device_lookup 1646function returns a pointer to the first entry in device table 1647.Fa table 1648that matches the device 1649.Fa dev . 1650The table entry size is specified by 1651.Fa entry_size . 1652.Pp 1653The 1654.Fn bhnd_device_quirks 1655function scan the device table 1656.Fa table 1657for all quirk entries that match the device 1658.Fa dev , 1659returning the bitwise OR of all matching quirk flags. 1660The table entry size is specified by 1661.Fa entry_size . 1662.Pp 1663The 1664.Vt bhnd_device 1665structure contains the following fields: 1666.Bl -tag -width "quirks_table" -offset indent -compact 1667.It Fa core 1668A 1669.Vt bhnd_device_match 1670descriptor. 1671.It Fa desc 1672A verbose device description suitable for use with 1673.Xr device_set_desc 9 , 1674or 1675.Dv NULL . 1676.It Fa quirks_table 1677The quirks table for this device, or 1678.Dv NULL . 1679.It Fa device_flags 1680The device flags required when matching this entry. 1681.El 1682.Pp 1683The following device flags are supported: 1684.Bl -tag -width ".Dv BHND_DF_ADAPTER" -offset indent -compact 1685.It Dv BHND_DF_ANY 1686Match on any device. 1687.It Dv BHND_DF_HOSTB 1688Match only if the device is the 1689.Xr bhndb 4 1690host bridge. 1691Implies 1692.Dv BHND_DF_ADAPTER . 1693.It Dv BHND_DF_SOC 1694Match only if the device is attached to a native SoC backplane. 1695.It Dv BHND_DF_ADAPTER 1696Match only if the device is attached to a 1697.Xr bhndb 4 1698bridged backplane. 1699.El 1700.Pp 1701A 1702.Vt bhnd_device 1703table entry may be initialized using one of the following macros: 1704.Bl -ohang -offset indent 1705.It Fn BHND_DEVICE "vendor" "device" "desc" "quirks" "flags" 1706Match on devices with a vendor ID equal to 1707.Dv BHND_MFGID_ ## 1708.Fa vendor 1709and a core device ID equal to 1710.Dv BHND_COREID_ ## 1711.Fa device . 1712.Pp 1713The device's verbose description is specified by the 1714.Fa desc 1715argument, a pointer to the device-specific quirks table is specified by the 1716.Fa quirks 1717argument, and any required device flags may be provided in 1718.Fa flags . 1719The optional 1720.Fa flags 1721argument defaults to 1722.Dv BHND_DF_ANY 1723if omitted. 1724.It Dv BHND_DEVICE_END 1725Terminate the 1726.Vt bhnd_device 1727table. 1728.El 1729.Pp 1730For example: 1731.Bd -literal -offset indent 1732struct bhnd_device bhnd_usb11_devices[] = { 1733 BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller", 1734 bhnd_usb11_quirks), 1735 BHND_DEVICE_END 1736}; 1737.Ed 1738.Pp 1739The 1740.Vt bhnd_device_quirk 1741structure contains the following fields: 1742.Bl -tag -width "quirks_table" -offset indent -compact 1743.It Fa desc 1744A 1745.Vt bhnd_device_match 1746descriptor. 1747.It Fa quirks 1748Applicable quirk flags. 1749.El 1750.Pp 1751A bhnd_device_quirk table entry may be initialized using one of the following 1752convenience macros: 1753.Bl -tag -width "Fn BHND_CHIP_QUIRK chip hwrev flags" -offset indent 1754.It Fn BHND_BOARD_QUIRK "board" "flags" 1755Set quirk flags 1756.Fa flags 1757on devices with a board type equal to 1758.Dv BHND_BOARD_ ## 1759.Fa board . 1760.It Fn BHND_CHIP_QUIRK "chip" "hwrev" "flags" 1761Set quirk flags 1762.Fa flags 1763on devices with a chip ID equal to 1764.Dv BHND_CHIPID_BCM ## 1765.Fa chip 1766and chip hardware revision that matches 1767.Dv BHND_ ## 1768.Fa hwrev . 1769.It Fn BHND_PKG_QUIRK "chip" "pkg" flags" 1770Set quirk flags 1771.Fa flags 1772on devices with a chip ID equal to 1773.Dv BHND_CHIPID_BCM ## 1774.Fa chip 1775and chip package equal to 1776.Dv BHND_ ## chip ## 1777.Fa pkg . 1778.It Fn BHND_CORE_QUIRK "hwrev" flags" 1779Set quirk flags 1780.Fa flags 1781on devices with a core hardware revision that matches 1782.Dv BHND_ ## 1783.Fa hwrev . 1784.El 1785For example: 1786.Bd -literal -offset indent 1787struct bhnd_device_quirk bhnd_usb11_quirks[] = { 1788 BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller", 1789 bhnd_usb11_quirks), 1790 BHND_DEVICE_END 1791}; 1792.Ed 1793.Ss "DMA Address Translation Functions" 1794The 1795.Fn bhnd_get_dma_translation 1796function is used to request a DMA address translation descriptor suitable 1797for use with a maximum DMA address width of 1798.Fa width , 1799with support for the requested translation 1800.Fa flags . 1801.Pp 1802If a suitable DMA address translation descriptor is found, it will be stored in 1803.Fa translation , 1804and a bus DMA tag specifying the DMA translation's address restrictions will 1805be stored in 1806.Fa dmat . 1807The 1808.Fa translation 1809and 1810.Fa dmat 1811arguments may be 1812.Dv NULL 1813if the translation descriptor or DMA tag are not desired. 1814.Pp 1815The following DMA translation flags are supported: 1816.Bl -ohang -width ".Dv BHND_DMA_TRANSLATION_BYTESWAPPED" -offset indent 1817.It Dv BHND_DMA_TRANSLATION_PHYSMAP 1818The translation remaps the device's physical address space. 1819.Pp 1820This is used in conjunction with 1821.Dv BHND_DMA_TRANSLATION_BYTESWAPPED 1822to define a DMA translation that provides byteswapped access to physical memory 1823on big-endian MIPS SoCs. 1824.It Dv BHND_DMA_TRANSLATION_BYTESWAPPED 1825The translation provides a byte-swapped mapping; write requests will be 1826byte-swapped before being written to memory, and read requests will be 1827byte-swapped before being returned. 1828.Pp 1829This is primarily used to perform efficient byte swapping of DMA data on 1830embedded MIPS SoCs executing in big-endian mode. 1831.El 1832.Pp 1833The following symbolic constants are defined for common DMA address widths: 1834.Pp 1835.Bl -tag -width ".Dv BHND_DMA_ADDR_64BIT" -offset indent -compact 1836.It Dv BHND_DMA_ADDR_30BIT 183730-bit DMA 1838.It Dv BHND_DMA_ADDR_32BIT 183932-bit DMA 1840.It Dv BHND_DMA_ADDR_64BIT 184164-bit DMA 1842.El 1843.Pp 1844The 1845.Vt bhnd_dma_translation 1846structure contains the following fields: 1847.Bl -tag -width "addrext_mask" 1848.It Fa base_addr 1849Host-to-device physical address translation. 1850This may be added to a host physical address to produce a device DMA address. 1851.It Fa addr_mask 1852Device-addressable address mask. 1853This defines the device DMA address range, and excludes any bits reserved for 1854mapping the address within the translation window at 1855.Fa base_addr . 1856.It Fa addrext_mask 1857Device-addressable extended address mask. 1858If a the per-core BHND DMA engine supports the 'addrext' control field, it can 1859be used to provide address bits excluded by 1860.Fa addr_mask . 1861.Pp 1862Support for DMA extended address changes \(em including coordination with the 1863core providing device-to-host DMA address translation \(em is handled 1864transparently by the DMA engine. 1865.Pp 1866For example, on PCI Wi-Fi devices, the Wi-Fi core's DMA engine will (in effect) 1867update the PCI host bridge core's DMA 1868.Dv sbtopcitranslation 1869base address to map the target address prior to performing a DMA transaction. 1870.It Fa flags 1871Translation flags. 1872.El 1873.\" 1874.Ss "Interrupt Functions" 1875The 1876.Fn bhnd_get_intr_count 1877function is used to determine the number of backplane interrupt lines assigned 1878to the device 1879.Fa dev . 1880Interrupt line identifiers are allocated in monotonically increasing order, 1881starting with 0. 1882.Pp 1883The 1884.Fn bhnd_get_intr_ivec 1885function is used to determine the backplane interrupt vector assigned to 1886interrupt line 1887.Fa intr 1888on the device 1889.Fa dev , 1890writing the result to 1891.Fa ivec . 1892Interrupt vector assignments are backplane-specific: On BCMA devices, this 1893function returns the OOB bus line assigned to the interrupt. 1894On SIBA devices, it returns the target OCP slave flag number assigned to the 1895interrupt. 1896.Pp 1897The 1898.Fn bhnd_map_intr 1899function is used to map interrupt line 1900.Fa intr 1901assigned to device 1902.Fa dev 1903to an IRQ number, writing the result to 1904.Fa irq . 1905Until unmapped, this IRQ may be used when allocating a resource of type 1906SYS_RES_IRQ. 1907.Pp 1908Ownership of the interrupt mapping is assumed by the caller, and must be 1909explicitly released using 1910.Fa bhnd_unmap_intr . 1911.Pp 1912The 1913.Fn bhnd_unmap_intr 1914function is used to unmap bus IRQ 1915.Fa irq 1916previously mapped using 1917.Fn bhnd_map_intr 1918by the device 1919.Fa dev . 1920.\" 1921.Ss "NVRAM Functions" 1922The 1923.Fn bhnd_nvram_getvar 1924function is used to read the value of NVRAM variable 1925.Fa name 1926from the NVRAM provider(s) registered with the parent 1927.Xr bhnd 4 1928bus of device 1929.Fa dev , 1930coerced to the desired data representation 1931.Fa type , 1932written to the buffer specified by 1933.Fa buf . 1934.Pp 1935Before the call, the maximum capacity of 1936.Fa buf 1937is specified by 1938.Fa len . 1939After a successful call \(em or if 1940.Er ENOMEM 1941is returned \(em the size of the available data will be written to 1942.Fa len . 1943The size of the desired data representation can be determined by calling 1944.Fn bhnd_nvram_getvar 1945with a 1946.Dv NULL 1947argument for 1948.Fa buf . 1949.Pp 1950The following NVRAM data types are supported: 1951.Pp 1952.Bl -tag -width ".Dv BHND_NVRAM_TYPE_UINT64_ARRAY" -offset indent -compact 1953.It Dv BHND_NVRAM_TYPE_UINT8 1954unsigned 8-bit integer 1955.It Dv BHND_NVRAM_TYPE_UINT16 1956unsigned 16-bit integer 1957.It Dv BHND_NVRAM_TYPE_UINT32 1958unsigned 32-bit integer 1959.It Dv BHND_NVRAM_TYPE_UINT64 1960signed 64-bit integer 1961.It Dv BHND_NVRAM_TYPE_INT8 1962signed 8-bit integer 1963.It Dv BHND_NVRAM_TYPE_INT16 1964signed 16-bit integer 1965.It Dv BHND_NVRAM_TYPE_INT32 1966signed 32-bit integer 1967.It Dv BHND_NVRAM_TYPE_INT64 1968signed 64-bit integer 1969.It Dv BHND_NVRAM_TYPE_CHAR 1970UTF-8 character 1971.It Dv BHND_NVRAM_TYPE_STRING 1972UTF-8 NUL-terminated string 1973.It Dv BHND_NVRAM_TYPE_BOOL 1974uint8 boolean value 1975.It Dv BHND_NVRAM_TYPE_NULL 1976NULL (empty) value 1977.It Dv BHND_NVRAM_TYPE_DATA 1978opaque octet string 1979.It Dv BHND_NVRAM_TYPE_UINT8_ARRAY 1980array of uint8 integers 1981.It Dv BHND_NVRAM_TYPE_UINT16_ARRAY 1982array of uint16 integers 1983.It Dv BHND_NVRAM_TYPE_UINT32_ARRAY 1984array of uint32 integers 1985.It Dv BHND_NVRAM_TYPE_UINT64_ARRAY 1986array of uint64 integers 1987.It Dv BHND_NVRAM_TYPE_INT8_ARRAY 1988array of int8 integers 1989.It Dv BHND_NVRAM_TYPE_INT16_ARRAY 1990array of int16 integers 1991.It Dv BHND_NVRAM_TYPE_INT32_ARRAY 1992array of int32 integers 1993.It Dv BHND_NVRAM_TYPE_INT64_ARRAY 1994array of int64 integers 1995.It Dv BHND_NVRAM_TYPE_CHAR_ARRAY 1996array of UTF-8 characters 1997.It Dv BHND_NVRAM_TYPE_STRING_ARRAY 1998array of UTF-8 NUL-terminated strings 1999.It Dv BHND_NVRAM_TYPE_BOOL_ARRAY 2000array of uint8 boolean values 2001.El 2002.Pp 2003The 2004.Fn bhnd_nvram_getvar_array , 2005.Fn bhnd_nvram_getvar_int , 2006.Fn bhnd_nvram_getvar_int8 , 2007.Fn bhnd_nvram_getvar_int16 , 2008.Fn bhnd_nvram_getvar_int32 , 2009.Fn bhnd_nvram_getvar_uint , 2010.Fn bhnd_nvram_getvar_uint8 , 2011.Fn bhnd_nvram_getvar_uint16 , 2012.Fn bhnd_nvram_getvar_uint32 , 2013and 2014.Fn bhnd_nvram_getvar_str 2015functions are convenience wrappers for 2016.Fn bhnd_nvram_getvar . 2017.Pp 2018The 2019.Fn bhnd_nvram_getvar_array 2020function returns either a value of exactly 2021.Fa size 2022in 2023.Fa buf , 2024or returns an error code of 2025.Er ENXIO 2026if the data representation is not exactly 2027.Fa size 2028in length. 2029.Pp 2030The 2031.Fn bhnd_nvram_getvar_int 2032and 2033.Fn bhnd_nvram_getvar_uint 2034functions return the value of NVRAM variable 2035.Fa name , 2036coerced to a signed or unsigned integer 2037type of 2038.Fa width 2039(1, 2, or 4 bytes). 2040.Pp 2041The 2042.Fn bhnd_nvram_getvar_int8 , 2043.Fn bhnd_nvram_getvar_int16 , 2044.Fn bhnd_nvram_getvar_int32 , 2045.Fn bhnd_nvram_getvar_uint , 2046.Fn bhnd_nvram_getvar_uint8 , 2047.Fn bhnd_nvram_getvar_uint16 , 2048and 2049.Fn bhnd_nvram_getvar_uint32 2050functions return the value of NVRAM variable 2051.Fa name , 2052coerced to a signed or unsigned 8, 16, or 32-bit integer type. 2053.Pp 2054The 2055.Fn bhnd_nvram_getvar_str 2056functions return the value of NVRAM variable 2057.Fa name , 2058coerced to a NUL-terminated string. 2059.Pp 2060The 2061.Fn bhnd_nvram_string_array_next 2062function iterates over all strings in the 2063.Fa inp 2064.Dv BHND_NVRAM_TYPE_STRING_ARRAY 2065value. 2066The size of 2067.Fa inp , 2068including any terminating NUL character(s), is specified using the 2069.Fa ilen 2070argument. 2071The 2072.Fa prev 2073argument should be either a string pointer previously returned by 2074.Fn bhnd_nvram_string_array_next , 2075or 2076.Dv NULL 2077to begin iteration. 2078If 2079.Fa prev is not 2080.Dv NULL , 2081the 2082.Fa olen 2083argument must be a pointer to the length previously returned by 2084.Fn bhnd_nvram_string_array_next . 2085On success, the next string element's length will be written to this pointer. 2086.\" 2087.Ss "Port/Region Functions" 2088Per-device interconnect memory mappings are identified by a combination of 2089.Em port type , 2090.Em port number , 2091and 2092.Em region number . 2093Port and memory region identifiers are allocated in monotonically increasing 2094order for each 2095.Em port type , 2096starting with 0. 2097.Pp 2098The following port types are supported: 2099.Bl -tag -width ".Dv BHND_PORT_DEVICE" -offset indent 2100.It Dv BHND_PORT_DEVICE 2101Device memory. 2102The device's control/status registers are always mapped by the first device port 2103and region, and will be assigned a 2104.Dv SYS_RES_MEMORY 2105resource ID of 0. 2106.It Dv BHND_PORT_BRIDGE 2107Bridge memory. 2108.It Dv BHND_PORT_AGENT 2109Interconnect agent/wrapper. 2110.El 2111.Pp 2112The 2113.Fn bhnd_decode_port_rid 2114function is used to decode the resource ID 2115.Fa rid 2116assigned to device 2117.Fa dev , 2118of resource type 2119.Fa type , 2120writing the port type to 2121.Fa port_type , 2122port number to 2123.Fa port , 2124and region number 2125to 2126.Fa region . 2127.Pp 2128The 2129.Fn bhnd_get_port_count 2130function returns the number of ports of type 2131.Fa type 2132assigned to device 2133.Fa dev . 2134.Pp 2135The 2136.Fn bhnd_get_port_rid 2137function returns the resource ID for the 2138.Dv SYS_RES_MEMORY 2139resource mapping the 2140.Fa port 2141of 2142.Fa type 2143and 2144.Fa region 2145on device 2146.Fa dev , 2147or -1 if the port or region are invalid, or do not have an assigned resource ID. 2148.Pp 2149The 2150.Fn bhnd_get_region_addr 2151function is used to determine the base address and size of the memory 2152.Fa region 2153on 2154.Fa port 2155of 2156.Fa type 2157assigned to 2158.Fa dev . 2159The region's base device address will be written to 2160.Fa region_addr , 2161and the region size to 2162.Fa region_size . 2163.Pp 2164The 2165.Fn bhnd_get_region_count 2166function returns the number of memory regions mapped to 2167.Fa port 2168of 2169.Fa type 2170on device 2171.Fa dev . 2172.Pp 2173The 2174.Fn bhnd_is_region_valid 2175function returns 2176.Dv true 2177if 2178.Fa region 2179is a valid region mapped by 2180.Fa port 2181of 2182.Fa type 2183on device 2184.Fa dev . 2185.\" 2186.Ss "Power Management Functions" 2187Drivers must ask the parent 2188.Xr bhnd 4 2189bus to allocate device PMU state using 2190.Fn bhnd_alloc_pmu 2191before calling any another bhnd PMU functions. 2192.Pp 2193The 2194.Fn bhnd_alloc_pmu 2195function is used to allocate per-device PMU state and enable PMU request 2196handling for device 2197.Fa dev . 2198The memory region containing the device's PMU register block must be allocated 2199using 2200.Xr bus_alloc_resource 9 2201or 2202.Fn bhnd_alloc_resource 2203before calling 2204.Fn bhnd_alloc_pmu , 2205and must not be released until after calling 2206.Fn bhnd_release_pmu . 2207.Pp 2208On all supported BHND hardware, the PMU register block is mapped by the device's 2209control/status registers in the first device port and region. 2210.Pp 2211The 2212.Fn bhnd_release_pmu 2213function releases the per-device PMU state previously allocated for device 2214.Fa dev 2215using 2216.Fn bhnd_alloc_pmu . 2217Any outstanding clock and external resource requests will be discarded upon 2218release of the device PMU state. 2219.Pp 2220The 2221.Fn bhnd_enable_clocks 2222function is used to request that 2223.Fa clocks 2224be powered up and routed to the backplane on behalf of device 2225.Fa dev . 2226This will power any clock sources required (e.g., XTAL, PLL, etc) and wait until 2227the requested clocks are stable. 2228If the request succeeds, any previous clock requests issued by 2229.Fa dev 2230will be discarded. 2231.Pp 2232The following clocks are supported, and may be combined using bitwise OR to 2233request multiple clocks: 2234.Bl -tag -width ".Dv BHND_CLOCK_DYN" -offset indent 2235.It BHND_CLOCK_DYN 2236Dynamically select an appropriate clock source based on all outstanding clock 2237requests by any device attached to the parent 2238.Xr bhnd 4 2239bus. 2240.It BHND_CLOCK_ILP 2241Idle Low-Power (ILP) Clock. 2242May be used if no register access is required, or long request latency is 2243acceptable. 2244.It BHND_CLOCK_ALP 2245Active Low-Power (ALP) Clock. 2246Supports low-latency register access and low-rate DMA. 2247.It BHND_CLOCK_HT 2248High Throughput (HT) Clock. 2249Supports high bus throughput and lowest-latency register access. 2250.El 2251.Pp 2252The 2253.Fn bhnd_request_clock 2254function is used to request that 2255.Fa clock 2256(or faster) be powered up and routed to device 2257.Fa dev . 2258.Pp 2259The 2260.Fn bhnd_get_clock_freq 2261function is used to request the current clock frequency of 2262.Fa clock , 2263writing the frequency in Hz to 2264.Fa freq . 2265.Pp 2266The 2267.Fn bhnd_get_clock_latency 2268function is used to determine the transition latency required for 2269.Fa clock , 2270writing the latency in microseconds to 2271.Fa latency . 2272The 2273.Dv BHND_CLOCK_HT 2274latency value is suitable for use as the D11 Wi-Fi core 2275.Em fastpwrup_dly 2276value. 2277.Pp 2278The 2279.Fn bhnd_request_ext_rsrc 2280function is used to request that the external PMU-managed resource assigned to 2281device 2282.Fa dev , 2283identified by device-specific identifier 2284.Fa rsrc , 2285be powered up. 2286.Pp 2287The 2288.Fn bhnd_release_ext_rsrc 2289function releases any outstanding requests by device 2290.Fa dev 2291for the PMU-managed resource identified by device-specific identifier 2292.Fa rsrc . 2293If an external resource is shared by multiple devices, it will not be powered 2294down until all device requests are released. 2295.\" 2296.Ss "Service Provider Functions" 2297The 2298.Fn bhnd_register_provider 2299function is used to register device 2300.Fa dev 2301as a provider for platform 2302.Fa service 2303with the parent 2304.Xr bhnd 4 2305bus. 2306.Pp 2307The following service types are supported: 2308.Bl -tag -width ".Dv BHND_SERVICE_INVALID" -offset indent 2309.It Dv BHND_SERVICE_CHIPC 2310ChipCommon service. 2311The providing device must implement the bhnd_chipc interface. 2312.It Dv BHND_SERVICE_PWRCTL 2313Legacy PWRCTL service. 2314The providing device must implement the bhnd_pwrctl interface. 2315.It Dv BHND_SERVICE_PMU 2316PMU service. 2317The providing device must implement the bhnd_pmu interface. 2318.It Dv BHND_SERVICE_NVRAM 2319NVRAM service. 2320The providing device must implement the bhnd_nvram interface. 2321.It Dv BHND_SERVICE_GPIO 2322GPIO service. 2323The providing device must implement the standard 2324.Xr gpio 4 2325interface. 2326.It Dv BHND_SERVICE_ANY 2327Matches on any service type. 2328May be used with 2329.Fn bhnd_deregister_provider 2330to remove all service provider registrations for a device. 2331.El 2332.Pp 2333The 2334.Fn bhnd_deregister_provider 2335function attempts to remove provider registration for the device 2336.Fa dev 2337and 2338.Fa service . 2339If a 2340.Fa service 2341argument of 2342.Dv BHND_SERVICE_ANY 2343is specified, this function will attempt to remove 2344.Em all service provider registrations for 2345.Fa dev . 2346.Pp 2347The 2348.Fn bhnd_retain_provider 2349function retains and returns a reference to the provider registered for 2350.Fa service 2351with the parent 2352.Xr bhnd 4 2353bus of devce 2354.Fa dev , 2355if available. 2356On success, the caller is responsible for releasing this provider reference 2357using 2358.Fn bhnd_release_provider . 2359The service provider is guaranteed to remain available until the provider 2360reference is released. 2361.Pp 2362The 2363.Fn bhnd_release_provider 2364function releases a reference to a 2365.Fa provider 2366for 2367.Fa service , 2368previously retained by device 2369.Fa dev 2370using 2371.Fn bhnd_retain_provider . 2372.\" 2373.Ss "Utility Functions" 2374The 2375.Fn bhnd_driver_get_erom_class 2376function returns the 2377.Xr bhnd_erom 9 2378class for the device enumeration table format used by 2379.Xr bhnd 4 2380bus driver instance 2381.Fa driver . 2382If the driver does not support 2383.Xr bhnd_erom 9 2384device enumeration, 2385.Dv NULL 2386is returned. 2387.Pp 2388The 2389.Fn bhnd_find_core_class 2390function looks up the BHND class, if known, for the BHND vendor ID 2391.Fa vendor 2392and device ID 2393.Fa device . 2394.Pp 2395The 2396.Fn bhnd_find_core_name 2397function is used to fetch the human-readable name, if known, for the BHND core 2398with a vendor ID of 2399.Fa vendor 2400and device ID of 2401.Fa device . 2402.Pp 2403The 2404.Fn bhnd_core_class 2405and 2406.Fn bhnd_core_name 2407functions are convenience wrappers for 2408.Fn bhnd_find_core_class 2409and 2410.Fn bhnd_find_core_name , 2411that use the 2412.Fa vendor 2413and 2414.Fa device 2415fields of the core info structure 2416.Fa ci . 2417.Pp 2418The 2419.Fn bhnd_format_chip_id 2420function writes a NUL-terminated human-readable representation of the BHND 2421.Fa chip_id 2422value to the specified 2423.Fa buffer 2424with a capacity of 2425.Fa size . 2426No more than 2427.Fa size-1 2428characters will be written, with the 2429.Fa size'th 2430character set to '\\0'. 2431A buffer size of 2432.Dv BHND_CHIPID_MAX_NAMELEN 2433is sufficient for any string representation produced using 2434.Fn bhnd_format_chip_id . 2435.Pp 2436The 2437.Fn bhnd_set_custom_core_desc 2438function uses the 2439.Xr bhnd 4 2440device identification of 2441.Fa dev , 2442overriding the core name with the specified 2443.Fa dev_name , 2444to populate the device's verbose description using 2445.Xr device_set_desc 9 . 2446.Pp 2447The 2448.Fn bhnd_set_default_core_desc 2449function uses the 2450.Xr bhnd 4 2451device identification of 2452.Fa dev 2453to populate the device's verbose description using 2454.Xr device_set_desc 9 . 2455.Pp 2456The 2457.Fn bhnd_vendor_name 2458function returns the human-readable name for the JEP-106, ARM 4-bit 2459continuation encoded manufacturer ID 2460.Fa vendor , 2461if known. 2462.\" 2463.Sh RETURN VALUES 2464.Ss Bus Resource Functions 2465The 2466.Fn bhnd_activate_resource , 2467.Fn bhnd_alloc_resources , 2468.Fn bhnd_deactivate_resource , 2469and 2470.Fn bhnd_release_resource 2471functions return 0 on success, otherwise an appropriate error code is returned. 2472.Pp 2473The 2474.Fn bhnd_alloc_resource 2475and 2476.Fn bhnd_alloc_resource_any 2477functions return a pointer to 2478.Vt "struct resource" 2479on success, a null pointer otherwise. 2480.\" 2481.Ss "Device Configuration Functions" 2482The 2483.Fn bhnd_read_config 2484and 2485.Fn bhnd_write_config 2486functions return 0 on success, or one of the following values on error: 2487.Bl -tag -width Er 2488.It Bq Er EINVAL 2489The device is not a direct child of the 2490.Xr bhnd 4 2491bus 2492.It Bq Er EINVAL 2493The requested width is not one of 1, 2, or 4 bytes. 2494.It Bq Er ENODEV 2495Accessing agent/config space for the device is unsupported. 2496.It Bq Er EFAULT 2497The requested offset or width exceeds the bounds of the mapped agent/config 2498space. 2499.El 2500.Pp 2501The 2502.Fn bhnd_read_ioctl , 2503.Fn bhnd_write_ioctl , 2504.Fn bhnd_read_iost , 2505.Fn bhnd_reset_hw , 2506and 2507.Fn bhnd_suspend_hw 2508functions return 0 on success, otherwise an appropriate error code is returned. 2509.\" 2510.Ss "Device Information Functions" 2511The 2512.Fn bhnd_read_board_info 2513function returns 0 on success, otherwise an appropriate error code is returned. 2514.\" 2515.Ss "DMA Address Translation Functions" 2516The 2517.Fn bhnd_get_dma_translation 2518function returns 0 on success, or one of the following values on error: 2519.Bl -tag -width Er 2520.It Bq Er ENODEV 2521DMA is not supported. 2522.It Bq Er ENOENT 2523No DMA translation matching the requested address width and translation flags 2524is available. 2525.El 2526.Pp 2527If fetching the requested DMA address translation otherwise fails, an 2528appropriate error code will be returned. 2529.\" 2530.Ss "Interrupt Functions" 2531The 2532.Fn bhnd_get_intr_ivec 2533function returns 25340 on success, or 2535.Er ENXIO 2536if the requested interrupt line exceeds the number of interrupt lines assigned 2537to the device. 2538.Pp 2539The 2540.Fn bhnd_map_intr 2541function returns 0 on success, otherwise an appropriate error code is returned. 2542.\" 2543.Ss "NVRAM Functions" 2544The 2545.Fn bhnd_nvram_getvar , 2546.Fn bhnd_nvram_getvar_array , 2547.Fn bhnd_nvram_getvar_int , 2548.Fn bhnd_nvram_getvar_int8 , 2549.Fn bhnd_nvram_getvar_int16 , 2550.Fn bhnd_nvram_getvar_int32 , 2551.Fn bhnd_nvram_getvar_uint , 2552.Fn bhnd_nvram_getvar_uint8 , 2553.Fn bhnd_nvram_getvar_uint16 , 2554and 2555.Fn bhnd_nvram_getvar_uint32 2556functions return 0 on success, or one of the following values on error: 2557.Bl -tag -width Er 2558.It Bq Er ENODEV 2559If an NVRAM provider has not been registered with the bus. 2560.It Bq Er ENOENT 2561The requested variable was not found. 2562.It Bq Er ENOMEM 2563If the buffer of size is too small to hold the requested value. 2564.It Bq Er EOPNOTSUPP 2565If the value's native type is incompatible with and cannot be coerced to the 2566requested type. 2567.It Bq Er ERANGE 2568If value coercion would overflow (or underflow) the requested type 2569.El 2570.Pp 2571If reading the variable otherwise fails, an appropriate error code will be 2572returned. 2573.\" 2574.Ss "Port/Region Functions" 2575The 2576.Fn bhnd_decode_port_rid 2577function returns 25780 on success, or an appropriate error code if no matching port/region is found. 2579.Pp 2580The 2581.Fn bhnd_get_port_rid 2582function returns the resource ID for the requested port and region, 2583or -1 if the port or region are invalid, or do not have an assigned resource ID. 2584.Pp 2585The 2586.Fn bhnd_get_region_addr 2587function returns 25880 on success, or an appropriate error code if no matching port/region is found. 2589.\" 2590.Ss "PMU Functions" 2591The 2592.Fn bhnd_alloc_pmu 2593function returns 0 on success, otherwise an appropriate error code is returned. 2594.Pp 2595The 2596.Fn bhnd_release_pmu 2597function returns 0 on success, otherwise an appropriate error code is returned, 2598and the core state will be left unmodified. 2599.Pp 2600The 2601.Fn bhnd_enable_clocks 2602and 2603.Fn bhnd_request_clock 2604functions return 0 on success, or one of the following values on error: 2605.Bl -tag -width Er 2606.It Bq Er ENODEV 2607An unsupported clock was requested. 2608.It Bq Er ENXIO 2609No PMU or PWRCTL provider has been registered with the bus. 2610.El 2611.Pp 2612The 2613.Fn bhnd_get_clock_freq 2614function returns 0 on success, or 2615.Er ENODEV 2616if the frequency for the specified clock is not available. 2617.Pp 2618The 2619.Fn bhnd_get_clock_latency 2620function returns 0 on success, or 2621.Er ENODEV 2622if the transition latency for the specified clock is not available. 2623.Pp 2624The 2625.Fn bhnd_request_ext_rsrc 2626and 2627.Fn bhnd_release_ext_rsrc 2628functions return 0 on success, otherwise an appropriate error code is returned. 2629.\" 2630.Ss "Service Provider Functions" 2631The 2632.Fn bhnd_register_provider 2633function returns 0 on success, 2634.Er EEXIST 2635if an entry for service already exists, or an appropriate error code if 2636service registration otherwise fails. 2637.Pp 2638The 2639.Fn bhnd_deregister_provider 2640function returns 0 on success, or 2641.Er EBUSY 2642if active references to the service provider exist. 2643.Pp 2644The 2645.Fn bhnd_retain_provider 2646function returns a pointer to 2647.Vt "device_t" 2648on success, a null pointer if the requested provider is not registered. 2649.\" 2650.Ss "Utility Functions" 2651The 2652.Fn bhnd_format_chip_id 2653function returns the total number of bytes written on success, or a negative 2654integer on failure. 2655.\" 2656.Sh SEE ALSO 2657.Xr bhnd 4 , 2658.Xr bhnd_erom 9 2659.Sh AUTHORS 2660.An -nosplit 2661The 2662.Nm 2663driver programming interface and this manual page were written by 2664.An Landon Fuller Aq Mt landonf@FreeBSD.org . 2665