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