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