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