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