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