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