1.\" $NetBSD: bus_space.9,v 1.55 2022/08/13 17:06:55 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 August 12, 2022 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 469Bus space I/O operations on mappings made with 470.Dv BUS_SPACE_MAP_PREFETCHABLE 471or 472.Dv BUS_SPACE_MAP_CACHEABLE 473may be reordered or combined for performance on devices that support 474it, such as write-combining 475.Pq "a.k.a." Sq prefetchable 476graphics framebuffers or cacheable ROM images. 477The 478.Fn bus_space_barrier 479function orders reads and writes in prefetchable or cacheable mappings 480relative to other reads and writes in bus spaces. 481Barriers are needed 482.Em only 483when prefetchable or cacheable mappings are involved: 484.Bl -bullet 485.It 486Bus space reads and writes on non-prefetchable, non-cacheable mappings 487at a single device are totally ordered with one another. 488.It 489Ordering of memory operations on normal memory with bus space I/O 490for triggering DMA or being notified of DMA completion requires 491.Xr bus_dmamap_sync 9 . 492.El 493.Pp 494People trying to write portable drivers with the 495.Nm 496functions should 497try to make minimal assumptions about what the system allows. 498In particular, they should expect that the system requires bus space 499addresses being accessed to be naturally aligned (i.e., base address of 500handle added to offset is a multiple of the access size), and that the 501system does alignment checking on pointers (i.e., pointer to objects being 502read and written must point to properly-aligned data). 503.Pp 504The descriptions of the 505.Nm 506functions given below all assume that 507they are called with proper arguments. 508If called with invalid arguments or arguments that are out of range 509(e.g., trying to access data outside of the region mapped when a given 510handle was created), undefined behaviour results. 511In that case, they may cause the system to halt, either intentionally 512(via panic) or unintentionally (by causing a fatal trap or by some other 513means) or may cause improper operation which is not immediately fatal. 514Functions which return void or which return data read from bus space 515(i.e., functions which don't obviously return an error code) do not fail. 516They could only fail if given invalid arguments, and in that case their 517behaviour is undefined. 518Functions which take a count of bytes have undefined results if the specified 519.Fa count 520is zero. 521.Sh TYPES 522Several types are defined in 523.In machine/bus_defs.h 524to facilitate use of the 525.Nm 526functions by drivers. 527.Pp 528.Bl -ohang -compact 529.It Fa bus_addr_t 530.Pp 531The 532.Fa bus_addr_t 533type is used to describe bus addresses. 534It must be an unsigned integral type capable of holding the largest bus 535address usable by the architecture. 536This type is primarily used when mapping and unmapping bus space. 537.Pp 538.It Fa bus_size_t 539.Pp 540The 541.Fa bus_size_t 542type is used to describe sizes of ranges in bus space. 543It must be an unsigned integral type capable of holding the size of the 544largest bus address range usable on the architecture. 545This type is used by virtually all of the 546.Nm 547functions, describing sizes when mapping regions and 548offsets into regions when performing space access operations. 549.Pp 550.It Fa bus_space_tag_t 551.Pp 552The 553.Fa bus_space_tag_t 554type is used to describe a particular bus space on a machine. 555Its contents are machine-dependent and should be considered opaque by 556machine-independent code. 557This type is used by all 558.Nm 559functions to name the space on which they're operating. 560.Pp 561.It Fa bus_space_handle_t 562.Pp 563The 564.Fa bus_space_handle_t 565type is used to describe a mapping of a range of bus space. 566Its contents are machine-dependent and should be considered opaque by 567machine-independent code. 568This type is used when performing bus space access operations. 569.Pp 570.It Fa bus_space_reservation_t 571.Pp 572The 573.Fa bus_space_reservation_t 574type is used to describe a range of bus space. 575It logically consists of a 576.Fa bus_addr_t , 577the first address in the range, 578and a 579.Fa bus_size_t , 580the length in bytes of the range. 581Machine-independent code creates and interrogates a 582.Fa bus_space_reservation_t 583using a constructor, 584.Fn bus_space_reservation_init , 585and accessor functions, 586.Fn bus_space_reservation_addr 587and 588.Fn bus_space_reservation_size . 589.El 590.Sh COMPARING BUS SPACE TAGS 591To check whether or not one 592.Fa bus_space_tag_t 593refers to the same space as another in machine-independent code, 594do not use either 595.Xr memcmp 9 596or the C equals 597.Po 598== 599.Pc 600operator. 601Use 602.Fn bus_space_is_equal , 603instead. 604.Sh MAPPING AND UNMAPPING BUS SPACE 605Bus space must be mapped before it can be used, and should be 606unmapped when it is no longer needed. 607The 608.Fn bus_space_map , 609.Fn bus_space_reservation_map , 610.Fn bus_space_reservation_unmap , 611and 612.Fn bus_space_unmap 613functions provide these capabilities. 614.Pp 615Some drivers need to be able to pass a subregion of already-mapped bus 616space to another driver or module within a driver. 617The 618.Fn bus_space_subregion 619function allows such subregions to be created. 620.Pp 621.Bl -ohang -compact 622.It Fn bus_space_map "space" "address" "size" "flags" "handlep" 623.Pp 624The 625.Fn bus_space_map 626function exclusively reserves and maps the region of bus space named by the 627.Fa space , 628.Fa address , 629and 630.Fa size 631arguments. 632If successful, it returns zero and fills in the bus space handle pointed 633to by 634.Fa handlep 635with the handle 636that can be used to access the mapped region. 637If unsuccessful, it will return non-zero and leave the bus space handle 638pointed to by 639.Fa handlep 640in an undefined state. 641.Pp 642The 643.Fa flags 644argument controls how the space is to be mapped. 645Supported flags include: 646.Bl -tag -width BUS_SPACE_MAP_CACHEABLE -offset indent 647.It Dv BUS_SPACE_MAP_CACHEABLE 648Try to map the space so that accesses can be cached 649by the system cache. 650If this flag is not specified, the implementation should map the space so 651that it will not be cached. 652This mapping method will only be useful in very rare occasions. 653.Pp 654This flag must have a value of 1 on all implementations for backward 655compatibility. 656.It Dv BUS_SPACE_MAP_PREFETCHABLE 657Try to map the space so that accesses can be prefetched by the system, 658and writes can be buffered. 659This means, accesses should be side effect free (idempotent). 660The 661.Fn bus_space_barrier 662methods will flush the write buffer or force actual read accesses. 663If this flag is not specified, the 664implementation should map the space so that it will not be prefetched 665or delayed. 666.It Dv BUS_SPACE_MAP_LINEAR 667Try to map the space so that its contents can be accessed linearly via 668normal memory access methods (e.g., pointer dereferencing and structure 669accesses). 670The 671.Fn bus_space_vaddr 672method can be used to obtain the kernel virtual address of the mapped range. 673This is useful when software wants to do direct access to a memory 674device, e.g., a frame buffer. 675If this flag is specified and linear mapping is not possible, the 676.Fn bus_space_map 677call should fail. 678If this flag is not specified, the system may map the space in whatever 679way is most convenient. 680Use of this mapping method is not encouraged for normal device access; 681where linear access is not essential, use of the 682.Fn bus_space_read/write 683methods is strongly recommended. 684.El 685.Pp 686Not all combinations of flags make sense or are supported with all 687spaces. 688For instance, 689.Dv BUS_SPACE_MAP_CACHEABLE 690may be meaningless when 691used on many systems' I/O port spaces, and on some systems 692.Dv BUS_SPACE_MAP_LINEAR 693without 694.Dv BUS_SPACE_MAP_PREFETCHABLE 695may never work. 696When the system hardware or firmware provides hints as to how spaces should be 697mapped (e.g., the PCI memory mapping registers' "prefetchable" bit), those 698hints should be followed for maximum compatibility. 699On some systems, requesting a mapping that cannot be satisfied (e.g., 700requesting a non-prefetchable mapping when the system can only provide 701a prefetchable one) will cause the request to fail. 702.Pp 703Some implementations may keep track of use of bus space for some or all 704bus spaces and refuse to allow duplicate allocations. 705This is encouraged for bus spaces which have no notion of slot-specific 706space addressing, such as ISA and VME, and for spaces which coexist with 707those spaces (e.g., EISA and PCI memory and I/O spaces co-existing with 708ISA memory and I/O spaces). 709.Pp 710Mapped regions may contain areas for which there is no device on the bus. 711If space in those areas is accessed, the results are bus-dependent. 712.Pp 713.It Fn bus_space_reservation_map "space" "bsr" "flags" "handlep" 714.Pp 715The 716.Fn bus_space_reservation_map 717function is similar to 718.Fn bus_space_map 719but it maps a region of bus space 720that was previously reserved by a call to 721.Fn bus_space_reserve 722or 723.Fn bus_space_reserve_subregion . 724The region is given by the 725.Fa space 726and 727.Fa bsr 728arguments. 729If successful, it returns zero and fills in the bus space handle pointed 730to by 731.Fa handlep 732with the handle that can be used to access the mapped region. 733If unsuccessful, it will return non-zero and leave the bus space handle 734pointed to by 735.Fa handlep 736in an undefined state. 737.Pp 738A region mapped by 739.Fn bus_space_reservation_map 740may only be unmapped by a call to 741.Fn bus_space_reservation_unmap . 742.Pp 743For more details, see the description of 744.Fn bus_space_map . 745.Pp 746.It Fn bus_space_unmap "space" "handle" "size" 747.Pp 748The 749.Fn bus_space_unmap 750function unmaps and relinquishes a region of bus space reserved and 751mapped with 752.Fn bus_space_map . 753When unmapping a region, the 754.Fa size 755specified should be 756the same as the size given to 757.Fn bus_space_map 758when mapping that region. 759.Pp 760After 761.Fn bus_space_unmap 762is called on a handle, that handle is no longer valid. 763(If copies were made of the handle they are no longer valid, either.) 764.Pp 765This function will never fail. 766If it would fail (e.g., because of an argument error), that indicates 767a software bug which should cause a panic. 768In that case, 769.Fn bus_space_unmap 770will never return. 771.Pp 772.It Fn bus_space_reservation_unmap "space" "handle" "size" 773.Pp 774The 775.Fn bus_space_reservation_unmap 776function is similar to 777.Fn bus_space_unmap 778but it should be called on handles 779mapped by 780.Fn bus_space_reservation_map 781and only on such handles. 782Unlike 783.Fn bus_space_unmap , 784.Fn bus_space_reservation_unmap 785does not relinquish exclusive use of the bus space named by 786.Fa handle 787and 788.Fa size ; 789that is the job of 790.Fn bus_space_release . 791.Pp 792.It Fn bus_space_subregion "space" "handle" "offset" "size" "nhandlep" 793.Pp 794The 795.Fn bus_space_subregion 796function is a convenience function which makes a 797new handle to some subregion of an already-mapped region of bus space. 798The subregion described by the new handle starts at byte offset 799.Fa offset 800into the region described by 801.Fa handle , 802with the size given by 803.Fa size , 804and must be wholly contained within the original region. 805.Pp 806If successful, 807.Fn bus_space_subregion 808returns zero and fills in the bus 809space handle pointed to by 810.Fa nhandlep . 811If unsuccessful, it returns non-zero and leaves the bus space handle 812pointed to by 813.Fa nhandlep 814in an 815undefined state. 816In either case, the handle described by 817.Fa handle 818remains valid and is unmodified. 819.Pp 820When done with a handle created by 821.Fn bus_space_subregion , 822the handle should 823be thrown away. 824Under no circumstances should 825.Fn bus_space_unmap 826be used on the handle. 827Doing so may confuse any resource management being done on the space, 828and will result in undefined behaviour. 829When 830.Fn bus_space_unmap 831or 832.Fn bus_space_free 833is called on a handle, all subregions of that handle become invalid. 834.Pp 835.It Fn bus_space_vaddr "tag" "handle" 836.Pp 837This method returns the kernel virtual address of a mapped bus space if and 838only if it was mapped with the 839.Dv BUS_SPACE_MAP_LINEAR 840flag. 841The range can be accessed by normal (volatile) pointer dereferences. 842If mapped with the 843.Dv BUS_SPACE_MAP_PREFETCHABLE 844flag, the 845.Fn bus_space_barrier 846method must be used to force a particular access order. 847.Pp 848.It Fn bus_space_mmap "tag" "addr" "off" "prot" "flags" 849.Pp 850This method is used to provide support for memory mapping bus space 851into user applications. 852If an address space is addressable via volatile pointer dereferences, 853.Fn bus_space_mmap 854will return the physical address (possibly encoded as a machine-dependent 855cookie) of the bus space indicated by 856.Fa addr 857and 858.Fa off . 859.Fa addr 860is the base address of the device or device region, and 861.Fa off 862is the offset into that region that is being requested. 863If the request is made with 864.Dv BUS_SPACE_MAP_LINEAR 865as a flag, then a linear region must be returned to the caller. 866If the region cannot be mapped (either the address does not exist, 867or the constraints can not be met), 868.Fn bus_space_mmap 869returns 870.Dv -1 871to indicate failure. 872.Pp 873Note that it is not necessary that the region being requested by a 874.Fn bus_space_mmap 875call be mapped into a 876.Fa bus_space_handle_t . 877.Pp 878.Fn bus_space_mmap 879is called once per 880.Dv PAGE_SIZE 881page in the range. 882The 883.Fa prot 884argument indicates the memory protection requested by the user application 885for the range. 886.Pp 887.It Fn bus_space_handle_is_equal "space" "handle1" "handle2" 888Use 889.Fn bus_space_handle_is_equal 890to check whether or not 891.Fa handle1 892and 893.Fa handle2 894refer to regions starting at the same address in the bus space 895.Fa space . 896.El 897.Sh ALLOCATING AND FREEING BUS SPACE 898Some devices require or allow bus space to be allocated by the operating 899system for device use. 900When the devices no longer need the space, the 901operating system should free it for use by other devices. 902The 903.Fn bus_space_alloc , 904.Fn bus_space_free , 905.Fn bus_space_reserve , 906.Fn bus_space_reserve_subregion , 907and 908.Fn bus_space_release 909functions provide these capabilities. 910The functions 911.Fn bus_space_reserve , 912.Fn bus_space_reserve_subregion , 913and 914.Fn bus_space_release 915are not yet available on all architectures. 916.Pp 917.Bl -ohang -compact 918.It Fn bus_space_alloc "space" "reg_start" "reg_end" "size" "alignment" \ 919"boundary" "flags" "addrp" "handlep" 920.Pp 921The 922.Fn bus_space_alloc 923function allocates and maps a region of bus space with the size given by 924.Fa size , 925corresponding to the given constraints. 926If successful, it returns zero, fills in the bus address pointed to by 927.Fa addrp 928with the bus space address of the allocated region, and fills in 929the bus space handle pointed to by 930.Fa handlep 931with the handle that can be used to access that region. 932If unsuccessful, it returns non-zero and leaves the bus address pointed to by 933.Fa addrp 934and the bus space handle pointed to by 935.Fa handlep 936in an undefined state. 937.Pp 938Constraints on the allocation are given by the 939.Fa reg_start , 940.Fa reg_end , 941.Fa alignment , 942and 943.Fa boundary 944parameters. 945The allocated region will start at or after 946.Fa reg_start 947and end before or at 948.Fa reg_end . 949The 950.Fa alignment 951constraint must be a power of two, and the allocated region will start at 952an address that is an even multiple of that power of two. 953The 954.Fa boundary 955constraint, if non-zero, ensures that the region is allocated so that 956.Fa "first address in region" 957/ 958.Fa boundary 959has the same value as 960.Fa "last address in region" 961/ 962.Fa boundary . 963If the constraints cannot be met, 964.Fn bus_space_alloc 965will fail. 966It is an error to specify a set of constraints that can never be met 967.Po 968for example, 969.Fa size 970greater than 971.Fa boundary 972.Pc . 973.Pp 974The 975.Fa flags 976parameter is the same as the like-named parameter to 977.Fa bus_space_map , 978the same flag values should be used, and they have the 979same meanings. 980.Pp 981Handles created by 982.Fn bus_space_alloc 983should only be freed with 984.Fn bus_space_free . 985Trying to use 986.Fn bus_space_unmap 987on them causes undefined behaviour. 988The 989.Fn bus_space_subregion 990function can be used on handles created by 991.Fn bus_space_alloc . 992.Pp 993.It Fn bus_space_reserve "t" "bpa" "size" "flags" "bsrp" 994.Pp 995The 996.Fn bus_space_reserve 997function reserves, for the caller's exclusive use, 998.Fa size 999bytes starting at the address 1000.Fa bpa 1001in the space referenced by 1002.Fa t . 1003.Pp 1004.Fn bus_space_reserve 1005does 1006.Em not 1007map the space. 1008The caller should use 1009.Fn bus_space_reservation_map 1010to map the reservation. 1011.Fa flags 1012contains a hint how the caller may map the reservation, later. 1013Whenever possible, callers should pass the same flags to 1014.Fn bus_space_reserve 1015as they will pass to 1016.Fn bus_space_reservation_map 1017to map the reservation. 1018.Pp 1019On success, 1020.Fn bus_space_reserve 1021records the reservation at 1022.Fa bsrp 1023and returns 0. 1024On failure, 1025.Fa bsrp 1026is undefined, and 1027.Fn bus_space_reserve 1028returns a non-zero error code. 1029Possible error codes include 1030.Bl -tag -width EOPNOTSUPP -offset indent 1031.It Er ENOMEM 1032There was not sufficient bus space at 1033.Fa bpa 1034to satisfy the request. 1035.It Er EOPNOTSUPP 1036.Fn bus_space_reserve 1037is not supported on this architecture, or 1038.Fa flags 1039was incompatible with the bus space represented by 1040.Fa t . 1041.El 1042.Pp 1043.It Fn bus_space_reserve_subregion "t" "reg_start" "reg_end" \ 1044 "size" "alignment" "boundary" "flags" "bsrp" 1045.Pp 1046The 1047.Fn bus_space_reserve_subregion 1048function reserves, for the caller's exclusive use, 1049.Fa size 1050bytes in the space referenced by 1051.Fa t . 1052The parameters 1053.Fa reg_start , 1054.Fa reg_end , 1055.Fa alignment , 1056.Fa boundary , 1057and 1058.Fa flags 1059each work alike to the 1060.Fn bus_space_alloc 1061parameters of the same names. 1062.Pp 1063On success, 1064.Fn bus_space_reserve_subregion 1065records the reservation at 1066.Fa bsrp 1067and returns 0. 1068On failure, 1069.Fa bsrp 1070is undefined, and 1071.Fn bus_space_reserve_subregion 1072returns a non-zero error code. 1073Possible error codes include 1074.Bl -tag -width EOPNOTSUPP -offset indent 1075.It Er ENOMEM 1076There was not sufficient bus space at 1077.Fa bpa 1078to satisfy the request. 1079.It Er EOPNOTSUPP 1080.Fn bus_space_reserve 1081is not supported on this architecture, or 1082.Fa flags 1083was incompatible with the bus space represented by 1084.Fa t . 1085.El 1086.Pp 1087.It Fn bus_space_release "t" "bsr" 1088.Pp 1089The 1090.Fn bus_space_release 1091function releases the bus space 1092.Fa bsr 1093in 1094.Fa t 1095that was previously reserved by 1096.Fn bus_space_reserve 1097or 1098.Fn bus_space_reserve_subregion . 1099.Pp 1100If 1101.Fn bus_space_release 1102is called on a reservation that has been mapped by 1103.Fn bus_space_reservation_map 1104without subsequently being unmapped, the behavior of the system is 1105undefined. 1106.Pp 1107.It Fn bus_space_free "space" "handle" "size" 1108.Pp 1109The 1110.Fn bus_space_free 1111function unmaps and frees a region of bus space mapped 1112and allocated with 1113.Fn bus_space_alloc . 1114When unmapping a region, the 1115.Fa size 1116specified should be the same as the size given to 1117.Fn bus_space_alloc 1118when allocating the region. 1119.Pp 1120After 1121.Fn bus_space_free 1122is called on a handle, that handle is no longer valid. 1123(If copies were made of the handle, they are no longer valid, either.) 1124.Pp 1125This function will never fail. 1126If it would fail (e.g., because of an argument error), that indicates 1127a software bug which should cause a panic. 1128In that case, 1129.Fn bus_space_free 1130will never return. 1131.El 1132.Sh READING AND WRITING SINGLE DATA ITEMS 1133The simplest way to access bus space is to read or write a single data 1134item. 1135The 1136.Fn bus_space_read_N 1137and 1138.Fn bus_space_write_N 1139families of functions provide 1140the ability to read and write 1, 2, 4, and 8 byte data items on busses 1141which support those access sizes. 1142.Pp 1143.Bl -ohang -compact 1144.It Fn bus_space_read_1 "space" "handle" "offset" 1145.It Fn bus_space_read_2 "space" "handle" "offset" 1146.It Fn bus_space_read_4 "space" "handle" "offset" 1147.It Fn bus_space_read_8 "space" "handle" "offset" 1148.Pp 1149The 1150.Fn bus_space_read_N 1151family of functions reads a 1, 2, 4, or 8 byte data item from 1152the offset specified by 1153.Fa offset 1154into the region specified by 1155.Fa handle 1156of the bus space specified by 1157.Fa space . 1158The location being read must lie within the bus space region specified by 1159.Fa handle . 1160.Pp 1161For portability, the starting address of the region specified by 1162.Fa handle 1163plus the offset should be a multiple of the size of data item being read. 1164On some systems, not obeying this requirement may cause incorrect data to 1165be read, on others it may cause a system crash. 1166.Pp 1167Read operations done by the 1168.Fn bus_space_read_N 1169functions may be executed out of order with respect to other read and 1170write operations if either are on prefetchable or cacheable mappings 1171unless order is enforced by use of the 1172.Fn bus_space_barrier 1173function. 1174.Pp 1175These functions will never fail. 1176If they would fail (e.g., because of an argument error), that indicates 1177a software bug which should cause a panic. 1178In that case, they will never return. 1179.Pp 1180.It Fn bus_space_write_1 "space" "handle" "offset" "value" 1181.It Fn bus_space_write_2 "space" "handle" "offset" "value" 1182.It Fn bus_space_write_4 "space" "handle" "offset" "value" 1183.It Fn bus_space_write_8 "space" "handle" "offset" "value" 1184.Pp 1185The 1186.Fn bus_space_write_N 1187family of functions writes a 1, 2, 4, or 8 byte data item to the offset 1188specified by 1189.Fa offset 1190into the region specified by 1191.Fa handle 1192of the bus space specified by 1193.Fa space . 1194The location being written must lie within 1195the bus space region specified by 1196.Fa handle . 1197.Pp 1198For portability, the starting address of the region specified by 1199.Fa handle 1200plus the offset should be a multiple of the size of data item being 1201written. 1202On some systems, not obeying this requirement may cause incorrect data 1203to be written, on others it may cause a system crash. 1204.Pp 1205Write operations done by the 1206.Fn bus_space_write_N 1207functions may be executed out of order with respect to other read and 1208write operations if either are on prefetchable or cacheable mappings 1209unless order is enforced by use of the 1210.Fn bus_space_barrier 1211function. 1212.Pp 1213These functions will never fail. 1214If they would fail (e.g., because of an argument error), that indicates 1215a software bug which should cause a panic. 1216In that case, they will never return. 1217.El 1218.Sh PROBING BUS SPACE FOR HARDWARE WHICH MAY NOT RESPOND 1219One problem with the 1220.Fn bus_space_read_N 1221and 1222.Fn bus_space_write_N 1223family of functions is that they provide no protection against 1224exceptions which can occur when no physical hardware or 1225device responds to the read or write cycles. 1226In such a situation, the system typically would panic due to a kernel-mode 1227bus error. 1228The 1229.Fn bus_space_peek_N 1230and 1231.Fn bus_space_poke_N 1232family of functions provide a mechanism to handle these exceptions 1233gracefully without the risk of crashing the system. 1234.Pp 1235As with 1236.Fn bus_space_read_N 1237and 1238.Fn bus_space_write_N , 1239the peek and poke functions provide the ability to read and 1240write 1, 2, 4, and 8 byte data items on busses which support those 1241access sizes. 1242All of the constraints specified in the descriptions of the 1243.Fn bus_space_read_N 1244and 1245.Fn bus_space_write_N 1246functions also apply to 1247.Fn bus_space_peek_N 1248and 1249.Fn bus_space_poke_N . 1250.Pp 1251The return value indicates the outcome of the peek or poke operation. 1252A return value of zero implies that a hardware device is 1253responding to the operation at the specified offset in the bus space. 1254A non-zero return value indicates that the kernel intercepted a 1255hardware exception (e.g., bus error) when the peek or poke operation 1256was attempted. 1257Note that some busses are incapable of generating exceptions when 1258non-existent hardware is accessed. 1259In such cases, these functions will always return zero and the value of 1260the data read by 1261.Fn bus_space_peek_N 1262will be unspecified. 1263.Pp 1264Finally, it should be noted that at this time the 1265.Fn bus_space_peek_N 1266and 1267.Fn bus_space_poke_N 1268functions are not re-entrant and should not, therefore, be used 1269from within an interrupt service routine. 1270This constraint may be removed at some point in the future. 1271.Pp 1272.Bl -ohang -compact 1273.It Fn bus_space_peek_1 "space" "handle" "offset" "datap" 1274.It Fn bus_space_peek_2 "space" "handle" "offset" "datap" 1275.It Fn bus_space_peek_4 "space" "handle" "offset" "datap" 1276.It Fn bus_space_peek_8 "space" "handle" "offset" "datap" 1277.Pp 1278The 1279.Fn bus_space_peek_N 1280family of functions cautiously read a 1, 2, 4, or 8 byte data item from 1281the offset specified by 1282.Fa offset 1283in the region specified by 1284.Fa handle 1285of the bus space specified by 1286.Fa space . 1287The data item read is stored in the location pointed to by 1288.Fa datap . 1289It is permissible for 1290.Fa datap 1291to be NULL, in which case the data item will be discarded after being read. 1292.Pp 1293.It Fn bus_space_poke_1 "space" "handle" "offset" "value" 1294.It Fn bus_space_poke_2 "space" "handle" "offset" "value" 1295.It Fn bus_space_poke_4 "space" "handle" "offset" "value" 1296.It Fn bus_space_poke_8 "space" "handle" "offset" "value" 1297.Pp 1298The 1299.Fn bus_space_poke_N 1300family of functions cautiously write a 1, 2, 4, or 8 byte data item 1301specified by 1302.Fa value 1303to the offset specified by 1304.Fa offset 1305in the region specified by 1306.Fa handle 1307of the bus space specified by 1308.Fa space . 1309.El 1310.Sh BARRIERS 1311Devices that support prefetchable (also known as 1312.Sq write-combining ) 1313or cacheable I/O may be mapped with 1314.Dv BUS_SPACE_MAP_PREFETCHABLE 1315or 1316.Dv BUS_SPACE_MAP_CACHEABLE 1317for higher performance by allowing bus space read and write operations 1318to be reordered, fused, torn, and/or cached by the system. 1319.Pp 1320When a driver requires ordering, e.g. to write to a command ring in bus 1321space and then update the command ring pointer, the 1322.Fn bus_space_barrier 1323function enforces it. 1324.Pp 1325.Bl -ohang -compact 1326.It Fn bus_space_barrier "space" "handle" "offset" "length" "flags" 1327.Pp 1328The 1329.Fn bus_space_barrier 1330function enforces ordering of bus space read and write operations 1331for the specified subregion (described by the 1332.Fa offset 1333and 1334.Fa length 1335parameters) of the region named by 1336.Fa handle 1337in the space named by 1338.Fa space . 1339.Pp 1340The 1341.Fa flags 1342argument controls what types of operations are to be ordered. 1343Supported flags are: 1344.Bl -tag -width BUS_SPACE_BARRIER_WRITE -offset indent 1345.It Dv BUS_SPACE_BARRIER_READ 1346Guarantee that any program-prior bus space read on 1347.Em any 1348bus space has returned data from the device or memory before any 1349program-later bus space read, bus space write, or memory access via 1350.Fn bus_space_vaddr , 1351on the specified range in the given bus space. 1352.Pp 1353This functions similarly to 1354.Xr membar_acquire 3 , 1355but additionally orders bus space I/O which 1356.Xr membar_ops 3 1357may not. 1358.It Dv BUS_SPACE_BARRIER_WRITE 1359Guarantee that any program-prior bus space read, bus space write, or 1360memory access via 1361.Fn bus_space_vaddr , 1362on the specified range in the given bus space, has completed before any 1363program-later bus space write on 1364.Em any 1365bus space. 1366.Pp 1367This functions similarly to 1368.Xr membar_release 3 , 1369but additionally orders bus space I/O which 1370.Xr membar_ops 3 1371may not. 1372.It Dv "BUS_SPACE_BARRIER_READ" | Dv "BUS_SPACE_BARRIER_WRITE" 1373Guarantee that any program-prior bus space read, bus space write, or 1374memory access via 1375.Fn bus_space_vaddr 1376on 1377.Em any 1378bus space has completed before any program-later bus space read, bus 1379space write, or memory access via 1380.Fn bus_space_vaddr 1381on 1382.Em any 1383bus space. 1384.Pp 1385Note that this is independent of the specified bus space and range. 1386.Pp 1387This functions similarly to 1388.Xr membar_sync 3 , 1389but additionally orders bus space I/O which 1390.Xr membar_ops 3 1391may not. 1392This combination is very unusual, and often much more expensive; most 1393drivers do not need it. 1394.El 1395.Pp 1396Example: Consider a command ring in bus space with a command ring 1397pointer register, and a response ring in bus space with a response ring 1398pointer register. 1399.Bd -literal 1400error = bus_space_map(sc->sc_regt, ..., 0, &sc->sc_regh); 1401if (error) 1402 \&... 1403error = bus_space_map(sc->sc_memt, ..., BUS_SPACE_MAP_PREFETCHABLE, 1404 &sc->sc_memh); 1405if (error) 1406 \&... 1407.Ed 1408.Pp 1409To submit a command (assuming there is space in the ring), first write 1410it out and then update the pointer: 1411.Bd -literal 1412i = sc->sc_nextcmdslot; 1413bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i), cmd); 1414bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i) + 4, arg1); 1415bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i) + 8, arg2); 1416\&... 1417bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i) + 4*n, argn); 1418bus_space_barrier(sc->sc_memt, sc->sc_memh, CMDSLOT(i), 4*n, 1419 BUS_SPACE_BARRIER_WRITE); 1420bus_space_write_4(sc->sc_regt, sc->sc_regh, CMDPTR, i); 1421sc->sc_nextcmdslot = (i + n + 1) % sc->sc_ncmdslots; 1422.Ed 1423.Pp 1424To obtain a response, read the pointer first and then the ring data: 1425.Bd -literal 1426ptr = bus_space_read_4(sc->sc_regt, sc->sc_regh, RESPPTR); 1427while ((i = sc->sc_nextrespslot) != ptr) { 1428 bus_space_barrier(sc->sc_memt, sc->sc_memh, RESPSLOT(i), 4, 1429 BUS_SPACE_BARRIER_READ); 1430 status = bus_space_read_4(sc->sc_memt, sc->sc_memh, RESPSLOT(i)); 1431 handle_response(status); 1432 sc->sc_nextrespslot = (i + 1) % sc->sc_nrespslots; 1433} 1434.Ed 1435.El 1436.Sh REGION OPERATIONS 1437Some devices use buffers which are mapped as regions in bus space. 1438Often, drivers want to copy the contents of those buffers to or from 1439memory, e.g., into mbufs which can be passed to higher levels of the 1440system or from mbufs to be output to a network. 1441In order to allow drivers to do this as efficiently as possible, the 1442.Fn bus_space_read_region_N 1443and 1444.Fn bus_space_write_region_N 1445families of functions are provided. 1446.Pp 1447Drivers occasionally need to copy one region of a bus space to another, 1448or to set all locations in a region of bus space to contain a single 1449value. 1450The 1451.Fn bus_space_copy_region_N 1452family of functions and the 1453.Fn bus_space_set_region_N 1454family of functions allow drivers to perform these operations. 1455.Pp 1456.Bl -ohang -compact 1457.It Fn bus_space_read_region_1 "space" "handle" "offset" "datap" "count" 1458.It Fn bus_space_read_region_2 "space" "handle" "offset" "datap" "count" 1459.It Fn bus_space_read_region_4 "space" "handle" "offset" "datap" "count" 1460.It Fn bus_space_read_region_8 "space" "handle" "offset" "datap" "count" 1461.Pp 1462The 1463.Fn bus_space_read_region_N 1464family of functions reads 1465.Fa count 14661, 2, 4, or 8 byte data items from bus space 1467starting at byte offset 1468.Fa offset 1469in the region specified by 1470.Fa handle 1471of the bus space specified by 1472.Fa space 1473and writes them into the array specified by 1474.Fa datap . 1475Each successive data item is read from an offset 14761, 2, 4, or 8 bytes after the previous data item (depending on which 1477function is used). 1478All locations being read must lie within the bus space region specified by 1479.Fa handle . 1480.Pp 1481For portability, the starting address of the region specified by 1482.Fa handle 1483plus the offset should be a multiple of the size of data items being 1484read and the data array pointer should be properly aligned. 1485On some systems, not obeying these requirements may cause incorrect data 1486to be read, on others it may cause a system crash. 1487.Pp 1488Read operations done by the 1489.Fn bus_space_read_region_N 1490functions may be executed in any order. 1491They may also be executed out of order with respect to other read and 1492write operations if either are on prefetchable or cacheable mappings 1493unless order is enforced by use of the 1494.Fn bus_space_barrier 1495function. 1496There is no way to insert barriers between reads of individual bus 1497space locations executed by the 1498.Fn bus_space_read_region_N 1499functions. 1500.Pp 1501These functions will never fail. 1502If they would fail (e.g., because of an argument error), that indicates a 1503software bug which should cause a panic. 1504In that case, they will never return. 1505.Pp 1506.It Fn bus_space_write_region_1 "space" "handle" "offset" "datap" "count" 1507.It Fn bus_space_write_region_2 "space" "handle" "offset" "datap" "count" 1508.It Fn bus_space_write_region_4 "space" "handle" "offset" "datap" "count" 1509.It Fn bus_space_write_region_8 "space" "handle" "offset" "datap" "count" 1510.Pp 1511The 1512.Fn bus_space_write_region_N 1513family of functions reads 1514.Fa count 15151, 2, 4, or 8 byte data items from the array 1516specified by 1517.Fa datap 1518and writes them to bus space starting at byte offset 1519.Fa offset 1520in the region specified by 1521.Fa handle 1522of the bus space specified 1523by 1524.Fa space . 1525Each successive data item is written to an offset 1, 2, 4, 1526or 8 bytes after the previous data item (depending on which function is 1527used). 1528All locations being written must lie within the bus space region specified by 1529.Fa handle . 1530.Pp 1531For portability, the starting address of the region specified by 1532.Fa handle 1533plus the offset should be a multiple of the size of data items being 1534written and the data array pointer should be properly aligned. 1535On some systems, not obeying these requirements may cause incorrect data 1536to be written, on others it may cause a system crash. 1537.Pp 1538Write operations done by the 1539.Fn bus_space_write_region_N 1540functions may be 1541executed in any order. 1542They may also be executed out of order with respect to other read and 1543write operations if either are on prefetchable or cacheable mappings 1544unless order is enforced by use of the 1545.Fn bus_space_barrier 1546function. 1547There is no way to insert barriers between writes of individual bus 1548space locations executed by the 1549.Fn bus_space_write_region_N 1550functions. 1551.Pp 1552These functions will never fail. 1553If they would fail (e.g., because of an argument error), that indicates 1554a software bug which should cause a panic. 1555In that case, they will never return. 1556.Pp 1557.It Fn bus_space_copy_region_1 "space" "srchandle" "srcoffset" "dsthandle" \ 1558"dstoffset" "count" 1559.It Fn bus_space_copy_region_2 "space" "srchandle" "srcoffset" "dsthandle" \ 1560"dstoffset" "count" 1561.It Fn bus_space_copy_region_4 "space" "srchandle" "srcoffset" "dsthandle" \ 1562"dstoffset" "count" 1563.It Fn bus_space_copy_region_8 "space" "srchandle" "srcoffset" "dsthandle" \ 1564"dstoffset" "count" 1565.Pp 1566The 1567.Fn bus_space_copy_region_N 1568family of functions copies 1569.Fa count 15701, 2, 4, or 8 byte data items in bus space 1571from the area starting at byte offset 1572.Fa srcoffset 1573in the region specified by 1574.Fa srchandle 1575of the bus space specified by 1576.Fa space 1577to the area starting at byte offset 1578.Fa dstoffset 1579in the region specified by 1580.Fa dsthandle 1581in the same bus space. 1582Each successive data item read or written has an offset 1, 2, 4, or 8 1583bytes after the previous data item (depending on which function is used). 1584All locations being read and written must lie within the bus space 1585region specified by their respective handles. 1586.Pp 1587For portability, the starting addresses of the regions specified by 1588each handle plus its respective offset should be a multiple of the size 1589of data items being copied. 1590On some systems, not obeying this requirement may cause incorrect data 1591to be copied, on others it may cause a system crash. 1592.Pp 1593Read and write operations done by the 1594.Fn bus_space_copy_region_N 1595functions may be executed in any order. 1596They may also be executed out of order with respect to other read and 1597write operations if either are on prefetchable or cacheable mappings 1598unless order is enforced by use of the 1599.Fn bus_space_barrier 1600function. 1601There is no way to insert barriers between reads or writes of 1602individual bus space locations executed by the 1603.Fn bus_space_copy_region_N 1604functions. 1605.Pp 1606Overlapping copies between different subregions of a single region 1607of bus space are handled correctly by the 1608.Fn bus_space_copy_region_N 1609functions. 1610.Pp 1611These functions will never fail. 1612If they would fail (e.g., because of an argument error), that indicates 1613a software bug which should cause a panic. 1614In that case, they will never return. 1615.Pp 1616.It Fn bus_space_set_region_1 "space" "handle" "offset" "value" "count" 1617.It Fn bus_space_set_region_2 "space" "handle" "offset" "value" "count" 1618.It Fn bus_space_set_region_4 "space" "handle" "offset" "value" "count" 1619.It Fn bus_space_set_region_8 "space" "handle" "offset" "value" "count" 1620.Pp 1621The 1622.Fn bus_space_set_region_N 1623family of functions writes the given 1624.Fa value 1625to 1626.Fa count 16271, 2, 4, or 8 byte 1628data items in bus space starting at byte offset 1629.Fa offset 1630in the region specified by 1631.Fa handle 1632of the bus space specified by 1633.Fa space . 1634Each successive data item has an offset 1, 2, 4, or 8 bytes after the 1635previous data item (depending on which function is used). 1636All locations being written must lie within the bus space region 1637specified by 1638.Fa handle . 1639.Pp 1640For portability, the starting address of the region specified by 1641.Fa handle 1642plus the offset should be a multiple of the size of data items being 1643written. 1644On some systems, not obeying this requirement may cause incorrect data 1645to be written, on others it may cause a system crash. 1646.Pp 1647Write operations done by the 1648.Fn bus_space_set_region_N 1649functions may be 1650executed in any order. 1651They may also be executed out of order with respect to other read and 1652write operations if either are on prefetchable or cacheable mappings 1653unless order is enforced by use of the 1654.Fn bus_space_barrier 1655function. 1656There is no way to insert barriers between writes of 1657individual bus space locations executed by the 1658.Fn bus_space_set_region_N 1659functions. 1660.Pp 1661These functions will never fail. 1662If they would fail (e.g., because of an argument error), that indicates 1663a software bug which should cause a panic. 1664In that case, they will never return. 1665.El 1666.Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES 1667Some devices implement single locations in bus space which are to be read 1668or written multiple times to communicate data, e.g., some ethernet 1669devices' packet buffer FIFOs. 1670In order to allow drivers to manipulate these types of devices as 1671efficiently as possible, the 1672.Fn bus_space_read_multi_N 1673and 1674.Fn bus_space_write_multi_N 1675families of functions are provided. 1676.Pp 1677.Bl -ohang -compact 1678.It Fn bus_space_read_multi_1 "space" "handle" "offset" "datap" "count" 1679.It Fn bus_space_read_multi_2 "space" "handle" "offset" "datap" "count" 1680.It Fn bus_space_read_multi_4 "space" "handle" "offset" "datap" "count" 1681.It Fn bus_space_read_multi_8 "space" "handle" "offset" "datap" "count" 1682.Pp 1683The 1684.Fn bus_space_read_multi_N 1685family of functions reads 1686.Fa count 16871, 2, 4, or 8 byte data items from bus space 1688at byte offset 1689.Fa offset 1690in the region specified by 1691.Fa handle 1692of the bus space specified by 1693.Fa space 1694and writes them into the array specified by 1695.Fa datap . 1696Each successive data item is read from the same location in bus 1697space. 1698The location being read must lie within the bus space region specified by 1699.Fa handle . 1700.Pp 1701For portability, the starting address of the region specified by 1702.Fa handle 1703plus the offset should be a multiple of the size of data items being 1704read and the data array pointer should be properly aligned. 1705On some systems, not obeying these requirements may cause incorrect data 1706to be read, on others it may cause a system crash. 1707.Pp 1708Read operations done by the 1709.Fn bus_space_read_multi_N 1710functions may be executed out of order with respect to other read and 1711write operations if the latter are on prefetchable or cacheable 1712mappings unless order is enforced by use of the 1713.Fn bus_space_barrier 1714function. 1715.Fn bus_space_read_multi_N 1716makes no sense itself on prefetchable or cacheable mappings. 1717.Pp 1718These functions will never fail. 1719If they would fail (e.g., because of an argument error), that indicates 1720a software bug which should cause a panic. 1721In that case, they will never return. 1722.Pp 1723.It Fn bus_space_write_multi_1 "space" "handle" "offset" "datap" "count" 1724.It Fn bus_space_write_multi_2 "space" "handle" "offset" "datap" "count" 1725.It Fn bus_space_write_multi_4 "space" "handle" "offset" "datap" "count" 1726.It Fn bus_space_write_multi_8 "space" "handle" "offset" "datap" "count" 1727.Pp 1728The 1729.Fn bus_space_write_multi_N 1730family of functions reads 1731.Fa count 17321, 2, 4, or 8 byte data items from the array 1733specified by 1734.Fa datap 1735and writes them into bus space at byte offset 1736.Fa offset 1737in the region specified by 1738.Fa handle 1739of the bus space specified by 1740.Fa space . 1741Each successive data item is written to the same location in 1742bus space. 1743The location being written must lie within the bus space region specified by 1744.Fa handle . 1745.Pp 1746For portability, the starting address of the region specified by 1747.Fa handle 1748plus the offset should be a multiple of the size of data items being 1749written and the data array pointer should be properly aligned. 1750On some systems, not obeying these requirements may cause incorrect data 1751to be written, on others it may cause a system crash. 1752.Pp 1753Write operations done by the 1754.Fn bus_space_write_multi_N 1755functions may be executed out of order with respect to other read and 1756write operations if the latter are on prefetchable or cacheable 1757mappings unless order is enforced by use of the 1758.Fn bus_space_barrier 1759function. 1760.Fn bus_space_write_multi_N 1761makes no sense itself on prefetchable or cacheable mappings. 1762.Pp 1763These functions will never fail. 1764If they would fail (e.g., because of an argument error), that indicates 1765a software bug which should cause a panic. 1766In that case, they will never return. 1767.El 1768.Sh STREAM FUNCTIONS 1769Most of the 1770.Nm 1771functions imply a host byte-order and a bus byte-order and take care of 1772any translation for the caller. 1773In some cases, however, hardware may map a FIFO or some other memory region 1774for which the caller may want to use multi-word, yet untranslated access. 1775Access to these types of memory regions should be with the 1776.Fn bus_space_*_stream_N 1777functions. 1778.Pp 1779.Bl -ohang -compact 1780.It Fn bus_space_read_stream_1 "space" "handle" "offset" 1781.It Fn bus_space_read_stream_2 "space" "handle" "offset" 1782.It Fn bus_space_read_stream_4 "space" "handle" "offset" 1783.It Fn bus_space_read_stream_8 "space" "handle" "offset" 1784.It Fn bus_space_read_multi_stream_1 "space" "handle" "offset" "datap" "count" 1785.It Fn bus_space_read_multi_stream_2 "space" "handle" "offset" "datap" "count" 1786.It Fn bus_space_read_multi_stream_4 "space" "handle" "offset" "datap" "count" 1787.It Fn bus_space_read_multi_stream_8 "space" "handle" "offset" "datap" "count" 1788.It Fn bus_space_read_region_stream_1 "space" "handle" "offset" "datap" "count" 1789.It Fn bus_space_read_region_stream_2 "space" "handle" "offset" "datap" "count" 1790.It Fn bus_space_read_region_stream_4 "space" "handle" "offset" "datap" "count" 1791.It Fn bus_space_read_region_stream_8 "space" "handle" "offset" "datap" "count" 1792.It Fn bus_space_write_stream_1 "space" "handle" "offset" "value" 1793.It Fn bus_space_write_stream_2 "space" "handle" "offset" "value" 1794.It Fn bus_space_write_stream_4 "space" "handle" "offset" "value" 1795.It Fn bus_space_write_stream_8 "space" "handle" "offset" "value" 1796.It Fn bus_space_write_multi_stream_1 "space" "handle" "offset" "datap" "count" 1797.It Fn bus_space_write_multi_stream_2 "space" "handle" "offset" "datap" "count" 1798.It Fn bus_space_write_multi_stream_4 "space" "handle" "offset" "datap" "count" 1799.It Fn bus_space_write_multi_stream_8 "space" "handle" "offset" "datap" "count" 1800.It Fn bus_space_write_region_stream_1 "space" "handle" "offset" "datap" "count" 1801.It Fn bus_space_write_region_stream_2 "space" "handle" "offset" "datap" "count" 1802.It Fn bus_space_write_region_stream_4 "space" "handle" "offset" "datap" "count" 1803.It Fn bus_space_write_region_stream_8 "space" "handle" "offset" "datap" "count" 1804.El 1805.Pp 1806These functions are defined just as their non-stream counterparts, 1807except that they provide no byte-order translation. 1808.Sh IMPLEMENTING BUS SPACES IN MACHINE-INDEPENDENT CODE 1809.Bl -ohang -compact 1810.It Fn bus_space_tag_create "obst" "present" "extpresent" "ov" "ctx" "bstp" 1811Create a copy of the tag 1812.Fa obst 1813at 1814.Fa *bstp . 1815Except for the behavior 1816overridden by 1817.Fa ov , 1818.Fa *bstp 1819inherits the behavior of 1820.Fa obst 1821under 1822.Nm 1823calls. 1824.Pp 1825.Fa ov 1826contains function pointers corresponding to 1827.Nm 1828routines. 1829Each function pointer has a corresponding bit in 1830.Fa present 1831or 1832.Fa extpresent , 1833and if that bit is 1, the function pointer overrides the corresponding 1834.Nm 1835call for the new tag. 1836Any combination of these bits may be set in 1837.Fa present : 1838.Pp 1839.Bl -tag -width BUS_SPACE_OVERRIDE_RESERVE_SUBREGION -compact 1840.It Dv BUS_SPACE_OVERRIDE_MAP 1841.It Dv BUS_SPACE_OVERRIDE_UNMAP 1842.It Dv BUS_SPACE_OVERRIDE_ALLOC 1843.It Dv BUS_SPACE_OVERRIDE_FREE 1844.It Dv BUS_SPACE_OVERRIDE_RESERVE 1845.It Dv BUS_SPACE_OVERRIDE_RELEASE 1846.It Dv BUS_SPACE_OVERRIDE_RESERVATION_MAP 1847.It Dv BUS_SPACE_OVERRIDE_RESERVATION_UNMAP 1848.It Dv BUS_SPACE_OVERRIDE_RESERVE_SUBREGION 1849.El 1850.Pp 1851.Fn bus_space_tag_create 1852does not copy 1853.Fa ov . 1854After a new tag is created by 1855.Fn bus_space_tag_create , 1856.Fa ov 1857must not be destroyed until after the 1858tag is destroyed by 1859.Fn bus_space_tag_destroy . 1860.Pp 1861The first argument of every override-function is a 1862.Vt "void *" , 1863and 1864.Fa ctx 1865is passed in that argument. 1866.Pp 1867Return 0 if the call succeeds. 1868Return 1869.Er EOPNOTSUPP 1870if the architecture does not support overrides. 1871Return 1872.Er EINVAL 1873if 1874.Fa present 1875is 0, if 1876.Fa ov 1877is 1878.Dv NULL , 1879or if 1880.Fa present 1881indicates that an override is present, but the corresponding override 1882in 1883.Fa ov 1884is 1885.Dv NULL . 1886.Pp 1887If the call does not succeed, 1888.Fa *bstp 1889is undefined. 1890.It Fn bus_space_tag_destroy "bst" 1891Destroy a tag, 1892.Fa bst , 1893created by a prior call to 1894.Fn bus_space_tag_create . 1895If 1896.Fa bst 1897was not created by 1898.Fn bus_space_tag_create , 1899results are undefined. 1900If 1901.Fa bst 1902was already destroyed, results are undefined. 1903.El 1904.Sh EXPECTED CHANGES TO THE BUS_SPACE FUNCTIONS 1905The definition of the 1906.Nm 1907functions should not yet be considered finalized. 1908There are several changes and improvements which should be explored, 1909including: 1910.Bl -bullet 1911.It 1912Exporting the 1913.Nm 1914functions to userland so that applications 1915(such as X servers) have easier, more portable access to device space. 1916.It 1917Redefining bus space tags and handles so that machine-independent bus 1918interface drivers (for example PCI to VME bridges) could define and 1919implement bus spaces without requiring machine-dependent code. 1920If this is done, it should be done in such a way that machine-dependent 1921optimizations should remain possible. 1922.It 1923Converting bus spaces (such as PCI configuration space) which currently 1924use space-specific access methods to use the 1925.Nm 1926functions where that is appropriate. 1927.It 1928Redefining the way bus space is mapped and allocated, so that mapping 1929and allocation are done with bus specific functions which return bus 1930space tags. 1931This would allow further optimization than is currently possible, and 1932would also ease translation of the 1933.Nm 1934functions into user space (since mapping in user space would look like 1935it just used a different bus-specific mapping function). 1936.El 1937.Sh COMPATIBILITY 1938The current version of the 1939.Nm 1940interface specification differs slightly from the original 1941specification that came into wide use. 1942A few of the function names and arguments have changed 1943for consistency and increased functionality. 1944Drivers that were written to the 1945old, deprecated specification can be compiled by defining the 1946.Dv __BUS_SPACE_COMPAT_OLDDEFS 1947preprocessor symbol before including 1948.In sys/bus.h . 1949.Sh SEE ALSO 1950.Xr membar_ops 3 , 1951.Xr bus_dma 9 1952.Sh HISTORY 1953The 1954.Nm 1955functions were introduced in a different form (memory and I/O spaces 1956were accessed via different sets of functions) in 1957.Nx 1.2 . 1958The functions were merged to work on generic 1959.Dq spaces 1960early in the 1961.Nx 1.3 1962development cycle, and many drivers were converted to use them. 1963This document was written later during the 1964.Nx 1.3 1965development cycle and the specification was updated to fix some 1966consistency problems and to add some missing functionality. 1967.Sh AUTHORS 1968.An -nosplit 1969The 1970.Nm 1971interfaces were designed and implemented by the 1972.Nx 1973developer 1974community. 1975Primary contributors and implementors were 1976.An Chris Demetriou , 1977.An Jason Thorpe , 1978and 1979.An Charles Hannum , 1980but the rest of the 1981.Nx 1982developers and the user community played a significant role in development. 1983.Pp 1984.An Chris Demetriou 1985wrote this manual page. 1986