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