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