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