1.\" $NetBSD: bus_space.9,v 1.37 2009/03/10 10:30:28 joerg 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 March 1, 2008 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_map , 42.Nm bus_space_peek_1 , 43.Nm bus_space_peek_2 , 44.Nm bus_space_peek_4 , 45.Nm bus_space_peek_8 , 46.Nm bus_space_poke_1 , 47.Nm bus_space_poke_2 , 48.Nm bus_space_poke_4 , 49.Nm bus_space_poke_8 , 50.Nm bus_space_read_1 , 51.Nm bus_space_read_2 , 52.Nm bus_space_read_4 , 53.Nm bus_space_read_8 , 54.Nm bus_space_read_multi_1 , 55.Nm bus_space_read_multi_2 , 56.Nm bus_space_read_multi_4 , 57.Nm bus_space_read_multi_8 , 58.Nm bus_space_read_multi_stream_1 , 59.Nm bus_space_read_multi_stream_2 , 60.Nm bus_space_read_multi_stream_4 , 61.Nm bus_space_read_multi_stream_8 , 62.Nm bus_space_read_region_1 , 63.Nm bus_space_read_region_2 , 64.Nm bus_space_read_region_4 , 65.Nm bus_space_read_region_8 , 66.Nm bus_space_read_region_stream_1 , 67.Nm bus_space_read_region_stream_2 , 68.Nm bus_space_read_region_stream_4 , 69.Nm bus_space_read_region_stream_8 , 70.Nm bus_space_read_stream_1 , 71.Nm bus_space_read_stream_2 , 72.Nm bus_space_read_stream_4 , 73.Nm bus_space_read_stream_8 , 74.Nm bus_space_set_region_1 , 75.Nm bus_space_set_region_2 , 76.Nm bus_space_set_region_4 , 77.Nm bus_space_set_region_8 , 78.Nm bus_space_subregion , 79.Nm bus_space_unmap , 80.Nm bus_space_vaddr , 81.Nm bus_space_mmap , 82.Nm bus_space_write_1 , 83.Nm bus_space_write_2 , 84.Nm bus_space_write_4 , 85.Nm bus_space_write_8 , 86.Nm bus_space_write_multi_1 , 87.Nm bus_space_write_multi_2 , 88.Nm bus_space_write_multi_4 , 89.Nm bus_space_write_multi_8 , 90.Nm bus_space_write_multi_stream_1 , 91.Nm bus_space_write_multi_stream_2 , 92.Nm bus_space_write_multi_stream_4 , 93.Nm bus_space_write_multi_stream_8 , 94.Nm bus_space_write_region_1 , 95.Nm bus_space_write_region_2 , 96.Nm bus_space_write_region_4 , 97.Nm bus_space_write_region_8 , 98.Nm bus_space_write_region_stream_1 , 99.Nm bus_space_write_region_stream_2 , 100.Nm bus_space_write_region_stream_4 , 101.Nm bus_space_write_region_stream_8 , 102.Nm bus_space_write_stream_1 , 103.Nm bus_space_write_stream_2 , 104.Nm bus_space_write_stream_4 , 105.Nm bus_space_write_stream_8 106.Nd bus space manipulation functions 107.Sh SYNOPSIS 108.In machine/bus.h 109.Ft int 110.Fn bus_space_map "bus_space_tag_t space" "bus_addr_t address" \ 111"bus_size_t size" "int flags" "bus_space_handle_t *handlep" 112.Ft void 113.Fn bus_space_unmap "bus_space_tag_t space" "bus_space_handle_t handle" \ 114"bus_size_t size" 115.Ft int 116.Fn bus_space_subregion "bus_space_tag_t space" "bus_space_handle_t handle" \ 117"bus_size_t offset" "bus_size_t size" "bus_space_handle_t *nhandlep" 118.Ft int 119.Fo bus_space_alloc 120.Fa "bus_space_tag_t space" "bus_addr_t reg_start" "bus_addr_t reg_end" 121.Fa "bus_size_t size" "bus_size_t alignment" "bus_size_t boundary" 122.Fa "int flags" "bus_addr_t *addrp" "bus_space_handle_t *handlep" 123.Fc 124.Ft void 125.Fn bus_space_free "bus_space_tag_t space" "bus_space_handle_t handle" \ 126"bus_size_t size" 127.Ft void * 128.Fn bus_space_vaddr "bus_space_tag_t space" "bus_space_handle_t handle" 129.Ft paddr_t 130.Fn bus_space_mmap "bus_space_tag_t space" "bus_addr_t addr" "off_t off" \ 131"int prot" "int flags" 132.Ft int 133.Fn bus_space_peek_1 "bus_space_tag_t space" "bus_space_handle_t handle" \ 134"bus_size_t offset" "uint8_t *datap" 135.Ft int 136.Fn bus_space_peek_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ 137"bus_size_t offset" "uint16_t *datap" 138.Ft int 139.Fn bus_space_peek_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ 140"bus_size_t offset" "uint32_t *datap" 141.Ft int 142.Fn bus_space_peek_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ 143"bus_size_t offset" "uint64_t *datap" 144.Ft int 145.Fn bus_space_poke_1 "bus_space_tag_t space" "bus_space_handle_t handle" \ 146"bus_size_t offset" "uint8_t data" 147.Ft int 148.Fn bus_space_poke_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ 149"bus_size_t offset" "uint16_t data" 150.Ft int 151.Fn bus_space_poke_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ 152"bus_size_t offset" "uint32_t data" 153.Ft int 154.Fn bus_space_poke_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ 155"bus_size_t offset" "uint64_t data" 156.Ft uint8_t 157.Fn bus_space_read_1 "bus_space_tag_t space" "bus_space_handle_t handle" \ 158"bus_size_t offset" 159.Ft uint16_t 160.Fn bus_space_read_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ 161"bus_size_t offset" 162.Ft uint32_t 163.Fn bus_space_read_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ 164"bus_size_t offset" 165.Ft uint64_t 166.Fn bus_space_read_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ 167"bus_size_t offset" 168.Ft void 169.Fn bus_space_write_1 "bus_space_tag_t space" "bus_space_handle_t handle" \ 170"bus_size_t offset" "uint8_t value" 171.Ft void 172.Fn bus_space_write_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ 173"bus_size_t offset" "uint16_t value" 174.Ft void 175.Fn bus_space_write_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ 176"bus_size_t offset" "uint32_t value" 177.Ft void 178.Fn bus_space_write_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ 179"bus_size_t offset" "uint64_t value" 180.Ft void 181.Fn bus_space_barrier "bus_space_tag_t space" "bus_space_handle_t handle" \ 182"bus_size_t offset" "bus_size_t length" "int flags" 183.Ft void 184.Fn bus_space_read_region_1 "bus_space_tag_t space" \ 185"bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" \ 186"bus_size_t count" 187.Ft void 188.Fn bus_space_read_region_2 "bus_space_tag_t space" \ 189"bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" \ 190"bus_size_t count" 191.Ft void 192.Fn bus_space_read_region_4 "bus_space_tag_t space" \ 193"bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" \ 194"bus_size_t count" 195.Ft void 196.Fn bus_space_read_region_8 "bus_space_tag_t space" \ 197"bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" \ 198"bus_size_t count" 199.Ft void 200.Fn bus_space_read_region_stream_1 "bus_space_tag_t space" \ 201"bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" \ 202"bus_size_t count" 203.Ft void 204.Fn bus_space_read_region_stream_2 "bus_space_tag_t space" \ 205"bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" \ 206"bus_size_t count" 207.Ft void 208.Fn bus_space_read_region_stream_4 "bus_space_tag_t space" \ 209"bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" \ 210"bus_size_t count" 211.Ft void 212.Fn bus_space_read_region_stream_8 "bus_space_tag_t space" \ 213"bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" \ 214"bus_size_t count" 215.Ft void 216.Fn bus_space_write_region_1 "bus_space_tag_t space" \ 217"bus_space_handle_t handle" "bus_size_t offset" "const uint8_t *datap" \ 218"bus_size_t count" 219.Ft void 220.Fn bus_space_write_region_2 "bus_space_tag_t space" \ 221"bus_space_handle_t handle" "bus_size_t offset" "const uint16_t *datap" \ 222"bus_size_t count" 223.Ft void 224.Fn bus_space_write_region_4 "bus_space_tag_t space" \ 225"bus_space_handle_t handle" "bus_size_t offset" "const uint32_t *datap" \ 226"bus_size_t count" 227.Ft void 228.Fn bus_space_write_region_8 "bus_space_tag_t space" \ 229"bus_space_handle_t handle" "bus_size_t offset" "const uint64_t *datap" \ 230"bus_size_t count" 231.Ft void 232.Fn bus_space_write_region_stream_1 "bus_space_tag_t space" \ 233"bus_space_handle_t handle" "bus_size_t offset" "const uint8_t *datap" \ 234"bus_size_t count" 235.Ft void 236.Fn bus_space_write_region_stream_2 "bus_space_tag_t space" \ 237"bus_space_handle_t handle" "bus_size_t offset" "const uint16_t *datap" \ 238"bus_size_t count" 239.Ft void 240.Fn bus_space_write_region_stream_4 "bus_space_tag_t space" \ 241"bus_space_handle_t handle" "bus_size_t offset" "const uint32_t *datap" \ 242"bus_size_t count" 243.Ft void 244.Fn bus_space_write_region_stream_8 "bus_space_tag_t space" \ 245"bus_space_handle_t handle" "bus_size_t offset" "const uint64_t *datap" \ 246"bus_size_t count" 247.Ft void 248.Fn bus_space_copy_region_1 "bus_space_tag_t space" \ 249"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ 250"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" 251.Ft void 252.Fn bus_space_copy_region_2 "bus_space_tag_t space" \ 253"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ 254"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" 255.Ft void 256.Fn bus_space_copy_region_4 "bus_space_tag_t space" \ 257"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ 258"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" 259.Ft void 260.Fn bus_space_copy_region_8 "bus_space_tag_t space" \ 261"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ 262"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" 263.Ft void 264.Fn bus_space_set_region_1 "bus_space_tag_t space" \ 265"bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" \ 266"bus_size_t count" 267.Ft void 268.Fn bus_space_set_region_2 "bus_space_tag_t space" \ 269"bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" \ 270"bus_size_t count" 271.Ft void 272.Fn bus_space_set_region_4 "bus_space_tag_t space" \ 273"bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" \ 274"bus_size_t count" 275.Ft void 276.Fn bus_space_set_region_8 "bus_space_tag_t space" \ 277"bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" \ 278"bus_size_t count" 279.Ft void 280.Fn bus_space_read_multi_1 "bus_space_tag_t space" \ 281"bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" \ 282"bus_size_t count" 283.Ft void 284.Fn bus_space_read_multi_2 "bus_space_tag_t space" \ 285"bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" \ 286"bus_size_t count" 287.Ft void 288.Fn bus_space_read_multi_4 "bus_space_tag_t space" \ 289"bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" \ 290"bus_size_t count" 291.Ft void 292.Fn bus_space_read_multi_8 "bus_space_tag_t space" \ 293"bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" \ 294"bus_size_t count" 295.Ft void 296.Fn bus_space_read_multi_stream_1 "bus_space_tag_t space" \ 297"bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" \ 298"bus_size_t count" 299.Ft void 300.Fn bus_space_read_multi_stream_2 "bus_space_tag_t space" \ 301"bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" \ 302"bus_size_t count" 303.Ft void 304.Fn bus_space_read_multi_stream_4 "bus_space_tag_t space" \ 305"bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" \ 306"bus_size_t count" 307.Ft void 308.Fn bus_space_read_multi_stream_8 "bus_space_tag_t space" \ 309"bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" \ 310"bus_size_t count" 311.Ft void 312.Fn bus_space_write_multi_1 "bus_space_tag_t space" \ 313"bus_space_handle_t handle" "bus_size_t offset" "const uint8_t *datap" \ 314"bus_size_t count" 315.Ft void 316.Fn bus_space_write_multi_2 "bus_space_tag_t space" \ 317"bus_space_handle_t handle" "bus_size_t offset" "const uint16_t *datap" \ 318"bus_size_t count" 319.Ft void 320.Fn bus_space_write_multi_4 "bus_space_tag_t space" \ 321"bus_space_handle_t handle" "bus_size_t offset" "const uint32_t *datap" \ 322"bus_size_t count" 323.Ft void 324.Fn bus_space_write_multi_8 "bus_space_tag_t space" \ 325"bus_space_handle_t handle" "bus_size_t offset" "const uint64_t *datap" \ 326"bus_size_t count" 327.Ft void 328.Fn bus_space_write_multi_stream_1 "bus_space_tag_t space" \ 329"bus_space_handle_t handle" "bus_size_t offset" "const uint8_t *datap" \ 330"bus_size_t count" 331.Ft void 332.Fn bus_space_write_multi_stream_2 "bus_space_tag_t space" \ 333"bus_space_handle_t handle" "bus_size_t offset" "const uint16_t *datap" \ 334"bus_size_t count" 335.Ft void 336.Fn bus_space_write_multi_stream_4 "bus_space_tag_t space" \ 337"bus_space_handle_t handle" "bus_size_t offset" "const uint32_t *datap" \ 338"bus_size_t count" 339.Ft void 340.Fn bus_space_write_multi_stream_8 "bus_space_tag_t space" \ 341"bus_space_handle_t handle" "bus_size_t offset" "const uint64_t *datap" \ 342"bus_size_t count" 343.Sh DESCRIPTION 344The 345.Nm 346functions exist to allow device drivers 347machine-independent access to bus memory and register areas. 348All of the functions and types described in this document can be used 349by including the 350.Aq Pa machine/bus.h 351header file. 352.Pp 353Many common devices are used on multiple architectures, but are accessed 354differently on each because of architectural constraints. 355For instance, a device which is mapped in one system's I/O space may be 356mapped in memory space on a second system. 357On a third system, architectural limitations might change the way 358registers need to be accessed (e.g., creating a non-linear register space). 359In some cases, a single 360driver may need to access the same type of device in multiple ways in a 361single system or architecture. 362The goal of the 363.Nm 364functions is to allow a single driver source file to manipulate a set 365of devices on different system architectures, and to allow a single driver 366object file to manipulate a set of devices on multiple bus types on a 367single architecture. 368.Pp 369Not all busses have to implement all functions described in this 370document, though that is encouraged if the operations are logically 371supported by the bus. 372Unimplemented functions should cause compile-time errors if possible. 373.Pp 374All of the interface definitions described in this document are shown as 375function prototypes and discussed as if they were required to be 376functions. 377Implementations are encouraged to implement prototyped (type-checked) 378versions of these interfaces, but may implement them as macros if appropriate. 379Machine-dependent types, variables, and functions should be marked clearly in 380.Aq Pa machine/bus.h 381to avoid confusion with the 382machine-independent types and functions, and, if possible, should be 383given names which make the machine-dependence clear. 384.Sh CONCEPTS AND GUIDELINES 385Bus spaces are described by bus space tags, which can be created only by 386machine-dependent code. 387A given machine may have several different types of bus space 388(e.g., memory space and I/O space), and thus may provide multiple different 389bus space tags. 390Individual busses or devices on a machine may use more than one bus space 391tag. 392For instance, ISA devices are given an ISA memory space tag and an 393ISA I/O space tag. 394Architectures may have several different tags which represent the same 395type of space, for instance because of multiple different host bus 396interface chipsets. 397.Pp 398A range in bus space is described by a bus address and a bus size. 399The bus address describes the start of the range in bus space. 400The bus size describes the size of the range in bytes. 401Busses which are not byte addressable may require use of bus space ranges 402with appropriately aligned addresses and properly rounded sizes. 403.Pp 404Access to regions of bus space is facilitated by use of bus space handles, 405which are usually created by mapping a specific range of a bus space. 406Handles may also be created by allocating 407and mapping a range of bus space, the actual location of which is picked 408by the implementation within bounds specified by the caller of the 409allocation function. 410.Pp 411All of the bus space access functions require one bus space tag 412argument, at least one handle argument, and at least one offset argument 413(a bus size). 414The bus space tag specifies the space, each handle specifies a region in 415the space, and each offset specifies the offset into the region of the 416actual location(s) to be accessed. 417Offsets are given in bytes, though busses may impose alignment constraints. 418The offset used to access data relative to a given handle must be such 419that all of the data being accessed is in the mapped region that the 420handle describes. 421Trying to access data outside that region is an error. 422.Pp 423Because some architectures' memory systems use buffering to improve 424memory and device access performance, there is a mechanism which can be 425used to create 426.Dq barriers 427in the bus space read and write stream. 428.Pp 429There are two types of barriers: ordering barriers and completion 430barriers. 431.Pp 432Ordering barriers prevent some operations from bypassing other 433operations. 434They are relatively light weight and described in terms of the 435operations they are intended to order. 436The important thing to note is that they create specific ordering 437constraint surrounding bus accesses but do not necessarily force any 438synchronization themselves. 439So, if there is enough distance between the memory operations being 440ordered, the preceding ones could complete by themselves resulting 441in no performance penalty. 442.Pp 443For instance, a write before read barrier will force any writes 444issued before the barrier instruction to complete before any reads 445after the barrier are issued. 446This forces processors with write buffers to read data from memory rather 447than from the pending write in the write buffer. 448.Pp 449Ordering barriers are usually sufficient for most circumstances, 450and can be combined together. 451For instance a read before write barrier can be combined with a write 452before write barrier to force all memory operations to complete before 453the next write is started. 454.Pp 455Completion barriers force all memory operations and any pending 456exceptions to be completed before any instructions after the 457barrier may be issued. 458Completion barriers are extremely expensive and almost never required 459in device driver code. 460A single completion barrier can force the processor to stall on memory 461for hundreds of cycles on some machines. 462.Pp 463Correctly-written drivers will include all appropriate barriers, 464and assume only the read/write ordering imposed by the barrier 465operations. 466.Pp 467People trying to write portable drivers with the 468.Nm 469functions should 470try to make minimal assumptions about what the system allows. 471In particular, they should expect that the system requires bus space 472addresses being accessed to be naturally aligned (i.e., base address of 473handle added to offset is a multiple of the access size), and that the 474system does alignment checking on pointers (i.e., pointer to objects being 475read and written must point to properly-aligned data). 476.Pp 477The descriptions of the 478.Nm 479functions given below all assume that 480they are called with proper arguments. 481If called with invalid arguments or arguments that are out of range 482(e.g., trying to access data outside of the region mapped when a given 483handle was created), undefined behaviour results. 484In that case, they may cause the system to halt, either intentionally 485(via panic) or unintentionally (by causing a fatal trap or by some other 486means) or may cause improper operation which is not immediately fatal. 487Functions which return void or which return data read from bus space 488(i.e., functions which don't obviously return an error code) do not fail. 489They could only fail if given invalid arguments, and in that case their 490behaviour is undefined. 491Functions which take a count of bytes have undefined results if the specified 492.Fa count 493is zero. 494.Sh TYPES 495Several types are defined in 496.Aq Pa machine/bus.h 497to facilitate use of the 498.Nm 499functions by drivers. 500.Pp 501.Bl -ohang -compact 502.It Fa bus_addr_t 503.Pp 504The 505.Fa bus_addr_t 506type is used to describe bus addresses. 507It must be an unsigned integral type capable of holding the largest bus 508address usable by the architecture. 509This type is primarily used when mapping and unmapping bus space. 510.Pp 511.It Fa bus_size_t 512.Pp 513The 514.Fa bus_size_t 515type is used to describe sizes of ranges in bus space. 516It must be an unsigned integral type capable of holding the size of the 517largest bus address range usable on the architecture. 518This type is used by virtually all of the 519.Nm 520functions, describing sizes when mapping regions and 521offsets into regions when performing space access operations. 522.Pp 523.It Fa bus_space_tag_t 524.Pp 525The 526.Fa bus_space_tag_t 527type is used to describe a particular bus space on a machine. 528Its contents are machine-dependent and should be considered opaque by 529machine-independent code. 530This type is used by all 531.Nm 532functions to name the space on which they're operating. 533.Pp 534.It Fa bus_space_handle_t 535.Pp 536The 537.Fa bus_space_handle_t 538type is used to describe a mapping of a range of bus space. 539Its contents are machine-dependent and should be considered opaque by 540machine-independent code. 541This type is used when performing bus space access operations. 542.El 543.Sh MAPPING AND UNMAPPING BUS SPACE 544Bus space must be mapped before it can be used, and should be 545unmapped when it is no longer needed. 546The 547.Fn bus_space_map 548and 549.Fn bus_space_unmap 550functions provide these capabilities. 551.Pp 552Some drivers need to be able to pass a subregion of already-mapped bus 553space to another driver or module within a driver. 554The 555.Fn bus_space_subregion 556function allows such subregions to be created. 557.Pp 558.Bl -ohang -compact 559.It Fn bus_space_map "space" "address" "size" "flags" "handlep" 560.Pp 561The 562.Fn bus_space_map 563function maps the region of bus space named by the 564.Fa space , 565.Fa address , 566and 567.Fa size 568arguments. 569If successful, it returns zero and fills in the bus space handle pointed 570to by 571.Fa handlep 572with the handle 573that can be used to access the mapped region. 574If unsuccessful, it will return non-zero and leave the bus space handle 575pointed to by 576.Fa handlep 577in an undefined state. 578.Pp 579The 580.Fa flags 581argument controls how the space is to be mapped. 582Supported flags include: 583.Bl -tag -width BUS_SPACE_MAP_CACHEABLE -offset indent 584.It Dv BUS_SPACE_MAP_CACHEABLE 585Try to map the space so that accesses can be cached 586by the system cache. 587If this flag is not specified, the implementation should map the space so 588that it will not be cached. 589This mapping method will only be useful in very rare occasions. 590.Pp 591This flag must have a value of 1 on all implementations for backward 592compatibility. 593.It Dv BUS_SPACE_MAP_PREFETCHABLE 594Try to map the space so that accesses can be prefetched by the system, 595and writes can be buffered. 596This means, accesses should be side effect free (idempotent). 597The 598.Fn bus_space_barrier 599methods will flush the write buffer or force actual read accesses. 600If this flag is not specified, the 601implementation should map the space so that it will not be prefetched 602or delayed. 603.It Dv BUS_SPACE_MAP_LINEAR 604Try to map the space so that its contents can be accessed linearly via 605normal memory access methods (e.g., pointer dereferencing and structure 606accesses). 607The 608.Fn bus_space_vaddr 609method can be used to obtain the kernel virtual address of the mapped range. 610This is useful when software wants to do direct access to a memory 611device, e.g., a frame buffer. 612If this flag is specified and linear mapping is not possible, the 613.Fn bus_space_map 614call should fail. 615If this flag is not specified, the system may map the space in whatever 616way is most convenient. 617Use of this mapping method is not encouraged for normal device access; 618where linear access is not essential, use of the 619.Fn bus_space_read/write 620methods is strongly recommended. 621.El 622.Pp 623Not all combinations of flags make sense or are supported with all 624spaces. 625For instance, 626.Dv BUS_SPACE_MAP_CACHEABLE 627may be meaningless when 628used on many systems' I/O port spaces, and on some systems 629.Dv BUS_SPACE_MAP_LINEAR 630without 631.Dv BUS_SPACE_MAP_PREFETCHABLE 632may never work. 633When the system hardware or firmware provides hints as to how spaces should be 634mapped (e.g., the PCI memory mapping registers' "prefetchable" bit), those 635hints should be followed for maximum compatibility. 636On some systems, requesting a mapping that cannot be satisfied (e.g., 637requesting a non-prefetchable mapping when the system can only provide 638a prefetchable one) will cause the request to fail. 639.Pp 640Some implementations may keep track of use of bus space for some or all 641bus spaces and refuse to allow duplicate allocations. 642This is encouraged for bus spaces which have no notion of slot-specific 643space addressing, such as ISA and VME, and for spaces which coexist with 644those spaces (e.g., EISA and PCI memory and I/O spaces co-existing with 645ISA memory and I/O spaces). 646.Pp 647Mapped regions may contain areas for which there is no device on the bus. 648If space in those areas is accessed, the results are bus-dependent. 649.Pp 650.It Fn bus_space_unmap "space" "handle" "size" 651.Pp 652The 653.Fn bus_space_unmap 654function unmaps a region of bus space mapped with 655.Fn bus_space_map . 656When unmapping a region, the 657.Fa size 658specified should be 659the same as the size given to 660.Fn bus_space_map 661when mapping that region. 662.Pp 663After 664.Fn bus_space_unmap 665is called on a handle, that handle is no longer valid. 666(If copies were made of the handle they are no longer valid, either.) 667.Pp 668This function will never fail. 669If it would fail (e.g., because of an argument error), that indicates 670a software bug which should cause a panic. 671In that case, 672.Fn bus_space_unmap 673will never return. 674.Pp 675.It Fn bus_space_subregion "space" "handle" "offset" "size" "nhandlep" 676.Pp 677The 678.Fn bus_space_subregion 679function is a convenience function which makes a 680new handle to some subregion of an already-mapped region of bus space. 681The subregion described by the new handle starts at byte offset 682.Fa offset 683into the region described by 684.Fa handle , 685with the size given by 686.Fa size , 687and must be wholly contained within the original region. 688.Pp 689If successful, 690.Fn bus_space_subregion 691returns zero and fills in the bus 692space handle pointed to by 693.Fa nhandlep . 694If unsuccessful, it returns non-zero and leaves the bus space handle 695pointed to by 696.Fa nhandlep 697in an 698undefined state. 699In either case, the handle described by 700.Fa handle 701remains valid and is unmodified. 702.Pp 703When done with a handle created by 704.Fn bus_space_subregion , 705the handle should 706be thrown away. 707Under no circumstances should 708.Fn bus_space_unmap 709be used on the handle. 710Doing so may confuse any resource management being done on the space, 711and will result in undefined behaviour. 712When 713.Fn bus_space_unmap 714or 715.Fn bus_space_free 716is called on a handle, all subregions of that handle become invalid. 717.Pp 718.It Fn bus_space_vaddr "tag" "handle" 719.Pp 720This method returns the kernel virtual address of a mapped bus space if and 721only if it was mapped with the 722.Dv BUS_SPACE_MAP_LINEAR 723flag. 724The range can be accessed by normal (volatile) pointer dereferences. 725If mapped with the 726.Dv BUS_SPACE_MAP_PREFETCHABLE 727flag, the 728.Fn bus_space_barrier 729method must be used to force a particular access order. 730.Pp 731.It Fn bus_space_mmap "tag" "addr" "off" "prot" "flags" 732.Pp 733This method is used to provide support for memory mapping bus space 734into user applications. 735If an address space is addressable via volatile pointer dereferences, 736.Fn bus_space_mmap 737will return the physical address (possibly encoded as a machine-dependent 738cookie) of the bus space indicated by 739.Fa addr 740and 741.Fa off . 742.Fa addr 743is the base address of the device or device region, and 744.Fa off 745is the offset into that region that is being requested. 746If the request is made with 747.Dv BUS_SPACE_MAP_LINEAR 748as a flag, then a linear region must be returned to the caller. 749If the region cannot be mapped (either the address does not exist, 750or the constraints can not be met), 751.Fn bus_space_mmap 752returns 753.Dv -1 754to indicate failure. 755.Pp 756Note that it is not necessary that the region being requested by a 757.Fn bus_space_mmap 758call be mapped into a 759.Fa bus_space_handle_t . 760.Pp 761.Fn bus_space_mmap 762is called once per 763.Dv PAGE_SIZE 764page in the range. 765The 766.Fa prot 767argument indicates the memory protection requested by the user application 768for the range. 769.El 770.Sh ALLOCATING AND FREEING BUS SPACE 771Some devices require or allow bus space to be allocated by the operating 772system for device use. 773When the devices no longer need the space, the 774operating system should free it for use by other devices. 775The 776.Fn bus_space_alloc 777and 778.Fn bus_space_free 779functions provide these capabilities. 780.Pp 781.Bl -ohang -compact 782.It Fn bus_space_alloc "space" "reg_start" "reg_end" "size" "alignment" \ 783"boundary" "flags" "addrp" "handlep" 784.Pp 785The 786.Fn bus_space_alloc 787function allocates and maps a region of bus space with the size given by 788.Fa size , 789corresponding to the given constraints. 790If successful, it returns zero, fills in the bus address pointed to by 791.Fa addrp 792with the bus space address of the allocated region, and fills in 793the bus space handle pointed to by 794.Fa handlep 795with the handle that can be used to access that region. 796If unsuccessful, it returns non-zero and leaves the bus address pointed to by 797.Fa addrp 798and the bus space handle pointed to by 799.Fa handlep 800in an undefined state. 801.Pp 802Constraints on the allocation are given by the 803.Fa reg_start , 804.Fa reg_end , 805.Fa alignment , 806and 807.Fa boundary 808parameters. 809The allocated region will start at or after 810.Fa reg_start 811and end before or at 812.Fa reg_end . 813The 814.Fa alignment 815constraint must be a power of two, and the allocated region will start at 816an address that is an even multiple of that power of two. 817The 818.Fa boundary 819constraint, if non-zero, ensures that the region is allocated so that 820.Fa "first address in region" 821/ 822.Fa boundary 823has the same value as 824.Fa "last address in region" 825/ 826.Fa boundary . 827If the constraints cannot be met, 828.Fn bus_space_alloc 829will fail. 830It is an error to specify a set of constraints that can never be met 831.Po 832for example, 833.Fa size 834greater than 835.Fa boundary 836.Pc . 837.Pp 838The 839.Fa flags 840parameter is the same as the like-named parameter to 841.Fa bus_space_map , 842the same flag values should be used, and they have the 843same meanings. 844.Pp 845Handles created by 846.Fn bus_space_alloc 847should only be freed with 848.Fn bus_space_free . 849Trying to use 850.Fn bus_space_unmap 851on them causes undefined behaviour. 852The 853.Fn bus_space_subregion 854function can be used on handles created by 855.Fn bus_space_alloc . 856.Pp 857.It Fn bus_space_free "space" "handle" "size" 858.Pp 859The 860.Fn bus_space_free 861function unmaps and frees a region of bus space mapped 862and allocated with 863.Fn bus_space_alloc . 864When unmapping a region, the 865.Fa size 866specified should be the same as the size given to 867.Fn bus_space_alloc 868when allocating the region. 869.Pp 870After 871.Fn bus_space_free 872is called on a handle, that handle is no longer valid. 873(If copies were made of the handle, they are no longer valid, either.) 874.Pp 875This function will never fail. 876If it would fail (e.g., because of an argument error), that indicates 877a software bug which should cause a panic. 878In that case, 879.Fn bus_space_free 880will never return. 881.El 882.Sh READING AND WRITING SINGLE DATA ITEMS 883The simplest way to access bus space is to read or write a single data 884item. 885The 886.Fn bus_space_read_N 887and 888.Fn bus_space_write_N 889families of functions provide 890the ability to read and write 1, 2, 4, and 8 byte data items on busses 891which support those access sizes. 892.Pp 893.Bl -ohang -compact 894.It Fn bus_space_read_1 "space" "handle" "offset" 895.It Fn bus_space_read_2 "space" "handle" "offset" 896.It Fn bus_space_read_4 "space" "handle" "offset" 897.It Fn bus_space_read_8 "space" "handle" "offset" 898.Pp 899The 900.Fn bus_space_read_N 901family of functions reads a 1, 2, 4, or 8 byte data item from 902the offset specified by 903.Fa offset 904into the region specified by 905.Fa handle 906of the bus space specified by 907.Fa space . 908The location being read must lie within the bus space region specified by 909.Fa handle . 910.Pp 911For portability, the starting address of the region specified by 912.Fa handle 913plus the offset should be a multiple of the size of data item being read. 914On some systems, not obeying this requirement may cause incorrect data to 915be read, on others it may cause a system crash. 916.Pp 917Read operations done by the 918.Fn bus_space_read_N 919functions may be executed out 920of order with respect to other pending read and write operations unless 921order is enforced by use of the 922.Fn bus_space_barrier 923function. 924.Pp 925These functions will never fail. 926If they would fail (e.g., because of an argument error), that indicates 927a software bug which should cause a panic. 928In that case, they will never return. 929.Pp 930.It Fn bus_space_write_1 "space" "handle" "offset" "value" 931.It Fn bus_space_write_2 "space" "handle" "offset" "value" 932.It Fn bus_space_write_4 "space" "handle" "offset" "value" 933.It Fn bus_space_write_8 "space" "handle" "offset" "value" 934.Pp 935The 936.Fn bus_space_write_N 937family of functions writes a 1, 2, 4, or 8 byte data item to the offset 938specified by 939.Fa offset 940into the region specified by 941.Fa handle 942of the bus space specified by 943.Fa space . 944The location being written must lie within 945the bus space region specified by 946.Fa handle . 947.Pp 948For portability, the starting address of the region specified by 949.Fa handle 950plus the offset should be a multiple of the size of data item being 951written. 952On some systems, not obeying this requirement may cause incorrect data 953to be written, on others it may cause a system crash. 954.Pp 955Write operations done by the 956.Fn bus_space_write_N 957functions may be executed 958out of order with respect to other pending read and write operations 959unless order is enforced by use of the 960.Fn bus_space_barrier 961function. 962.Pp 963These functions will never fail. 964If they would fail (e.g., because of an argument error), that indicates 965a software bug which should cause a panic. 966In that case, they will never return. 967.El 968.Sh PROBING BUS SPACE FOR HARDWARE WHICH MAY NOT RESPOND 969One problem with the 970.Fn bus_space_read_N 971and 972.Fn bus_space_write_N 973family of functions is that they provide no protection against 974exceptions which can occur when no physical hardware or 975device responds to the read or write cycles. 976In such a situation, the system typically would panic due to a kernel-mode 977bus error. 978The 979.Fn bus_space_peek_N 980and 981.Fn bus_space_poke_N 982family of functions provide a mechanism to handle these exceptions 983gracefully without the risk of crashing the system. 984.Pp 985As with 986.Fn bus_space_read_N 987and 988.Fn bus_space_write_N , 989the peek and poke functions provide the ability to read and 990write 1, 2, 4, and 8 byte data items on busses which support those 991access sizes. 992All of the constraints specified in the descriptions of the 993.Fn bus_space_read_N 994and 995.Fn bus_space_write_N 996functions also apply to 997.Fn bus_space_peek_N 998and 999.Fn bus_space_poke_N . 1000.Pp 1001In addition, explicit calls to the 1002.Fn bus_space_barrier 1003function are not required as the implementation will ensure all 1004pending operations complete before the peek or poke operation starts. 1005The implementation will also ensure that the peek or poke operations 1006complete before returning. 1007.Pp 1008The return value indicates the outcome of the peek or poke operation. 1009A return value of zero implies that a hardware device is 1010responding to the operation at the specified offset in the bus space. 1011A non-zero return value indicates that the kernel intercepted a 1012hardware exception (e.g., bus error) when the peek or poke operation 1013was attempted. 1014Note that some busses are incapable of generating exceptions when 1015non-existent hardware is accessed. 1016In such cases, these functions will always return zero and the value of 1017the data read by 1018.Fn bus_space_peek_N 1019will be unspecified. 1020.Pp 1021Finally, it should be noted that at this time the 1022.Fn bus_space_peek_N 1023and 1024.Fn bus_space_poke_N 1025functions are not re-entrant and should not, therefore, be used 1026from within an interrupt service routine. 1027This constraint may be removed at some point in the future. 1028.Pp 1029.Bl -ohang -compact 1030.It Fn bus_space_peek_1 "space" "handle" "offset" "datap" 1031.It Fn bus_space_peek_2 "space" "handle" "offset" "datap" 1032.It Fn bus_space_peek_4 "space" "handle" "offset" "datap" 1033.It Fn bus_space_peek_8 "space" "handle" "offset" "datap" 1034.Pp 1035The 1036.Fn bus_space_peek_N 1037family of functions cautiously read a 1, 2, 4, or 8 byte data item from 1038the offset specified by 1039.Fa offset 1040in the region specified by 1041.Fa handle 1042of the bus space specified by 1043.Fa space . 1044The data item read is stored in the location pointed to by 1045.Fa datap . 1046It is permissible for 1047.Fa datap 1048to be NULL, in which case the data item will be discarded after being read. 1049.Pp 1050.It Fn bus_space_poke_1 "space" "handle" "offset" "value" 1051.It Fn bus_space_poke_2 "space" "handle" "offset" "value" 1052.It Fn bus_space_poke_4 "space" "handle" "offset" "value" 1053.It Fn bus_space_poke_8 "space" "handle" "offset" "value" 1054.Pp 1055The 1056.Fn bus_space_poke_N 1057family of functions cautiously write a 1, 2, 4, or 8 byte data item 1058specified by 1059.Fa value 1060to the offset specified by 1061.Fa offset 1062in the region specified by 1063.Fa handle 1064of the bus space specified by 1065.Fa space . 1066.El 1067.Sh BARRIERS 1068In order to allow high-performance buffering implementations to avoid bus 1069activity on every operation, read and write ordering should be specified 1070explicitly by drivers when necessary. 1071The 1072.Fn bus_space_barrier 1073function provides that ability. 1074.Pp 1075.Bl -ohang -compact 1076.It Fn bus_space_barrier "space" "handle" "offset" "length" "flags" 1077.Pp 1078The 1079.Fn bus_space_barrier 1080function enforces ordering of bus space read and write operations 1081for the specified subregion (described by the 1082.Fa offset 1083and 1084.Fa length 1085parameters) of the region named by 1086.Fa handle 1087in the space named by 1088.Fa space . 1089.Pp 1090The 1091.Fa flags 1092argument controls what types of operations are to be ordered. 1093Supported flags are: 1094.Bl -tag -width BUS_SPACE_BARRIER_WRITE_BEFORE_WRITE -offset indent 1095.It Dv BUS_SPACE_BARRIER_READ_BEFORE_READ 1096Force all reads before the barrier to complete before any reads 1097after the barrier may be issued. 1098.It Dv BUS_SPACE_BARRIER_READ_BEFORE_WRITE 1099Force all reads before the barrier to complete before any writes 1100after the barrier may be issued. 1101.It Dv BUS_SPACE_BARRIER_WRITE_BEFORE_READ 1102Force all writes before the barrier to complete before any reads 1103after the barrier may be issued. 1104.It Dv BUS_SPACE_BARRIER_WRITE_BEFORE_WRITE 1105Force all writes before the barrier to complete before any writes 1106after the barrier may be issued. 1107.It Dv BUS_SPACE_BARRIER_SYNC 1108Force all memory operations and any pending exceptions to be 1109completed before any instructions after the barrier may be issued. 1110.El 1111.Pp 1112Those flags can be combined (or-ed together) to enforce ordering on 1113different combinations of read and write operations. 1114.Pp 1115All of the specified type(s) of operation which are done to the region 1116before the barrier operation are guaranteed to complete before any of the 1117specified type(s) of operation done after the barrier. 1118.Pp 1119Example: Consider a hypothetical device with two single-byte ports, one 1120write-only input port (at offset 0) and a read-only output port (at 1121offset 1). 1122Operation of the device is as follows: data bytes are written to the 1123input port, and are placed by the device on a stack, the top of 1124which is read by reading from the output port. 1125The sequence to correctly write two data bytes to the device then read 1126those two data bytes back would be: 1127.Pp 1128.Bd -literal 1129/* 1130 * t and h are the tag and handle for the mapped device's 1131 * space. 1132 */ 1133bus_space_write_1(t, h, 0, data0); 1134bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE_BEFORE_WRITE); /* 1 */ 1135bus_space_write_1(t, h, 0, data1); 1136bus_space_barrier(t, h, 0, 2, BUS_SPACE_BARRIER_WRITE_BEFORE_READ); /* 2 */ 1137ndata1 = bus_space_read_1(t, h, 1); 1138bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ_BEFORE_READ); /* 3 */ 1139ndata0 = bus_space_read_1(t, h, 1); 1140/* data0 == ndata0, data1 == ndata1 */ 1141.Ed 1142.Pp 1143The first barrier makes sure that the first write finishes before the 1144second write is issued, so that two writes to the input port are done 1145in order and are not collapsed into a single write. 1146This ensures that the data bytes are written to the device correctly and 1147in order. 1148.Pp 1149The second barrier forces the writes to the output port finish before 1150any of the reads to the input port are issued, thereby making sure 1151that all of the writes are finished before data is read. 1152This ensures that the first byte read from the device really is the last 1153one that was written. 1154.Pp 1155The third barrier makes sure that the first read finishes before the 1156second read is issued, ensuring that data is read correctly and in order. 1157.Pp 1158The barriers in the example above are specified to cover the absolute 1159minimum number of bus space locations. 1160It is correct (and often easier) to make barrier operations cover the 1161device's whole range of bus space, that is, to specify an offset of zero 1162and the size of the whole region. 1163.Pp 1164The following barrier operations are obsolete and should be removed 1165from existing code: 1166.Bl -tag -width BUS_SPACE_BARRIER_WRITE -offset indent 1167.It Dv BUS_SPACE_BARRIER_READ 1168Synchronize read operations. 1169.It Dv BUS_SPACE_BARRIER_WRITE 1170Synchronize write operations. 1171.El 1172.El 1173.Sh REGION OPERATIONS 1174Some devices use buffers which are mapped as regions in bus space. 1175Often, drivers want to copy the contents of those buffers to or from 1176memory, e.g., into mbufs which can be passed to higher levels of the 1177system or from mbufs to be output to a network. 1178In order to allow drivers to do this as efficiently as possible, the 1179.Fn bus_space_read_region_N 1180and 1181.Fn bus_space_write_region_N 1182families of functions are provided. 1183.Pp 1184Drivers occasionally need to copy one region of a bus space to another, 1185or to set all locations in a region of bus space to contain a single 1186value. 1187The 1188.Fn bus_space_copy_region_N 1189family of functions and the 1190.Fn bus_space_set_region_N 1191family of functions allow drivers to perform these operations. 1192.Pp 1193.Bl -ohang -compact 1194.It Fn bus_space_read_region_1 "space" "handle" "offset" "datap" "count" 1195.It Fn bus_space_read_region_2 "space" "handle" "offset" "datap" "count" 1196.It Fn bus_space_read_region_4 "space" "handle" "offset" "datap" "count" 1197.It Fn bus_space_read_region_8 "space" "handle" "offset" "datap" "count" 1198.Pp 1199The 1200.Fn bus_space_read_region_N 1201family of functions reads 1202.Fa count 12031, 2, 4, or 8 byte data items from bus space 1204starting at byte offset 1205.Fa offset 1206in the region specified by 1207.Fa handle 1208of the bus space specified by 1209.Fa space 1210and writes them into the array specified by 1211.Fa datap . 1212Each successive data item is read from an offset 12131, 2, 4, or 8 bytes after the previous data item (depending on which 1214function is used). 1215All locations being read must lie within the bus space region specified by 1216.Fa handle . 1217.Pp 1218For portability, the starting address of the region specified by 1219.Fa handle 1220plus the offset should be a multiple of the size of data items being 1221read and the data array pointer should be properly aligned. 1222On some systems, not obeying these requirements may cause incorrect data 1223to be read, on others it may cause a system crash. 1224.Pp 1225Read operations done by the 1226.Fn bus_space_read_region_N 1227functions may be executed in any order. 1228They may also be executed out of order with respect to other pending 1229read and write operations unless order is enforced by use of the 1230.Fn bus_space_barrier 1231function. 1232There is no way to insert barriers between reads of individual bus 1233space locations executed by the 1234.Fn bus_space_read_region_N 1235functions. 1236.Pp 1237These functions will never fail. 1238If they would fail (e.g., because of an argument error), that indicates a 1239software bug which should cause a panic. 1240In that case, they will never return. 1241.Pp 1242.It Fn bus_space_write_region_1 "space" "handle" "offset" "datap" "count" 1243.It Fn bus_space_write_region_2 "space" "handle" "offset" "datap" "count" 1244.It Fn bus_space_write_region_4 "space" "handle" "offset" "datap" "count" 1245.It Fn bus_space_write_region_8 "space" "handle" "offset" "datap" "count" 1246.Pp 1247The 1248.Fn bus_space_write_region_N 1249family of functions reads 1250.Fa count 12511, 2, 4, or 8 byte data items from the array 1252specified by 1253.Fa datap 1254and writes them to bus space starting at byte offset 1255.Fa offset 1256in the region specified by 1257.Fa handle 1258of the bus space specified 1259by 1260.Fa space . 1261Each successive data item is written to an offset 1, 2, 4, 1262or 8 bytes after the previous data item (depending on which function is 1263used). 1264All locations being written must lie within the bus space region specified by 1265.Fa handle . 1266.Pp 1267For portability, the starting address of the region specified by 1268.Fa handle 1269plus the offset should be a multiple of the size of data items being 1270written and the data array pointer should be properly aligned. 1271On some systems, not obeying these requirements may cause incorrect data 1272to be written, on others it may cause a system crash. 1273.Pp 1274Write operations done by the 1275.Fn bus_space_write_region_N 1276functions may be 1277executed in any order. 1278They may also be executed out of order with respect to other pending read 1279and write operations unless order is enforced by use of the 1280.Fn bus_space_barrier 1281function. 1282There is no way to insert barriers between writes of individual bus 1283space locations executed by the 1284.Fn bus_space_write_region_N 1285functions. 1286.Pp 1287These functions will never fail. 1288If they would fail (e.g., because of an argument error), that indicates 1289a software bug which should cause a panic. 1290In that case, they will never return. 1291.Pp 1292.It Fn bus_space_copy_region_1 "space" "srchandle" "srcoffset" "dsthandle" \ 1293"dstoffset" "count" 1294.It Fn bus_space_copy_region_2 "space" "srchandle" "srcoffset" "dsthandle" \ 1295"dstoffset" "count" 1296.It Fn bus_space_copy_region_4 "space" "srchandle" "srcoffset" "dsthandle" \ 1297"dstoffset" "count" 1298.It Fn bus_space_copy_region_8 "space" "srchandle" "srcoffset" "dsthandle" \ 1299"dstoffset" "count" 1300.Pp 1301The 1302.Fn bus_space_copy_region_N 1303family of functions copies 1304.Fa count 13051, 2, 4, or 8 byte data items in bus space 1306from the area starting at byte offset 1307.Fa srcoffset 1308in the region specified by 1309.Fa srchandle 1310of the bus space specified by 1311.Fa space 1312to the area starting at byte offset 1313.Fa dstoffset 1314in the region specified by 1315.Fa dsthandle 1316in the same bus space. 1317Each successive data item read or written has an offset 1, 2, 4, or 8 1318bytes after the previous data item (depending on which function is used). 1319All locations being read and written must lie within the bus space 1320region specified by their respective handles. 1321.Pp 1322For portability, the starting addresses of the regions specified by 1323each handle plus its respective offset should be a multiple of the size 1324of data items being copied. 1325On some systems, not obeying this requirement may cause incorrect data 1326to be copied, on others it may cause a system crash. 1327.Pp 1328Read and write operations done by the 1329.Fn bus_space_copy_region_N 1330functions may be executed in any order. 1331They may also be executed out of order with respect to other pending 1332read and write operations unless order is enforced by use of the 1333.Fn bus_space_barrier function . 1334There is no way to insert barriers between reads or writes of 1335individual bus space locations executed by the 1336.Fn bus_space_copy_region_N 1337functions. 1338.Pp 1339Overlapping copies between different subregions of a single region 1340of bus space are handled correctly by the 1341.Fn bus_space_copy_region_N 1342functions. 1343.Pp 1344These functions will never fail. 1345If they would fail (e.g., because of an argument error), that indicates 1346a software bug which should cause a panic. 1347In that case, they will never return. 1348.Pp 1349.It Fn bus_space_set_region_1 "space" "handle" "offset" "value" "count" 1350.It Fn bus_space_set_region_2 "space" "handle" "offset" "value" "count" 1351.It Fn bus_space_set_region_4 "space" "handle" "offset" "value" "count" 1352.It Fn bus_space_set_region_8 "space" "handle" "offset" "value" "count" 1353.Pp 1354The 1355.Fn bus_space_set_region_N 1356family of functions writes the given 1357.Fa value 1358to 1359.Fa count 13601, 2, 4, or 8 byte 1361data items in bus space starting at byte offset 1362.Fa offset 1363in the region specified by 1364.Fa handle 1365of the bus space specified by 1366.Fa space . 1367Each successive data item has an offset 1, 2, 4, or 8 bytes after the 1368previous data item (depending on which function is used). 1369All locations being written must lie within the bus space region 1370specified by 1371.Fa handle . 1372.Pp 1373For portability, the starting address of the region specified by 1374.Fa handle 1375plus the offset should be a multiple of the size of data items being 1376written. 1377On some systems, not obeying this requirement may cause incorrect data 1378to be written, on others it may cause a system crash. 1379.Pp 1380Write operations done by the 1381.Fn bus_space_set_region_N 1382functions may be 1383executed in any order. 1384They may also be executed out of order with respect to other pending read 1385and write operations unless order is enforced by use of the 1386.Fn bus_space_barrier 1387function. 1388There is no way to insert barriers between writes of 1389individual bus space locations executed by the 1390.Fn bus_space_set_region_N 1391functions. 1392.Pp 1393These functions will never fail. 1394If they would fail (e.g., because of an argument error), that indicates 1395a software bug which should cause a panic. 1396In that case, they will never return. 1397.El 1398.Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES 1399Some devices implement single locations in bus space which are to be read 1400or written multiple times to communicate data, e.g., some ethernet 1401devices' packet buffer FIFOs. 1402In order to allow drivers to manipulate these types of devices as 1403efficiently as possible, the 1404.Fn bus_space_read_multi_N 1405and 1406.Fn bus_space_write_multi_N 1407families of functions are provided. 1408.Pp 1409.Bl -ohang -compact 1410.It Fn bus_space_read_multi_1 "space" "handle" "offset" "datap" "count" 1411.It Fn bus_space_read_multi_2 "space" "handle" "offset" "datap" "count" 1412.It Fn bus_space_read_multi_4 "space" "handle" "offset" "datap" "count" 1413.It Fn bus_space_read_multi_8 "space" "handle" "offset" "datap" "count" 1414.Pp 1415The 1416.Fn bus_space_read_multi_N 1417family of functions reads 1418.Fa count 14191, 2, 4, or 8 byte data items from bus space 1420at byte offset 1421.Fa offset 1422in the region specified by 1423.Fa handle 1424of the bus space specified by 1425.Fa space 1426and writes them into the array specified by 1427.Fa datap . 1428Each successive data item is read from the same location in bus 1429space. 1430The location being read must lie within the bus space region specified by 1431.Fa handle . 1432.Pp 1433For portability, the starting address of the region specified by 1434.Fa handle 1435plus the offset should be a multiple of the size of data items being 1436read and the data array pointer should be properly aligned. 1437On some systems, not obeying these requirements may cause incorrect data 1438to be read, on others it may cause a system crash. 1439.Pp 1440Read operations done by the 1441.Fn bus_space_read_multi_N 1442functions may be 1443executed out of order with respect to other pending read and write 1444operations unless order is enforced by use of the 1445.Fn bus_space_barrier 1446function. 1447Because the 1448.Fn bus_space_read_multi_N 1449functions read the same bus space location multiple times, they 1450place an implicit read barrier between each successive read of that bus 1451space location. 1452.Pp 1453These functions will never fail. 1454If they would fail (e.g., because of an argument error), that indicates 1455a software bug which should cause a panic. 1456In that case, they will never return. 1457.Pp 1458.It Fn bus_space_write_multi_1 "space" "handle" "offset" "datap" "count" 1459.It Fn bus_space_write_multi_2 "space" "handle" "offset" "datap" "count" 1460.It Fn bus_space_write_multi_4 "space" "handle" "offset" "datap" "count" 1461.It Fn bus_space_write_multi_8 "space" "handle" "offset" "datap" "count" 1462.Pp 1463The 1464.Fn bus_space_write_multi_N 1465family of functions reads 1466.Fa count 14671, 2, 4, or 8 byte data items from the array 1468specified by 1469.Fa datap 1470and writes them into bus space at byte offset 1471.Fa offset 1472in the region specified by 1473.Fa handle 1474of the bus space specified by 1475.Fa space . 1476Each successive data item is written to the same location in 1477bus space. 1478The location being written must lie within the bus space region specified by 1479.Fa handle . 1480.Pp 1481For portability, the starting address of the region specified by 1482.Fa handle 1483plus the offset should be a multiple of the size of data items being 1484written and the data array pointer should be properly aligned. 1485On some systems, not obeying these requirements may cause incorrect data 1486to be written, on others it may cause a system crash. 1487.Pp 1488Write operations done by the 1489.Fn bus_space_write_multi_N 1490functions may be executed out of order with respect to other pending 1491read and write operations unless order is enforced by use of the 1492.Fn bus_space_barrier 1493function. 1494Because the 1495.Fn bus_space_write_multi_N 1496functions write the same bus space location multiple times, they 1497place an implicit write barrier between each successive write of that 1498bus space location. 1499.Pp 1500These functions will never fail. 1501If they would fail (e.g., because of an argument error), that indicates 1502a software bug which should cause a panic. 1503In that case, they will never return. 1504.El 1505.Sh STREAM FUNCTIONS 1506Most of the 1507.Nm 1508functions imply a host byte-order and a bus byte-order and take care of 1509any translation for the caller. 1510In some cases, however, hardware may map a FIFO or some other memory region 1511for which the caller may want to use multi-word, yet untranslated access. 1512Access to these types of memory regions should be with the 1513.Fn bus_space_*_stream_N 1514functions. 1515.Pp 1516.Bl -ohang -compact 1517.It Fn bus_space_read_stream_1 "space" "handle" "offset" 1518.It Fn bus_space_read_stream_2 "space" "handle" "offset" 1519.It Fn bus_space_read_stream_4 "space" "handle" "offset" 1520.It Fn bus_space_read_stream_8 "space" "handle" "offset" 1521.It Fn bus_space_read_multi_stream_1 "space" "handle" "offset" "datap" "count" 1522.It Fn bus_space_read_multi_stream_2 "space" "handle" "offset" "datap" "count" 1523.It Fn bus_space_read_multi_stream_4 "space" "handle" "offset" "datap" "count" 1524.It Fn bus_space_read_multi_stream_8 "space" "handle" "offset" "datap" "count" 1525.It Fn bus_space_read_region_stream_1 "space" "handle" "offset" "datap" "count" 1526.It Fn bus_space_read_region_stream_2 "space" "handle" "offset" "datap" "count" 1527.It Fn bus_space_read_region_stream_4 "space" "handle" "offset" "datap" "count" 1528.It Fn bus_space_read_region_stream_8 "space" "handle" "offset" "datap" "count" 1529.It Fn bus_space_write_stream_1 "space" "handle" "offset" "value" 1530.It Fn bus_space_write_stream_2 "space" "handle" "offset" "value" 1531.It Fn bus_space_write_stream_4 "space" "handle" "offset" "value" 1532.It Fn bus_space_write_stream_8 "space" "handle" "offset" "value" 1533.It Fn bus_space_write_multi_stream_1 "space" "handle" "offset" "datap" "count" 1534.It Fn bus_space_write_multi_stream_2 "space" "handle" "offset" "datap" "count" 1535.It Fn bus_space_write_multi_stream_4 "space" "handle" "offset" "datap" "count" 1536.It Fn bus_space_write_multi_stream_8 "space" "handle" "offset" "datap" "count" 1537.It Fn bus_space_write_region_stream_1 "space" "handle" "offset" "datap" "count" 1538.It Fn bus_space_write_region_stream_2 "space" "handle" "offset" "datap" "count" 1539.It Fn bus_space_write_region_stream_4 "space" "handle" "offset" "datap" "count" 1540.It Fn bus_space_write_region_stream_8 "space" "handle" "offset" "datap" "count" 1541.El 1542.Pp 1543These functions are defined just as their non-stream counterparts, 1544except that they provide no byte-order translation. 1545.Sh EXPECTED CHANGES TO THE BUS_SPACE FUNCTIONS 1546The definition of the 1547.Nm 1548functions should not yet be considered finalized. 1549There are several changes and improvements which should be explored, 1550including: 1551.Pp 1552.Bl -bullet 1553.It 1554Providing a mechanism by which incorrectly-written drivers will be 1555automatically given barriers and properly-written drivers won't be forced 1556to use more barriers than they need. 1557This should probably be done via a 1558.Li #define 1559in the incorrectly-written drivers. 1560Unfortunately, at this time, few drivers actually use barriers correctly 1561(or at all). 1562Because of that, 1563.Nm 1564implementations on architectures which do buffering must always 1565do the barriers inside the 1566.Nm 1567calls, to be safe. 1568That has a potentially significant performance impact. 1569.It 1570Exporting the 1571.Nm 1572functions to user-land so that applications 1573(such as X servers) have easier, more portable access to device space. 1574.It 1575Redefining bus space tags and handles so that machine-independent bus 1576interface drivers (for example PCI to VME bridges) could define and 1577implement bus spaces without requiring machine-dependent code. 1578If this is done, it should be done in such a way that machine-dependent 1579optimizations should remain possible. 1580.It 1581Converting bus spaces (such as PCI configuration space) which currently 1582use space-specific access methods to use the 1583.Nm 1584functions where that is appropriate. 1585.It 1586Redefining the way bus space is mapped and allocated, so that mapping 1587and allocation are done with bus specific functions which return bus 1588space tags. 1589This would allow further optimization than is currently possible, and 1590would also ease translation of the 1591.Nm 1592functions into user space (since mapping in user space would look like 1593it just used a different bus-specific mapping function). 1594.El 1595.Sh COMPATIBILITY 1596The current version of the 1597.Nm 1598interface specification differs slightly from the original 1599specification that came into wide use. 1600A few of the function names and arguments have changed 1601for consistency and increased functionality. 1602Drivers that were written to the 1603old, deprecated specification can be compiled by defining the 1604.Dv __BUS_SPACE_COMPAT_OLDDEFS 1605preprocessor symbol before including 1606.Aq Pa machine/bus.h . 1607.Sh SEE ALSO 1608.Xr bus_dma 9 , 1609.Xr mb 9 1610.Sh HISTORY 1611The 1612.Nm 1613functions were introduced in a different form (memory and I/O spaces 1614were accessed via different sets of functions) in 1615.Nx 1.2 . 1616The functions were merged to work on generic 1617.Dq spaces 1618early in the 1619.Nx 1.3 1620development cycle, and many drivers were converted to use them. 1621This document was written later during the 1622.Nx 1.3 1623development cycle and the specification was updated to fix some 1624consistency problems and to add some missing functionality. 1625.Sh AUTHORS 1626The 1627.Nm 1628interfaces were designed and implemented by the 1629.Nx 1630developer 1631community. 1632Primary contributors and implementors were Chris Demetriou, 1633Jason Thorpe, and Charles Hannum, but the rest of the 1634.Nx 1635developers and the user community played a significant role in development. 1636.Pp 1637Chris Demetriou wrote this manual page. 1638