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