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