share/man/man9/bhnd.9

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