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