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