share/man/man9/bus_space.9

   1 .\" $NetBSD: bus_space.9,v 1.9 1999/03/06 22:09:29 mycroft Exp $
   2 .\"
   3 .\" Copyright (c) 2005 M. Warner Losh.  All Rights Reserved.
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  13 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  14 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  15 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  16 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  17 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  18 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  19 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  20 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  21 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  22 .\" POSSIBILITY OF SUCH DAMAGE.
  23 .\"
  24 .\"
  25 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
  26 .\" All rights reserved.
  27 .\"
  28 .\" This code is derived from software contributed to The NetBSD Foundation
  29 .\" by Christopher G. Demetriou.
  30 .\"
  31 .\" Redistribution and use in source and binary forms, with or without
  32 .\" modification, are permitted provided that the following conditions
  33 .\" are met:
  34 .\" 1. Redistributions of source code must retain the above copyright
  35 .\"    notice, this list of conditions and the following disclaimer.
  36 .\" 2. Redistributions in binary form must reproduce the above copyright
  37 .\"    notice, this list of conditions and the following disclaimer in the
  38 .\"    documentation and/or other materials provided with the distribution.
  39 .\"
  40 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  41 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  42 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  43 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  44 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  45 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  46 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  47 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  48 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  50 .\" POSSIBILITY OF SUCH DAMAGE.
  51 .\"
  52 .\" $FreeBSD$
  53 .\"
  54 .Dd June 13, 2005
  55 .Dt BUS_SPACE 9
  56 .Os
  57 .Sh NAME
  58 .Nm bus_space ,
  59 .Nm bus_space_barrier ,
  60 .Nm bus_space_copy_region_1 ,
  61 .Nm bus_space_copy_region_2 ,
  62 .Nm bus_space_copy_region_4 ,
  63 .Nm bus_space_copy_region_8 ,
  64 .Nm bus_space_copy_region_stream_1 ,
  65 .Nm bus_space_copy_region_stream_2 ,
  66 .Nm bus_space_copy_region_stream_4 ,
  67 .Nm bus_space_copy_region_stream_8 ,
  68 .Nm bus_space_free ,
  69 .Nm bus_space_map ,
  70 .Nm bus_space_read_1 ,
  71 .Nm bus_space_read_2 ,
  72 .Nm bus_space_read_4 ,
  73 .Nm bus_space_read_8 ,
  74 .Nm bus_space_read_multi_1 ,
  75 .Nm bus_space_read_multi_2 ,
  76 .Nm bus_space_read_multi_4 ,
  77 .Nm bus_space_read_multi_8 ,
  78 .Nm bus_space_read_multi_stream_1 ,
  79 .Nm bus_space_read_multi_stream_2 ,
  80 .Nm bus_space_read_multi_stream_4 ,
  81 .Nm bus_space_read_multi_stream_8 ,
  82 .Nm bus_space_read_region_1 ,
  83 .Nm bus_space_read_region_2 ,
  84 .Nm bus_space_read_region_4 ,
  85 .Nm bus_space_read_region_8 ,
  86 .Nm bus_space_read_region_stream_1 ,
  87 .Nm bus_space_read_region_stream_2 ,
  88 .Nm bus_space_read_region_stream_4 ,
  89 .Nm bus_space_read_region_stream_8 ,
  90 .Nm bus_space_read_stream_1 ,
  91 .Nm bus_space_read_stream_2 ,
  92 .Nm bus_space_read_stream_4 ,
  93 .Nm bus_space_read_stream_8 ,
  94 .Nm bus_space_set_multi_1 ,
  95 .Nm bus_space_set_multi_2 ,
  96 .Nm bus_space_set_multi_4 ,
  97 .Nm bus_space_set_multi_8 ,
  98 .Nm bus_space_set_multi_stream_1 ,
  99 .Nm bus_space_set_multi_stream_2 ,
 100 .Nm bus_space_set_multi_stream_4 ,
 101 .Nm bus_space_set_multi_stream_8 ,
 102 .Nm bus_space_set_region_1 ,
 103 .Nm bus_space_set_region_2 ,
 104 .Nm bus_space_set_region_4 ,
 105 .Nm bus_space_set_region_8 ,
 106 .Nm bus_space_set_region_stream_1 ,
 107 .Nm bus_space_set_region_stream_2 ,
 108 .Nm bus_space_set_region_stream_4 ,
 109 .Nm bus_space_set_region_stream_8 ,
 110 .Nm bus_space_subregion ,
 111 .Nm bus_space_unmap ,
 112 .Nm bus_space_write_1 ,
 113 .Nm bus_space_write_2 ,
 114 .Nm bus_space_write_4 ,
 115 .Nm bus_space_write_8 ,
 116 .Nm bus_space_write_multi_1 ,
 117 .Nm bus_space_write_multi_2 ,
 118 .Nm bus_space_write_multi_4 ,
 119 .Nm bus_space_write_multi_8 ,
 120 .Nm bus_space_write_multi_stream_1 ,
 121 .Nm bus_space_write_multi_stream_2 ,
 122 .Nm bus_space_write_multi_stream_4 ,
 123 .Nm bus_space_write_multi_stream_8 ,
 124 .Nm bus_space_write_region_1 ,
 125 .Nm bus_space_write_region_2 ,
 126 .Nm bus_space_write_region_4 ,
 127 .Nm bus_space_write_region_8 ,
 128 .Nm bus_space_write_region_stream_1 ,
 129 .Nm bus_space_write_region_stream_2 ,
 130 .Nm bus_space_write_region_stream_4 ,
 131 .Nm bus_space_write_region_stream_8 ,
 132 .Nm bus_space_write_stream_1 ,
 133 .Nm bus_space_write_stream_2 ,
 134 .Nm bus_space_write_stream_4 ,
 135 .Nm bus_space_write_stream_8
 136 .Nd "bus space manipulation functions"
 137 .Sh SYNOPSIS
 138 .In machine/bus.h
 139 .Ft int
 140 .Fo bus_space_map
 141 .Fa "bus_space_tag_t space" "bus_addr_t address"
 142 .Fa "bus_size_t size" "int flags" "bus_space_handle_t *handlep"
 143 .Fc
 144 .Ft void
 145 .Fo bus_space_unmap
 146 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size"
 147 .Fc
 148 .Ft int
 149 .Fo bus_space_subregion
 150 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
 151 .Fa "bus_size_t offset" "bus_size_t size" "bus_space_handle_t *nhandlep"
 152 .Fc
 153 .Ft int
 154 .Fo bus_space_alloc
 155 .Fa "bus_space_tag_t space" "bus_addr_t reg_start" "bus_addr_t reg_end"
 156 .Fa "bus_size_t size" "bus_size_t alignment" "bus_size_t boundary"
 157 .Fa "int flags" "bus_addr_t *addrp" "bus_space_handle_t *handlep"
 158 .Fc
 159 .Ft void
 160 .Fo bus_space_free
 161 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size"
 162 .Fc
 163 .Ft uint8_t
 164 .Fo bus_space_read_1
 165 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
 166 .Fc
 167 .Ft uint16_t
 168 .Fo bus_space_read_2
 169 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
 170 .Fc
 171 .Ft uint32_t
 172 .Fo bus_space_read_4
 173 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
 174 .Fc
 175 .Ft uint64_t
 176 .Fo bus_space_read_8
 177 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
 178 .Fc
 179 .Ft uint8_t
 180 .Fo bus_space_read_stream_1
 181 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
 182 .Fc
 183 .Ft uint16_t
 184 .Fo bus_space_read_stream_2
 185 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
 186 .Fc
 187 .Ft uint32_t
 188 .Fo bus_space_read_stream_4
 189 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
 190 .Fc
 191 .Ft uint64_t
 192 .Fo bus_space_read_stream_8
 193 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
 194 .Fc
 195 .Ft void
 196 .Fo bus_space_write_1
 197 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
 198 .Fa "bus_size_t offset" "uint8_t value"
 199 .Fc
 200 .Ft void
 201 .Fo bus_space_write_2
 202 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
 203 .Fa "bus_size_t offset" "uint16_t value"
 204 .Fc
 205 .Ft void
 206 .Fo bus_space_write_4
 207 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
 208 .Fa "bus_size_t offset" "uint32_t value"
 209 .Fc
 210 .Ft void
 211 .Fo bus_space_write_8
 212 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
 213 .Fa "bus_size_t offset" "uint64_t value"
 214 .Fc
 215 .Ft void
 216 .Fo bus_space_write_stream_1
 217 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
 218 .Fa "bus_size_t offset" "uint8_t value"
 219 .Fc
 220 .Ft void
 221 .Fo bus_space_write_stream_2
 222 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
 223 .Fa "bus_size_t offset" "uint16_t value"
 224 .Fc
 225 .Ft void
 226 .Fo bus_space_write_stream_4
 227 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
 228 .Fa "bus_size_t offset" "uint32_t value"
 229 .Fc
 230 .Ft void
 231 .Fo bus_space_write_stream_8
 232 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
 233 .Fa "bus_size_t offset" "uint64_t value"
 234 .Fc
 235 .Ft void
 236 .Fo bus_space_barrier
 237 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
 238 .Fa "bus_size_t offset" "bus_size_t length" "int flags"
 239 .Fc
 240 .Ft void
 241 .Fo bus_space_read_region_1
 242 .Fa "bus_space_tag_t space"
 243 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
 244 .Fa "bus_size_t count"
 245 .Fc
 246 .Ft void
 247 .Fo bus_space_read_region_2
 248 .Fa "bus_space_tag_t space"
 249 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
 250 .Fa "bus_size_t count"
 251 .Fc
 252 .Ft void
 253 .Fo bus_space_read_region_4
 254 .Fa "bus_space_tag_t space"
 255 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
 256 .Fa "bus_size_t count"
 257 .Fc
 258 .Ft void
 259 .Fo bus_space_read_region_8
 260 .Fa "bus_space_tag_t space"
 261 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
 262 .Fa "bus_size_t count"
 263 .Fc
 264 .Ft void
 265 .Fo bus_space_read_region_stream_1
 266 .Fa "bus_space_tag_t space"
 267 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
 268 .Fa "bus_size_t count"
 269 .Fc
 270 .Ft void
 271 .Fo bus_space_read_region_stream_2
 272 .Fa "bus_space_tag_t space"
 273 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
 274 .Fa "bus_size_t count"
 275 .Fc
 276 .Ft void
 277 .Fo bus_space_read_region_stream_4
 278 .Fa "bus_space_tag_t space"
 279 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
 280 .Fa "bus_size_t count"
 281 .Fc
 282 .Ft void
 283 .Fo bus_space_read_region_stream_8
 284 .Fa "bus_space_tag_t space"
 285 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
 286 .Fa "bus_size_t count"
 287 .Fc
 288 .Ft void
 289 .Fo bus_space_write_region_1
 290 .Fa "bus_space_tag_t space"
 291 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
 292 .Fa "bus_size_t count"
 293 .Fc
 294 .Ft void
 295 .Fo bus_space_write_region_2
 296 .Fa "bus_space_tag_t space"
 297 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
 298 .Fa "bus_size_t count"
 299 .Fc
 300 .Ft void
 301 .Fo bus_space_write_region_4
 302 .Fa "bus_space_tag_t space"
 303 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
 304 .Fa "bus_size_t count"
 305 .Fc
 306 .Ft void
 307 .Fo bus_space_write_region_8
 308 .Fa "bus_space_tag_t space"
 309 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
 310 .Fa "bus_size_t count"
 311 .Fc
 312 .Ft void
 313 .Fo bus_space_write_region_stream_1
 314 .Fa "bus_space_tag_t space"
 315 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
 316 .Fa "bus_size_t count"
 317 .Fc
 318 .Ft void
 319 .Fo bus_space_write_region_stream_2
 320 .Fa "bus_space_tag_t space"
 321 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
 322 .Fa "bus_size_t count"
 323 .Fc
 324 .Ft void
 325 .Fo bus_space_write_region_stream_4
 326 .Fa "bus_space_tag_t space"
 327 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
 328 .Fa "bus_size_t count"
 329 .Fc
 330 .Ft void
 331 .Fo bus_space_write_region_stream_8
 332 .Fa "bus_space_tag_t space"
 333 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
 334 .Fa "bus_size_t count"
 335 .Fc
 336 .Ft void
 337 .Fo bus_space_copy_region_1
 338 .Fa "bus_space_tag_t space"
 339 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
 340 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
 341 .Fc
 342 .Ft void
 343 .Fo bus_space_copy_region_2
 344 .Fa "bus_space_tag_t space"
 345 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
 346 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
 347 .Fc
 348 .Ft void
 349 .Fo bus_space_copy_region_4
 350 .Fa "bus_space_tag_t space"
 351 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
 352 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
 353 .Fc
 354 .Ft void
 355 .Fo bus_space_copy_region_8
 356 .Fa "bus_space_tag_t space"
 357 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
 358 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
 359 .Fc
 360 .Ft void
 361 .Fo bus_space_copy_region_stream_1
 362 .Fa "bus_space_tag_t space"
 363 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
 364 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
 365 .Fc
 366 .Ft void
 367 .Fo bus_space_copy_region_stream_2
 368 .Fa "bus_space_tag_t space"
 369 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
 370 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
 371 .Fc
 372 .Ft void
 373 .Fo bus_space_copy_region_stream_4
 374 .Fa "bus_space_tag_t space"
 375 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
 376 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
 377 .Fc
 378 .Ft void
 379 .Fo bus_space_copy_region_stream_8
 380 .Fa "bus_space_tag_t space"
 381 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
 382 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
 383 .Fc
 384 .Ft void
 385 .Fo bus_space_set_region_1
 386 .Fa "bus_space_tag_t space"
 387 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
 388 .Fa "bus_size_t count"
 389 .Fc
 390 .Ft void
 391 .Fo bus_space_set_region_2
 392 .Fa "bus_space_tag_t space"
 393 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
 394 .Fa "bus_size_t count"
 395 .Fc
 396 .Ft void
 397 .Fo bus_space_set_region_4
 398 .Fa "bus_space_tag_t space"
 399 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
 400 .Fa "bus_size_t count"
 401 .Fc
 402 .Ft void
 403 .Fo bus_space_set_region_8
 404 .Fa "bus_space_tag_t space"
 405 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
 406 .Fa "bus_size_t count"
 407 .Fc
 408 .Ft void
 409 .Fo bus_space_set_region_stream_1
 410 .Fa "bus_space_tag_t space"
 411 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
 412 .Fa "bus_size_t count"
 413 .Fc
 414 .Ft void
 415 .Fo bus_space_set_region_stream_2
 416 .Fa "bus_space_tag_t space"
 417 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
 418 .Fa "bus_size_t count"
 419 .Fc
 420 .Ft void
 421 .Fo bus_space_set_region_stream_4
 422 .Fa "bus_space_tag_t space"
 423 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
 424 .Fa "bus_size_t count"
 425 .Fc
 426 .Ft void
 427 .Fo bus_space_set_region_stream_8
 428 .Fa "bus_space_tag_t space"
 429 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
 430 .Fa "bus_size_t count"
 431 .Fc
 432 .Ft void
 433 .Fo bus_space_read_multi_1
 434 .Fa "bus_space_tag_t space"
 435 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
 436 .Fa "bus_size_t count"
 437 .Fc
 438 .Ft void
 439 .Fo bus_space_read_multi_2
 440 .Fa "bus_space_tag_t space"
 441 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
 442 .Fa "bus_size_t count"
 443 .Fc
 444 .Ft void
 445 .Fo bus_space_read_multi_4
 446 .Fa "bus_space_tag_t space"
 447 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
 448 .Fa "bus_size_t count"
 449 .Fc
 450 .Ft void
 451 .Fo bus_space_read_multi_8
 452 .Fa "bus_space_tag_t space"
 453 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
 454 .Fa "bus_size_t count"
 455 .Fc
 456 .Ft void
 457 .Fo bus_space_read_multi_stream_1
 458 .Fa "bus_space_tag_t space"
 459 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
 460 .Fa "bus_size_t count"
 461 .Fc
 462 .Ft void
 463 .Fo bus_space_read_multi_stream_2
 464 .Fa "bus_space_tag_t space"
 465 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
 466 .Fa "bus_size_t count"
 467 .Fc
 468 .Ft void
 469 .Fo bus_space_read_multi_stream_4
 470 .Fa "bus_space_tag_t space"
 471 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
 472 .Fa "bus_size_t count"
 473 .Fc
 474 .Ft void
 475 .Fo bus_space_read_multi_stream_8
 476 .Fa "bus_space_tag_t space"
 477 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
 478 .Fa "bus_size_t count"
 479 .Fc
 480 .Ft void
 481 .Fo bus_space_write_multi_1
 482 .Fa "bus_space_tag_t space"
 483 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
 484 .Fa "bus_size_t count"
 485 .Fc
 486 .Ft void
 487 .Fo bus_space_write_multi_2
 488 .Fa "bus_space_tag_t space"
 489 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
 490 .Fa "bus_size_t count"
 491 .Fc
 492 .Ft void
 493 .Fo bus_space_write_multi_4
 494 .Fa "bus_space_tag_t space"
 495 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
 496 .Fa "bus_size_t count"
 497 .Fc
 498 .Ft void
 499 .Fo bus_space_write_multi_8
 500 .Fa "bus_space_tag_t space"
 501 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
 502 .Fa "bus_size_t count"
 503 .Fc
 504 .Ft void
 505 .Fo bus_space_write_multi_stream_1
 506 .Fa "bus_space_tag_t space"
 507 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
 508 .Fa "bus_size_t count"
 509 .Fc
 510 .Ft void
 511 .Fo bus_space_write_multi_stream_2
 512 .Fa "bus_space_tag_t space"
 513 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
 514 .Fa "bus_size_t count"
 515 .Fc
 516 .Ft void
 517 .Fo bus_space_write_multi_stream_4
 518 .Fa "bus_space_tag_t space"
 519 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
 520 .Fa "bus_size_t count"
 521 .Fc
 522 .Ft void
 523 .Fo bus_space_write_multi_stream_8
 524 .Fa "bus_space_tag_t space"
 525 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
 526 .Fa "bus_size_t count"
 527 .Fc
 528 .Ft void
 529 .Fo bus_space_set_multi_1
 530 .Fa "bus_space_tag_t space"
 531 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
 532 .Fa "bus_size_t count"
 533 .Fc
 534 .Ft void
 535 .Fo bus_space_set_multi_2
 536 .Fa "bus_space_tag_t space"
 537 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
 538 .Fa "bus_size_t count"
 539 .Fc
 540 .Ft void
 541 .Fo bus_space_set_multi_4
 542 .Fa "bus_space_tag_t space"
 543 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
 544 .Fa "bus_size_t count"
 545 .Fc
 546 .Ft void
 547 .Fo bus_space_set_multi_8
 548 .Fa "bus_space_tag_t space"
 549 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
 550 .Fa "bus_size_t count"
 551 .Fc
 552 .Ft void
 553 .Fo bus_space_set_multi_stream_1
 554 .Fa "bus_space_tag_t space"
 555 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
 556 .Fa "bus_size_t count"
 557 .Fc
 558 .Ft void
 559 .Fo bus_space_set_multi_stream_2
 560 .Fa "bus_space_tag_t space"
 561 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
 562 .Fa "bus_size_t count"
 563 .Fc
 564 .Ft void
 565 .Fo bus_space_set_multi_stream_4
 566 .Fa "bus_space_tag_t space"
 567 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
 568 .Fa "bus_size_t count"
 569 .Fc
 570 .Ft void
 571 .Fo bus_space_set_multi_stream_8
 572 .Fa "bus_space_tag_t space"
 573 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
 574 .Fa "bus_size_t count"
 575 .Fc
 576 .Sh DESCRIPTION
 577 The
 578 .Nm
 579 functions exist to allow device drivers
 580 machine-independent access to bus memory and register areas.
 581 All of the
 582 functions and types described in this document can be used by including
 583 the
 584 .In machine/bus.h
 585 header file.
 586 .Pp
 587 Many common devices are used on multiple architectures, but are accessed
 588 differently on each because of architectural constraints.
 589 For instance, a device which is mapped in one system's I/O space may be
 590 mapped in memory space on a second system.
 591 On a third system, architectural
 592 limitations might change the way registers need to be accessed (e.g.\&
 593 creating a non-linear register space).
 594 In some cases, a single
 595 driver may need to access the same type of device in multiple ways in a
 596 single system or architecture.
 597 The goal of the
 598 .Nm
 599 functions is to allow a single driver source file to manipulate a set
 600 of devices on different system architectures, and to allow a single driver
 601 object file to manipulate a set of devices on multiple bus types on a
 602 single architecture.
 603 .Pp
 604 Not all busses have to implement all functions described in this
 605 document, though that is encouraged if the operations are logically
 606 supported by the bus.
 607 Unimplemented functions should cause
 608 compile-time errors if possible.
 609 .Pp
 610 All of the interface definitions described in this document are shown as
 611 function prototypes and discussed as if they were required to be
 612 functions.
 613 Implementations are encouraged to implement prototyped
 614 (type-checked) versions of these interfaces, but may implement them as
 615 macros if appropriate.
 616 Machine-dependent types, variables, and functions
 617 should be marked clearly in
 618 .In machine/bus.h
 619 to avoid confusion with the
 620 machine-independent types and functions, and, if possible, should be
 621 given names which make the machine-dependence clear.
 622 .Sh CONCEPTS AND GUIDELINES
 623 Bus spaces are described by bus space tags, which can be created only by
 624 machine-dependent code.
 625 A given machine may have several different types
 626 of bus space (e.g.\& memory space and I/O space), and thus may provide
 627 multiple different bus space tags.
 628 Individual busses or devices on a machine may use more than one bus space
 629 tag.
 630 For instance, ISA devices are
 631 given an ISA memory space tag and an ISA I/O space tag.
 632 Architectures
 633 may have several different tags which represent the same type of
 634 space, for instance because of multiple different host bus interface
 635 chipsets.
 636 .Pp
 637 A range in bus space is described by a bus address and a bus size.
 638 The
 639 bus address describes the start of the range in bus space.
 640 The bus
 641 size describes the size of the range in bytes.
 642 Busses which are not byte
 643 addressable may require use of bus space ranges with appropriately
 644 aligned addresses and properly rounded sizes.
 645 .Pp
 646 Access to regions of bus space is facilitated by use of bus space handles,
 647 which are usually created by mapping a specific range of a bus space.
 648 Handles may also be created by allocating
 649 and mapping a range of bus space, the actual location of which is picked
 650 by the implementation within bounds specified by the caller of the
 651 allocation function.
 652 .Pp
 653 All of the bus space access functions require one bus space tag
 654 argument, at least one handle argument, and at least one offset argument
 655 (a bus size).
 656 The bus space tag specifies the space, each handle specifies a region in
 657 the space, and each offset specifies the offset into the region of the
 658 actual location(s) to be accessed.
 659 Offsets are given in bytes, though busses
 660 may impose alignment constraints.
 661 The offset used to access data
 662 relative to a given handle must be such that all of the data being
 663 accessed is in the mapped region that the handle describes.
 664 Trying to
 665 access data outside that region is an error.
 666 .Pp
 667 Because some architectures' memory systems use buffering to improve
 668 memory and device access performance, there is a mechanism which can be
 669 used to create
 670 .Dq barriers
 671 in the bus space read and write stream.
 672 There
 673 are three types of barriers: read, write, and read/write.
 674 All reads
 675 started to the region before a read barrier must complete before any reads
 676 after the read barrier are started.
 677 (The analogous requirement is true for
 678 write barriers.)
 679 Read/write barriers force all reads and writes started
 680 before the barrier to complete before any reads or writes after the
 681 barrier are started.
 682 Correctly-written drivers will include all
 683 appropriate barriers, and assume only the read/write ordering imposed by
 684 the barrier operations.
 685 .Pp
 686 People trying to write portable drivers with the
 687 .Nm
 688 functions should
 689 try to make minimal assumptions about what the system allows.
 690 In particular,
 691 they should expect that the system requires bus space addresses being
 692 accessed to be naturally aligned (i.e., base address of handle added to
 693 offset is a multiple of the access size), and that the system does
 694 alignment checking on pointers (i.e., pointer to objects being read and
 695 written must point to properly-aligned data).
 696 .Pp
 697 The descriptions of the
 698 .Nm
 699 functions given below all assume that
 700 they are called with proper arguments.
 701 If called with invalid arguments
 702 or arguments that are out of range (e.g.\& trying to access data outside of
 703 the region mapped when a given handle was created), undefined behaviour
 704 results.
 705 In that case, they may cause the
 706 system to halt, either intentionally (via panic) or unintentionally (by
 707 causing a fatal trap of by some other means) or may cause improper
 708 operation which is not immediately fatal.
 709 Functions which return
 710 .Ft void
 711 or which return data read from bus space (i.e., functions which
 712 do not obviously return an error code) do not fail.
 713 They could only fail
 714 if given invalid arguments, and in that case their behaviour is undefined.
 715 Functions which take a count of bytes have undefined results if the specified
 716 .Fa count
 717 is zero.
 718 .Sh TYPES
 719 Several types are defined in
 720 .In machine/bus.h
 721 to facilitate use of the
 722 .Nm
 723 functions by drivers.
 724 .Ss Vt bus_addr_t
 725 The
 726 .Vt bus_addr_t
 727 type is used to describe bus addresses.
 728 It must be an
 729 unsigned integral type
 730 capable of holding the largest bus address usable by the architecture.
 731 This
 732 type is primarily used when mapping and unmapping bus space.
 733 .Ss Vt bus_size_t
 734 The
 735 .Vt bus_size_t
 736 type is used to describe sizes of ranges in bus space.
 737 It must be an
 738 unsigned integral type capable of holding the size of the largest bus
 739 address range usable on the architecture.
 740 This type is used by virtually all
 741 of the
 742 .Nm
 743 functions, describing sizes when mapping regions and
 744 offsets into regions when performing space access operations.
 745 .Ss Vt bus_space_tag_t
 746 The
 747 .Vt bus_space_tag_t
 748 type is used to describe a particular bus space on a machine.
 749 Its
 750 contents are machine-dependent and should be considered opaque by
 751 machine-independent code.
 752 This type is used by all
 753 .Nm
 754 functions to name the space on which they are operating.
 755 .Ss Vt bus_space_handle_t
 756 The
 757 .Vt bus_space_handle_t
 758 type is used to describe a mapping of a range of bus space.
 759 Its
 760 contents are machine-dependent and should be considered opaque by
 761 machine-independent code.
 762 This type is used when performing bus space
 763 access operations.
 764 .Sh MAPPING AND UNMAPPING BUS SPACE
 765 This section is specific to the
 766 .Nx
 767 version of these functions and may or may not apply to the
 768 .Fx
 769 version.
 770 .Pp
 771 Bus space must be mapped before it can be used, and should be
 772 unmapped when it is no longer needed.
 773 The
 774 .Fn bus_space_map
 775 and
 776 .Fn bus_space_unmap
 777 functions provide these capabilities.
 778 .Pp
 779 Some drivers need to be able to pass a subregion of already-mapped bus
 780 space to another driver or module within a driver.
 781 The
 782 .Fn bus_space_subregion
 783 function allows such subregions to be created.
 784 .Ss Fn bus_space_map space address size flags handlep
 785 The
 786 .Fn bus_space_map
 787 function maps the region of bus space named by the
 788 .Fa space , address ,
 789 and
 790 .Fa size
 791 arguments.
 792 If successful, it returns zero
 793 and fills in the bus space handle pointed to by
 794 .Fa handlep
 795 with the handle
 796 that can be used to access the mapped region.
 797 If unsuccessful,
 798 it will return non-zero and leave the bus space handle pointed
 799 to by
 800 .Fa handlep
 801 in an undefined state.
 802 .Pp
 803 The
 804 .Fa flags
 805 argument controls how the space is to be mapped.
 806 Supported flags include:
 807 .Bl -tag -width ".Dv BUS_SPACE_MAP_CACHEABLE"
 808 .It Dv BUS_SPACE_MAP_CACHEABLE
 809 Try to map the space so that accesses can be cached and/or
 810 prefetched by the system.
 811 If this flag is not specified, the
 812 implementation should map the space so that it will not be cached or
 813 prefetched.
 814 .Pp
 815 This flag must have a value of 1 on all implementations for backward
 816 compatibility.
 817 .It Dv BUS_SPACE_MAP_LINEAR
 818 Try to map the space so that its contents can be accessed linearly via
 819 normal memory access methods (e.g.\& pointer dereferencing and structure
 820 accesses).
 821 This is useful when software wants to do direct access to a memory
 822 device, e.g.\& a frame buffer.
 823 If this flag is specified and linear
 824 mapping is not possible, the
 825 .Fn bus_space_map
 826 call should fail.
 827 If this
 828 flag is not specified, the system may map the space in whatever way is
 829 most convenient.
 830 .El
 831 .Pp
 832 Not all combinations of flags make sense or are supported with all
 833 spaces.
 834 For instance,
 835 .Dv BUS_SPACE_MAP_CACHEABLE
 836 may be meaningless when
 837 used on many systems' I/O port spaces, and on some systems
 838 .Dv BUS_SPACE_MAP_LINEAR
 839 without
 840 .Dv BUS_SPACE_MAP_CACHEABLE
 841 may never work.
 842 When the system hardware or firmware provides hints as to how spaces should be
 843 mapped (e.g.\& the PCI memory mapping registers'
 844 .Dq prefetchable
 845 bit), those
 846 hints should be followed for maximum compatibility.
 847 On some systems,
 848 requesting a mapping that cannot be satisfied (e.g.\& requesting a
 849 non-cacheable mapping when the system can only provide a cacheable one)
 850 will cause the request to fail.
 851 .Pp
 852 Some implementations may keep track of use of bus space for some or all
 853 bus spaces and refuse to allow duplicate allocations.
 854 This is encouraged
 855 for bus spaces which have no notion of slot-specific space addressing,
 856 such as ISA and VME, and for spaces which coexist with those spaces
 857 (e.g.\& EISA and PCI memory and I/O spaces co-existing with ISA memory and
 858 I/O spaces).
 859 .Pp
 860 Mapped regions may contain areas for which there is no device on the
 861 bus.
 862 If space in those areas is accessed, the results are
 863 bus-dependent.
 864 .Ss Fn bus_space_unmap space handle size
 865 The
 866 .Fn bus_space_unmap
 867 function unmaps a region of bus space mapped with
 868 .Fn bus_space_map .
 869 When unmapping a region, the
 870 .Fa size
 871 specified should be
 872 the same as the size given to
 873 .Fn bus_space_map
 874 when mapping that region.
 875 .Pp
 876 After
 877 .Fn bus_space_unmap
 878 is called on a handle, that handle is no longer
 879 valid.
 880 (If copies were made of the handle they are no longer valid,
 881 either.)
 882 .Pp
 883 This function will never fail.
 884 If it would fail (e.g.\& because of an
 885 argument error), that indicates a software bug which should cause a
 886 panic.
 887 In that case,
 888 .Fn bus_space_unmap
 889 will never return.
 890 .Ss Fn bus_space_subregion space handle offset size nhandlep
 891 The
 892 .Fn bus_space_subregion
 893 function is a convenience function which makes a
 894 new handle to some subregion of an already-mapped region of bus space.
 895 The subregion described by the new handle starts at byte offset
 896 .Fa offset
 897 into the region described by
 898 .Fa handle ,
 899 with the size give by
 900 .Fa size ,
 901 and must be wholly contained within the original region.
 902 .Pp
 903 If successful,
 904 .Fn bus_space_subregion
 905 returns zero and fills in the bus
 906 space handle pointed to by
 907 .Fa nhandlep .
 908 If unsuccessful, it returns non-zero and leaves the bus space handle
 909 pointed to by
 910 .Fa nhandlep
 911 in an
 912 undefined state.
 913 In either case, the handle described by
 914 .Fa handle
 915 remains valid and is unmodified.
 916 .Pp
 917 When done with a handle created by
 918 .Fn bus_space_subregion ,
 919 the handle should
 920 be thrown away.
 921 Under no circumstances should
 922 .Fn bus_space_unmap
 923 be used on the handle.
 924 Doing so may confuse any resource management
 925 being done on the space, and will result in undefined behaviour.
 926 When
 927 .Fn bus_space_unmap
 928 or
 929 .Fn bus_space_free
 930 is called on a handle, all subregions of that handle become invalid.
 931 .Sh ALLOCATING AND FREEING BUS SPACE
 932 This section is specific to the
 933 .Nx
 934 version of these functions and may or may not apply to the
 935 .Fx
 936 version.
 937 .Pp
 938 Some devices require or allow bus space to be allocated by the operating
 939 system for device use.
 940 When the devices no longer need the space, the
 941 operating system should free it for use by other devices.
 942 The
 943 .Fn bus_space_alloc
 944 and
 945 .Fn bus_space_free
 946 functions provide these capabilities.
 947 .Ss Fn bus_space_alloc space reg_start reg_end size alignment boundary \
 948 flags addrp handlep
 949 The
 950 .Fn bus_space_alloc
 951 function allocates and maps a region of bus space with the size given by
 952 .Fa size ,
 953 corresponding to the given constraints.
 954 If successful, it returns
 955 zero, fills in the bus address pointed to by
 956 .Fa addrp
 957 with the bus space address of the allocated region, and fills in
 958 the bus space handle pointed to by
 959 .Fa handlep
 960 with the handle that can be used to access that region.
 961 If unsuccessful, it returns non-zero and leaves the bus address pointed to by
 962 .Fa addrp
 963 and the bus space handle pointed to by
 964 .Fa handlep
 965 in an undefined state.
 966 .Pp
 967 Constraints on the allocation are given by the
 968 .Fa reg_start , reg_end , alignment ,
 969 and
 970 .Fa boundary
 971 parameters.
 972 The allocated region will start at or after
 973 .Fa reg_start
 974 and end before or at
 975 .Fa reg_end .
 976 The
 977 .Fa alignment
 978 constraint must be a power of two, and the allocated region will start at
 979 an address that is an even multiple of that power of two.
 980 The
 981 .Fa boundary
 982 constraint, if non-zero, ensures that the region is allocated so that
 983 .Fa "first address in region"
 984 /
 985 .Fa boundary
 986 has the same value as
 987 .Fa "last address in region"
 988 /
 989 .Fa boundary .
 990 If the constraints cannot be met,
 991 .Fn bus_space_alloc
 992 will fail.
 993 It is an error to specify a set of
 994 constraints that can never be met
 995 (for example,
 996 .Fa size
 997 greater than
 998 .Fa boundary ) .
 999 .Pp
1000 The
1001 .Fa flags
1002 parameter is the same as the like-named parameter to
1003 .Fn bus_space_map ,
1004 the same flag values should be used, and they have the
1005 same meanings.
1006 .Pp
1007 Handles created by
1008 .Fn bus_space_alloc
1009 should only be freed with
1010 .Fn bus_space_free .
1011 Trying to use
1012 .Fn bus_space_unmap
1013 on them causes undefined behaviour.
1014 The
1015 .Fn bus_space_subregion
1016 function can be used on
1017 handles created by
1018 .Fn bus_space_alloc .
1019 .Ss Fn bus_space_free space handle size
1020 The
1021 .Fn bus_space_free
1022 function unmaps and frees a region of bus space mapped
1023 and allocated with
1024 .Fn bus_space_alloc .
1025 When unmapping a region, the
1026 .Fa size
1027 specified should be the same as the size given to
1028 .Fn bus_space_alloc
1029 when allocating the region.
1030 .Pp
1031 After
1032 .Fn bus_space_free
1033 is called on a handle, that handle is no longer valid.
1034 (If copies were
1035 made of the handle, they are no longer valid, either.)
1036 .Pp
1037 This function will never fail.
1038 If it would fail (e.g.\& because of an
1039 argument error), that indicates a software bug which should cause a
1040 panic.
1041 In that case,
1042 .Fn bus_space_free
1043 will never return.
1044 .Sh READING AND WRITING SINGLE DATA ITEMS
1045 The simplest way to access bus space is to read or write a single data
1046 item.
1047 The
1048 .Fn bus_space_read_N
1049 and
1050 .Fn bus_space_write_N
1051 families of functions provide
1052 the ability to read and write 1, 2, 4, and 8 byte data items on busses
1053 which support those access sizes.
1054 .Ss Fn bus_space_read_1 space handle offset
1055 .Ss Fn bus_space_read_2 space handle offset
1056 .Ss Fn bus_space_read_4 space handle offset
1057 .Ss Fn bus_space_read_8 space handle offset
1058 The
1059 .Fn bus_space_read_N
1060 family of functions reads a 1, 2, 4, or 8 byte data item from
1061 the offset specified by
1062 .Fa offset
1063 into the region specified by
1064 .Fa handle
1065 of the bus space specified by
1066 .Fa space .
1067 The location being read must lie within the bus space region specified by
1068 .Fa handle .
1069 .Pp
1070 For portability, the starting address of the region specified by
1071 .Fa handle
1072 plus the offset should be a multiple of the size of data item being read.
1073 On some systems, not obeying this requirement may cause incorrect data to
1074 be read, on others it may cause a system crash.
1075 .Pp
1076 Read operations done by the
1077 .Fn bus_space_read_N
1078 functions may be executed out
1079 of order with respect to other pending read and write operations unless
1080 order is enforced by use of the
1081 .Fn bus_space_barrier
1082 function.
1083 .Pp
1084 These functions will never fail.
1085 If they would fail (e.g.\& because of an
1086 argument error), that indicates a software bug which should cause a
1087 panic.
1088 In that case, they will never return.
1089 .Ss Fn bus_space_write_1 space handle offset value
1090 .Ss Fn bus_space_write_2 space handle offset value
1091 .Ss Fn bus_space_write_4 space handle offset value
1092 .Ss Fn bus_space_write_8 space handle offset value
1093 The
1094 .Fn bus_space_write_N
1095 family of functions writes a 1, 2, 4, or 8 byte data item to the offset
1096 specified by
1097 .Fa offset
1098 into the region specified by
1099 .Fa handle
1100 of the bus space specified by
1101 .Fa space .
1102 The location being written must lie within
1103 the bus space region specified by
1104 .Fa handle .
1105 .Pp
1106 For portability, the starting address of the region specified by
1107 .Fa handle
1108 plus the offset should be a multiple of the size of data item being
1109 written.
1110 On some systems, not obeying this requirement may cause
1111 incorrect data to be written, on others it may cause a system crash.
1112 .Pp
1113 Write operations done by the
1114 .Fn bus_space_write_N
1115 functions may be executed
1116 out of order with respect to other pending read and write operations
1117 unless order is enforced by use of the
1118 .Fn bus_space_barrier
1119 function.
1120 .Pp
1121 These functions will never fail.
1122 If they would fail (e.g.\& because of an
1123 argument error), that indicates a software bug which should cause a
1124 panic.
1125 In that case, they will never return.
1126 .Sh BARRIERS
1127 In order to allow high-performance buffering implementations to avoid bus
1128 activity on every operation, read and write ordering should be specified
1129 explicitly by drivers when necessary.
1130 The
1131 .Fn bus_space_barrier
1132 function provides that ability.
1133 .Ss Fn bus_space_barrier space handle offset length flags
1134 The
1135 .Fn bus_space_barrier
1136 function enforces ordering of bus space read and write operations
1137 for the specified subregion (described by the
1138 .Fa offset
1139 and
1140 .Fa length
1141 parameters) of the region named by
1142 .Fa handle
1143 in the space named by
1144 .Fa space .
1145 .Pp
1146 The
1147 .Fa flags
1148 argument controls what types of operations are to be ordered.
1149 Supported flags are:
1150 .Bl -tag -width ".Dv BUS_SPACE_BARRIER_WRITE"
1151 .It Dv BUS_SPACE_BARRIER_READ
1152 Synchronize read operations.
1153 .It Dv BUS_SPACE_BARRIER_WRITE
1154 Synchronize write operations.
1155 .El
1156 .Pp
1157 Those flags can be combined (or-ed together) to enforce ordering on both
1158 read and write operations.
1159 .Pp
1160 All of the specified type(s) of operation which are done to the region
1161 before the barrier operation are guaranteed to complete before any of the
1162 specified type(s) of operation done after the barrier.
1163 .Pp
1164 Example: Consider a hypothetical device with two single-byte ports, one
1165 write-only input port (at offset 0) and a read-only output port (at
1166 offset 1).
1167 Operation of the device is as follows: data bytes are written
1168 to the input port, and are placed by the device on a stack, the top of
1169 which is read by reading from the output port.
1170 The sequence to correctly
1171 write two data bytes to the device then read those two data bytes back
1172 would be:
1173 .Bd -literal
1174 /*
1175  * t and h are the tag and handle for the mapped device's
1176  * space.
1177  */
1178 bus_space_write_1(t, h, 0, data0);
1179 bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE);  /* 1 */
1180 bus_space_write_1(t, h, 0, data1);
1181 bus_space_barrier(t, h, 0, 2,
1182     BUS_SPACE_BARRIER_READ|BUS_SPACE_BARRIER_WRITE);     /* 2 */
1183 ndata1 = bus_space_read_1(t, h, 1);
1184 bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ);   /* 3 */
1185 ndata0 = bus_space_read_1(t, h, 1);
1186 /* data0 == ndata0, data1 == ndata1 */
1187 .Ed
1188 .Pp
1189 The first barrier makes sure that the first write finishes before the
1190 second write is issued, so that two writes to the input port are done
1191 in order and are not collapsed into a single write.
1192 This ensures that
1193 the data bytes are written to the device correctly and in order.
1194 .Pp
1195 The second barrier makes sure that the writes to the output port finish
1196 before any of the reads to the input port are issued, thereby making sure
1197 that all of the writes are finished before data is read.
1198 This ensures
1199 that the first byte read from the device really is the last one that was
1200 written.
1201 .Pp
1202 The third barrier makes sure that the first read finishes before the
1203 second read is issued, ensuring that data is read correctly and in order.
1204 .Pp
1205 The barriers in the example above are specified to cover the absolute
1206 minimum number of bus space locations.
1207 It is correct (and often
1208 easier) to make barrier operations cover the device's whole range of bus
1209 space, that is, to specify an offset of zero and the size of the
1210 whole region.
1211 .Sh REGION OPERATIONS
1212 Some devices use buffers which are mapped as regions in bus space.
1213 Often, drivers want to copy the contents of those buffers to or from
1214 memory, e.g.\& into mbufs which can be passed to higher levels of the
1215 system or from mbufs to be output to a network.
1216 In order to allow
1217 drivers to do this as efficiently as possible, the
1218 .Fn bus_space_read_region_N
1219 and
1220 .Fn bus_space_write_region_N
1221 families of functions are provided.
1222 .Pp
1223 Drivers occasionally need to copy one region of a bus space to another,
1224 or to set all locations in a region of bus space to contain a single
1225 value.
1226 The
1227 .Fn bus_space_copy_region_N
1228 family of functions and the
1229 .Fn bus_space_set_region_N
1230 family of functions allow drivers to perform these operations.
1231 .Ss Fn bus_space_read_region_1 space handle offset datap count
1232 .Ss Fn bus_space_read_region_2 space handle offset datap count
1233 .Ss Fn bus_space_read_region_4 space handle offset datap count
1234 .Ss Fn bus_space_read_region_8 space handle offset datap count
1235 The
1236 .Fn bus_space_read_region_N
1237 family of functions reads
1238 .Fa count
1239 1, 2, 4, or 8 byte data items from bus space
1240 starting at byte offset
1241 .Fa offset
1242 in the region specified by
1243 .Fa handle
1244 of the bus space specified by
1245 .Fa space
1246 and writes them into the array specified by
1247 .Fa datap .
1248 Each successive data item is read from an offset
1249 1, 2, 4, or 8 bytes after the previous data item (depending on which
1250 function is used).
1251 All locations being read must lie within the bus
1252 space region specified by
1253 .Fa handle .
1254 .Pp
1255 For portability, the starting address of the region specified by
1256 .Fa handle
1257 plus the offset should be a multiple of the size of data items being
1258 read and the data array pointer should be properly aligned.
1259 On some
1260 systems, not obeying these requirements may cause incorrect data to be
1261 read, on others it may cause a system crash.
1262 .Pp
1263 Read operations done by the
1264 .Fn bus_space_read_region_N
1265 functions may be executed in any order.
1266 They may also be executed out
1267 of order with respect to other pending read and write operations unless
1268 order is enforced by use of the
1269 .Fn bus_space_barrier
1270 function.
1271 There is no way to insert barriers between reads of
1272 individual bus space locations executed by the
1273 .Fn bus_space_read_region_N
1274 functions.
1275 .Pp
1276 These functions will never fail.
1277 If they would fail (e.g.\& because of an
1278 argument error), that indicates a software bug which should cause a
1279 panic.
1280 In that case, they will never return.
1281 .Ss Fn bus_space_write_region_1 space handle offset datap count
1282 .Ss Fn bus_space_write_region_2 space handle offset datap count
1283 .Ss Fn bus_space_write_region_4 space handle offset datap count
1284 .Ss Fn bus_space_write_region_8 space handle offset datap count
1285 The
1286 .Fn bus_space_write_region_N
1287 family of functions reads
1288 .Fa count
1289 1, 2, 4, or 8 byte data items from the array
1290 specified by
1291 .Fa datap
1292 and writes them to bus space starting at byte offset
1293 .Fa offset
1294 in the region specified by
1295 .Fa handle
1296 of the bus space specified
1297 by
1298 .Fa space .
1299 Each successive data item is written to an offset 1, 2, 4,
1300 or 8 bytes after the previous data item (depending on which function is
1301 used).
1302 All locations being written must lie within the bus space region
1303 specified by
1304 .Fa handle .
1305 .Pp
1306 For portability, the starting address of the region specified by
1307 .Fa handle
1308 plus the offset should be a multiple of the size of data items being
1309 written and the data array pointer should be properly aligned.
1310 On some
1311 systems, not obeying these requirements may cause incorrect data to be
1312 written, on others it may cause a system crash.
1313 .Pp
1314 Write operations done by the
1315 .Fn bus_space_write_region_N
1316 functions may be
1317 executed in any order.
1318 They may also be executed out of order with
1319 respect to other pending read and write operations unless order is
1320 enforced by use of the
1321 .Fn bus_space_barrier
1322 function.
1323 There is no way to insert barriers between writes of
1324 individual bus space locations executed by the
1325 .Fn bus_space_write_region_N
1326 functions.
1327 .Pp
1328 These functions will never fail.
1329 If they would fail (e.g.\& because of an
1330 argument error), that indicates a software bug which should cause a
1331 panic.
1332 In that case, they will never return.
1333 .Ss Fn bus_space_copy_region_1 space srchandle srcoffset dsthandle \
1334 dstoffset count
1335 .Ss Fn bus_space_copy_region_2 space srchandle srcoffset dsthandle \
1336 dstoffset count
1337 .Ss Fn bus_space_copy_region_4 space srchandle srcoffset dsthandle \
1338 dstoffset count
1339 .Ss Fn bus_space_copy_region_8 space srchandle srcoffset dsthandle \
1340 dstoffset count
1341 The
1342 .Fn bus_space_copy_region_N
1343 family of functions copies
1344 .Fa count
1345 1, 2, 4, or 8 byte data items in bus space
1346 from the area starting at byte offset
1347 .Fa srcoffset
1348 in the region specified by
1349 .Fa srchandle
1350 of the bus space specified by
1351 .Fa space
1352 to the area starting at byte offset
1353 .Fa dstoffset
1354 in the region specified by
1355 .Fa dsthandle
1356 in the same bus space.
1357 Each successive data item read or written has
1358 an offset 1, 2, 4, or 8 bytes after the previous data item (depending
1359 on which function is used).
1360 All locations being read and written must
1361 lie within the bus space region specified by their respective handles.
1362 .Pp
1363 For portability, the starting addresses of the regions specified by the
1364 each handle plus its respective offset should be a multiple of the size
1365 of data items being copied.
1366 On some systems, not obeying this
1367 requirement may cause incorrect data to be copied, on others it may cause
1368 a system crash.
1369 .Pp
1370 Read and write operations done by the
1371 .Fn bus_space_copy_region_N
1372 functions may be executed in any order.
1373 They may also be executed out
1374 of order with respect to other pending read and write operations unless
1375 order is enforced by use of the
1376 .Fn bus_space_barrier
1377 function.
1378 There is no way to insert barriers between reads or writes of
1379 individual bus space locations executed by the
1380 .Fn bus_space_copy_region_N
1381 functions.
1382 .Pp
1383 Overlapping copies between different subregions of a single region
1384 of bus space are handled correctly by the
1385 .Fn bus_space_copy_region_N
1386 functions.
1387 .Pp
1388 These functions will never fail.
1389 If they would fail (e.g.\& because of an
1390 argument error), that indicates a software bug which should cause a
1391 panic.
1392 In that case, they will never return.
1393 .Ss Fn bus_space_set_region_1 space handle offset value count
1394 .Ss Fn bus_space_set_region_2 space handle offset value count
1395 .Ss Fn bus_space_set_region_4 space handle offset value count
1396 .Ss Fn bus_space_set_region_8 space handle offset value count
1397 The
1398 .Fn bus_space_set_region_N
1399 family of functions writes the given
1400 .Fa value
1401 to
1402 .Fa count
1403 1, 2, 4, or 8 byte
1404 data items in bus space starting at byte offset
1405 .Fa offset
1406 in the region specified by
1407 .Fa handle
1408 of the bus space specified by
1409 .Fa space .
1410 Each successive data item has an offset 1, 2, 4, or 8 bytes after the
1411 previous data item (depending on which function is used).
1412 All
1413 locations being written must lie within the bus space region specified
1414 by
1415 .Fa handle .
1416 .Pp
1417 For portability, the starting address of the region specified by
1418 .Fa handle
1419 plus the offset should be a multiple of the size of data items being
1420 written.
1421 On some systems, not obeying this requirement may cause
1422 incorrect data to be written, on others it may cause a system crash.
1423 .Pp
1424 Write operations done by the
1425 .Fn bus_space_set_region_N
1426 functions may be
1427 executed in any order.
1428 They may also be executed out of order with
1429 respect to other pending read and write operations unless order is
1430 enforced by use of the
1431 .Fn bus_space_barrier
1432 function.
1433 There is no way to insert barriers between writes of
1434 individual bus space locations executed by the
1435 .Fn bus_space_set_region_N
1436 functions.
1437 .Pp
1438 These functions will never fail.
1439 If they would fail (e.g.\& because of an
1440 argument error), that indicates a software bug which should cause a
1441 panic.
1442 In that case, they will never return.
1443 .Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES
1444 Some devices implement single locations in bus space which are to be read
1445 or written multiple times to communicate data, e.g.\& some ethernet
1446 devices' packet buffer FIFOs.
1447 In order to allow drivers to manipulate
1448 these types of devices as efficiently as possible, the
1449 .Fn bus_space_read_multi_N ,
1450 .Fn bus_space_set_multi_N ,
1451 and
1452 .Fn bus_space_write_multi_N
1453 families of functions are provided.
1454 .Ss Fn bus_space_read_multi_1 space handle offset datap count
1455 .Ss Fn bus_space_read_multi_2 space handle offset datap count
1456 .Ss Fn bus_space_read_multi_4 space handle offset datap count
1457 .Ss Fn bus_space_read_multi_8 space handle offset datap count
1458 The
1459 .Fn bus_space_read_multi_N
1460 family of functions reads
1461 .Fa count
1462 1, 2, 4, or 8 byte data items from bus space
1463 at byte offset
1464 .Fa offset
1465 in the region specified by
1466 .Fa handle
1467 of the bus space specified by
1468 .Fa space
1469 and writes them into the array specified by
1470 .Fa datap .
1471 Each successive data item is read from the same location in bus
1472 space.
1473 The location being read must lie within the bus space region
1474 specified by
1475 .Fa handle .
1476 .Pp
1477 For portability, the starting address of the region specified by
1478 .Fa handle
1479 plus the offset should be a multiple of the size of data items being
1480 read and the data array pointer should be properly aligned.
1481 On some
1482 systems, not obeying these requirements may cause incorrect data to be
1483 read, on others it may cause a system crash.
1484 .Pp
1485 Read operations done by the
1486 .Fn bus_space_read_multi_N
1487 functions may be
1488 executed out of order with respect to other pending read and write
1489 operations unless order is enforced by use of the
1490 .Fn bus_space_barrier
1491 function.
1492 Because the
1493 .Fn bus_space_read_multi_N
1494 functions read the same bus space location multiple times, they
1495 place an implicit read barrier between each successive read of that bus
1496 space location.
1497 .Pp
1498 These functions will never fail.
1499 If they would fail (e.g.\& because of an
1500 argument error), that indicates a software bug which should cause a
1501 panic.
1502 In that case, they will never return.
1503 .Ss Fn bus_space_write_multi_1 space handle offset datap count
1504 .Ss Fn bus_space_write_multi_2 space handle offset datap count
1505 .Ss Fn bus_space_write_multi_4 space handle offset datap count
1506 .Ss Fn bus_space_write_multi_8 space handle offset datap count
1507 The
1508 .Fn bus_space_write_multi_N
1509 family of functions reads
1510 .Fa count
1511 1, 2, 4, or 8 byte data items from the array
1512 specified by
1513 .Fa datap
1514 and writes them into bus space at byte offset
1515 .Fa offset
1516 in the region specified by
1517 .Fa handle
1518 of the bus space specified by
1519 .Fa space .
1520 Each successive data item is written to the same location in
1521 bus space.
1522 The location being written must lie within the bus space
1523 region specified by
1524 .Fa handle .
1525 .Pp
1526 For portability, the starting address of the region specified by
1527 .Fa handle
1528 plus the offset should be a multiple of the size of data items being
1529 written and the data array pointer should be properly aligned.
1530 On some
1531 systems, not obeying these requirements may cause incorrect data to be
1532 written, on others it may cause a system crash.
1533 .Pp
1534 Write operations done by the
1535 .Fn bus_space_write_multi_N
1536 functions may be executed out of order with respect to other pending
1537 read and write operations unless order is enforced by use of the
1538 .Fn bus_space_barrier
1539 function.
1540 Because the
1541 .Fn bus_space_write_multi_N
1542 functions write the same bus space location multiple times, they
1543 place an implicit write barrier between each successive write of that
1544 bus space location.
1545 .Pp
1546 These functions will never fail.
1547 If they would fail (e.g.\& because of an
1548 argument error), that indicates a software bug which should cause a
1549 panic.
1550 In that case, they will never return.
1551 .Ss Fn bus_space_set_multi_1 space handle offset value count
1552 .Ss Fn bus_space_set_multi_2 space handle offset value count
1553 .Ss Fn bus_space_set_multi_4 space handle offset value count
1554 .Ss Fn bus_space_set_multi_8 space handle offset value count
1555 The
1556 .Fn bus_space_set_multi_N
1557 writes
1558 .Fa value
1559 into bus space at byte offset
1560 .Fa offset
1561 in the region specified by
1562 .Fa handle
1563 of the bus space specified by
1564 .Fa space ,
1565 .Fa count
1566 times.
1567 The location being written must lie within the bus space
1568 region specified by
1569 .Fa handle .
1570 .Pp
1571 For portability, the starting address of the region specified by
1572 .Fa handle
1573 plus the offset should be a multiple of the size of data items being
1574 written and the data array pointer should be properly aligned.
1575 On some
1576 systems, not obeying these requirements may cause incorrect data to be
1577 written, on others it may cause a system crash.
1578 .Pp
1579 Write operations done by the
1580 .Fn bus_space_set_multi_N
1581 functions may be executed out of order with respect to other pending
1582 read and write operations unless order is enforced by use of the
1583 .Fn bus_space_barrier
1584 function.
1585 Because the
1586 .Fn bus_space_set_multi_N
1587 functions write the same bus space location multiple times, they
1588 place an implicit write barrier between each successive write of that
1589 bus space location.
1590 .Pp
1591 These functions will never fail.
1592 If they would fail (e.g.\& because of an
1593 argument error), that indicates a software bug which should cause a
1594 panic.
1595 In that case, they will never return.
1596 .Sh STREAM FUNCTIONS
1597 Most of the
1598 .Nm
1599 functions imply a host byte-order and a bus byte-order and take care of
1600 any translation for the caller.
1601 In some cases, however, hardware may map a FIFO or some other memory region
1602 for which the caller may want to use multi-word, yet untranslated access.
1603 Access to these types of memory regions should be with the
1604 .Fn bus_space_*_stream_N
1605 functions.
1606 .Pp
1607 .Bl -tag -compact -width Fn
1608 .It Fn bus_space_read_stream_1
1609 .It Fn bus_space_read_stream_2
1610 .It Fn bus_space_read_stream_4
1611 .It Fn bus_space_read_stream_8
1612 .It Fn bus_space_read_multi_stream_1
1613 .It Fn bus_space_read_multi_stream_2
1614 .It Fn bus_space_read_multi_stream_4
1615 .It Fn bus_space_read_multi_stream_8
1616 .It Fn bus_space_read_region_stream_1
1617 .It Fn bus_space_read_region_stream_2
1618 .It Fn bus_space_read_region_stream_4
1619 .It Fn bus_space_read_region_stream_8
1620 .It Fn bus_space_write_stream_1
1621 .It Fn bus_space_write_stream_2
1622 .It Fn bus_space_write_stream_4
1623 .It Fn bus_space_write_stream_8
1624 .It Fn bus_space_write_multi_stream_1
1625 .It Fn bus_space_write_multi_stream_2
1626 .It Fn bus_space_write_multi_stream_4
1627 .It Fn bus_space_write_multi_stream_8
1628 .It Fn bus_space_write_region_stream_1
1629 .It Fn bus_space_write_region_stream_2
1630 .It Fn bus_space_write_region_stream_4
1631 .It Fn bus_space_write_region_stream_8
1632 .It Fn bus_space_copy_region_stream_1
1633 .It Fn bus_space_copy_region_stream_2
1634 .It Fn bus_space_copy_region_stream_4
1635 .It Fn bus_space_copy_region_stream_8
1636 .It Fn bus_space_set_multi_stream_1
1637 .It Fn bus_space_set_multi_stream_2
1638 .It Fn bus_space_set_multi_stream_4
1639 .It Fn bus_space_set_multi_stream_8
1640 .It Fn bus_space_set_region_stream_1
1641 .It Fn bus_space_set_region_stream_2
1642 .It Fn bus_space_set_region_stream_4
1643 .It Fn bus_space_set_region_stream_8
1644 .El
1645 .Pp
1646 These functions are defined just as their non-stream counterparts,
1647 except that they provide no byte-order translation.
1648 .Sh COMPATIBILITY
1649 The current
1650 .Nx
1651 version of the
1652 .Nm
1653 interface specification differs slightly from the original
1654 specification that came into wide use and
1655 .Fx
1656 adopted.
1657 A few of the function names and arguments have changed
1658 for consistency and increased functionality.
1659 .Sh SEE ALSO
1660 .Xr bus_dma 9
1661 .Sh HISTORY
1662 The
1663 .Nm
1664 functions were introduced in a different form (memory and I/O spaces
1665 were accessed via different sets of functions) in
1666 .Nx 1.2 .
1667 The functions were merged to work on generic
1668 .Dq spaces
1669 early in the
1670 .Nx 1.3
1671 development cycle, and many drivers were converted to use them.
1672 This document was written later during the
1673 .Nx 1.3
1674 development cycle, and the specification was updated to fix some
1675 consistency problems and to add some missing functionality.
1676 .Pp
1677 The manual page was then adapted to the version of the interface that
1678 .Fx
1679 imported for the CAM SCSI drivers, plus subsequent evolution.
1680 The
1681 .Fx
1682 .Nm
1683 version was imported in
1684 .Fx 3.0 .
1685 .Sh AUTHORS
1686 .An -nosplit
1687 The
1688 .Nm
1689 interfaces were designed and implemented by the
1690 .Nx
1691 developer
1692 community.
1693 Primary contributors and implementors were
1694 .An Chris Demetriou ,
1695 .An Jason Thorpe ,
1696 and
1697 .An Charles Hannum ,
1698 but the rest of the
1699 .Nx
1700 developers and the user community played a significant role in development.
1701 .Pp
1702 .An Justin Gibbs
1703 ported these interfaces to
1704 .Fx .
1705 .Pp
1706 .An Chris Demetriou
1707 wrote this manual page.
1708 .Pp
1709 .An Warner Losh
1710 modified it for the
1711 .Fx
1712 implementation.
1713 .Sh BUGS
1714 This manual may not completely and accurately document the interface,
1715 and many parts of the interface are unspecified.