1.\" $NetBSD: bus_space.9,v 1.53 2017/11/13 09:10:37 wiz Exp $ 2.\" 3.\" Copyright (c) 1997 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Christopher G. Demetriou. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd September 15, 2016 31.Dt BUS_SPACE 9 32.Os 33.Sh NAME 34.Nm bus_space , 35.Nm bus_space_barrier , 36.Nm bus_space_copy_region_1 , 37.Nm bus_space_copy_region_2 , 38.Nm bus_space_copy_region_4 , 39.Nm bus_space_copy_region_8 , 40.Nm bus_space_free , 41.Nm bus_space_handle_is_equal , 42.Nm bus_space_is_equal , 43.Nm bus_space_map , 44.Nm bus_space_mmap , 45.Nm bus_space_peek_1 , 46.Nm bus_space_peek_2 , 47.Nm bus_space_peek_4 , 48.Nm bus_space_peek_8 , 49.Nm bus_space_poke_1 , 50.Nm bus_space_poke_2 , 51.Nm bus_space_poke_4 , 52.Nm bus_space_poke_8 , 53.Nm bus_space_read_1 , 54.Nm bus_space_read_2 , 55.Nm bus_space_read_4 , 56.Nm bus_space_read_8 , 57.Nm bus_space_read_multi_1 , 58.Nm bus_space_read_multi_2 , 59.Nm bus_space_read_multi_4 , 60.Nm bus_space_read_multi_8 , 61.Nm bus_space_read_multi_stream_1 , 62.Nm bus_space_read_multi_stream_2 , 63.Nm bus_space_read_multi_stream_4 , 64.Nm bus_space_read_multi_stream_8 , 65.Nm bus_space_read_region_1 , 66.Nm bus_space_read_region_2 , 67.Nm bus_space_read_region_4 , 68.Nm bus_space_read_region_8 , 69.Nm bus_space_read_region_stream_1 , 70.Nm bus_space_read_region_stream_2 , 71.Nm bus_space_read_region_stream_4 , 72.Nm bus_space_read_region_stream_8 , 73.Nm bus_space_read_stream_1 , 74.Nm bus_space_read_stream_2 , 75.Nm bus_space_read_stream_4 , 76.Nm bus_space_read_stream_8 , 77.Nm bus_space_release , 78.Nm bus_space_reservation_addr , 79.Nm bus_space_reservation_init , 80.Nm bus_space_reservation_size , 81.Nm bus_space_reservation_map , 82.Nm bus_space_reservation_unmap , 83.Nm bus_space_reserve , 84.Nm bus_space_reserve_subregion , 85.Nm bus_space_set_region_1 , 86.Nm bus_space_set_region_2 , 87.Nm bus_space_set_region_4 , 88.Nm bus_space_set_region_8 , 89.Nm bus_space_subregion , 90.Nm bus_space_tag_create , 91.Nm bus_space_tag_destroy , 92.Nm bus_space_unmap , 93.Nm bus_space_vaddr , 94.Nm bus_space_write_1 , 95.Nm bus_space_write_2 , 96.Nm bus_space_write_4 , 97.Nm bus_space_write_8 , 98.Nm bus_space_write_multi_1 , 99.Nm bus_space_write_multi_2 , 100.Nm bus_space_write_multi_4 , 101.Nm bus_space_write_multi_8 , 102.Nm bus_space_write_multi_stream_1 , 103.Nm bus_space_write_multi_stream_2 , 104.Nm bus_space_write_multi_stream_4 , 105.Nm bus_space_write_multi_stream_8 , 106.Nm bus_space_write_region_1 , 107.Nm bus_space_write_region_2 , 108.Nm bus_space_write_region_4 , 109.Nm bus_space_write_region_8 , 110.Nm bus_space_write_region_stream_1 , 111.Nm bus_space_write_region_stream_2 , 112.Nm bus_space_write_region_stream_4 , 113.Nm bus_space_write_region_stream_8 , 114.Nm bus_space_write_stream_1 , 115.Nm bus_space_write_stream_2 , 116.Nm bus_space_write_stream_4 , 117.Nm bus_space_write_stream_8 118.Nd bus space manipulation functions 119.Sh SYNOPSIS 120.In sys/bus.h 121.Ft bool 122.Fn bus_space_handle_is_equal "bus_space_tag_t space" \ 123 "bus_space_handle_t handle1" "bus_space_handle_t handle2" 124.Ft bool 125.Fn bus_space_is_equal "bus_space_tag_t space1" "bus_space_tag_t space2" 126.Ft void 127.Fn bus_space_release "bus_space_tag_t t" "bus_space_reservation_t *bsr" 128.Ft int 129.Fn bus_space_reserve "bus_space_tag_t t" "bus_addr_t bpa" "bus_size_t size" \ 130 "int flags" "bus_space_reservation_t *bsrp" 131.Ft int 132.Fn bus_space_reserve_subregion "bus_space_tag_t t" \ 133 "bus_addr_t reg_start" "bus_addr_t reg_end" \ 134 "bus_size_t size" "bus_size_t alignment" "bus_size_t boundary" \ 135 "int flags" "bus_space_reservation_t *bsrp" 136.Ft void 137.Fn bus_space_reservation_init "bus_space_reservation_t *bsr" \ 138 "bus_addr_t addr" "bus_size_t size" 139.Ft bus_size_t 140.Fn bus_space_reservation_size "bus_space_reservation_t *bsr" 141.Ft int 142.Fn bus_space_reservation_map "bus_space_tag_t t" \ 143 "bus_space_reservation_t *bsr" "int flags" "bus_space_handle_t *bshp" 144.Ft void 145.Fn bus_space_reservation_unmap "bus_space_tag_t t" "bus_space_handle_t bsh" \ 146 "bus_size_t size" 147.Ft int 148.Fn bus_space_map "bus_space_tag_t space" "bus_addr_t address" \ 149"bus_size_t size" "int flags" "bus_space_handle_t *handlep" 150.Ft void 151.Fn bus_space_unmap "bus_space_tag_t space" "bus_space_handle_t handle" \ 152"bus_size_t size" 153.Ft int 154.Fn bus_space_subregion "bus_space_tag_t space" "bus_space_handle_t handle" \ 155"bus_size_t offset" "bus_size_t size" "bus_space_handle_t *nhandlep" 156.Ft int 157.Fo bus_space_alloc 158.Fa "bus_space_tag_t space" "bus_addr_t reg_start" "bus_addr_t reg_end" 159.Fa "bus_size_t size" "bus_size_t alignment" "bus_size_t boundary" 160.Fa "int flags" "bus_addr_t *addrp" "bus_space_handle_t *handlep" 161.Fc 162.Ft void 163.Fn bus_space_free "bus_space_tag_t space" "bus_space_handle_t handle" \ 164"bus_size_t size" 165.Ft void * 166.Fn bus_space_vaddr "bus_space_tag_t space" "bus_space_handle_t handle" 167.Ft paddr_t 168.Fn bus_space_mmap "bus_space_tag_t space" "bus_addr_t addr" "off_t off" \ 169"int prot" "int flags" 170.Ft int 171.Fn bus_space_tag_create "bus_space_tag_t obst" "uint64_t present" \ 172 "uint64_t extpresent" "const struct bus_space_overrides *ov" "void *ctx" \ 173 "bus_space_tag_t *bstp" 174.Ft void 175.Fn bus_space_tag_destroy "bus_space_tag_t bst" 176.Ft int 177.Fn bus_space_peek_1 "bus_space_tag_t space" "bus_space_handle_t handle" \ 178"bus_size_t offset" "uint8_t *datap" 179.Ft int 180.Fn bus_space_peek_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ 181"bus_size_t offset" "uint16_t *datap" 182.Ft int 183.Fn bus_space_peek_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ 184"bus_size_t offset" "uint32_t *datap" 185.Ft int 186.Fn bus_space_peek_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ 187"bus_size_t offset" "uint64_t *datap" 188.Ft int 189.Fn bus_space_poke_1 "bus_space_tag_t space" "bus_space_handle_t handle" \ 190"bus_size_t offset" "uint8_t data" 191.Ft int 192.Fn bus_space_poke_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ 193"bus_size_t offset" "uint16_t data" 194.Ft int 195.Fn bus_space_poke_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ 196"bus_size_t offset" "uint32_t data" 197.Ft int 198.Fn bus_space_poke_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ 199"bus_size_t offset" "uint64_t data" 200.Ft uint8_t 201.Fn bus_space_read_1 "bus_space_tag_t space" "bus_space_handle_t handle" \ 202"bus_size_t offset" 203.Ft uint16_t 204.Fn bus_space_read_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ 205"bus_size_t offset" 206.Ft uint32_t 207.Fn bus_space_read_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ 208"bus_size_t offset" 209.Ft uint64_t 210.Fn bus_space_read_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ 211"bus_size_t offset" 212.Ft void 213.Fn bus_space_write_1 "bus_space_tag_t space" "bus_space_handle_t handle" \ 214"bus_size_t offset" "uint8_t value" 215.Ft void 216.Fn bus_space_write_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ 217"bus_size_t offset" "uint16_t value" 218.Ft void 219.Fn bus_space_write_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ 220"bus_size_t offset" "uint32_t value" 221.Ft void 222.Fn bus_space_write_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ 223"bus_size_t offset" "uint64_t value" 224.Ft void 225.Fn bus_space_barrier "bus_space_tag_t space" "bus_space_handle_t handle" \ 226"bus_size_t offset" "bus_size_t length" "int flags" 227.Ft void 228.Fn bus_space_read_region_1 "bus_space_tag_t space" \ 229"bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" \ 230"bus_size_t count" 231.Ft void 232.Fn bus_space_read_region_2 "bus_space_tag_t space" \ 233"bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" \ 234"bus_size_t count" 235.Ft void 236.Fn bus_space_read_region_4 "bus_space_tag_t space" \ 237"bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" \ 238"bus_size_t count" 239.Ft void 240.Fn bus_space_read_region_8 "bus_space_tag_t space" \ 241"bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" \ 242"bus_size_t count" 243.Ft void 244.Fn bus_space_read_region_stream_1 "bus_space_tag_t space" \ 245"bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" \ 246"bus_size_t count" 247.Ft void 248.Fn bus_space_read_region_stream_2 "bus_space_tag_t space" \ 249"bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" \ 250"bus_size_t count" 251.Ft void 252.Fn bus_space_read_region_stream_4 "bus_space_tag_t space" \ 253"bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" \ 254"bus_size_t count" 255.Ft void 256.Fn bus_space_read_region_stream_8 "bus_space_tag_t space" \ 257"bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" \ 258"bus_size_t count" 259.Ft void 260.Fn bus_space_write_region_1 "bus_space_tag_t space" \ 261"bus_space_handle_t handle" "bus_size_t offset" "const uint8_t *datap" \ 262"bus_size_t count" 263.Ft void 264.Fn bus_space_write_region_2 "bus_space_tag_t space" \ 265"bus_space_handle_t handle" "bus_size_t offset" "const uint16_t *datap" \ 266"bus_size_t count" 267.Ft void 268.Fn bus_space_write_region_4 "bus_space_tag_t space" \ 269"bus_space_handle_t handle" "bus_size_t offset" "const uint32_t *datap" \ 270"bus_size_t count" 271.Ft void 272.Fn bus_space_write_region_8 "bus_space_tag_t space" \ 273"bus_space_handle_t handle" "bus_size_t offset" "const uint64_t *datap" \ 274"bus_size_t count" 275.Ft void 276.Fn bus_space_write_region_stream_1 "bus_space_tag_t space" \ 277"bus_space_handle_t handle" "bus_size_t offset" "const uint8_t *datap" \ 278"bus_size_t count" 279.Ft void 280.Fn bus_space_write_region_stream_2 "bus_space_tag_t space" \ 281"bus_space_handle_t handle" "bus_size_t offset" "const uint16_t *datap" \ 282"bus_size_t count" 283.Ft void 284.Fn bus_space_write_region_stream_4 "bus_space_tag_t space" \ 285"bus_space_handle_t handle" "bus_size_t offset" "const uint32_t *datap" \ 286"bus_size_t count" 287.Ft void 288.Fn bus_space_write_region_stream_8 "bus_space_tag_t space" \ 289"bus_space_handle_t handle" "bus_size_t offset" "const uint64_t *datap" \ 290"bus_size_t count" 291.Ft void 292.Fn bus_space_copy_region_1 "bus_space_tag_t space" \ 293"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ 294"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" 295.Ft void 296.Fn bus_space_copy_region_2 "bus_space_tag_t space" \ 297"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ 298"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" 299.Ft void 300.Fn bus_space_copy_region_4 "bus_space_tag_t space" \ 301"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ 302"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" 303.Ft void 304.Fn bus_space_copy_region_8 "bus_space_tag_t space" \ 305"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ 306"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" 307.Ft void 308.Fn bus_space_set_region_1 "bus_space_tag_t space" \ 309"bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" \ 310"bus_size_t count" 311.Ft void 312.Fn bus_space_set_region_2 "bus_space_tag_t space" \ 313"bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" \ 314"bus_size_t count" 315.Ft void 316.Fn bus_space_set_region_4 "bus_space_tag_t space" \ 317"bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" \ 318"bus_size_t count" 319.Ft void 320.Fn bus_space_set_region_8 "bus_space_tag_t space" \ 321"bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" \ 322"bus_size_t count" 323.Ft void 324.Fn bus_space_read_multi_1 "bus_space_tag_t space" \ 325"bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" \ 326"bus_size_t count" 327.Ft void 328.Fn bus_space_read_multi_2 "bus_space_tag_t space" \ 329"bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" \ 330"bus_size_t count" 331.Ft void 332.Fn bus_space_read_multi_4 "bus_space_tag_t space" \ 333"bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" \ 334"bus_size_t count" 335.Ft void 336.Fn bus_space_read_multi_8 "bus_space_tag_t space" \ 337"bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" \ 338"bus_size_t count" 339.Ft void 340.Fn bus_space_read_multi_stream_1 "bus_space_tag_t space" \ 341"bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" \ 342"bus_size_t count" 343.Ft void 344.Fn bus_space_read_multi_stream_2 "bus_space_tag_t space" \ 345"bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" \ 346"bus_size_t count" 347.Ft void 348.Fn bus_space_read_multi_stream_4 "bus_space_tag_t space" \ 349"bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" \ 350"bus_size_t count" 351.Ft void 352.Fn bus_space_read_multi_stream_8 "bus_space_tag_t space" \ 353"bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" \ 354"bus_size_t count" 355.Ft void 356.Fn bus_space_write_multi_1 "bus_space_tag_t space" \ 357"bus_space_handle_t handle" "bus_size_t offset" "const uint8_t *datap" \ 358"bus_size_t count" 359.Ft void 360.Fn bus_space_write_multi_2 "bus_space_tag_t space" \ 361"bus_space_handle_t handle" "bus_size_t offset" "const uint16_t *datap" \ 362"bus_size_t count" 363.Ft void 364.Fn bus_space_write_multi_4 "bus_space_tag_t space" \ 365"bus_space_handle_t handle" "bus_size_t offset" "const uint32_t *datap" \ 366"bus_size_t count" 367.Ft void 368.Fn bus_space_write_multi_8 "bus_space_tag_t space" \ 369"bus_space_handle_t handle" "bus_size_t offset" "const uint64_t *datap" \ 370"bus_size_t count" 371.Ft void 372.Fn bus_space_write_multi_stream_1 "bus_space_tag_t space" \ 373"bus_space_handle_t handle" "bus_size_t offset" "const uint8_t *datap" \ 374"bus_size_t count" 375.Ft void 376.Fn bus_space_write_multi_stream_2 "bus_space_tag_t space" \ 377"bus_space_handle_t handle" "bus_size_t offset" "const uint16_t *datap" \ 378"bus_size_t count" 379.Ft void 380.Fn bus_space_write_multi_stream_4 "bus_space_tag_t space" \ 381"bus_space_handle_t handle" "bus_size_t offset" "const uint32_t *datap" \ 382"bus_size_t count" 383.Ft void 384.Fn bus_space_write_multi_stream_8 "bus_space_tag_t space" \ 385"bus_space_handle_t handle" "bus_size_t offset" "const uint64_t *datap" \ 386"bus_size_t count" 387.Sh DESCRIPTION 388The 389.Nm 390functions exist to allow device drivers 391machine-independent access to bus memory and register areas. 392All of the functions and types described in this document can be used 393by including the 394.In sys/bus.h 395header file. 396.Pp 397Many common devices are used on multiple architectures, but are accessed 398differently on each because of architectural constraints. 399For instance, a device which is mapped in one system's I/O space may be 400mapped in memory space on a second system. 401On a third system, architectural limitations might change the way 402registers need to be accessed (e.g., creating a non-linear register space). 403In some cases, a single 404driver may need to access the same type of device in multiple ways in a 405single system or architecture. 406The goal of the 407.Nm 408functions is to allow a single driver source file to manipulate a set 409of devices on different system architectures, and to allow a single driver 410object file to manipulate a set of devices on multiple bus types on a 411single architecture. 412.Pp 413Not all busses have to implement all functions described in this 414document, though that is encouraged if the operations are logically 415supported by the bus. 416Unimplemented functions should cause compile-time errors if possible. 417.Pp 418All of the interface definitions described in this document are shown as 419function prototypes and discussed as if they were required to be 420functions. 421Implementations are encouraged to implement prototyped (type-checked) 422versions of these interfaces, but may implement them as macros if appropriate. 423Machine-dependent types, variables, and functions should be marked clearly in 424.In machine/bus_defs.h 425and in 426.In machine/bus_funcs.h 427to avoid confusion with the 428machine-independent types and functions, and, if possible, should be 429given names which make the machine-dependence clear. 430.Sh CONCEPTS AND GUIDELINES 431Bus spaces are described by bus space tags, which can be created only by 432machine-dependent code. 433A given machine may have several different types of bus space 434(e.g., memory space and I/O space), and thus may provide multiple different 435bus space tags. 436Individual busses or devices on a machine may use more than one bus space 437tag. 438For instance, ISA devices are given an ISA memory space tag and an 439ISA I/O space tag. 440Architectures may have several different tags which represent the same 441type of space, for instance because of multiple different host bus 442interface chipsets. 443.Pp 444A range in bus space is described by a bus address and a bus size. 445The bus address describes the start of the range in bus space. 446The bus size describes the size of the range in bytes. 447Busses which are not byte addressable may require use of bus space ranges 448with appropriately aligned addresses and properly rounded sizes. 449.Pp 450Access to regions of bus space is facilitated by use of bus space handles, 451which are usually created by mapping a specific range of a bus space. 452Handles may also be created by allocating 453and mapping a range of bus space, the actual location of which is picked 454by the implementation within bounds specified by the caller of the 455allocation function. 456.Pp 457All of the bus space access functions require one bus space tag 458argument, at least one handle argument, and at least one offset argument 459(a bus size). 460The bus space tag specifies the space, each handle specifies a region in 461the space, and each offset specifies the offset into the region of the 462actual location(s) to be accessed. 463Offsets are given in bytes, though busses may impose alignment constraints. 464The offset used to access data relative to a given handle must be such 465that all of the data being accessed is in the mapped region that the 466handle describes. 467Trying to access data outside that region is an error. 468.Pp 469Because some architectures' memory systems use buffering to improve 470memory and device access performance, there is a mechanism which can be 471used to create 472.Dq barriers 473in the bus space read and write stream. 474.Pp 475There are two types of barriers: ordering barriers and completion 476barriers. 477.Pp 478Ordering barriers prevent some operations from bypassing other 479operations. 480They are relatively light weight and described in terms of the 481operations they are intended to order. 482The important thing to note is that they create specific ordering 483constraint surrounding bus accesses but do not necessarily force any 484synchronization themselves. 485So, if there is enough distance between the memory operations being 486ordered, the preceding ones could complete by themselves resulting 487in no performance penalty. 488.Pp 489For instance, a write before read barrier will force any writes 490issued before the barrier instruction to complete before any reads 491after the barrier are issued. 492This forces processors with write buffers to read data from memory rather 493than from the pending write in the write buffer. 494.Pp 495Ordering barriers are usually sufficient for most circumstances, 496and can be combined together. 497For instance a read before write barrier can be combined with a write 498before write barrier to force all memory operations to complete before 499the next write is started. 500.Pp 501Completion barriers force all memory operations and any pending 502exceptions to be completed before any instructions after the 503barrier may be issued. 504Completion barriers are extremely expensive and almost never required 505in device driver code. 506A single completion barrier can force the processor to stall on memory 507for hundreds of cycles on some machines. 508.Pp 509Correctly-written drivers will include all appropriate barriers, 510and assume only the read/write ordering imposed by the barrier 511operations. 512.Pp 513People trying to write portable drivers with the 514.Nm 515functions should 516try to make minimal assumptions about what the system allows. 517In particular, they should expect that the system requires bus space 518addresses being accessed to be naturally aligned (i.e., base address of 519handle added to offset is a multiple of the access size), and that the 520system does alignment checking on pointers (i.e., pointer to objects being 521read and written must point to properly-aligned data). 522.Pp 523The descriptions of the 524.Nm 525functions given below all assume that 526they are called with proper arguments. 527If called with invalid arguments or arguments that are out of range 528(e.g., trying to access data outside of the region mapped when a given 529handle was created), undefined behaviour results. 530In that case, they may cause the system to halt, either intentionally 531(via panic) or unintentionally (by causing a fatal trap or by some other 532means) or may cause improper operation which is not immediately fatal. 533Functions which return void or which return data read from bus space 534(i.e., functions which don't obviously return an error code) do not fail. 535They could only fail if given invalid arguments, and in that case their 536behaviour is undefined. 537Functions which take a count of bytes have undefined results if the specified 538.Fa count 539is zero. 540.Sh TYPES 541Several types are defined in 542.In machine/bus_defs.h 543to facilitate use of the 544.Nm 545functions by drivers. 546.Pp 547.Bl -ohang -compact 548.It Fa bus_addr_t 549.Pp 550The 551.Fa bus_addr_t 552type is used to describe bus addresses. 553It must be an unsigned integral type capable of holding the largest bus 554address usable by the architecture. 555This type is primarily used when mapping and unmapping bus space. 556.Pp 557.It Fa bus_size_t 558.Pp 559The 560.Fa bus_size_t 561type is used to describe sizes of ranges in bus space. 562It must be an unsigned integral type capable of holding the size of the 563largest bus address range usable on the architecture. 564This type is used by virtually all of the 565.Nm 566functions, describing sizes when mapping regions and 567offsets into regions when performing space access operations. 568.Pp 569.It Fa bus_space_tag_t 570.Pp 571The 572.Fa bus_space_tag_t 573type is used to describe a particular bus space on a machine. 574Its contents are machine-dependent and should be considered opaque by 575machine-independent code. 576This type is used by all 577.Nm 578functions to name the space on which they're operating. 579.Pp 580.It Fa bus_space_handle_t 581.Pp 582The 583.Fa bus_space_handle_t 584type is used to describe a mapping of a range of bus space. 585Its contents are machine-dependent and should be considered opaque by 586machine-independent code. 587This type is used when performing bus space access operations. 588.Pp 589.It Fa bus_space_reservation_t 590.Pp 591The 592.Fa bus_space_reservation_t 593type is used to describe a range of bus space. 594It logically consists of a 595.Fa bus_addr_t , 596the first address in the range, 597and a 598.Fa bus_size_t , 599the length in bytes of the range. 600Machine-independent code creates and interrogates a 601.Fa bus_space_reservation_t 602using a constructor, 603.Fn bus_space_reservation_init , 604and accessor functions, 605.Fn bus_space_reservation_addr 606and 607.Fn bus_space_reservation_size . 608.El 609.Sh COMPARING BUS SPACE TAGS 610To check whether or not one 611.Fa bus_space_tag_t 612refers to the same space as another in machine-independent code, 613do not use either 614.Xr memcmp 9 615or the C equals 616.Po 617== 618.Pc 619operator. 620Use 621.Fn bus_space_is_equal , 622instead. 623.Sh MAPPING AND UNMAPPING BUS SPACE 624Bus space must be mapped before it can be used, and should be 625unmapped when it is no longer needed. 626The 627.Fn bus_space_map , 628.Fn bus_space_reservation_map , 629.Fn bus_space_reservation_unmap , 630and 631.Fn bus_space_unmap 632functions provide these capabilities. 633.Pp 634Some drivers need to be able to pass a subregion of already-mapped bus 635space to another driver or module within a driver. 636The 637.Fn bus_space_subregion 638function allows such subregions to be created. 639.Pp 640.Bl -ohang -compact 641.It Fn bus_space_map "space" "address" "size" "flags" "handlep" 642.Pp 643The 644.Fn bus_space_map 645function exclusively reserves and maps the region of bus space named by the 646.Fa space , 647.Fa address , 648and 649.Fa size 650arguments. 651If successful, it returns zero and fills in the bus space handle pointed 652to by 653.Fa handlep 654with the handle 655that can be used to access the mapped region. 656If unsuccessful, it will return non-zero and leave the bus space handle 657pointed to by 658.Fa handlep 659in an undefined state. 660.Pp 661The 662.Fa flags 663argument controls how the space is to be mapped. 664Supported flags include: 665.Bl -tag -width BUS_SPACE_MAP_CACHEABLE -offset indent 666.It Dv BUS_SPACE_MAP_CACHEABLE 667Try to map the space so that accesses can be cached 668by the system cache. 669If this flag is not specified, the implementation should map the space so 670that it will not be cached. 671This mapping method will only be useful in very rare occasions. 672.Pp 673This flag must have a value of 1 on all implementations for backward 674compatibility. 675.It Dv BUS_SPACE_MAP_PREFETCHABLE 676Try to map the space so that accesses can be prefetched by the system, 677and writes can be buffered. 678This means, accesses should be side effect free (idempotent). 679The 680.Fn bus_space_barrier 681methods will flush the write buffer or force actual read accesses. 682If this flag is not specified, the 683implementation should map the space so that it will not be prefetched 684or delayed. 685.It Dv BUS_SPACE_MAP_LINEAR 686Try to map the space so that its contents can be accessed linearly via 687normal memory access methods (e.g., pointer dereferencing and structure 688accesses). 689The 690.Fn bus_space_vaddr 691method can be used to obtain the kernel virtual address of the mapped range. 692This is useful when software wants to do direct access to a memory 693device, e.g., a frame buffer. 694If this flag is specified and linear mapping is not possible, the 695.Fn bus_space_map 696call should fail. 697If this flag is not specified, the system may map the space in whatever 698way is most convenient. 699Use of this mapping method is not encouraged for normal device access; 700where linear access is not essential, use of the 701.Fn bus_space_read/write 702methods is strongly recommended. 703.El 704.Pp 705Not all combinations of flags make sense or are supported with all 706spaces. 707For instance, 708.Dv BUS_SPACE_MAP_CACHEABLE 709may be meaningless when 710used on many systems' I/O port spaces, and on some systems 711.Dv BUS_SPACE_MAP_LINEAR 712without 713.Dv BUS_SPACE_MAP_PREFETCHABLE 714may never work. 715When the system hardware or firmware provides hints as to how spaces should be 716mapped (e.g., the PCI memory mapping registers' "prefetchable" bit), those 717hints should be followed for maximum compatibility. 718On some systems, requesting a mapping that cannot be satisfied (e.g., 719requesting a non-prefetchable mapping when the system can only provide 720a prefetchable one) will cause the request to fail. 721.Pp 722Some implementations may keep track of use of bus space for some or all 723bus spaces and refuse to allow duplicate allocations. 724This is encouraged for bus spaces which have no notion of slot-specific 725space addressing, such as ISA and VME, and for spaces which coexist with 726those spaces (e.g., EISA and PCI memory and I/O spaces co-existing with 727ISA memory and I/O spaces). 728.Pp 729Mapped regions may contain areas for which there is no device on the bus. 730If space in those areas is accessed, the results are bus-dependent. 731.Pp 732.It Fn bus_space_reservation_map "space" "bsr" "flags" "handlep" 733.Pp 734The 735.Fn bus_space_reservation_map 736function is similar to 737.Fn bus_space_map 738but it maps a region of bus space 739that was previously reserved by a call to 740.Fn bus_space_reserve 741or 742.Fn bus_space_reserve_subregion . 743The region is given by the 744.Fa space 745and 746.Fa bsr 747arguments. 748If successful, it returns zero and fills in the bus space handle pointed 749to by 750.Fa handlep 751with the handle that can be used to access the mapped region. 752If unsuccessful, it will return non-zero and leave the bus space handle 753pointed to by 754.Fa handlep 755in an undefined state. 756.Pp 757A region mapped by 758.Fn bus_space_reservation_map 759may only be unmapped by a call to 760.Fn bus_space_reservation_unmap . 761.Pp 762For more details, see the description of 763.Fn bus_space_map . 764.Pp 765.It Fn bus_space_unmap "space" "handle" "size" 766.Pp 767The 768.Fn bus_space_unmap 769function unmaps and relinquishes a region of bus space reserved and 770mapped with 771.Fn bus_space_map . 772When unmapping a region, the 773.Fa size 774specified should be 775the same as the size given to 776.Fn bus_space_map 777when mapping that region. 778.Pp 779After 780.Fn bus_space_unmap 781is called on a handle, that handle is no longer valid. 782(If copies were made of the handle they are no longer valid, either.) 783.Pp 784This function will never fail. 785If it would fail (e.g., because of an argument error), that indicates 786a software bug which should cause a panic. 787In that case, 788.Fn bus_space_unmap 789will never return. 790.Pp 791.It Fn bus_space_reservation_unmap "space" "handle" "size" 792.Pp 793The 794.Fn bus_space_reservation_unmap 795function is similar to 796.Fn bus_space_unmap 797but it should be called on handles 798mapped by 799.Fn bus_space_reservation_map 800and only on such handles. 801Unlike 802.Fn bus_space_unmap , 803.Fn bus_space_reservation_unmap 804does not relinquish exclusive use of the bus space named by 805.Fa handle 806and 807.Fa size ; 808that is the job of 809.Fn bus_space_release . 810.Pp 811.It Fn bus_space_subregion "space" "handle" "offset" "size" "nhandlep" 812.Pp 813The 814.Fn bus_space_subregion 815function is a convenience function which makes a 816new handle to some subregion of an already-mapped region of bus space. 817The subregion described by the new handle starts at byte offset 818.Fa offset 819into the region described by 820.Fa handle , 821with the size given by 822.Fa size , 823and must be wholly contained within the original region. 824.Pp 825If successful, 826.Fn bus_space_subregion 827returns zero and fills in the bus 828space handle pointed to by 829.Fa nhandlep . 830If unsuccessful, it returns non-zero and leaves the bus space handle 831pointed to by 832.Fa nhandlep 833in an 834undefined state. 835In either case, the handle described by 836.Fa handle 837remains valid and is unmodified. 838.Pp 839When done with a handle created by 840.Fn bus_space_subregion , 841the handle should 842be thrown away. 843Under no circumstances should 844.Fn bus_space_unmap 845be used on the handle. 846Doing so may confuse any resource management being done on the space, 847and will result in undefined behaviour. 848When 849.Fn bus_space_unmap 850or 851.Fn bus_space_free 852is called on a handle, all subregions of that handle become invalid. 853.Pp 854.It Fn bus_space_vaddr "tag" "handle" 855.Pp 856This method returns the kernel virtual address of a mapped bus space if and 857only if it was mapped with the 858.Dv BUS_SPACE_MAP_LINEAR 859flag. 860The range can be accessed by normal (volatile) pointer dereferences. 861If mapped with the 862.Dv BUS_SPACE_MAP_PREFETCHABLE 863flag, the 864.Fn bus_space_barrier 865method must be used to force a particular access order. 866.Pp 867.It Fn bus_space_mmap "tag" "addr" "off" "prot" "flags" 868.Pp 869This method is used to provide support for memory mapping bus space 870into user applications. 871If an address space is addressable via volatile pointer dereferences, 872.Fn bus_space_mmap 873will return the physical address (possibly encoded as a machine-dependent 874cookie) of the bus space indicated by 875.Fa addr 876and 877.Fa off . 878.Fa addr 879is the base address of the device or device region, and 880.Fa off 881is the offset into that region that is being requested. 882If the request is made with 883.Dv BUS_SPACE_MAP_LINEAR 884as a flag, then a linear region must be returned to the caller. 885If the region cannot be mapped (either the address does not exist, 886or the constraints can not be met), 887.Fn bus_space_mmap 888returns 889.Dv -1 890to indicate failure. 891.Pp 892Note that it is not necessary that the region being requested by a 893.Fn bus_space_mmap 894call be mapped into a 895.Fa bus_space_handle_t . 896.Pp 897.Fn bus_space_mmap 898is called once per 899.Dv PAGE_SIZE 900page in the range. 901The 902.Fa prot 903argument indicates the memory protection requested by the user application 904for the range. 905.Pp 906.It Fn bus_space_handle_is_equal "space" "handle1" "handle2" 907Use 908.Fn bus_space_handle_is_equal 909to check whether or not 910.Fa handle1 911and 912.Fa handle2 913refer to regions starting at the same address in the bus space 914.Fa space . 915.El 916.Sh ALLOCATING AND FREEING BUS SPACE 917Some devices require or allow bus space to be allocated by the operating 918system for device use. 919When the devices no longer need the space, the 920operating system should free it for use by other devices. 921The 922.Fn bus_space_alloc , 923.Fn bus_space_free , 924.Fn bus_space_reserve , 925.Fn bus_space_reserve_subregion , 926and 927.Fn bus_space_release 928functions provide these capabilities. 929The functions 930.Fn bus_space_reserve , 931.Fn bus_space_reserve_subregion , 932and 933.Fn bus_space_release 934are not yet available on all architectures. 935.Pp 936.Bl -ohang -compact 937.It Fn bus_space_alloc "space" "reg_start" "reg_end" "size" "alignment" \ 938"boundary" "flags" "addrp" "handlep" 939.Pp 940The 941.Fn bus_space_alloc 942function allocates and maps a region of bus space with the size given by 943.Fa size , 944corresponding to the given constraints. 945If successful, it returns zero, fills in the bus address pointed to by 946.Fa addrp 947with the bus space address of the allocated region, and fills in 948the bus space handle pointed to by 949.Fa handlep 950with the handle that can be used to access that region. 951If unsuccessful, it returns non-zero and leaves the bus address pointed to by 952.Fa addrp 953and the bus space handle pointed to by 954.Fa handlep 955in an undefined state. 956.Pp 957Constraints on the allocation are given by the 958.Fa reg_start , 959.Fa reg_end , 960.Fa alignment , 961and 962.Fa boundary 963parameters. 964The allocated region will start at or after 965.Fa reg_start 966and end before or at 967.Fa reg_end . 968The 969.Fa alignment 970constraint must be a power of two, and the allocated region will start at 971an address that is an even multiple of that power of two. 972The 973.Fa boundary 974constraint, if non-zero, ensures that the region is allocated so that 975.Fa "first address in region" 976/ 977.Fa boundary 978has the same value as 979.Fa "last address in region" 980/ 981.Fa boundary . 982If the constraints cannot be met, 983.Fn bus_space_alloc 984will fail. 985It is an error to specify a set of constraints that can never be met 986.Po 987for example, 988.Fa size 989greater than 990.Fa boundary 991.Pc . 992.Pp 993The 994.Fa flags 995parameter is the same as the like-named parameter to 996.Fa bus_space_map , 997the same flag values should be used, and they have the 998same meanings. 999.Pp 1000Handles created by 1001.Fn bus_space_alloc 1002should only be freed with 1003.Fn bus_space_free . 1004Trying to use 1005.Fn bus_space_unmap 1006on them causes undefined behaviour. 1007The 1008.Fn bus_space_subregion 1009function can be used on handles created by 1010.Fn bus_space_alloc . 1011.Pp 1012.It Fn bus_space_reserve "t" "bpa" "size" "flags" "bsrp" 1013.Pp 1014The 1015.Fn bus_space_reserve 1016function reserves, for the caller's exclusive use, 1017.Fa size 1018bytes starting at the address 1019.Fa bpa 1020in the space referenced by 1021.Fa t . 1022.Pp 1023.Fn bus_space_reserve 1024does 1025.Em not 1026map the space. 1027The caller should use 1028.Fn bus_space_reservation_map 1029to map the reservation. 1030.Fa flags 1031contains a hint how the caller may map the reservation, later. 1032Whenever possible, callers should pass the same flags to 1033.Fn bus_space_reserve 1034as they will pass to 1035.Fn bus_space_reservation_map 1036to map the reservation. 1037.Pp 1038On success, 1039.Fn bus_space_reserve 1040records the reservation at 1041.Fa bsrp 1042and returns 0. 1043On failure, 1044.Fa bsrp 1045is undefined, and 1046.Fn bus_space_reserve 1047returns a non-zero error code. 1048Possible error codes include 1049.Bl -tag -width EOPNOTSUPP -offset indent 1050.It Er ENOMEM 1051There was not sufficient bus space at 1052.Fa bpa 1053to satisfy the request. 1054.It Er EOPNOTSUPP 1055.Fn bus_space_reserve 1056is not supported on this architecture, or 1057.Fa flags 1058was incompatible with the bus space represented by 1059.Fa t . 1060.El 1061.Pp 1062.It Fn bus_space_reserve_subregion "t" "reg_start" "reg_end" \ 1063 "size" "alignment" "boundary" "flags" "bsrp" 1064.Pp 1065The 1066.Fn bus_space_reserve_subregion 1067function reserves, for the caller's exclusive use, 1068.Fa size 1069bytes in the space referenced by 1070.Fa t . 1071The parameters 1072.Fa reg_start , 1073.Fa reg_end , 1074.Fa alignment , 1075.Fa boundary , 1076and 1077.Fa flags 1078each work alike to the 1079.Fn bus_space_alloc 1080parameters of the same names. 1081.Pp 1082On success, 1083.Fn bus_space_reserve_subregion 1084records the reservation at 1085.Fa bsrp 1086and returns 0. 1087On failure, 1088.Fa bsrp 1089is undefined, and 1090.Fn bus_space_reserve_subregion 1091returns a non-zero error code. 1092Possible error codes include 1093.Bl -tag -width EOPNOTSUPP -offset indent 1094.It Er ENOMEM 1095There was not sufficient bus space at 1096.Fa bpa 1097to satisfy the request. 1098.It Er EOPNOTSUPP 1099.Fn bus_space_reserve 1100is not supported on this architecture, or 1101.Fa flags 1102was incompatible with the bus space represented by 1103.Fa t . 1104.El 1105.Pp 1106.It Fn bus_space_release "t" "bsr" 1107.Pp 1108The 1109.Fn bus_space_release 1110function releases the bus space 1111.Fa bsr 1112in 1113.Fa t 1114that was previously reserved by 1115.Fn bus_space_reserve 1116or 1117.Fn bus_space_reserve_subregion . 1118.Pp 1119If 1120.Fn bus_space_release 1121is called on a reservation that has been mapped by 1122.Fn bus_space_reservation_map 1123without subsequently being unmapped, the behavior of the system is 1124undefined. 1125.Pp 1126.It Fn bus_space_free "space" "handle" "size" 1127.Pp 1128The 1129.Fn bus_space_free 1130function unmaps and frees a region of bus space mapped 1131and allocated with 1132.Fn bus_space_alloc . 1133When unmapping a region, the 1134.Fa size 1135specified should be the same as the size given to 1136.Fn bus_space_alloc 1137when allocating the region. 1138.Pp 1139After 1140.Fn bus_space_free 1141is called on a handle, that handle is no longer valid. 1142(If copies were made of the handle, they are no longer valid, either.) 1143.Pp 1144This function will never fail. 1145If it would fail (e.g., because of an argument error), that indicates 1146a software bug which should cause a panic. 1147In that case, 1148.Fn bus_space_free 1149will never return. 1150.El 1151.Sh READING AND WRITING SINGLE DATA ITEMS 1152The simplest way to access bus space is to read or write a single data 1153item. 1154The 1155.Fn bus_space_read_N 1156and 1157.Fn bus_space_write_N 1158families of functions provide 1159the ability to read and write 1, 2, 4, and 8 byte data items on busses 1160which support those access sizes. 1161.Pp 1162.Bl -ohang -compact 1163.It Fn bus_space_read_1 "space" "handle" "offset" 1164.It Fn bus_space_read_2 "space" "handle" "offset" 1165.It Fn bus_space_read_4 "space" "handle" "offset" 1166.It Fn bus_space_read_8 "space" "handle" "offset" 1167.Pp 1168The 1169.Fn bus_space_read_N 1170family of functions reads a 1, 2, 4, or 8 byte data item from 1171the offset specified by 1172.Fa offset 1173into the region specified by 1174.Fa handle 1175of the bus space specified by 1176.Fa space . 1177The location being read must lie within the bus space region specified by 1178.Fa handle . 1179.Pp 1180For portability, the starting address of the region specified by 1181.Fa handle 1182plus the offset should be a multiple of the size of data item being read. 1183On some systems, not obeying this requirement may cause incorrect data to 1184be read, on others it may cause a system crash. 1185.Pp 1186Read operations done by the 1187.Fn bus_space_read_N 1188functions may be executed out 1189of order with respect to other pending read and write operations unless 1190order is enforced by use of the 1191.Fn bus_space_barrier 1192function. 1193.Pp 1194These functions will never fail. 1195If they would fail (e.g., because of an argument error), that indicates 1196a software bug which should cause a panic. 1197In that case, they will never return. 1198.Pp 1199.It Fn bus_space_write_1 "space" "handle" "offset" "value" 1200.It Fn bus_space_write_2 "space" "handle" "offset" "value" 1201.It Fn bus_space_write_4 "space" "handle" "offset" "value" 1202.It Fn bus_space_write_8 "space" "handle" "offset" "value" 1203.Pp 1204The 1205.Fn bus_space_write_N 1206family of functions writes a 1, 2, 4, or 8 byte data item to the offset 1207specified by 1208.Fa offset 1209into the region specified by 1210.Fa handle 1211of the bus space specified by 1212.Fa space . 1213The location being written must lie within 1214the bus space region specified by 1215.Fa handle . 1216.Pp 1217For portability, the starting address of the region specified by 1218.Fa handle 1219plus the offset should be a multiple of the size of data item being 1220written. 1221On some systems, not obeying this requirement may cause incorrect data 1222to be written, on others it may cause a system crash. 1223.Pp 1224Write operations done by the 1225.Fn bus_space_write_N 1226functions may be executed 1227out of order with respect to other pending read and write operations 1228unless order is enforced by use of the 1229.Fn bus_space_barrier 1230function. 1231.Pp 1232These functions will never fail. 1233If they would fail (e.g., because of an argument error), that indicates 1234a software bug which should cause a panic. 1235In that case, they will never return. 1236.El 1237.Sh PROBING BUS SPACE FOR HARDWARE WHICH MAY NOT RESPOND 1238One problem with the 1239.Fn bus_space_read_N 1240and 1241.Fn bus_space_write_N 1242family of functions is that they provide no protection against 1243exceptions which can occur when no physical hardware or 1244device responds to the read or write cycles. 1245In such a situation, the system typically would panic due to a kernel-mode 1246bus error. 1247The 1248.Fn bus_space_peek_N 1249and 1250.Fn bus_space_poke_N 1251family of functions provide a mechanism to handle these exceptions 1252gracefully without the risk of crashing the system. 1253.Pp 1254As with 1255.Fn bus_space_read_N 1256and 1257.Fn bus_space_write_N , 1258the peek and poke functions provide the ability to read and 1259write 1, 2, 4, and 8 byte data items on busses which support those 1260access sizes. 1261All of the constraints specified in the descriptions of the 1262.Fn bus_space_read_N 1263and 1264.Fn bus_space_write_N 1265functions also apply to 1266.Fn bus_space_peek_N 1267and 1268.Fn bus_space_poke_N . 1269.Pp 1270In addition, explicit calls to the 1271.Fn bus_space_barrier 1272function are not required as the implementation will ensure all 1273pending operations complete before the peek or poke operation starts. 1274The implementation will also ensure that the peek or poke operations 1275complete before returning. 1276.Pp 1277The return value indicates the outcome of the peek or poke operation. 1278A return value of zero implies that a hardware device is 1279responding to the operation at the specified offset in the bus space. 1280A non-zero return value indicates that the kernel intercepted a 1281hardware exception (e.g., bus error) when the peek or poke operation 1282was attempted. 1283Note that some busses are incapable of generating exceptions when 1284non-existent hardware is accessed. 1285In such cases, these functions will always return zero and the value of 1286the data read by 1287.Fn bus_space_peek_N 1288will be unspecified. 1289.Pp 1290Finally, it should be noted that at this time the 1291.Fn bus_space_peek_N 1292and 1293.Fn bus_space_poke_N 1294functions are not re-entrant and should not, therefore, be used 1295from within an interrupt service routine. 1296This constraint may be removed at some point in the future. 1297.Pp 1298.Bl -ohang -compact 1299.It Fn bus_space_peek_1 "space" "handle" "offset" "datap" 1300.It Fn bus_space_peek_2 "space" "handle" "offset" "datap" 1301.It Fn bus_space_peek_4 "space" "handle" "offset" "datap" 1302.It Fn bus_space_peek_8 "space" "handle" "offset" "datap" 1303.Pp 1304The 1305.Fn bus_space_peek_N 1306family of functions cautiously read a 1, 2, 4, or 8 byte data item from 1307the offset specified by 1308.Fa offset 1309in the region specified by 1310.Fa handle 1311of the bus space specified by 1312.Fa space . 1313The data item read is stored in the location pointed to by 1314.Fa datap . 1315It is permissible for 1316.Fa datap 1317to be NULL, in which case the data item will be discarded after being read. 1318.Pp 1319.It Fn bus_space_poke_1 "space" "handle" "offset" "value" 1320.It Fn bus_space_poke_2 "space" "handle" "offset" "value" 1321.It Fn bus_space_poke_4 "space" "handle" "offset" "value" 1322.It Fn bus_space_poke_8 "space" "handle" "offset" "value" 1323.Pp 1324The 1325.Fn bus_space_poke_N 1326family of functions cautiously write a 1, 2, 4, or 8 byte data item 1327specified by 1328.Fa value 1329to the offset specified by 1330.Fa offset 1331in the region specified by 1332.Fa handle 1333of the bus space specified by 1334.Fa space . 1335.El 1336.Sh BARRIERS 1337In order to allow high-performance buffering implementations to avoid bus 1338activity on every operation, read and write ordering should be specified 1339explicitly by drivers when necessary. 1340The 1341.Fn bus_space_barrier 1342function provides that ability. 1343.Pp 1344.Bl -ohang -compact 1345.It Fn bus_space_barrier "space" "handle" "offset" "length" "flags" 1346.Pp 1347The 1348.Fn bus_space_barrier 1349function enforces ordering of bus space read and write operations 1350for the specified subregion (described by the 1351.Fa offset 1352and 1353.Fa length 1354parameters) of the region named by 1355.Fa handle 1356in the space named by 1357.Fa space . 1358.Pp 1359The 1360.Fa flags 1361argument controls what types of operations are to be ordered. 1362Supported flags are: 1363.Bl -tag -width BUS_SPACE_BARRIER_WRITE -offset indent 1364.It Dv BUS_SPACE_BARRIER_READ 1365Force all 1366.Nm 1367operations before the barrier to complete before any reads 1368after the barrier may be issued. 1369.It Dv BUS_SPACE_BARRIER_WRITE 1370Force all 1371.Nm 1372operations before the barrier to complete before any writes 1373after the barrier may be issued. 1374.El 1375.Pp 1376Those flags can be combined (or-ed together) to enforce ordering on 1377different combinations of read and write operations. 1378.Pp 1379All of the specified type(s) of operation which are done to the region 1380before the barrier operation are guaranteed to complete before any of the 1381specified type(s) of operation done after the barrier. 1382.Pp 1383Example: Consider a hypothetical device with two single-byte ports, one 1384write-only input port (at offset 0) and a read-only output port (at 1385offset 1). 1386Operation of the device is as follows: data bytes are written to the 1387input port, and are placed by the device on a stack, the top of 1388which is read by reading from the output port. 1389The sequence to correctly write two data bytes to the device then read 1390those two data bytes back would be: 1391.Bd -literal 1392/* 1393 * t and h are the tag and handle for the mapped device's 1394 * space. 1395 */ 1396bus_space_write_1(t, h, 0, data0); 1397bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE); /* 1 */ 1398bus_space_write_1(t, h, 0, data1); 1399bus_space_barrier(t, h, 0, 2, BUS_SPACE_BARRIER_WRITE); /* 2 */ 1400ndata1 = bus_space_read_1(t, h, 1); 1401bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ); /* 3 */ 1402ndata0 = bus_space_read_1(t, h, 1); 1403/* data0 == ndata0, data1 == ndata1 */ 1404.Ed 1405.Pp 1406The first barrier makes sure that the first write finishes before the 1407second write is issued, so that two writes to the input port are done 1408in order and are not collapsed into a single write. 1409This ensures that the data bytes are written to the device correctly and 1410in order. 1411.Pp 1412The second barrier forces the writes to the output port finish before 1413any of the reads to the input port are issued, thereby making sure 1414that all of the writes are finished before data is read. 1415This ensures that the first byte read from the device really is the last 1416one that was written. 1417.Pp 1418The third barrier makes sure that the first read finishes before the 1419second read is issued, ensuring that data is read correctly and in order. 1420.Pp 1421The barriers in the example above are specified to cover the absolute 1422minimum number of bus space locations. 1423It is correct (and often easier) to make barrier operations cover the 1424device's whole range of bus space, that is, to specify an offset of zero 1425and the size of the whole region. 1426.El 1427.Sh REGION OPERATIONS 1428Some devices use buffers which are mapped as regions in bus space. 1429Often, drivers want to copy the contents of those buffers to or from 1430memory, e.g., into mbufs which can be passed to higher levels of the 1431system or from mbufs to be output to a network. 1432In order to allow drivers to do this as efficiently as possible, the 1433.Fn bus_space_read_region_N 1434and 1435.Fn bus_space_write_region_N 1436families of functions are provided. 1437.Pp 1438Drivers occasionally need to copy one region of a bus space to another, 1439or to set all locations in a region of bus space to contain a single 1440value. 1441The 1442.Fn bus_space_copy_region_N 1443family of functions and the 1444.Fn bus_space_set_region_N 1445family of functions allow drivers to perform these operations. 1446.Pp 1447.Bl -ohang -compact 1448.It Fn bus_space_read_region_1 "space" "handle" "offset" "datap" "count" 1449.It Fn bus_space_read_region_2 "space" "handle" "offset" "datap" "count" 1450.It Fn bus_space_read_region_4 "space" "handle" "offset" "datap" "count" 1451.It Fn bus_space_read_region_8 "space" "handle" "offset" "datap" "count" 1452.Pp 1453The 1454.Fn bus_space_read_region_N 1455family of functions reads 1456.Fa count 14571, 2, 4, or 8 byte data items from bus space 1458starting at byte offset 1459.Fa offset 1460in the region specified by 1461.Fa handle 1462of the bus space specified by 1463.Fa space 1464and writes them into the array specified by 1465.Fa datap . 1466Each successive data item is read from an offset 14671, 2, 4, or 8 bytes after the previous data item (depending on which 1468function is used). 1469All locations being read must lie within the bus space region specified by 1470.Fa handle . 1471.Pp 1472For portability, the starting address of the region specified by 1473.Fa handle 1474plus the offset should be a multiple of the size of data items being 1475read and the data array pointer should be properly aligned. 1476On some systems, not obeying these requirements may cause incorrect data 1477to be read, on others it may cause a system crash. 1478.Pp 1479Read operations done by the 1480.Fn bus_space_read_region_N 1481functions may be executed in any order. 1482They may also be executed out of order with respect to other pending 1483read and write operations unless order is enforced by use of the 1484.Fn bus_space_barrier 1485function. 1486There is no way to insert barriers between reads of individual bus 1487space locations executed by the 1488.Fn bus_space_read_region_N 1489functions. 1490.Pp 1491These functions will never fail. 1492If they would fail (e.g., because of an argument error), that indicates a 1493software bug which should cause a panic. 1494In that case, they will never return. 1495.Pp 1496.It Fn bus_space_write_region_1 "space" "handle" "offset" "datap" "count" 1497.It Fn bus_space_write_region_2 "space" "handle" "offset" "datap" "count" 1498.It Fn bus_space_write_region_4 "space" "handle" "offset" "datap" "count" 1499.It Fn bus_space_write_region_8 "space" "handle" "offset" "datap" "count" 1500.Pp 1501The 1502.Fn bus_space_write_region_N 1503family of functions reads 1504.Fa count 15051, 2, 4, or 8 byte data items from the array 1506specified by 1507.Fa datap 1508and writes them to bus space starting at byte offset 1509.Fa offset 1510in the region specified by 1511.Fa handle 1512of the bus space specified 1513by 1514.Fa space . 1515Each successive data item is written to an offset 1, 2, 4, 1516or 8 bytes after the previous data item (depending on which function is 1517used). 1518All locations being written must lie within the bus space region specified by 1519.Fa handle . 1520.Pp 1521For portability, the starting address of the region specified by 1522.Fa handle 1523plus the offset should be a multiple of the size of data items being 1524written and the data array pointer should be properly aligned. 1525On some systems, not obeying these requirements may cause incorrect data 1526to be written, on others it may cause a system crash. 1527.Pp 1528Write operations done by the 1529.Fn bus_space_write_region_N 1530functions may be 1531executed in any order. 1532They may also be executed out of order with respect to other pending read 1533and write operations unless order is enforced by use of the 1534.Fn bus_space_barrier 1535function. 1536There is no way to insert barriers between writes of individual bus 1537space locations executed by the 1538.Fn bus_space_write_region_N 1539functions. 1540.Pp 1541These functions will never fail. 1542If they would fail (e.g., because of an argument error), that indicates 1543a software bug which should cause a panic. 1544In that case, they will never return. 1545.Pp 1546.It Fn bus_space_copy_region_1 "space" "srchandle" "srcoffset" "dsthandle" \ 1547"dstoffset" "count" 1548.It Fn bus_space_copy_region_2 "space" "srchandle" "srcoffset" "dsthandle" \ 1549"dstoffset" "count" 1550.It Fn bus_space_copy_region_4 "space" "srchandle" "srcoffset" "dsthandle" \ 1551"dstoffset" "count" 1552.It Fn bus_space_copy_region_8 "space" "srchandle" "srcoffset" "dsthandle" \ 1553"dstoffset" "count" 1554.Pp 1555The 1556.Fn bus_space_copy_region_N 1557family of functions copies 1558.Fa count 15591, 2, 4, or 8 byte data items in bus space 1560from the area starting at byte offset 1561.Fa srcoffset 1562in the region specified by 1563.Fa srchandle 1564of the bus space specified by 1565.Fa space 1566to the area starting at byte offset 1567.Fa dstoffset 1568in the region specified by 1569.Fa dsthandle 1570in the same bus space. 1571Each successive data item read or written has an offset 1, 2, 4, or 8 1572bytes after the previous data item (depending on which function is used). 1573All locations being read and written must lie within the bus space 1574region specified by their respective handles. 1575.Pp 1576For portability, the starting addresses of the regions specified by 1577each handle plus its respective offset should be a multiple of the size 1578of data items being copied. 1579On some systems, not obeying this requirement may cause incorrect data 1580to be copied, on others it may cause a system crash. 1581.Pp 1582Read and write operations done by the 1583.Fn bus_space_copy_region_N 1584functions may be executed in any order. 1585They may also be executed out of order with respect to other pending 1586read and write operations unless order is enforced by use of the 1587.Fn bus_space_barrier function . 1588There is no way to insert barriers between reads or writes of 1589individual bus space locations executed by the 1590.Fn bus_space_copy_region_N 1591functions. 1592.Pp 1593Overlapping copies between different subregions of a single region 1594of bus space are handled correctly by the 1595.Fn bus_space_copy_region_N 1596functions. 1597.Pp 1598These functions will never fail. 1599If they would fail (e.g., because of an argument error), that indicates 1600a software bug which should cause a panic. 1601In that case, they will never return. 1602.Pp 1603.It Fn bus_space_set_region_1 "space" "handle" "offset" "value" "count" 1604.It Fn bus_space_set_region_2 "space" "handle" "offset" "value" "count" 1605.It Fn bus_space_set_region_4 "space" "handle" "offset" "value" "count" 1606.It Fn bus_space_set_region_8 "space" "handle" "offset" "value" "count" 1607.Pp 1608The 1609.Fn bus_space_set_region_N 1610family of functions writes the given 1611.Fa value 1612to 1613.Fa count 16141, 2, 4, or 8 byte 1615data items in bus space starting at byte offset 1616.Fa offset 1617in the region specified by 1618.Fa handle 1619of the bus space specified by 1620.Fa space . 1621Each successive data item has an offset 1, 2, 4, or 8 bytes after the 1622previous data item (depending on which function is used). 1623All locations being written must lie within the bus space region 1624specified by 1625.Fa handle . 1626.Pp 1627For portability, the starting address of the region specified by 1628.Fa handle 1629plus the offset should be a multiple of the size of data items being 1630written. 1631On some systems, not obeying this requirement may cause incorrect data 1632to be written, on others it may cause a system crash. 1633.Pp 1634Write operations done by the 1635.Fn bus_space_set_region_N 1636functions may be 1637executed in any order. 1638They may also be executed out of order with respect to other pending read 1639and write operations unless order is enforced by use of the 1640.Fn bus_space_barrier 1641function. 1642There is no way to insert barriers between writes of 1643individual bus space locations executed by the 1644.Fn bus_space_set_region_N 1645functions. 1646.Pp 1647These functions will never fail. 1648If they would fail (e.g., because of an argument error), that indicates 1649a software bug which should cause a panic. 1650In that case, they will never return. 1651.El 1652.Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES 1653Some devices implement single locations in bus space which are to be read 1654or written multiple times to communicate data, e.g., some ethernet 1655devices' packet buffer FIFOs. 1656In order to allow drivers to manipulate these types of devices as 1657efficiently as possible, the 1658.Fn bus_space_read_multi_N 1659and 1660.Fn bus_space_write_multi_N 1661families of functions are provided. 1662.Pp 1663.Bl -ohang -compact 1664.It Fn bus_space_read_multi_1 "space" "handle" "offset" "datap" "count" 1665.It Fn bus_space_read_multi_2 "space" "handle" "offset" "datap" "count" 1666.It Fn bus_space_read_multi_4 "space" "handle" "offset" "datap" "count" 1667.It Fn bus_space_read_multi_8 "space" "handle" "offset" "datap" "count" 1668.Pp 1669The 1670.Fn bus_space_read_multi_N 1671family of functions reads 1672.Fa count 16731, 2, 4, or 8 byte data items from bus space 1674at byte offset 1675.Fa offset 1676in the region specified by 1677.Fa handle 1678of the bus space specified by 1679.Fa space 1680and writes them into the array specified by 1681.Fa datap . 1682Each successive data item is read from the same location in bus 1683space. 1684The location being read must lie within the bus space region specified by 1685.Fa handle . 1686.Pp 1687For portability, the starting address of the region specified by 1688.Fa handle 1689plus the offset should be a multiple of the size of data items being 1690read and the data array pointer should be properly aligned. 1691On some systems, not obeying these requirements may cause incorrect data 1692to be read, on others it may cause a system crash. 1693.Pp 1694Read operations done by the 1695.Fn bus_space_read_multi_N 1696functions may be 1697executed out of order with respect to other pending read and write 1698operations unless order is enforced by use of the 1699.Fn bus_space_barrier 1700function. 1701Because the 1702.Fn bus_space_read_multi_N 1703functions read the same bus space location multiple times, they 1704place an implicit read barrier between each successive read of that bus 1705space location. 1706.Pp 1707These functions will never fail. 1708If they would fail (e.g., because of an argument error), that indicates 1709a software bug which should cause a panic. 1710In that case, they will never return. 1711.Pp 1712.It Fn bus_space_write_multi_1 "space" "handle" "offset" "datap" "count" 1713.It Fn bus_space_write_multi_2 "space" "handle" "offset" "datap" "count" 1714.It Fn bus_space_write_multi_4 "space" "handle" "offset" "datap" "count" 1715.It Fn bus_space_write_multi_8 "space" "handle" "offset" "datap" "count" 1716.Pp 1717The 1718.Fn bus_space_write_multi_N 1719family of functions reads 1720.Fa count 17211, 2, 4, or 8 byte data items from the array 1722specified by 1723.Fa datap 1724and writes them into bus space at byte offset 1725.Fa offset 1726in the region specified by 1727.Fa handle 1728of the bus space specified by 1729.Fa space . 1730Each successive data item is written to the same location in 1731bus space. 1732The location being written must lie within the bus space region specified by 1733.Fa handle . 1734.Pp 1735For portability, the starting address of the region specified by 1736.Fa handle 1737plus the offset should be a multiple of the size of data items being 1738written and the data array pointer should be properly aligned. 1739On some systems, not obeying these requirements may cause incorrect data 1740to be written, on others it may cause a system crash. 1741.Pp 1742Write operations done by the 1743.Fn bus_space_write_multi_N 1744functions may be executed out of order with respect to other pending 1745read and write operations unless order is enforced by use of the 1746.Fn bus_space_barrier 1747function. 1748Because the 1749.Fn bus_space_write_multi_N 1750functions write the same bus space location multiple times, they 1751place an implicit write barrier between each successive write of that 1752bus space location. 1753.Pp 1754These functions will never fail. 1755If they would fail (e.g., because of an argument error), that indicates 1756a software bug which should cause a panic. 1757In that case, they will never return. 1758.El 1759.Sh STREAM FUNCTIONS 1760Most of the 1761.Nm 1762functions imply a host byte-order and a bus byte-order and take care of 1763any translation for the caller. 1764In some cases, however, hardware may map a FIFO or some other memory region 1765for which the caller may want to use multi-word, yet untranslated access. 1766Access to these types of memory regions should be with the 1767.Fn bus_space_*_stream_N 1768functions. 1769.Pp 1770.Bl -ohang -compact 1771.It Fn bus_space_read_stream_1 "space" "handle" "offset" 1772.It Fn bus_space_read_stream_2 "space" "handle" "offset" 1773.It Fn bus_space_read_stream_4 "space" "handle" "offset" 1774.It Fn bus_space_read_stream_8 "space" "handle" "offset" 1775.It Fn bus_space_read_multi_stream_1 "space" "handle" "offset" "datap" "count" 1776.It Fn bus_space_read_multi_stream_2 "space" "handle" "offset" "datap" "count" 1777.It Fn bus_space_read_multi_stream_4 "space" "handle" "offset" "datap" "count" 1778.It Fn bus_space_read_multi_stream_8 "space" "handle" "offset" "datap" "count" 1779.It Fn bus_space_read_region_stream_1 "space" "handle" "offset" "datap" "count" 1780.It Fn bus_space_read_region_stream_2 "space" "handle" "offset" "datap" "count" 1781.It Fn bus_space_read_region_stream_4 "space" "handle" "offset" "datap" "count" 1782.It Fn bus_space_read_region_stream_8 "space" "handle" "offset" "datap" "count" 1783.It Fn bus_space_write_stream_1 "space" "handle" "offset" "value" 1784.It Fn bus_space_write_stream_2 "space" "handle" "offset" "value" 1785.It Fn bus_space_write_stream_4 "space" "handle" "offset" "value" 1786.It Fn bus_space_write_stream_8 "space" "handle" "offset" "value" 1787.It Fn bus_space_write_multi_stream_1 "space" "handle" "offset" "datap" "count" 1788.It Fn bus_space_write_multi_stream_2 "space" "handle" "offset" "datap" "count" 1789.It Fn bus_space_write_multi_stream_4 "space" "handle" "offset" "datap" "count" 1790.It Fn bus_space_write_multi_stream_8 "space" "handle" "offset" "datap" "count" 1791.It Fn bus_space_write_region_stream_1 "space" "handle" "offset" "datap" "count" 1792.It Fn bus_space_write_region_stream_2 "space" "handle" "offset" "datap" "count" 1793.It Fn bus_space_write_region_stream_4 "space" "handle" "offset" "datap" "count" 1794.It Fn bus_space_write_region_stream_8 "space" "handle" "offset" "datap" "count" 1795.El 1796.Pp 1797These functions are defined just as their non-stream counterparts, 1798except that they provide no byte-order translation. 1799.Sh IMPLEMENTING BUS SPACES IN MACHINE-INDEPENDENT CODE 1800.Bl -ohang -compact 1801.It Fn bus_space_tag_create "obst" "present" "extpresent" "ov" "ctx" "bstp" 1802Create a copy of the tag 1803.Fa obst 1804at 1805.Fa *bstp . 1806Except for the behavior 1807overridden by 1808.Fa ov , 1809.Fa *bstp 1810inherits the behavior of 1811.Fa obst 1812under 1813.Nm 1814calls. 1815.Pp 1816.Fa ov 1817contains function pointers corresponding to 1818.Nm 1819routines. 1820Each function pointer has a corresponding bit in 1821.Fa present 1822or 1823.Fa extpresent , 1824and if that bit is 1, the function pointer overrides the corresponding 1825.Nm 1826call for the new tag. 1827Any combination of these bits may be set in 1828.Fa present : 1829.Pp 1830.Bl -tag -width BUS_SPACE_OVERRIDE_RESERVE_SUBREGION -compact 1831.It Dv BUS_SPACE_OVERRIDE_MAP 1832.It Dv BUS_SPACE_OVERRIDE_UNMAP 1833.It Dv BUS_SPACE_OVERRIDE_ALLOC 1834.It Dv BUS_SPACE_OVERRIDE_FREE 1835.It Dv BUS_SPACE_OVERRIDE_RESERVE 1836.It Dv BUS_SPACE_OVERRIDE_RELEASE 1837.It Dv BUS_SPACE_OVERRIDE_RESERVATION_MAP 1838.It Dv BUS_SPACE_OVERRIDE_RESERVATION_UNMAP 1839.It Dv BUS_SPACE_OVERRIDE_RESERVE_SUBREGION 1840.El 1841.Pp 1842.Fn bus_space_tag_create 1843does not copy 1844.Fa ov . 1845After a new tag is created by 1846.Fn bus_space_tag_create , 1847.Fa ov 1848must not be destroyed until after the 1849tag is destroyed by 1850.Fn bus_space_tag_destroy . 1851.Pp 1852The first argument of every override-function is a 1853.Vt "void *" , 1854and 1855.Fa ctx 1856is passed in that argument. 1857.Pp 1858Return 0 if the call succeeds. 1859Return 1860.Er EOPNOTSUPP 1861if the architecture does not support overrides. 1862Return 1863.Er EINVAL 1864if 1865.Fa present 1866is 0, if 1867.Fa ov 1868is 1869.Dv NULL , 1870or if 1871.Fa present 1872indicates that an override is present, but the corresponding override 1873in 1874.Fa ov 1875is 1876.Dv NULL . 1877.Pp 1878If the call does not succeed, 1879.Fa *bstp 1880is undefined. 1881.It Fn bus_space_tag_destroy "bst" 1882Destroy a tag, 1883.Fa bst , 1884created by a prior call to 1885.Fn bus_space_tag_create . 1886If 1887.Fa bst 1888was not created by 1889.Fn bus_space_tag_create , 1890results are undefined. 1891If 1892.Fa bst 1893was already destroyed, results are undefined. 1894.El 1895.Sh EXPECTED CHANGES TO THE BUS_SPACE FUNCTIONS 1896The definition of the 1897.Nm 1898functions should not yet be considered finalized. 1899There are several changes and improvements which should be explored, 1900including: 1901.Bl -bullet 1902.It 1903Providing a mechanism by which incorrectly-written drivers will be 1904automatically given barriers and properly-written drivers won't be forced 1905to use more barriers than they need. 1906This should probably be done via a 1907.Li #define 1908in the incorrectly-written drivers. 1909Unfortunately, at this time, few drivers actually use barriers correctly 1910(or at all). 1911Because of that, 1912.Nm 1913implementations on architectures which do buffering must always 1914do the barriers inside the 1915.Nm 1916calls, to be safe. 1917That has a potentially significant performance impact. 1918.It 1919Exporting the 1920.Nm 1921functions to userland so that applications 1922(such as X servers) have easier, more portable access to device space. 1923.It 1924Redefining bus space tags and handles so that machine-independent bus 1925interface drivers (for example PCI to VME bridges) could define and 1926implement bus spaces without requiring machine-dependent code. 1927If this is done, it should be done in such a way that machine-dependent 1928optimizations should remain possible. 1929.It 1930Converting bus spaces (such as PCI configuration space) which currently 1931use space-specific access methods to use the 1932.Nm 1933functions where that is appropriate. 1934.It 1935Redefining the way bus space is mapped and allocated, so that mapping 1936and allocation are done with bus specific functions which return bus 1937space tags. 1938This would allow further optimization than is currently possible, and 1939would also ease translation of the 1940.Nm 1941functions into user space (since mapping in user space would look like 1942it just used a different bus-specific mapping function). 1943.El 1944.Sh COMPATIBILITY 1945The current version of the 1946.Nm 1947interface specification differs slightly from the original 1948specification that came into wide use. 1949A few of the function names and arguments have changed 1950for consistency and increased functionality. 1951Drivers that were written to the 1952old, deprecated specification can be compiled by defining the 1953.Dv __BUS_SPACE_COMPAT_OLDDEFS 1954preprocessor symbol before including 1955.In sys/bus.h . 1956.Sh SEE ALSO 1957.Xr membar_ops 3 , 1958.Xr bus_dma 9 1959.Sh HISTORY 1960The 1961.Nm 1962functions were introduced in a different form (memory and I/O spaces 1963were accessed via different sets of functions) in 1964.Nx 1.2 . 1965The functions were merged to work on generic 1966.Dq spaces 1967early in the 1968.Nx 1.3 1969development cycle, and many drivers were converted to use them. 1970This document was written later during the 1971.Nx 1.3 1972development cycle and the specification was updated to fix some 1973consistency problems and to add some missing functionality. 1974.Sh AUTHORS 1975.An -nosplit 1976The 1977.Nm 1978interfaces were designed and implemented by the 1979.Nx 1980developer 1981community. 1982Primary contributors and implementors were 1983.An Chris Demetriou , 1984.An Jason Thorpe , 1985and 1986.An Charles Hannum , 1987but the rest of the 1988.Nx 1989developers and the user community played a significant role in development. 1990.Pp 1991.An Chris Demetriou 1992wrote this manual page. 1993