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