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 u_int8_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 u_int16_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 u_int32_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 u_int64_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 u_int8_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 u_int16_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 u_int32_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 u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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 function . 1384There is no way to insert barriers between reads or writes of 1385individual bus space locations executed by the 1386.Fn bus_space_copy_region_N 1387functions. 1388.Pp 1389Overlapping copies between different subregions of a single region 1390of bus space are handled correctly by the 1391.Fn bus_space_copy_region_N 1392functions. 1393.Pp 1394These functions will never fail. 1395If they would fail (e.g.\& because of an 1396argument error), that indicates a software bug which should cause a 1397panic. 1398In that case, they will never return. 1399.Ss Fn bus_space_set_region_1 space handle offset value count 1400.Ss Fn bus_space_set_region_2 space handle offset value count 1401.Ss Fn bus_space_set_region_4 space handle offset value count 1402.Ss Fn bus_space_set_region_8 space handle offset value count 1403The 1404.Fn bus_space_set_region_N 1405family of functions writes the given 1406.Fa value 1407to 1408.Fa count 14091, 2, 4, or 8 byte 1410data items in bus space starting at byte offset 1411.Fa offset 1412in the region specified by 1413.Fa handle 1414of the bus space specified by 1415.Fa space . 1416Each successive data item has an offset 1, 2, 4, or 8 bytes after the 1417previous data item (depending on which function is used). 1418All 1419locations being written must lie within the bus space region specified 1420by 1421.Fa handle . 1422.Pp 1423For portability, the starting address of the region specified by 1424.Fa handle 1425plus the offset should be a multiple of the size of data items being 1426written. 1427On some systems, not obeying this requirement may cause 1428incorrect data to be written, on others it may cause a system crash. 1429.Pp 1430Write operations done by the 1431.Fn bus_space_set_region_N 1432functions may be 1433executed in any order. 1434They may also be executed out of order with 1435respect to other pending read and write operations unless order is 1436enforced by use of the 1437.Fn bus_space_barrier 1438function. 1439There is no way to insert barriers between writes of 1440individual bus space locations executed by the 1441.Fn bus_space_set_region_N 1442functions. 1443.Pp 1444These functions will never fail. 1445If they would fail (e.g.\& because of an 1446argument error), that indicates a software bug which should cause a 1447panic. 1448In that case, they will never return. 1449.Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES 1450Some devices implement single locations in bus space which are to be read 1451or written multiple times to communicate data, e.g.\& some ethernet 1452devices' packet buffer FIFOs. 1453In order to allow drivers to manipulate 1454these types of devices as efficiently as possible, the 1455.Fn bus_space_read_multi_N , 1456.Fn bus_space_set_multi_N , 1457and 1458.Fn bus_space_write_multi_N 1459families of functions are provided. 1460.Ss Fn bus_space_read_multi_1 space handle offset datap count 1461.Ss Fn bus_space_read_multi_2 space handle offset datap count 1462.Ss Fn bus_space_read_multi_4 space handle offset datap count 1463.Ss Fn bus_space_read_multi_8 space handle offset datap count 1464The 1465.Fn bus_space_read_multi_N 1466family of functions reads 1467.Fa count 14681, 2, 4, or 8 byte data items from bus space 1469at byte offset 1470.Fa offset 1471in the region specified by 1472.Fa handle 1473of the bus space specified by 1474.Fa space 1475and writes them into the array specified by 1476.Fa datap . 1477Each successive data item is read from the same location in bus 1478space. 1479The location being read must lie within the bus space region 1480specified by 1481.Fa handle . 1482.Pp 1483For portability, the starting address of the region specified by 1484.Fa handle 1485plus the offset should be a multiple of the size of data items being 1486read and the data array pointer should be properly aligned. 1487On some 1488systems, not obeying these requirements may cause incorrect data to be 1489read, on others it may cause a system crash. 1490.Pp 1491Read operations done by the 1492.Fn bus_space_read_multi_N 1493functions may be 1494executed out of order with respect to other pending read and write 1495operations unless order is enforced by use of the 1496.Fn bus_space_barrier 1497function. 1498Because the 1499.Fn bus_space_read_multi_N 1500functions read the same bus space location multiple times, they 1501place an implicit read barrier between each successive read of that bus 1502space location. 1503.Pp 1504These functions will never fail. 1505If they would fail (e.g.\& because of an 1506argument error), that indicates a software bug which should cause a 1507panic. 1508In that case, they will never return. 1509.Ss Fn bus_space_write_multi_1 space handle offset datap count 1510.Ss Fn bus_space_write_multi_2 space handle offset datap count 1511.Ss Fn bus_space_write_multi_4 space handle offset datap count 1512.Ss Fn bus_space_write_multi_8 space handle offset datap count 1513The 1514.Fn bus_space_write_multi_N 1515family of functions reads 1516.Fa count 15171, 2, 4, or 8 byte data items from the array 1518specified by 1519.Fa datap 1520and writes them into bus space at byte offset 1521.Fa offset 1522in the region specified by 1523.Fa handle 1524of the bus space specified by 1525.Fa space . 1526Each successive data item is written to the same location in 1527bus space. 1528The location being written must lie within the bus space 1529region specified by 1530.Fa handle . 1531.Pp 1532For portability, the starting address of the region specified by 1533.Fa handle 1534plus the offset should be a multiple of the size of data items being 1535written and the data array pointer should be properly aligned. 1536On some 1537systems, not obeying these requirements may cause incorrect data to be 1538written, on others it may cause a system crash. 1539.Pp 1540Write operations done by the 1541.Fn bus_space_write_multi_N 1542functions may be executed out of order with respect to other pending 1543read and write operations unless order is enforced by use of the 1544.Fn bus_space_barrier 1545function. 1546Because the 1547.Fn bus_space_write_multi_N 1548functions write the same bus space location multiple times, they 1549place an implicit write barrier between each successive write of that 1550bus space location. 1551.Pp 1552These functions will never fail. 1553If they would fail (e.g.\& because of an 1554argument error), that indicates a software bug which should cause a 1555panic. 1556In that case, they will never return. 1557.Ss Fn bus_space_set_multi_1 space handle offset value count 1558.Ss Fn bus_space_set_multi_2 space handle offset value count 1559.Ss Fn bus_space_set_multi_4 space handle offset value count 1560.Ss Fn bus_space_set_multi_8 space handle offset value count 1561The 1562.Fn bus_space_set_multi_N 1563writes 1564.Fa value 1565into bus space at byte offset 1566.Fa offset 1567in the region specified by 1568.Fa handle 1569of the bus space specified by 1570.Fa space , 1571.Fa count 1572times. 1573The location being written must lie within the bus space 1574region specified by 1575.Fa handle . 1576.Pp 1577For portability, the starting address of the region specified by 1578.Fa handle 1579plus the offset should be a multiple of the size of data items being 1580written and the data array pointer should be properly aligned. 1581On some 1582systems, not obeying these requirements may cause incorrect data to be 1583written, on others it may cause a system crash. 1584.Pp 1585Write operations done by the 1586.Fn bus_space_set_multi_N 1587functions may be executed out of order with respect to other pending 1588read and write operations unless order is enforced by use of the 1589.Fn bus_space_barrier 1590function. 1591Because the 1592.Fn bus_space_set_multi_N 1593functions write the same bus space location multiple times, they 1594place an implicit write barrier between each successive write of that 1595bus space location. 1596.Pp 1597These functions will never fail. 1598If they would fail (e.g.\& because of an 1599argument error), that indicates a software bug which should cause a 1600panic. 1601In that case, they will never return. 1602.Sh STREAM FUNCTIONS 1603Most of the 1604.Nm 1605functions imply a host byte-order and a bus byte-order and take care of 1606any translation for the caller. 1607In some cases, however, hardware may map a FIFO or some other memory region 1608for which the caller may want to use multi-word, yet untranslated access. 1609Access to these types of memory regions should be with the 1610.Fn bus_space_*_stream_N 1611functions. 1612.Pp 1613.Bl -tag -compact 1614.It Fn bus_space_read_stream_1 1615.It Fn bus_space_read_stream_2 1616.It Fn bus_space_read_stream_4 1617.It Fn bus_space_read_stream_8 1618.It Fn bus_space_read_multi_stream_1 1619.It Fn bus_space_read_multi_stream_2 1620.It Fn bus_space_read_multi_stream_4 1621.It Fn bus_space_read_multi_stream_8 1622.It Fn bus_space_read_region_stream_1 1623.It Fn bus_space_read_region_stream_2 1624.It Fn bus_space_read_region_stream_4 1625.It Fn bus_space_read_region_stream_8 1626.It Fn bus_space_write_stream_1 1627.It Fn bus_space_write_stream_2 1628.It Fn bus_space_write_stream_4 1629.It Fn bus_space_write_stream_8 1630.It Fn bus_space_write_multi_stream_1 1631.It Fn bus_space_write_multi_stream_2 1632.It Fn bus_space_write_multi_stream_4 1633.It Fn bus_space_write_multi_stream_8 1634.It Fn bus_space_write_region_stream_1 1635.It Fn bus_space_write_region_stream_2 1636.It Fn bus_space_write_region_stream_4 1637.It Fn bus_space_write_region_stream_8 1638.It Fn bus_space_copy_region_stream_1 1639.It Fn bus_space_copy_region_stream_2 1640.It Fn bus_space_copy_region_stream_4 1641.It Fn bus_space_copy_region_stream_8 1642.It Fn bus_space_set_multi_stream_1 1643.It Fn bus_space_set_multi_stream_2 1644.It Fn bus_space_set_multi_stream_4 1645.It Fn bus_space_set_multi_stream_8 1646.It Fn bus_space_set_region_stream_1 1647.It Fn bus_space_set_region_stream_2 1648.It Fn bus_space_set_region_stream_4 1649.It Fn bus_space_set_region_stream_8 1650.El 1651.Pp 1652These functions are defined just as their non-stream counterparts, 1653except that they provide no byte-order translation. 1654.Sh COMPATIBILITY 1655The current 1656.Nx 1657version of the 1658.Nm 1659interface specification differs slightly from the original 1660specification that came into wide use and 1661.Fx 1662adopted. 1663A few of the function names and arguments have changed 1664for consistency and increased functionality. 1665.Sh SEE ALSO 1666.Xr bus_dma 9 1667.Sh HISTORY 1668The 1669.Nm 1670functions were introduced in a different form (memory and I/O spaces 1671were accessed via different sets of functions) in 1672.Nx 1.2 . 1673The functions were merged to work on generic 1674.Dq spaces 1675early in the 1676.Nx 1.3 1677development cycle, and many drivers were converted to use them. 1678This document was written later during the 1679.Nx 1.3 1680development cycle, and the specification was updated to fix some 1681consistency problems and to add some missing functionality. 1682.Pp 1683The manual page was then adapted to the version of the interface that 1684.Fx 1685imported for the CAM SCSI drivers, plus subsequent evolution. 1686The 1687.Fx 1688.Nm 1689version was imported in 1690.Fx 3.0 . 1691.Sh AUTHORS 1692.An -nosplit 1693The 1694.Nm 1695interfaces were designed and implemented by the 1696.Nx 1697developer 1698community. 1699Primary contributors and implementors were 1700.An Chris Demetriou , 1701.An Jason Thorpe , 1702and 1703.An Charles Hannum , 1704but the rest of the 1705.Nx 1706developers and the user community played a significant role in development. 1707.Pp 1708.An Justin Gibbs 1709ported these interfaces to 1710.Fx . 1711.Pp 1712.An Chris Demetriou 1713wrote this manual page. 1714.Pp 1715.An Warner Losh 1716modified it for the 1717.Fx 1718implementation. 1719.Sh BUGS 1720This manual may not completely and accurately document the interface, 1721and many parts of the interface are unspecified. 1722