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.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 chip_caps 1134The 1135.Nm 1136capability flags supported by this chip. 1137.It Fa enum_addr 1138The backplane enumeration address. 1139On SSB devices, this will be the base address of the first SSB core. 1140On BCMA devices, this will be the address of the enumeration ROM (EROM) core. 1141.It Fa ncores 1142The number of cores on the chip backplane, or 0 if unknown. 1143.El 1144.Pp 1145The following constants are defined for known 1146.Fa chip_type 1147values: 1148.Bl -tag -width ".Dv BHND_CHIPTYPE_BCMA_ALT" -offset indent -compact 1149.It Dv BHND_CHIPTYPE_SIBA 1150SSB interconnect. 1151.It Dv BHND_CHIPTYPE_BCMA 1152BCMA interconnect. 1153.It Dv BHND_CHIPTYPE_BCMA_ALT 1154BCMA-compatible variant found in Broadcom Northstar ARM SoCs. 1155.It Dv BHND_CHIPTYPE_UBUS 1156UBUS interconnect. 1157This BCMA-derived interconnect is found in Broadcom BCM33xx DOCSIS SoCs, and 1158BCM63xx xDSL SoCs. 1159UBUS is not currently supported by 1160.Xr bhnd 4 . 1161.El 1162.Pp 1163The following 1164.Fa chip_caps 1165flags are supported: 1166.Bl -tag -width ".Dv BHND_CAP_BP64" -offset indent -compact 1167.It Dv BHND_CAP_BP64 1168The backplane supports 64-bit addressing. 1169.It Dv BHND_CAP_PMU 1170PMU is present. 1171.El 1172.Pp 1173Additional symbolic constants for known 1174.Fa chip_id , 1175.Fa chip_pkg , 1176and 1177.Fa chip_type 1178values are defined in 1179.In dev/bhnd/bhnd_ids.h . 1180.Pp 1181The 1182.Fn bhnd_get_class 1183function returns the BHND class of device 1184.Fa dev , 1185if the device's 1186.Em vendor 1187and 1188.Em device 1189identifiers are recognized. 1190Otherwise, returns 1191.Dv BHND_DEVCLASS_OTHER . 1192.Pp 1193One of the following device classes will be returned: 1194.Pp 1195.Bl -tag -width ".Dv BHND_DEVCLASS_SOC_ROUTER" -offset indent -compact 1196.It Dv BHND_DEVCLASS_CC 1197ChipCommon I/O Controller 1198.It Dv BHND_DEVCLASS_CC_B 1199ChipCommon Auxiliary Controller 1200.It Dv BHND_DEVCLASS_PMU 1201PMU Controller 1202.It Dv BHND_DEVCLASS_PCI 1203PCI Host/Device Bridge 1204.It Dv BHND_DEVCLASS_PCIE 1205PCIe Host/Device Bridge 1206.It Dv BHND_DEVCLASS_PCCARD 1207PCMCIA Host/Device Bridge 1208.It Dv BHND_DEVCLASS_RAM 1209Internal RAM/SRAM 1210.It Dv BHND_DEVCLASS_MEMC 1211Memory Controller 1212.It Dv BHND_DEVCLASS_ENET 1213IEEE 802.3 MAC/PHY 1214.It Dv BHND_DEVCLASS_ENET_MAC 1215IEEE 802.3 MAC 1216.It Dv BHND_DEVCLASS_ENET_PHY 1217IEEE 802.3 PHY 1218.It Dv BHND_DEVCLASS_WLAN 1219IEEE 802.11 MAC/PHY/Radio 1220.It Dv BHND_DEVCLASS_WLAN_MAC 1221IEEE 802.11 MAC 1222.It Dv BHND_DEVCLASS_WLAN_PHY 1223IEEE 802.11 PHY 1224.It Dv BHND_DEVCLASS_CPU 1225CPU Core 1226.It Dv BHND_DEVCLASS_SOC_ROUTER 1227Interconnect Router 1228.It Dv BHND_DEVCLASS_SOC_BRIDGE 1229Interconnect Host Bridge 1230.It Dv BHND_DEVCLASS_EROM 1231Device Enumeration ROM 1232.It Dv BHND_DEVCLASS_NVRAM 1233NVRAM/Flash Controller 1234.It Dv BHND_DEVCLASS_SOFTMODEM 1235Analog/PSTN SoftModem Codec 1236.It Dv BHND_DEVCLASS_USB_HOST 1237USB Host Controller 1238.It Dv BHND_DEVCLASS_USB_DEV 1239USB Device Controller 1240.It Dv BHND_DEVCLASS_USB_DUAL 1241USB Host/Device Controller 1242.It Dv BHND_DEVCLASS_OTHER 1243Other / Unknown 1244.It Dv BHND_DEVCLASS_INVALID 1245Invalid Class 1246.El 1247.Pp 1248The 1249.Fn bhnd_get_core_info 1250function returns the core information for device 1251.Fa dev . 1252The returned 1253.Vt bhnd_core_info 1254structure contains the following fields: 1255.Pp 1256.Bl -tag -width "core_idx" -offset indent -compact 1257.It Fa vendor 1258Vendor identifier (JEP-106, ARM 4-bit continuation encoded) 1259.It Fa device 1260Device identifier 1261.It Fa hwrev 1262Hardware revision 1263.It Fa core_idx 1264Core index 1265.It Fa unit 1266Core unit 1267.El 1268.Pp 1269Symbolic constants for common vendor and device identifiers are defined in 1270.In dev/bhnd/bhnd_ids.h . 1271Common vendor identifiers include: 1272.Pp 1273.Bl -tag -width ".Dv BHND_MFGID_MIPS" -offset indent -compact 1274.It Dv BHND_MFGID_ARM 1275ARM 1276.It Dv BHND_MFGID_BCM 1277Broadcom 1278.It Dv BHND_MFGID_MIPS 1279MIPS 1280.El 1281.Pp 1282The 1283.Fn bhnd_get_core_index , 1284.Fn bhnd_get_core_unit , 1285.Fn bhnd_get_device , 1286.Fn bhnd_get_hwrev , 1287and 1288.Fn bhnd_get_vendor 1289functions are convenience wrappers for 1290.Fn bhnd_get_core_info , 1291returning, respect the 1292.Fa core_idx , 1293.Fa core_unit , 1294.Fa device , 1295.Fa hwrev , 1296or 1297.Fa vendor 1298field from the 1299.Vt bhnd_core_info 1300structure. 1301.Pp 1302The 1303.Fn bhnd_get_device_name 1304function returns a human readable name for device 1305.Fa dev . 1306.Pp 1307The 1308.Fn bhnd_get_vendor_name 1309function returns a human readable name for the vendor of device 1310.Fa dev . 1311.Pp 1312The 1313.Fn bhnd_read_board_info 1314function attempts to read the board information for device 1315.Fa dev . 1316The board information will be returned in the location pointed to by 1317.Fa info 1318on success. 1319.Pp 1320The 1321.Vt bhnd_board_info 1322structure contains the following fields: 1323.Pp 1324.Bl -tag -width "board_srom_rev" -offset indent 1325.It Fa board_vendor 1326Vendor ID of the board manufacturer (PCI-SIG assigned). 1327.It Fa board_type 1328Board ID. 1329.It Fa board_devid 1330Device ID. 1331.It Fa board_rev 1332Board revision. 1333.It Fa board_srom_rev 1334Board SROM format revision. 1335.It Fa board_flags 1336Board flags (1) 1337.It Fa board_flags2 1338Board flags (2) 1339.It Fa board_flags3 1340Board flags (3) 1341.El 1342.Pp 1343The 1344.Fa board_devid 1345field is the Broadcom PCI device ID that most closely matches the 1346capabilities of the BHND device (if any). 1347.Pp 1348On PCI devices, the 1349.Fa board_vendor , 1350.Fa board_type , 1351and 1352.Fa board_devid 1353fields default to the PCI Subsystem Vendor ID, PCI Subsystem ID, and PCI 1354device ID, unless overridden in device NVRAM. 1355.Pp 1356On other devices, including SoCs, the 1357.Fa board_vendor , 1358.Fa board_type , 1359and 1360.Fa board_devid 1361fields will be populated from device NVRAM. 1362.Pp 1363Symbolic constants for common board flags are defined in 1364.In dev/bhnd/bhnd_ids.h . 1365.Pp 1366.Ss "Device Matching Functions" 1367The bhnd device matching functions are used to match against core, chip, and 1368board-level device attributes. 1369Match requirements are specified using the 1370.Vt "struct bhnd_board_match" , 1371.Vt "struct bhnd_chip_match" , 1372.Vt "struct bhnd_core_match" , 1373.Vt "struct bhnd_device_match" , 1374and 1375.Vt "struct bhnd_hwrev_match" 1376match descriptor structures. 1377.Pp 1378The 1379.Fn bhnd_board_matches 1380function returns 1381.Dv true 1382if 1383.Fa board 1384matches the board match descriptor 1385.Fa desc . 1386Otherwise, it returns 1387.Dv false . 1388.Pp 1389The 1390.Fn bhnd_chip_matches 1391function returns 1392.Dv true 1393if 1394.Fa chip 1395matches the chip match descriptor 1396.Fa desc . 1397Otherwise, it returns 1398.Dv false . 1399.Pp 1400The 1401.Fn bhnd_core_matches 1402function returns 1403.Dv true 1404if 1405.Fa core 1406matches the core match descriptor 1407.Fa desc . 1408Otherwise, it returns 1409.Dv false . 1410.Pp 1411The 1412.Fn bhnd_device_matches 1413function returns 1414.Dv true 1415if the device 1416.Fa dev 1417matches the device match descriptor 1418.Fa desc . 1419Otherwise, it returns 1420.Dv false . 1421.Pp 1422The 1423.Fn bhnd_hwrev_matches 1424function returns 1425.Dv true 1426if 1427.Fa hwrev 1428matches the hwrev match descriptor 1429.Fa desc . 1430Otherwise, it returns 1431.Dv false . 1432.Pp 1433The 1434.Fn bhnd_bus_match_child 1435function returns the first child device of 1436.Fa bus 1437that matches the device match descriptor 1438.Fa desc . 1439If no matching child is found, 1440.Dv NULL 1441is returned. 1442.Pp 1443The 1444.Fn bhnd_core_get_match_desc 1445function returns an equality match descriptor for the core info in 1446.Fa core . 1447The returned descriptor will match only on core attributes identical to those 1448defined by 1449.Fa core . 1450.Pp 1451The 1452.Fn bhnd_cores_equal 1453function is a convenience wrapper for 1454.Fn bhnd_core_matches 1455and 1456.Fn bhnd_core_get_match_desc . 1457This function returns 1458.Dv true 1459if the 1460.Vt bhnd_core_info 1461structures 1462.Fa lhs 1463and 1464.Fa rhs 1465are equal. 1466Otherwise, it returns 1467.Dv false . 1468.Pp 1469The 1470.Fn bhnd_match_core 1471function returns a pointer to the first entry in the array 1472.Fa cores 1473of length 1474.Fa num_cores 1475that matches 1476.Fa desc . 1477If no matching core is found, 1478.Dv NULL 1479is returned. 1480.Pp 1481A 1482.Vt bhnd_board_match 1483match descriptor may be initialized using one or more of the following macros: 1484.Pp 1485.Bl -tag -width "Fn BHND_MATCH_BOARD_VENDOR vendor" -offset indent 1486.It Fn BHND_MATCH_BOARD_VENDOR "vendor" 1487Match on boards with a vendor equal to 1488.Fa vendor . 1489.It Fn BHND_MATCH_BOARD_TYPE "type" 1490Match on boards with a type equal to 1491.Dv "BHND_BOARD_ ##" 1492.Fa type 1493.It Fn BHND_MATCH_SROMREV "sromrev" 1494Match on boards with a sromrev that matches 1495.Dv "BHND_HWREV_ ##" 1496.Fa sromrev . 1497.It Fn BHND_MATCH_BOARD_REV "hwrev" 1498Match on boards with hardware revisions that match 1499.Dv "BHND_ ##" 1500.Fa hwrev . 1501.It Fn BHND_MATCH_BOARD "vendor" "type" 1502A convenience wrapper for 1503.Fn BHND_MATCH_BOARD_VENDOR 1504and 1505.Fn BHND_MATCH_BOARD_TYPE . 1506.El 1507.Pp 1508For example: 1509.Bd -literal -offset indent 1510struct bhnd_board_match board_desc = { 1511 BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM), 1512 BHND_MATCH_BOARD_TYPE(BCM94360X52C), 1513 BHND_MATCH_BOARD_REV(HWREV_ANY), 1514 BHND_MATCH_SROMREV(RANGE(0, 10)) 1515}; 1516.Ed 1517.Pp 1518A 1519.Vt bhnd_chip_match 1520match descriptor may be initialized using one or more of the following macros: 1521.Pp 1522.Bl -tag -width "Fn BHND_MATCH_CHIP_IPR id pkg hwrev" -offset indent 1523.It Fn BHND_MATCH_CHIP_ID "id" 1524Match on chips with an ID equal to 1525.Dv "BHND_CHIPID_ ##" 1526.Fa id 1527.It Fn BHND_MATCH_CHIP_REV "hwrev" 1528Match on chips with hardware revisions that match 1529.Dv "BHND_ ##" 1530.Fa hwrev . 1531.It Fn BHND_MATCH_CHIP_PKG "pkg" 1532Match on chips with a package ID equal to 1533.Dv "BHND_PKGID_ ##" 1534.Fa pkg 1535.It Fn BHND_MATCH_CHIP_TYPE "type" 1536Match on chips with a chip type equal to 1537.Dv "BHND_CHIPTYPE_ ##" 1538.Fa type 1539.It Fn BHND_MATCH_CHIP_IP "id" "pkg" 1540A convenience wrapper for 1541.Fn BHND_MATCH_CHIP_ID 1542and 1543.Fn BHND_MATCH_CHIP_PKG . 1544.It Fn BHND_MATCH_CHIP_IPR "id" "pkg" "hwrev" 1545A convenience wrapper for 1546.Fn BHND_MATCH_CHIP_ID , 1547.Fn BHND_MATCH_CHIP_PKG , 1548and 1549.Fn BHND_MATCH_CHIP_REV . 1550.It Fn BHND_MATCH_CHIP_IR "id" "hwrev" 1551A convenience wrapper for 1552.Fn BHND_MATCH_CHIP_ID 1553and 1554.Fn BHND_MATCH_CHIP_REV . 1555.El 1556.Pp 1557For example: 1558.Bd -literal -offset indent 1559struct bhnd_chip_match chip_desc = { 1560 BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN), 1561 BHND_MATCH_CHIP_TYPE(SIBA) 1562}; 1563.Ed 1564.Pp 1565A 1566.Vt bhnd_core_match 1567match descriptor may be initialized using one or more of the following macros: 1568.Pp 1569.Bl -tag -width "Fn BHND_MATCH_CORE_VENDOR vendor" -offset indent 1570.It Fn BHND_MATCH_CORE_VENDOR "vendor" 1571Match on cores with a vendor ID equal to 1572.Fa vendor 1573.It Fn BHND_MATCH_CORE_ID "id" 1574Match on cores with a device ID equal to 1575.Fa id 1576.It Fn BHND_MATCH_CORE_REV "hwrev" 1577Match on cores with hardware revisions that match 1578.Dv "BHND_ ##" 1579.Fa hwrev . 1580.It Fn BHND_MATCH_CORE_CLASS "class" 1581Match on cores with a core device class equal to 1582.Fa class 1583.It Fn BHND_MATCH_CORE_IDX "idx" 1584Match on cores with a core index equal to 1585.Fa idx 1586.It Fn BHND_MATCH_CORE_UNIT "unit" 1587Match on cores with a core unit equal to 1588.Fa unit 1589.It Fn BHND_MATCH_CORE "vendor" "id" 1590A convenience wrapper for 1591.Fn BHND_MATCH_CORE_VENDOR 1592and 1593.Fn BHND_MATCH_CORE_ID . 1594.El 1595.Pp 1596For example: 1597.Bd -literal -offset indent 1598struct bhnd_core_match core_desc = { 1599 BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC), 1600 BHND_MATCH_CORE_REV(HWREV_RANGE(0, 10)) 1601}; 1602.Ed 1603.Pp 1604The 1605.Vt bhnd_device_match 1606match descriptor supports matching on all board, chip, and core attributes, 1607and may be initialized using any of the 1608.Vt bhnd_board_match , 1609.Vt bhnd_chip_match , 1610or 1611.Vt bhnd_core_match 1612macros. 1613.Pp 1614For example: 1615.Bd -literal -offset indent 1616struct bhnd_device_match device_desc = { 1617 BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN), 1618 BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM), 1619 BHND_MATCH_BOARD_TYPE(BCM94329AGB), 1620 BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC), 1621}; 1622.Ed 1623.Pp 1624A 1625.Vt bhnd_hwrev_match 1626match descriptor may be initialized using one of the following macros: 1627.Pp 1628.Bl -tag -width "Fn BHND_HWREV_RANGE start end" -offset indent -compact 1629.It Dv BHND_HWREV_ANY 1630Matches any hardware revision. 1631.It Fn BHND_HWREV_EQ "hwrev" 1632Matches any hardware revision equal to 1633.Fa hwrev 1634.It Fn BHND_HWREV_GTE "hwrev" 1635Matches any hardware revision greater than or equal to 1636.Fa hwrev 1637.It Fn BHND_HWREV_LTE "hwrev" 1638Matches any hardware revision less than or equal to 1639.Fa hwrev 1640.It Fn BHND_HWREV_RANGE "start" "end" 1641Matches any hardware revision within an inclusive range. 1642If 1643.Dv BHND_HWREV_INVALID 1644is specified as the 1645.Fa end 1646value, will match on any revision equal to or greater than 1647.Fa start 1648.El 1649.\" 1650.Ss "Device Table Functions" 1651The bhnd device table functions are used to query device and 1652quirk tables. 1653.Pp 1654The 1655.Fn bhnd_device_lookup 1656function returns a pointer to the first entry in device table 1657.Fa table 1658that matches the device 1659.Fa dev . 1660The table entry size is specified by 1661.Fa entry_size . 1662.Pp 1663The 1664.Fn bhnd_device_quirks 1665function scan the device table 1666.Fa table 1667for all quirk entries that match the device 1668.Fa dev , 1669returning the bitwise OR of all matching quirk flags. 1670The table entry size is specified by 1671.Fa entry_size . 1672.Pp 1673The 1674.Vt bhnd_device 1675structure contains the following fields: 1676.Bl -tag -width "quirks_table" -offset indent -compact 1677.It Fa core 1678A 1679.Vt bhnd_device_match 1680descriptor. 1681.It Fa desc 1682A verbose device description suitable for use with 1683.Xr device_set_desc 9 , 1684or 1685.Dv NULL . 1686.It Fa quirks_table 1687The quirks table for this device, or 1688.Dv NULL . 1689.It Fa device_flags 1690The device flags required when matching this entry. 1691.El 1692.Pp 1693The following device flags are supported: 1694.Bl -tag -width ".Dv BHND_DF_ADAPTER" -offset indent -compact 1695.It Dv BHND_DF_ANY 1696Match on any device. 1697.It Dv BHND_DF_HOSTB 1698Match only if the device is the 1699.Xr bhndb 4 1700host bridge. 1701Implies 1702.Dv BHND_DF_ADAPTER . 1703.It Dv BHND_DF_SOC 1704Match only if the device is attached to a native SoC backplane. 1705.It Dv BHND_DF_ADAPTER 1706Match only if the device is attached to a 1707.Xr bhndb 4 1708bridged backplane. 1709.El 1710.Pp 1711A 1712.Vt bhnd_device 1713table entry may be initialized using one of the following macros: 1714.Pp 1715.Bl -ohang -offset indent 1716.It Fn BHND_DEVICE "vendor" "device" "desc" "quirks" "flags" 1717Match on devices with a vendor ID equal to 1718.Dv BHND_MFGID_ ## 1719.Fa vendor 1720and a core device ID equal to 1721.Dv BHND_COREID_ ## 1722.Fa device . 1723.Pp 1724The device's verbose description is specified by the 1725.Fa desc 1726argument, a pointer to the device-specific quirks table is specified by the 1727.Fa quirks 1728argument, and any required device flags may be provided in 1729.Fa flags . 1730The optional 1731.Fa flags 1732argument defaults to 1733.Dv BHND_DF_ANY 1734if omitted. 1735.It Dv BHND_DEVICE_END 1736Terminate the 1737.Vt bhnd_device 1738table. 1739.El 1740.Pp 1741For example: 1742.Bd -literal -offset indent 1743struct bhnd_device bhnd_usb11_devices[] = { 1744 BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller", 1745 bhnd_usb11_quirks), 1746 BHND_DEVICE_END 1747}; 1748.Ed 1749.Pp 1750The 1751.Vt bhnd_device_quirk 1752structure contains the following fields: 1753.Bl -tag -width "quirks_table" -offset indent -compact 1754.It Fa desc 1755A 1756.Vt bhnd_device_match 1757descriptor. 1758.It Fa quirks 1759Applicable quirk flags. 1760.El 1761.Pp 1762A bhnd_device_quirk table entry may be initialized using one of the following 1763convenience macros: 1764.Bl -tag -width "Fn BHND_CHIP_QUIRK chip hwrev flags" -offset indent 1765.It Fn BHND_BOARD_QUIRK "board" "flags" 1766Set quirk flags 1767.Fa flags 1768on devices with a board type equal to 1769.Dv BHND_BOARD_ ## 1770.Fa board . 1771.It Fn BHND_CHIP_QUIRK "chip" "hwrev" "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 hardware revision that matches 1778.Dv BHND_ ## 1779.Fa hwrev . 1780.It Fn BHND_PKG_QUIRK "chip" "pkg" flags" 1781Set quirk flags 1782.Fa flags 1783on devices with a chip ID equal to 1784.Dv BHND_CHIPID_BCM ## 1785.Fa chip 1786and chip package equal to 1787.Dv BHND_ ## chip ## 1788.Fa pkg . 1789.It Fn BHND_CORE_QUIRK "hwrev" flags" 1790Set quirk flags 1791.Fa flags 1792on devices with a core hardware revision that matches 1793.Dv BHND_ ## 1794.Fa hwrev . 1795.El 1796For example: 1797.Bd -literal -offset indent 1798struct bhnd_device_quirk bhnd_usb11_quirks[] = { 1799 BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller", 1800 bhnd_usb11_quirks), 1801 BHND_DEVICE_END 1802}; 1803.Ed 1804.Ss "DMA Address Translation Functions" 1805The 1806.Fn bhnd_get_dma_translation 1807function is used to request a DMA address translation descriptor suitable 1808for use with a maximum DMA address width of 1809.Fa width , 1810with support for the requested translation 1811.Fa flags . 1812.Pp 1813If a suitable DMA address translation descriptor is found, it will be stored in 1814.Fa translation , 1815and a bus DMA tag specifying the DMA translation's address restrictions will 1816be stored in 1817.Fa dmat . 1818The 1819.Fa translation 1820and 1821.Fa dmat 1822arguments may be 1823.Dv NULL 1824if the translation descriptor or DMA tag are not desired. 1825.Pp 1826The following DMA translation flags are supported: 1827.Bl -ohang -width ".Dv BHND_DMA_TRANSLATION_BYTESWAPPED" -offset indent 1828.It Dv BHND_DMA_TRANSLATION_PHYSMAP 1829The translation remaps the device's physical address space. 1830.Pp 1831This is used in conjunction with 1832.Dv BHND_DMA_TRANSLATION_BYTESWAPPED 1833to define a DMA translation that provides byteswapped access to physical memory 1834on big-endian MIPS SoCs. 1835.It Dv BHND_DMA_TRANSLATION_BYTESWAPPED 1836The translation provides a byte-swapped mapping; write requests will be 1837byte-swapped before being written to memory, and read requests will be 1838byte-swapped before being returned. 1839.Pp 1840This is primarily used to perform efficient byte swapping of DMA data on 1841embedded MIPS SoCs executing in big-endian mode. 1842.El 1843.Pp 1844The following symbolic constants are defined for common DMA address widths: 1845.Pp 1846.Bl -tag -width ".Dv BHND_DMA_ADDR_64BIT" -offset indent -compact 1847.It Dv BHND_DMA_ADDR_30BIT 184830-bit DMA 1849.It Dv BHND_DMA_ADDR_32BIT 185032-bit DMA 1851.It Dv BHND_DMA_ADDR_64BIT 185264-bit DMA 1853.El 1854.Pp 1855The 1856.Vt bhnd_dma_translation 1857structure contains the following fields: 1858.Bl -tag -width "addrext_mask" 1859.It Fa base_addr 1860Host-to-device physical address translation. 1861This may be added to a host physical address to produce a device DMA address. 1862.It Fa addr_mask 1863Device-addressable address mask. 1864This defines the device DMA address range, and excludes any bits reserved for 1865mapping the address within the translation window at 1866.Fa base_addr . 1867.It Fa addrext_mask 1868Device-addressable extended address mask. 1869If a the per-core BHND DMA engine supports the 'addrext' control field, it can 1870be used to provide address bits excluded by 1871.Fa addr_mask . 1872.Pp 1873Support for DMA extended address changes \(em including coordination with the 1874core providing device-to-host DMA address translation \(em is handled 1875transparently by the DMA engine. 1876.Pp 1877For example, on PCI Wi-Fi devices, the Wi-Fi core's DMA engine will (in effect) 1878update the PCI host bridge core's DMA 1879.Dv sbtopcitranslation 1880base address to map the target address prior to performing a DMA transaction. 1881.It Fa flags 1882Translation flags. 1883.El 1884.\" 1885.Ss "Interrupt Functions" 1886The 1887.Fn bhnd_get_intr_count 1888function is used to determine the number of backplane interrupt lines assigned 1889to the device 1890.Fa dev . 1891Interrupt line identifiers are allocated in monotonically increasing order, 1892starting with 0. 1893.Pp 1894The 1895.Fn bhnd_get_intr_ivec 1896function is used to determine the backplane interrupt vector assigned to 1897interrupt line 1898.Fa intr 1899on the device 1900.Fa dev , 1901writing the result to 1902.Fa ivec . 1903Interrupt vector assignments are backplane-specific: On BCMA devices, this 1904function returns the OOB bus line assigned to the interrupt. 1905On SIBA devices, it returns the target OCP slave flag number assigned to the 1906interrupt. 1907.Pp 1908The 1909.Fn bhnd_map_intr 1910function is used to map interrupt line 1911.Fa intr 1912assigned to device 1913.Fa dev 1914to an IRQ number, writing the result to 1915.Fa irq . 1916Until unmapped, this IRQ may be used when allocating a resource of type 1917SYS_RES_IRQ. 1918.Pp 1919Ownership of the interrupt mapping is assumed by the caller, and must be 1920explicitly released using 1921.Fa bhnd_unmap_intr . 1922.Pp 1923The 1924.Fn bhnd_unmap_intr 1925function is used to unmap bus IRQ 1926.Fa irq 1927previously mapped using 1928.Fn bhnd_map_intr 1929by the device 1930.Fa dev . 1931.\" 1932.Ss "NVRAM Functions" 1933The 1934.Fn bhnd_nvram_getvar 1935function is used to read the value of NVRAM variable 1936.Fa name 1937from the NVRAM provider(s) registered with the parent 1938.Xr bhnd 4 1939bus of device 1940.Fa dev , 1941coerced to the desired data representation 1942.Fa type , 1943written to the buffer specified by 1944.Fa buf . 1945.Pp 1946Before the call, the maximum capacity of 1947.Fa buf 1948is specified by 1949.Fa len . 1950After a successful call \(em or if 1951.Er ENOMEM 1952is returned \(em the size of the available data will be written to 1953.Fa len . 1954The size of the desired data representation can be determined by calling 1955.Fn bhnd_nvram_getvar 1956with a 1957.Dv NULL 1958argument for 1959.Fa buf . 1960.Pp 1961The following NVRAM data types are supported: 1962.Pp 1963.Bl -tag -width ".Dv BHND_NVRAM_TYPE_UINT64_ARRAY" -offset indent -compact 1964.It Dv BHND_NVRAM_TYPE_UINT8 1965unsigned 8-bit integer 1966.It Dv BHND_NVRAM_TYPE_UINT16 1967unsigned 16-bit integer 1968.It Dv BHND_NVRAM_TYPE_UINT32 1969unsigned 32-bit integer 1970.It Dv BHND_NVRAM_TYPE_UINT64 1971signed 64-bit integer 1972.It Dv BHND_NVRAM_TYPE_INT8 1973signed 8-bit integer 1974.It Dv BHND_NVRAM_TYPE_INT16 1975signed 16-bit integer 1976.It Dv BHND_NVRAM_TYPE_INT32 1977signed 32-bit integer 1978.It Dv BHND_NVRAM_TYPE_INT64 1979signed 64-bit integer 1980.It Dv BHND_NVRAM_TYPE_CHAR 1981UTF-8 character 1982.It Dv BHND_NVRAM_TYPE_STRING 1983UTF-8 NUL-terminated string 1984.It Dv BHND_NVRAM_TYPE_BOOL 1985uint8 boolean value 1986.It Dv BHND_NVRAM_TYPE_NULL 1987NULL (empty) value 1988.It Dv BHND_NVRAM_TYPE_DATA 1989opaque octet string 1990.It Dv BHND_NVRAM_TYPE_UINT8_ARRAY 1991array of uint8 integers 1992.It Dv BHND_NVRAM_TYPE_UINT16_ARRAY 1993array of uint16 integers 1994.It Dv BHND_NVRAM_TYPE_UINT32_ARRAY 1995array of uint32 integers 1996.It Dv BHND_NVRAM_TYPE_UINT64_ARRAY 1997array of uint64 integers 1998.It Dv BHND_NVRAM_TYPE_INT8_ARRAY 1999array of int8 integers 2000.It Dv BHND_NVRAM_TYPE_INT16_ARRAY 2001array of int16 integers 2002.It Dv BHND_NVRAM_TYPE_INT32_ARRAY 2003array of int32 integers 2004.It Dv BHND_NVRAM_TYPE_INT64_ARRAY 2005array of int64 integers 2006.It Dv BHND_NVRAM_TYPE_CHAR_ARRAY 2007array of UTF-8 characters 2008.It Dv BHND_NVRAM_TYPE_STRING_ARRAY 2009array of UTF-8 NUL-terminated strings 2010.It Dv BHND_NVRAM_TYPE_BOOL_ARRAY 2011array of uint8 boolean values 2012.El 2013.Pp 2014The 2015.Fn bhnd_nvram_getvar_array , 2016.Fn bhnd_nvram_getvar_int , 2017.Fn bhnd_nvram_getvar_int8 , 2018.Fn bhnd_nvram_getvar_int16 , 2019.Fn bhnd_nvram_getvar_int32 , 2020.Fn bhnd_nvram_getvar_uint , 2021.Fn bhnd_nvram_getvar_uint8 , 2022.Fn bhnd_nvram_getvar_uint16 , 2023.Fn bhnd_nvram_getvar_uint32 , 2024and 2025.Fn bhnd_nvram_getvar_str 2026functions are convenience wrappers for 2027.Fn bhnd_nvram_getvar . 2028.Pp 2029The 2030.Fn bhnd_nvram_getvar_array 2031function returns either a value of exactly 2032.Fa size 2033in 2034.Fa buf , 2035or returns an error code of 2036.Er ENXIO 2037if the data representation is not exactly 2038.Fa size 2039in length. 2040.Pp 2041The 2042.Fn bhnd_nvram_getvar_int 2043and 2044.Fn bhnd_nvram_getvar_uint 2045functions return the value of NVRAM variable 2046.Fa name , 2047coerced to a signed or unsigned integer 2048type of 2049.Fa width 2050(1, 2, or 4 bytes). 2051.Pp 2052The 2053.Fn bhnd_nvram_getvar_int8 , 2054.Fn bhnd_nvram_getvar_int16 , 2055.Fn bhnd_nvram_getvar_int32 , 2056.Fn bhnd_nvram_getvar_uint , 2057.Fn bhnd_nvram_getvar_uint8 , 2058.Fn bhnd_nvram_getvar_uint16 , 2059and 2060.Fn bhnd_nvram_getvar_uint32 2061functions return the value of NVRAM variable 2062.Fa name , 2063coerced to a signed or unsigned 8, 16, or 32-bit integer type. 2064.Pp 2065The 2066.Fn bhnd_nvram_getvar_str 2067functions return the value of NVRAM variable 2068.Fa name , 2069coerced to a NUL-terminated string. 2070.Pp 2071The 2072.Fn bhnd_nvram_string_array_next 2073function iterates over all strings in the 2074.Fa inp 2075.Dv BHND_NVRAM_TYPE_STRING_ARRAY 2076value. 2077The size of 2078.Fa inp , 2079including any terminating NUL character(s), is specified using the 2080.Fa ilen 2081argument. 2082The 2083.Fa prev 2084argument should be either a string pointer previously returned by 2085.Fn bhnd_nvram_string_array_next , 2086or 2087.Dv NULL 2088to begin iteration. 2089If 2090.Fa prev is not 2091.Dv NULL , 2092the 2093.Fa olen 2094argument must be a pointer to the length previously returned by 2095.Fn bhnd_nvram_string_array_next . 2096On success, the next string element's length will be written to this pointer. 2097.\" 2098.Ss "Port/Region Functions" 2099Per-device interconnect memory mappings are identified by a combination of 2100.Em port type , 2101.Em port number , 2102and 2103.Em region number . 2104Port and memory region identifiers are allocated in monotonically increasing 2105order for each 2106.Em port type , 2107starting with 0. 2108.Pp 2109The following port types are supported: 2110.Bl -tag -width ".Dv BHND_PORT_DEVICE" -offset indent 2111.It Dv BHND_PORT_DEVICE 2112Device memory. 2113The device's control/status registers are always mapped by the first device port 2114and region, and will be assigned a 2115.Dv SYS_RES_MEMORY 2116resource ID of 0. 2117.It Dv BHND_PORT_BRIDGE 2118Bridge memory. 2119.It Dv BHND_PORT_AGENT 2120Interconnect agent/wrapper. 2121.El 2122.Pp 2123The 2124.Fn bhnd_decode_port_rid 2125function is used to decode the resource ID 2126.Fa rid 2127assigned to device 2128.Fa dev , 2129of resource type 2130.Fa type , 2131writing the port type to 2132.Fa port_type , 2133port number to 2134.Fa port , 2135and region number 2136to 2137.Fa region . 2138.Pp 2139The 2140.Fn bhnd_get_port_count 2141function returns the number of ports of type 2142.Fa type 2143assigned to device 2144.Fa dev . 2145.Pp 2146The 2147.Fn bhnd_get_port_rid 2148function returns the resource ID for the 2149.Dv SYS_RES_MEMORY 2150resource mapping the 2151.Fa port 2152of 2153.Fa type 2154and 2155.Fa region 2156on device 2157.Fa dev , 2158or -1 if the port or region are invalid, or do not have an assigned resource ID. 2159.Pp 2160The 2161.Fn bhnd_get_region_addr 2162function is used to determine the base address and size of the memory 2163.Fa region 2164on 2165.Fa port 2166of 2167.Fa type 2168assigned to 2169.Fa dev . 2170The region's base device address will be written to 2171.Fa region_addr , 2172and the region size to 2173.Fa region_size . 2174.Pp 2175The 2176.Fn bhnd_get_region_count 2177function returns the number of memory regions mapped to 2178.Fa port 2179of 2180.Fa type 2181on device 2182.Fa dev . 2183.Pp 2184The 2185.Fn bhnd_is_region_valid 2186function returns 2187.Dv true 2188if 2189.Fa region 2190is a valid region mapped by 2191.Fa port 2192of 2193.Fa type 2194on device 2195.Fa dev . 2196.\" 2197.Ss "Power Management Functions" 2198Drivers must ask the parent 2199.Xr bhnd 4 2200bus to allocate device PMU state using 2201.Fn bhnd_alloc_pmu 2202before calling any another bhnd PMU functions. 2203.Pp 2204The 2205.Fn bhnd_alloc_pmu 2206function is used to allocate per-device PMU state and enable PMU request 2207handling for device 2208.Fa dev . 2209The memory region containing the device's PMU register block must be allocated 2210using 2211.Xr bus_alloc_resource 9 2212or 2213.Fn bhnd_alloc_resource 2214before calling 2215.Fn bhnd_alloc_pmu , 2216and must not be released until after calling 2217.Fn bhnd_release_pmu . 2218.Pp 2219On all supported BHND hardware, the PMU register block is mapped by the device's 2220control/status registers in the first device port and region. 2221.Pp 2222The 2223.Fn bhnd_release_pmu 2224function releases the per-device PMU state previously allocated for device 2225.Fa dev 2226using 2227.Fn bhnd_alloc_pmu . 2228Any outstanding clock and external resource requests will be discarded upon 2229release of the device PMU state. 2230.Pp 2231The 2232.Fn bhnd_enable_clocks 2233function is used to request that 2234.Fa clocks 2235be powered up and routed to the backplane on behalf of device 2236.Fa dev . 2237This will power any clock sources required (e.g., XTAL, PLL, etc) and wait until 2238the requested clocks are stable. 2239If the request succeeds, any previous clock requests issued by 2240.Fa dev 2241will be discarded. 2242.Pp 2243The following clocks are supported, and may be combined using bitwise OR to 2244request multiple clocks: 2245.Pp 2246.Bl -tag -width ".Dv BHND_CLOCK_DYN" -offset indent 2247.It BHND_CLOCK_DYN 2248Dynamically select an appropriate clock source based on all outstanding clock 2249requests by any device attached to the parent 2250.Xr bhnd 4 2251bus. 2252.It BHND_CLOCK_ILP 2253Idle Low-Power (ILP) Clock. 2254May be used if no register access is required, or long request latency is 2255acceptable. 2256.It BHND_CLOCK_ALP 2257Active Low-Power (ALP) Clock. 2258Supports low-latency register access and low-rate DMA. 2259.It BHND_CLOCK_HT 2260High Throughput (HT) Clock. 2261Supports high bus throughput and lowest-latency register access. 2262.El 2263.Pp 2264The 2265.Fn bhnd_request_clock 2266function is used to request that 2267.Fa clock 2268(or faster) be powered up and routed to device 2269.Fa dev . 2270.Pp 2271The 2272.Fn bhnd_get_clock_freq 2273function is used to request the current clock frequency of 2274.Fa clock , 2275writing the frequency in Hz to 2276.Fa freq . 2277.Pp 2278The 2279.Fn bhnd_get_clock_latency 2280function is used to determine the transition latency required for 2281.Fa clock , 2282writing the latency in microseconds to 2283.Fa latency . 2284The 2285.Dv BHND_CLOCK_HT 2286latency value is suitable for use as the D11 Wi-Fi core 2287.Em fastpwrup_dly 2288value. 2289.Pp 2290The 2291.Fn bhnd_request_ext_rsrc 2292function is used to request that the external PMU-managed resource assigned to 2293device 2294.Fa dev , 2295identified by device-specific identifier 2296.Fa rsrc , 2297be powered up. 2298.Pp 2299The 2300.Fn bhnd_release_ext_rsrc 2301function releases any outstanding requests by device 2302.Fa dev 2303for the PMU-managed resource identified by device-specific identifier 2304.Fa rsrc . 2305If an external resource is shared by multiple devices, it will not be powered 2306down until all device requests are released. 2307.\" 2308.Ss "Service Provider Functions" 2309The 2310.Fn bhnd_register_provider 2311function is used to register device 2312.Fa dev 2313as a provider for platform 2314.Fa service 2315with the parent 2316.Xr bhnd 4 2317bus. 2318.Pp 2319The following service types are supported: 2320.Bl -tag -width ".Dv BHND_SERVICE_INVALID" -offset indent 2321.It Dv BHND_SERVICE_CHIPC 2322ChipCommon service. 2323The providing device must implement the bhnd_chipc interface. 2324.It Dv BHND_SERVICE_PWRCTL 2325Legacy PWRCTL service. 2326The providing device must implement the bhnd_pwrctl interface. 2327.It Dv BHND_SERVICE_PMU 2328PMU service. 2329The providing device must implement the bhnd_pmu interface. 2330.It Dv BHND_SERVICE_NVRAM 2331NVRAM service. 2332The providing device must implement the bhnd_nvram interface. 2333.It Dv BHND_SERVICE_GPIO 2334GPIO service. 2335The providing device must implement the standard 2336.Xr gpio 4 2337interface. 2338.It Dv BHND_SERVICE_ANY 2339Matches on any service type. 2340May be used with 2341.Fn bhnd_deregister_provider 2342to remove all service provider registrations for a device. 2343.El 2344.Pp 2345The 2346.Fn bhnd_deregister_provider 2347function attempts to remove provider registration for the device 2348.Fa dev 2349and 2350.Fa service . 2351If a 2352.Fa service 2353argument of 2354.Dv BHND_SERVICE_ANY 2355is specified, this function will attempt to remove 2356.Em all service provider registrations for 2357.Fa dev . 2358.Pp 2359The 2360.Fn bhnd_retain_provider 2361function retains and returns a reference to the provider registered for 2362.Fa service 2363with the parent 2364.Xr bhnd 4 2365bus of devce 2366.Fa dev , 2367if available. 2368On success, the caller is responsible for releasing this provider reference 2369using 2370.Fn bhnd_release_provider . 2371The service provider is guaranteed to remain available until the provider 2372reference is released. 2373.Pp 2374The 2375.Fn bhnd_release_provider 2376function releases a reference to a 2377.Fa provider 2378for 2379.Fa service , 2380previously retained by device 2381.Fa dev 2382using 2383.Fn bhnd_retain_provider . 2384.\" 2385.Ss "Utility Functions" 2386The 2387.Fn bhnd_driver_get_erom_class 2388function returns the 2389.Xr bhnd_erom 9 2390class for the device enumeration table format used by 2391.Xr bhnd 4 2392bus driver instance 2393.Fa driver . 2394If the driver does not support 2395.Xr bhnd_erom 9 2396device enumeration, 2397.Dv NULL 2398is returned. 2399.Pp 2400The 2401.Fn bhnd_find_core_class 2402function looks up the BHND class, if known, for the BHND vendor ID 2403.Fa vendor 2404and device ID 2405.Fa device . 2406.Pp 2407The 2408.Fn bhnd_find_core_name 2409function is used to fetch the human-readable name, if known, for the BHND core 2410with a vendor ID of 2411.Fa vendor 2412and device ID of 2413.Fa device . 2414.Pp 2415The 2416.Fn bhnd_core_class 2417and 2418.Fn bhnd_core_name 2419functions are convenience wrappers for 2420.Fn bhnd_find_core_class 2421and 2422.Fn bhnd_find_core_name , 2423that use the 2424.Fa vendor 2425and 2426.Fa device 2427fields of the core info structure 2428.Fa ci . 2429.Pp 2430The 2431.Fn bhnd_format_chip_id 2432function writes a NUL-terminated human-readable representation of the BHND 2433.Fa chip_id 2434value to the specified 2435.Fa buffer 2436with a capacity of 2437.Fa size . 2438No more than 2439.Fa size-1 2440characters will be written, with the 2441.Fa size'th 2442character set to '\\0'. 2443A buffer size of 2444.Dv BHND_CHIPID_MAX_NAMELEN 2445is sufficient for any string representation produced using 2446.Fn bhnd_format_chip_id . 2447.Pp 2448The 2449.Fn bhnd_set_custom_core_desc 2450function uses the 2451.Xr bhnd 4 2452device identification of 2453.Fa dev , 2454overriding the core name with the specified 2455.Fa dev_name , 2456to populate the device's verbose description using 2457.Xr device_set_desc . 2458.Pp 2459The 2460.Fn bhnd_set_default_core_desc 2461function uses the 2462.Xr bhnd 4 2463device identification of 2464.Fa dev 2465to populate the device's verbose description using 2466.Xr device_set_desc . 2467.Pp 2468The 2469.Fn bhnd_vendor_name 2470function returns the human-readable name for the JEP-106, ARM 4-bit 2471continuation encoded manufacturer ID 2472.Fa vendor , 2473if known. 2474.\" 2475.Sh RETURN VALUES 2476.Ss Bus Resource Functions 2477The 2478.Fn bhnd_activate_resource , 2479.Fn bhnd_alloc_resources , 2480.Fn bhnd_deactivate_resource , 2481and 2482.Fn bhnd_release_resource 2483functions return 0 on success, otherwise an appropriate error code is returned. 2484.Pp 2485The 2486.Fn bhnd_alloc_resource 2487and 2488.Fn bhnd_alloc_resource_any 2489functions return a pointer to 2490.Vt "struct resource" 2491on success, a null pointer otherwise. 2492.\" 2493.Ss "Device Configuration Functions" 2494.Pp 2495The 2496.Fn bhnd_read_config 2497and 2498.Fn bhnd_write_config 2499functions return 0 on success, or one of the following values on error: 2500.Bl -tag -width Er 2501.It Bq Er EINVAL 2502The device is not a direct child of the 2503.Xr bhnd 4 2504bus 2505.It Bq Er EINVAL 2506The requested width is not one of 1, 2, or 4 bytes. 2507.It Bq Er ENODEV 2508Accessing agent/config space for the device is unsupported. 2509.It Bq Er EFAULT 2510The requested offset or width exceeds the bounds of the mapped agent/config 2511space. 2512.El 2513.Pp 2514The 2515.Fn bhnd_read_ioctl , 2516.Fn bhnd_write_ioctl , 2517.Fn bhnd_read_iost , 2518.Fn bhnd_reset_hw , 2519and 2520.Fn bhnd_suspend_hw 2521functions return 0 on success, otherwise an appropriate error code is returned. 2522.\" 2523.Ss "Device Information Functions" 2524.Pp 2525The 2526.Fn bhnd_read_board_info 2527function returns 0 on success, otherwise an appropriate error code is returned. 2528.\" 2529.Ss "DMA Address Translation Functions" 2530The 2531.Fn bhnd_get_dma_translation 2532function returns 0 on success, or one of the following values on error: 2533.Bl -tag -width Er 2534.It Bq Er ENODEV 2535DMA is not supported. 2536.It Bq Er ENOENT 2537No DMA translation matching the requested address width and translation flags 2538is available. 2539.El 2540.Pp 2541If fetching the requested DMA address translation otherwise fails, an 2542appropriate error code will be returned. 2543.\" 2544.Ss "Interrupt Functions" 2545.Pp 2546The 2547.Fn bhnd_get_intr_ivec 2548function returns 25490 on success, or 2550.Er ENXIO 2551if the requested interrupt line exceeds the number of interrupt lines assigned 2552to the device. 2553.Pp 2554The 2555.Fn bhnd_map_intr 2556function returns 0 on success, otherwise an appropriate error code is returned. 2557.\" 2558.Ss "NVRAM Functions" 2559The 2560.Fn bhnd_nvram_getvar , 2561.Fn bhnd_nvram_getvar_array , 2562.Fn bhnd_nvram_getvar_int , 2563.Fn bhnd_nvram_getvar_int8 , 2564.Fn bhnd_nvram_getvar_int16 , 2565.Fn bhnd_nvram_getvar_int32 , 2566.Fn bhnd_nvram_getvar_uint , 2567.Fn bhnd_nvram_getvar_uint8 , 2568.Fn bhnd_nvram_getvar_uint16 , 2569and 2570.Fn bhnd_nvram_getvar_uint32 2571functions return 0 on success, or one of the following values on error: 2572.Bl -tag -width Er 2573.It Bq Er ENODEV 2574If an NVRAM provider has not been registered with the bus. 2575.It Bq Er ENOENT 2576The requested variable was not found. 2577.It Bq Er ENOMEM 2578If the buffer of size is too small to hold the requested value. 2579.It Bq Er EOPNOTSUPP 2580If the value's native type is incompatible with and cannot be coerced to the 2581requested type. 2582.It Bq Er ERANGE 2583If value coercion would overflow (or underflow) the requested type 2584.El 2585.Pp 2586If reading the variable otherwise fails, an appropriate error code will be 2587returned. 2588.\" 2589.Ss "Port/Region Functions" 2590The 2591.Fn bhnd_decode_port_rid 2592function returns 25930 on success, or an appropriate error code if no matching port/region is found. 2594.Pp 2595The 2596.Fn bhnd_get_port_rid 2597function returns the resource ID for the requested port and region, 2598or -1 if the port or region are invalid, or do not have an assigned resource ID. 2599.Pp 2600The 2601.Fn bhnd_get_region_addr 2602function returns 26030 on success, or an appropriate error code if no matching port/region is found. 2604.\" 2605.Ss "PMU Functions" 2606The 2607.Fn bhnd_alloc_pmu 2608function returns 0 on success, otherwise an appropriate error code is returned. 2609.Pp 2610The 2611.Fn bhnd_release_pmu 2612function returns 0 on success, otherwise an appropriate error code is returned, 2613and the core state will be left unmodified. 2614.Pp 2615The 2616.Fn bhnd_enable_clocks 2617and 2618.Fn bhnd_request_clock 2619functions return 0 on success, or one of the following values on error: 2620.Bl -tag -width Er 2621.It Bq Er ENODEV 2622An unsupported clock was requested. 2623.It Bq Er ENXIO 2624No PMU or PWRCTL provider has been registered with the bus. 2625.El 2626.Pp 2627The 2628.Fn bhnd_get_clock_freq 2629function returns 0 on success, or 2630.Er ENODEV 2631if the frequency for the specified clock is not available. 2632.Pp 2633The 2634.Fn bhnd_get_clock_latency 2635function returns 0 on success, or 2636.Er ENODEV 2637if the transition latency for the specified clock is not available. 2638.Pp 2639The 2640.Fn bhnd_request_ext_rsrc 2641and 2642.Fn bhnd_release_ext_rsrc 2643functions return 0 on success, otherwise an appropriate error code is returned. 2644.Pp 2645.\" 2646.Ss "Service Provider Functions" 2647The 2648.Fn bhnd_register_provider 2649function returns 0 on success, 2650.Er EEXIST 2651if an entry for service already exists, or an appropriate error code if 2652service registration otherwise fails. 2653.Pp 2654The 2655.Fn bhnd_deregister_provider 2656function returns 0 on success, or 2657.Er EBUSY 2658if active references to the service provider exist. 2659.Pp 2660The 2661.Fn bhnd_retain_provider 2662function returns a pointer to 2663.Vt "device_t" 2664on success, a null pointer if the requested provider is not registered. 2665.\" 2666.Ss "Utility Functions" 2667.Pp 2668The 2669.Fn bhnd_format_chip_id 2670function returns the total number of bytes written on success, or a negative 2671integer on failure. 2672.\" 2673.Sh SEE ALSO 2674.Xr bhnd 4 2675.Xr bhnd_erom 9 2676.Sh AUTHORS 2677.An -nosplit 2678The 2679.Nm 2680driver programming interface and this manual page were written by 2681.An Landon Fuller Aq Mt landonf@FreeBSD.org . 2682