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