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