1.\" $NetBSD: bus_space.9,v 1.50 2016/09/16 08:26:16 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 EOPNOTSUPP 1051.Fn bus_space_reserve 1052is not supported on this architecture, or 1053.Fa flags 1054was incompatible with the bus space represented by 1055.Fa t . 1056.It Er ENOMEM 1057There was not sufficient bus space at 1058.Fa bpa 1059to satisfy the request. 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 EOPNOTSUPP 1095.Fn bus_space_reserve 1096is not supported on this architecture, or 1097.Fa flags 1098was incompatible with the bus space represented by 1099.Fa t . 1100.It Er ENOMEM 1101There was not sufficient bus space at 1102.Fa bpa 1103to satisfy the request. 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.Pp 1392.Bd -literal 1393/* 1394 * t and h are the tag and handle for the mapped device's 1395 * space. 1396 */ 1397bus_space_write_1(t, h, 0, data0); 1398bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE); /* 1 */ 1399bus_space_write_1(t, h, 0, data1); 1400bus_space_barrier(t, h, 0, 2, BUS_SPACE_BARRIER_WRITE); /* 2 */ 1401ndata1 = bus_space_read_1(t, h, 1); 1402bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ); /* 3 */ 1403ndata0 = bus_space_read_1(t, h, 1); 1404/* data0 == ndata0, data1 == ndata1 */ 1405.Ed 1406.Pp 1407The first barrier makes sure that the first write finishes before the 1408second write is issued, so that two writes to the input port are done 1409in order and are not collapsed into a single write. 1410This ensures that the data bytes are written to the device correctly and 1411in order. 1412.Pp 1413The second barrier forces the writes to the output port finish before 1414any of the reads to the input port are issued, thereby making sure 1415that all of the writes are finished before data is read. 1416This ensures that the first byte read from the device really is the last 1417one that was written. 1418.Pp 1419The third barrier makes sure that the first read finishes before the 1420second read is issued, ensuring that data is read correctly and in order. 1421.Pp 1422The barriers in the example above are specified to cover the absolute 1423minimum number of bus space locations. 1424It is correct (and often easier) to make barrier operations cover the 1425device's whole range of bus space, that is, to specify an offset of zero 1426and the size of the whole region. 1427.El 1428.El 1429.Sh REGION OPERATIONS 1430Some devices use buffers which are mapped as regions in bus space. 1431Often, drivers want to copy the contents of those buffers to or from 1432memory, e.g., into mbufs which can be passed to higher levels of the 1433system or from mbufs to be output to a network. 1434In order to allow drivers to do this as efficiently as possible, the 1435.Fn bus_space_read_region_N 1436and 1437.Fn bus_space_write_region_N 1438families of functions are provided. 1439.Pp 1440Drivers occasionally need to copy one region of a bus space to another, 1441or to set all locations in a region of bus space to contain a single 1442value. 1443The 1444.Fn bus_space_copy_region_N 1445family of functions and the 1446.Fn bus_space_set_region_N 1447family of functions allow drivers to perform these operations. 1448.Pp 1449.Bl -ohang -compact 1450.It Fn bus_space_read_region_1 "space" "handle" "offset" "datap" "count" 1451.It Fn bus_space_read_region_2 "space" "handle" "offset" "datap" "count" 1452.It Fn bus_space_read_region_4 "space" "handle" "offset" "datap" "count" 1453.It Fn bus_space_read_region_8 "space" "handle" "offset" "datap" "count" 1454.Pp 1455The 1456.Fn bus_space_read_region_N 1457family of functions reads 1458.Fa count 14591, 2, 4, or 8 byte data items from bus space 1460starting at byte offset 1461.Fa offset 1462in the region specified by 1463.Fa handle 1464of the bus space specified by 1465.Fa space 1466and writes them into the array specified by 1467.Fa datap . 1468Each successive data item is read from an offset 14691, 2, 4, or 8 bytes after the previous data item (depending on which 1470function is used). 1471All locations being read must lie within the bus space region specified by 1472.Fa handle . 1473.Pp 1474For portability, the starting address of the region specified by 1475.Fa handle 1476plus the offset should be a multiple of the size of data items being 1477read and the data array pointer should be properly aligned. 1478On some systems, not obeying these requirements may cause incorrect data 1479to be read, on others it may cause a system crash. 1480.Pp 1481Read operations done by the 1482.Fn bus_space_read_region_N 1483functions may be executed in any order. 1484They may also be executed out of order with respect to other pending 1485read and write operations unless order is enforced by use of the 1486.Fn bus_space_barrier 1487function. 1488There is no way to insert barriers between reads of individual bus 1489space locations executed by the 1490.Fn bus_space_read_region_N 1491functions. 1492.Pp 1493These functions will never fail. 1494If they would fail (e.g., because of an argument error), that indicates a 1495software bug which should cause a panic. 1496In that case, they will never return. 1497.Pp 1498.It Fn bus_space_write_region_1 "space" "handle" "offset" "datap" "count" 1499.It Fn bus_space_write_region_2 "space" "handle" "offset" "datap" "count" 1500.It Fn bus_space_write_region_4 "space" "handle" "offset" "datap" "count" 1501.It Fn bus_space_write_region_8 "space" "handle" "offset" "datap" "count" 1502.Pp 1503The 1504.Fn bus_space_write_region_N 1505family of functions reads 1506.Fa count 15071, 2, 4, or 8 byte data items from the array 1508specified by 1509.Fa datap 1510and writes them to bus space starting at byte offset 1511.Fa offset 1512in the region specified by 1513.Fa handle 1514of the bus space specified 1515by 1516.Fa space . 1517Each successive data item is written to an offset 1, 2, 4, 1518or 8 bytes after the previous data item (depending on which function is 1519used). 1520All locations being written must lie within the bus space region specified by 1521.Fa handle . 1522.Pp 1523For portability, the starting address of the region specified by 1524.Fa handle 1525plus the offset should be a multiple of the size of data items being 1526written and the data array pointer should be properly aligned. 1527On some systems, not obeying these requirements may cause incorrect data 1528to be written, on others it may cause a system crash. 1529.Pp 1530Write operations done by the 1531.Fn bus_space_write_region_N 1532functions may be 1533executed in any order. 1534They may also be executed out of order with respect to other pending read 1535and write operations unless order is enforced by use of the 1536.Fn bus_space_barrier 1537function. 1538There is no way to insert barriers between writes of individual bus 1539space locations executed by the 1540.Fn bus_space_write_region_N 1541functions. 1542.Pp 1543These functions will never fail. 1544If they would fail (e.g., because of an argument error), that indicates 1545a software bug which should cause a panic. 1546In that case, they will never return. 1547.Pp 1548.It Fn bus_space_copy_region_1 "space" "srchandle" "srcoffset" "dsthandle" \ 1549"dstoffset" "count" 1550.It Fn bus_space_copy_region_2 "space" "srchandle" "srcoffset" "dsthandle" \ 1551"dstoffset" "count" 1552.It Fn bus_space_copy_region_4 "space" "srchandle" "srcoffset" "dsthandle" \ 1553"dstoffset" "count" 1554.It Fn bus_space_copy_region_8 "space" "srchandle" "srcoffset" "dsthandle" \ 1555"dstoffset" "count" 1556.Pp 1557The 1558.Fn bus_space_copy_region_N 1559family of functions copies 1560.Fa count 15611, 2, 4, or 8 byte data items in bus space 1562from the area starting at byte offset 1563.Fa srcoffset 1564in the region specified by 1565.Fa srchandle 1566of the bus space specified by 1567.Fa space 1568to the area starting at byte offset 1569.Fa dstoffset 1570in the region specified by 1571.Fa dsthandle 1572in the same bus space. 1573Each successive data item read or written has an offset 1, 2, 4, or 8 1574bytes after the previous data item (depending on which function is used). 1575All locations being read and written must lie within the bus space 1576region specified by their respective handles. 1577.Pp 1578For portability, the starting addresses of the regions specified by 1579each handle plus its respective offset should be a multiple of the size 1580of data items being copied. 1581On some systems, not obeying this requirement may cause incorrect data 1582to be copied, on others it may cause a system crash. 1583.Pp 1584Read and write operations done by the 1585.Fn bus_space_copy_region_N 1586functions may be executed in any order. 1587They may also be executed out of order with respect to other pending 1588read and write operations unless order is enforced by use of the 1589.Fn bus_space_barrier function . 1590There is no way to insert barriers between reads or writes of 1591individual bus space locations executed by the 1592.Fn bus_space_copy_region_N 1593functions. 1594.Pp 1595Overlapping copies between different subregions of a single region 1596of bus space are handled correctly by the 1597.Fn bus_space_copy_region_N 1598functions. 1599.Pp 1600These functions will never fail. 1601If they would fail (e.g., because of an argument error), that indicates 1602a software bug which should cause a panic. 1603In that case, they will never return. 1604.Pp 1605.It Fn bus_space_set_region_1 "space" "handle" "offset" "value" "count" 1606.It Fn bus_space_set_region_2 "space" "handle" "offset" "value" "count" 1607.It Fn bus_space_set_region_4 "space" "handle" "offset" "value" "count" 1608.It Fn bus_space_set_region_8 "space" "handle" "offset" "value" "count" 1609.Pp 1610The 1611.Fn bus_space_set_region_N 1612family of functions writes the given 1613.Fa value 1614to 1615.Fa count 16161, 2, 4, or 8 byte 1617data items in bus space starting at byte offset 1618.Fa offset 1619in the region specified by 1620.Fa handle 1621of the bus space specified by 1622.Fa space . 1623Each successive data item has an offset 1, 2, 4, or 8 bytes after the 1624previous data item (depending on which function is used). 1625All locations being written must lie within the bus space region 1626specified by 1627.Fa handle . 1628.Pp 1629For portability, the starting address of the region specified by 1630.Fa handle 1631plus the offset should be a multiple of the size of data items being 1632written. 1633On some systems, not obeying this requirement may cause incorrect data 1634to be written, on others it may cause a system crash. 1635.Pp 1636Write operations done by the 1637.Fn bus_space_set_region_N 1638functions may be 1639executed in any order. 1640They may also be executed out of order with respect to other pending read 1641and write operations unless order is enforced by use of the 1642.Fn bus_space_barrier 1643function. 1644There is no way to insert barriers between writes of 1645individual bus space locations executed by the 1646.Fn bus_space_set_region_N 1647functions. 1648.Pp 1649These functions will never fail. 1650If they would fail (e.g., because of an argument error), that indicates 1651a software bug which should cause a panic. 1652In that case, they will never return. 1653.El 1654.Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES 1655Some devices implement single locations in bus space which are to be read 1656or written multiple times to communicate data, e.g., some ethernet 1657devices' packet buffer FIFOs. 1658In order to allow drivers to manipulate these types of devices as 1659efficiently as possible, the 1660.Fn bus_space_read_multi_N 1661and 1662.Fn bus_space_write_multi_N 1663families of functions are provided. 1664.Pp 1665.Bl -ohang -compact 1666.It Fn bus_space_read_multi_1 "space" "handle" "offset" "datap" "count" 1667.It Fn bus_space_read_multi_2 "space" "handle" "offset" "datap" "count" 1668.It Fn bus_space_read_multi_4 "space" "handle" "offset" "datap" "count" 1669.It Fn bus_space_read_multi_8 "space" "handle" "offset" "datap" "count" 1670.Pp 1671The 1672.Fn bus_space_read_multi_N 1673family of functions reads 1674.Fa count 16751, 2, 4, or 8 byte data items from bus space 1676at byte offset 1677.Fa offset 1678in the region specified by 1679.Fa handle 1680of the bus space specified by 1681.Fa space 1682and writes them into the array specified by 1683.Fa datap . 1684Each successive data item is read from the same location in bus 1685space. 1686The location being read must lie within the bus space region specified by 1687.Fa handle . 1688.Pp 1689For portability, the starting address of the region specified by 1690.Fa handle 1691plus the offset should be a multiple of the size of data items being 1692read and the data array pointer should be properly aligned. 1693On some systems, not obeying these requirements may cause incorrect data 1694to be read, on others it may cause a system crash. 1695.Pp 1696Read operations done by the 1697.Fn bus_space_read_multi_N 1698functions may be 1699executed out of order with respect to other pending read and write 1700operations unless order is enforced by use of the 1701.Fn bus_space_barrier 1702function. 1703Because the 1704.Fn bus_space_read_multi_N 1705functions read the same bus space location multiple times, they 1706place an implicit read barrier between each successive read of that bus 1707space location. 1708.Pp 1709These functions will never fail. 1710If they would fail (e.g., because of an argument error), that indicates 1711a software bug which should cause a panic. 1712In that case, they will never return. 1713.Pp 1714.It Fn bus_space_write_multi_1 "space" "handle" "offset" "datap" "count" 1715.It Fn bus_space_write_multi_2 "space" "handle" "offset" "datap" "count" 1716.It Fn bus_space_write_multi_4 "space" "handle" "offset" "datap" "count" 1717.It Fn bus_space_write_multi_8 "space" "handle" "offset" "datap" "count" 1718.Pp 1719The 1720.Fn bus_space_write_multi_N 1721family of functions reads 1722.Fa count 17231, 2, 4, or 8 byte data items from the array 1724specified by 1725.Fa datap 1726and writes them into bus space at byte offset 1727.Fa offset 1728in the region specified by 1729.Fa handle 1730of the bus space specified by 1731.Fa space . 1732Each successive data item is written to the same location in 1733bus space. 1734The location being written must lie within the bus space region specified by 1735.Fa handle . 1736.Pp 1737For portability, the starting address of the region specified by 1738.Fa handle 1739plus the offset should be a multiple of the size of data items being 1740written and the data array pointer should be properly aligned. 1741On some systems, not obeying these requirements may cause incorrect data 1742to be written, on others it may cause a system crash. 1743.Pp 1744Write operations done by the 1745.Fn bus_space_write_multi_N 1746functions may be executed out of order with respect to other pending 1747read and write operations unless order is enforced by use of the 1748.Fn bus_space_barrier 1749function. 1750Because the 1751.Fn bus_space_write_multi_N 1752functions write the same bus space location multiple times, they 1753place an implicit write barrier between each successive write of that 1754bus space location. 1755.Pp 1756These functions will never fail. 1757If they would fail (e.g., because of an argument error), that indicates 1758a software bug which should cause a panic. 1759In that case, they will never return. 1760.El 1761.Sh STREAM FUNCTIONS 1762Most of the 1763.Nm 1764functions imply a host byte-order and a bus byte-order and take care of 1765any translation for the caller. 1766In some cases, however, hardware may map a FIFO or some other memory region 1767for which the caller may want to use multi-word, yet untranslated access. 1768Access to these types of memory regions should be with the 1769.Fn bus_space_*_stream_N 1770functions. 1771.Pp 1772.Bl -ohang -compact 1773.It Fn bus_space_read_stream_1 "space" "handle" "offset" 1774.It Fn bus_space_read_stream_2 "space" "handle" "offset" 1775.It Fn bus_space_read_stream_4 "space" "handle" "offset" 1776.It Fn bus_space_read_stream_8 "space" "handle" "offset" 1777.It Fn bus_space_read_multi_stream_1 "space" "handle" "offset" "datap" "count" 1778.It Fn bus_space_read_multi_stream_2 "space" "handle" "offset" "datap" "count" 1779.It Fn bus_space_read_multi_stream_4 "space" "handle" "offset" "datap" "count" 1780.It Fn bus_space_read_multi_stream_8 "space" "handle" "offset" "datap" "count" 1781.It Fn bus_space_read_region_stream_1 "space" "handle" "offset" "datap" "count" 1782.It Fn bus_space_read_region_stream_2 "space" "handle" "offset" "datap" "count" 1783.It Fn bus_space_read_region_stream_4 "space" "handle" "offset" "datap" "count" 1784.It Fn bus_space_read_region_stream_8 "space" "handle" "offset" "datap" "count" 1785.It Fn bus_space_write_stream_1 "space" "handle" "offset" "value" 1786.It Fn bus_space_write_stream_2 "space" "handle" "offset" "value" 1787.It Fn bus_space_write_stream_4 "space" "handle" "offset" "value" 1788.It Fn bus_space_write_stream_8 "space" "handle" "offset" "value" 1789.It Fn bus_space_write_multi_stream_1 "space" "handle" "offset" "datap" "count" 1790.It Fn bus_space_write_multi_stream_2 "space" "handle" "offset" "datap" "count" 1791.It Fn bus_space_write_multi_stream_4 "space" "handle" "offset" "datap" "count" 1792.It Fn bus_space_write_multi_stream_8 "space" "handle" "offset" "datap" "count" 1793.It Fn bus_space_write_region_stream_1 "space" "handle" "offset" "datap" "count" 1794.It Fn bus_space_write_region_stream_2 "space" "handle" "offset" "datap" "count" 1795.It Fn bus_space_write_region_stream_4 "space" "handle" "offset" "datap" "count" 1796.It Fn bus_space_write_region_stream_8 "space" "handle" "offset" "datap" "count" 1797.El 1798.Pp 1799These functions are defined just as their non-stream counterparts, 1800except that they provide no byte-order translation. 1801.Sh IMPLEMENTING BUS SPACES IN MACHINE-INDEPENDENT CODE 1802.Bl -ohang -compact 1803.It Fn bus_space_tag_create "obst" "present" "extpresent" "ov" "ctx" "bstp" 1804Create a copy of the tag 1805.Fa obst 1806at 1807.Fa *bstp . 1808Except for the behavior 1809overridden by 1810.Fa ov , 1811.Fa *bstp 1812inherits the behavior of 1813.Fa obst 1814under 1815.Nm 1816calls. 1817.Pp 1818.Fa ov 1819contains function pointers corresponding to 1820.Nm 1821routines. 1822Each function pointer has a corresponding bit in 1823.Fa present 1824or 1825.Fa extpresent , 1826and if that bit is 1, the function pointer overrides the corresponding 1827.Nm 1828call for the new tag. 1829Any combination of these bits may be set in 1830.Fa present : 1831.Pp 1832.Bl -tag -width BUS_SPACE_OVERRIDE_RESERVE_SUBREGION -compact 1833.It Dv BUS_SPACE_OVERRIDE_MAP 1834.It Dv BUS_SPACE_OVERRIDE_UNMAP 1835.It Dv BUS_SPACE_OVERRIDE_ALLOC 1836.It Dv BUS_SPACE_OVERRIDE_FREE 1837.It Dv BUS_SPACE_OVERRIDE_RESERVE 1838.It Dv BUS_SPACE_OVERRIDE_RELEASE 1839.It Dv BUS_SPACE_OVERRIDE_RESERVATION_MAP 1840.It Dv BUS_SPACE_OVERRIDE_RESERVATION_UNMAP 1841.It Dv BUS_SPACE_OVERRIDE_RESERVE_SUBREGION 1842.El 1843.Pp 1844.Fn bus_space_tag_create 1845does not copy 1846.Fa ov . 1847After a new tag is created by 1848.Fn bus_space_tag_create , 1849.Fa ov 1850must not be destroyed until after the 1851tag is destroyed by 1852.Fn bus_space_tag_destroy . 1853.Pp 1854The first argument of every override-function is a 1855.Vt "void *" , 1856and 1857.Fa ctx 1858is passed in that argument. 1859.Pp 1860Return 0 if the call succeeds. 1861Return 1862.Er EOPNOTSUPP 1863if the architecture does not support overrides. 1864Return 1865.Er EINVAL 1866if 1867.Fa present 1868is 0, if 1869.Fa ov 1870is 1871.Dv NULL , 1872or if 1873.Fa present 1874indicates that an override is present, but the corresponding override 1875in 1876.Fa ov 1877is 1878.Dv NULL . 1879.Pp 1880If the call does not succeed, 1881.Fa *bstp 1882is undefined. 1883.It Fn bus_space_tag_destroy "bst" 1884Destroy a tag, 1885.Fa bst , 1886created by a prior call to 1887.Fn bus_space_tag_create . 1888If 1889.Fa bst 1890was not created by 1891.Fn bus_space_tag_create , 1892results are undefined. 1893If 1894.Fa bst 1895was already destroyed, results are undefined. 1896.El 1897.Sh EXPECTED CHANGES TO THE BUS_SPACE FUNCTIONS 1898The definition of the 1899.Nm 1900functions should not yet be considered finalized. 1901There are several changes and improvements which should be explored, 1902including: 1903.Pp 1904.Bl -bullet 1905.It 1906Providing a mechanism by which incorrectly-written drivers will be 1907automatically given barriers and properly-written drivers won't be forced 1908to use more barriers than they need. 1909This should probably be done via a 1910.Li #define 1911in the incorrectly-written drivers. 1912Unfortunately, at this time, few drivers actually use barriers correctly 1913(or at all). 1914Because of that, 1915.Nm 1916implementations on architectures which do buffering must always 1917do the barriers inside the 1918.Nm 1919calls, to be safe. 1920That has a potentially significant performance impact. 1921.It 1922Exporting the 1923.Nm 1924functions to user-land so that applications 1925(such as X servers) have easier, more portable access to device space. 1926.It 1927Redefining bus space tags and handles so that machine-independent bus 1928interface drivers (for example PCI to VME bridges) could define and 1929implement bus spaces without requiring machine-dependent code. 1930If this is done, it should be done in such a way that machine-dependent 1931optimizations should remain possible. 1932.It 1933Converting bus spaces (such as PCI configuration space) which currently 1934use space-specific access methods to use the 1935.Nm 1936functions where that is appropriate. 1937.It 1938Redefining the way bus space is mapped and allocated, so that mapping 1939and allocation are done with bus specific functions which return bus 1940space tags. 1941This would allow further optimization than is currently possible, and 1942would also ease translation of the 1943.Nm 1944functions into user space (since mapping in user space would look like 1945it just used a different bus-specific mapping function). 1946.El 1947.Sh COMPATIBILITY 1948The current version of the 1949.Nm 1950interface specification differs slightly from the original 1951specification that came into wide use. 1952A few of the function names and arguments have changed 1953for consistency and increased functionality. 1954Drivers that were written to the 1955old, deprecated specification can be compiled by defining the 1956.Dv __BUS_SPACE_COMPAT_OLDDEFS 1957preprocessor symbol before including 1958.In sys/bus.h . 1959.Sh SEE ALSO 1960.Xr bus_dma 9 , 1961.Xr mb 9 1962.Sh HISTORY 1963The 1964.Nm 1965functions were introduced in a different form (memory and I/O spaces 1966were accessed via different sets of functions) in 1967.Nx 1.2 . 1968The functions were merged to work on generic 1969.Dq spaces 1970early in the 1971.Nx 1.3 1972development cycle, and many drivers were converted to use them. 1973This document was written later during the 1974.Nx 1.3 1975development cycle and the specification was updated to fix some 1976consistency problems and to add some missing functionality. 1977.Sh AUTHORS 1978.An -nosplit 1979The 1980.Nm 1981interfaces were designed and implemented by the 1982.Nx 1983developer 1984community. 1985Primary contributors and implementors were 1986.An Chris Demetriou , 1987.An Jason Thorpe , 1988and 1989.An Charles Hannum , 1990but the rest of the 1991.Nx 1992developers and the user community played a significant role in development. 1993.Pp 1994.An Chris Demetriou 1995wrote this manual page. 1996