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. 722.Sh TYPES 723Several types are defined in 724.In machine/bus.h 725to facilitate use of the 726.Nm 727functions by drivers. 728.Ss Vt bus_addr_t 729The 730.Vt bus_addr_t 731type is used to describe bus addresses. 732It must be an 733unsigned integral type 734capable of holding the largest bus address usable by the architecture. 735This 736type is primarily used when mapping and unmapping bus space. 737.Ss Vt bus_size_t 738The 739.Vt bus_size_t 740type is used to describe sizes of ranges in bus space. 741It must be an 742unsigned integral type capable of holding the size of the largest bus 743address range usable on the architecture. 744This type is used by virtually all 745of the 746.Nm 747functions, describing sizes when mapping regions and 748offsets into regions when performing space access operations. 749.Ss Vt bus_space_tag_t 750The 751.Vt bus_space_tag_t 752type is used to describe a particular bus space on a machine. 753Its 754contents are machine-dependent and should be considered opaque by 755machine-independent code. 756This type is used by all 757.Nm 758functions to name the space on which they are operating. 759.Ss Vt bus_space_handle_t 760The 761.Vt bus_space_handle_t 762type is used to describe a mapping of a range of bus space. 763Its 764contents are machine-dependent and should be considered opaque by 765machine-independent code. 766This type is used when performing bus space 767access operations. 768.Sh MAPPING AND UNMAPPING BUS SPACE 769This section is specific to the 770.Nx 771version of these functions and may or may not apply to the 772.Fx 773version. 774.Pp 775Bus space must be mapped before it can be used, and should be 776unmapped when it is no longer needed. 777The 778.Fn bus_space_map 779and 780.Fn bus_space_unmap 781functions provide these capabilities. 782.Pp 783Some drivers need to be able to pass a subregion of already-mapped bus 784space to another driver or module within a driver. 785The 786.Fn bus_space_subregion 787function allows such subregions to be created. 788.Ss Fn bus_space_map space address size flags handlep 789The 790.Fn bus_space_map 791function maps the region of bus space named by the 792.Fa space , address , 793and 794.Fa size 795arguments. 796If successful, it returns zero 797and fills in the bus space handle pointed to by 798.Fa handlep 799with the handle 800that can be used to access the mapped region. 801If unsuccessful, 802it will return non-zero and leave the bus space handle pointed 803to by 804.Fa handlep 805in an undefined state. 806.Pp 807The 808.Fa flags 809argument controls how the space is to be mapped. 810Supported flags include: 811.Bl -tag -width ".Dv BUS_SPACE_MAP_CACHEABLE" 812.It Dv BUS_SPACE_MAP_CACHEABLE 813Try to map the space so that accesses can be cached and/or 814prefetched by the system. 815If this flag is not specified, the 816implementation should map the space so that it will not be cached or 817prefetched. 818.Pp 819This flag must have a value of 1 on all implementations for backward 820compatibility. 821.It Dv BUS_SPACE_MAP_LINEAR 822Try to map the space so that its contents can be accessed linearly via 823normal memory access methods (e.g.\& pointer dereferencing and structure 824accesses). 825This is useful when software wants to do direct access to a memory 826device, e.g.\& a frame buffer. 827If this flag is specified and linear 828mapping is not possible, the 829.Fn bus_space_map 830call should fail. 831If this 832flag is not specified, the system may map the space in whatever way is 833most convenient. 834.El 835.Pp 836Not all combinations of flags make sense or are supported with all 837spaces. 838For instance, 839.Dv BUS_SPACE_MAP_CACHEABLE 840may be meaningless when 841used on many systems' I/O port spaces, and on some systems 842.Dv BUS_SPACE_MAP_LINEAR 843without 844.Dv BUS_SPACE_MAP_CACHEABLE 845may never work. 846When the system hardware or firmware provides hints as to how spaces should be 847mapped (e.g.\& the PCI memory mapping registers' 848.Dq prefetchable 849bit), those 850hints should be followed for maximum compatibility. 851On some systems, 852requesting a mapping that cannot be satisfied (e.g.\& requesting a 853non-cacheable mapping when the system can only provide a cacheable one) 854will cause the request to fail. 855.Pp 856Some implementations may keep track of use of bus space for some or all 857bus spaces and refuse to allow duplicate allocations. 858This is encouraged 859for bus spaces which have no notion of slot-specific space addressing, 860such as ISA and VME, and for spaces which coexist with those spaces 861(e.g.\& EISA and PCI memory and I/O spaces co-existing with ISA memory and 862I/O spaces). 863.Pp 864Mapped regions may contain areas for which no there is no device on the 865bus. 866If space in those areas is accessed, the results are 867bus-dependent. 868.Ss Fn bus_space_unmap space handle size 869The 870.Fn bus_space_unmap 871function unmaps a region of bus space mapped with 872.Fn bus_space_map . 873When unmapping a region, the 874.Fa size 875specified should be 876the same as the size given to 877.Fn bus_space_map 878when mapping that region. 879.Pp 880After 881.Fn bus_space_unmap 882is called on a handle, that handle is no longer 883valid. 884(If copies were made of the handle they are no longer valid, 885either.) 886.Pp 887This function will never fail. 888If it would fail (e.g.\& because of an 889argument error), that indicates a software bug which should cause a 890panic. 891In that case, 892.Fn bus_space_unmap 893will never return. 894.Ss Fn bus_space_subregion space handle offset size nhandlep 895The 896.Fn bus_space_subregion 897function is a convenience function which makes a 898new handle to some subregion of an already-mapped region of bus space. 899The subregion described by the new handle starts at byte offset 900.Fa offset 901into the region described by 902.Fa handle , 903with the size give by 904.Fa size , 905and must be wholly contained within the original region. 906.Pp 907If successful, 908.Fn bus_space_subregion 909returns zero and fills in the bus 910space handle pointed to by 911.Fa nhandlep . 912If unsuccessful, it returns non-zero and leaves the bus space handle 913pointed to by 914.Fa nhandlep 915in an 916undefined state. 917In either case, the handle described by 918.Fa handle 919remains valid and is unmodified. 920.Pp 921When done with a handle created by 922.Fn bus_space_subregion , 923the handle should 924be thrown away. 925Under no circumstances should 926.Fn bus_space_unmap 927be used on the handle. 928Doing so may confuse any resource management 929being done on the space, and will result in undefined behaviour. 930When 931.Fn bus_space_unmap 932or 933.Fn bus_space_free 934is called on a handle, all subregions of that handle become invalid. 935.Sh ALLOCATING AND FREEING BUS SPACE 936This section is specific to the 937.Nx 938version of these functions and may or may not apply to the 939.Fx 940version. 941.Pp 942Some devices require or allow bus space to be allocated by the operating 943system for device use. 944When the devices no longer need the space, the 945operating system should free it for use by other devices. 946The 947.Fn bus_space_alloc 948and 949.Fn bus_space_free 950functions provide these capabilities. 951.Ss Fn bus_space_alloc space reg_start reg_end size alignment boundary \ 952flags addrp handlep 953The 954.Fn bus_space_alloc 955function allocates and maps a region of bus space with the size given by 956.Fa size , 957corresponding to the given constraints. 958If successful, it returns 959zero, fills in the bus address pointed to by 960.Fa addrp 961with the bus space address of the allocated region, and fills in 962the bus space handle pointed to by 963.Fa handlep 964with the handle that can be used to access that region. 965If unsuccessful, it returns non-zero and leaves the bus address pointed to by 966.Fa addrp 967and the bus space handle pointed to by 968.Fa handlep 969in an undefined state. 970.Pp 971Constraints on the allocation are given by the 972.Fa reg_start , reg_end , alignment , 973and 974.Fa boundary 975parameters. 976The allocated region will start at or after 977.Fa reg_start 978and end before or at 979.Fa reg_end . 980The 981.Fa alignment 982constraint must be a power of two, and the allocated region will start at 983an address that is an even multiple of that power of two. 984The 985.Fa boundary 986constraint, if non-zero, ensures that the region is allocated so that 987.Fa "first address in region" 988/ 989.Fa boundary 990has the same value as 991.Fa "last address in region" 992/ 993.Fa boundary . 994If the constraints cannot be met, 995.Fn bus_space_alloc 996will fail. 997It is an error to specify a set of 998constraints that can never be met 999(for example, 1000.Fa size 1001greater than 1002.Fa boundary ) . 1003.Pp 1004The 1005.Fa flags 1006parameter is the same as the like-named parameter to 1007.Fn bus_space_map , 1008the same flag values should be used, and they have the 1009same meanings. 1010.Pp 1011Handles created by 1012.Fn bus_space_alloc 1013should only be freed with 1014.Fn bus_space_free . 1015Trying to use 1016.Fn bus_space_unmap 1017on them causes undefined behaviour. 1018The 1019.Fn bus_space_subregion 1020function can be used on 1021handles created by 1022.Fn bus_space_alloc . 1023.Ss Fn bus_space_free space handle size 1024The 1025.Fn bus_space_free 1026function unmaps and frees a region of bus space mapped 1027and allocated with 1028.Fn bus_space_alloc . 1029When unmapping a region, the 1030.Fa size 1031specified should be the same as the size given to 1032.Fn bus_space_alloc 1033when allocating the region. 1034.Pp 1035After 1036.Fn bus_space_free 1037is called on a handle, that handle is no longer valid. 1038(If copies were 1039made of the handle, they are no longer valid, either.) 1040.Pp 1041This function will never fail. 1042If it would fail (e.g.\& because of an 1043argument error), that indicates a software bug which should cause a 1044panic. 1045In that case, 1046.Fn bus_space_free 1047will never return. 1048.Sh READING AND WRITING SINGLE DATA ITEMS 1049The simplest way to access bus space is to read or write a single data 1050item. 1051The 1052.Fn bus_space_read_N 1053and 1054.Fn bus_space_write_N 1055families of functions provide 1056the ability to read and write 1, 2, 4, and 8 byte data items on busses 1057which support those access sizes. 1058.Ss Fn bus_space_read_1 space handle offset 1059.Ss Fn bus_space_read_2 space handle offset 1060.Ss Fn bus_space_read_4 space handle offset 1061.Ss Fn bus_space_read_8 space handle offset 1062The 1063.Fn bus_space_read_N 1064family of functions reads a 1, 2, 4, or 8 byte data item from 1065the offset specified by 1066.Fa offset 1067into the region specified by 1068.Fa handle 1069of the bus space specified by 1070.Fa space . 1071The location being read must lie within the bus space region specified by 1072.Fa handle . 1073.Pp 1074For portability, the starting address of the region specified by 1075.Fa handle 1076plus the offset should be a multiple of the size of data item being read. 1077On some systems, not obeying this requirement may cause incorrect data to 1078be read, on others it may cause a system crash. 1079.Pp 1080Read operations done by the 1081.Fn bus_space_read_N 1082functions may be executed out 1083of order with respect to other pending read and write operations unless 1084order is enforced by use of the 1085.Fn bus_space_barrier 1086function. 1087.Pp 1088These functions will never fail. 1089If they would fail (e.g.\& because of an 1090argument error), that indicates a software bug which should cause a 1091panic. 1092In that case, they will never return. 1093.Ss Fn bus_space_write_1 space handle offset value 1094.Ss Fn bus_space_write_2 space handle offset value 1095.Ss Fn bus_space_write_4 space handle offset value 1096.Ss Fn bus_space_write_8 space handle offset value 1097The 1098.Fn bus_space_write_N 1099family of functions writes a 1, 2, 4, or 8 byte data item to the offset 1100specified by 1101.Fa offset 1102into the region specified by 1103.Fa handle 1104of the bus space specified by 1105.Fa space . 1106The location being written must lie within 1107the bus space region specified by 1108.Fa handle . 1109.Pp 1110For portability, the starting address of the region specified by 1111.Fa handle 1112plus the offset should be a multiple of the size of data item being 1113written. 1114On some systems, not obeying this requirement may cause 1115incorrect data to be written, on others it may cause a system crash. 1116.Pp 1117Write operations done by the 1118.Fn bus_space_write_N 1119functions may be executed 1120out of order with respect to other pending read and write operations 1121unless order is enforced by use of the 1122.Fn bus_space_barrier 1123function. 1124.Pp 1125These functions will never fail. 1126If they would fail (e.g.\& because of an 1127argument error), that indicates a software bug which should cause a 1128panic. 1129In that case, they will never return. 1130.Sh BARRIERS 1131In order to allow high-performance buffering implementations to avoid bus 1132activity on every operation, read and write ordering should be specified 1133explicitly by drivers when necessary. 1134The 1135.Fn bus_space_barrier 1136function provides that ability. 1137.Ss Fn bus_space_barrier space handle offset length flags 1138The 1139.Fn bus_space_barrier 1140function enforces ordering of bus space read and write operations 1141for the specified subregion (described by the 1142.Fa offset 1143and 1144.Fa length 1145parameters) of the region named by 1146.Fa handle 1147in the space named by 1148.Fa space . 1149.Pp 1150The 1151.Fa flags 1152argument controls what types of operations are to be ordered. 1153Supported flags are: 1154.Bl -tag -width ".Dv BUS_SPACE_BARRIER_WRITE" 1155.It Dv BUS_SPACE_BARRIER_READ 1156Synchronize read operations. 1157.It Dv BUS_SPACE_BARRIER_WRITE 1158Synchronize write operations. 1159.El 1160.Pp 1161Those flags can be combined (or-ed together) to enforce ordering on both 1162read and write operations. 1163.Pp 1164All of the specified type(s) of operation which are done to the region 1165before the barrier operation are guaranteed to complete before any of the 1166specified type(s) of operation done after the barrier. 1167.Pp 1168Example: Consider a hypothetical device with two single-byte ports, one 1169write-only input port (at offset 0) and a read-only output port (at 1170offset 1). 1171Operation of the device is as follows: data bytes are written 1172to the input port, and are placed by the device on a stack, the top of 1173which is read by reading from the output port. 1174The sequence to correctly 1175write two data bytes to the device then read those two data bytes back 1176would be: 1177.Bd -literal 1178/* 1179 * t and h are the tag and handle for the mapped device's 1180 * space. 1181 */ 1182bus_space_write_1(t, h, 0, data0); 1183bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE); /* 1 */ 1184bus_space_write_1(t, h, 0, data1); 1185bus_space_barrier(t, h, 0, 2, 1186 BUS_SPACE_BARRIER_READ|BUS_SPACE_BARRIER_WRITE); /* 2 */ 1187ndata1 = bus_space_read_1(t, h, 1); 1188bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ); /* 3 */ 1189ndata0 = bus_space_read_1(t, h, 1); 1190/* data0 == ndata0, data1 == ndata1 */ 1191.Ed 1192.Pp 1193The first barrier makes sure that the first write finishes before the 1194second write is issued, so that two writes to the input port are done 1195in order and are not collapsed into a single write. 1196This ensures that 1197the data bytes are written to the device correctly and in order. 1198.Pp 1199The second barrier makes sure that the writes to the output port finish 1200before any of the reads to the input port are issued, thereby making sure 1201that all of the writes are finished before data is read. 1202This ensures 1203that the first byte read from the device really is the last one that was 1204written. 1205.Pp 1206The third barrier makes sure that the first read finishes before the 1207second read is issued, ensuring that data is read correctly and in order. 1208.Pp 1209The barriers in the example above are specified to cover the absolute 1210minimum number of bus space locations. 1211It is correct (and often 1212easier) to make barrier operations cover the device's whole range of bus 1213space, that is, to specify an offset of zero and the size of the 1214whole region. 1215.Sh REGION OPERATIONS 1216Some devices use buffers which are mapped as regions in bus space. 1217Often, drivers want to copy the contents of those buffers to or from 1218memory, e.g.\& into mbufs which can be passed to higher levels of the 1219system or from mbufs to be output to a network. 1220In order to allow 1221drivers to do this as efficiently as possible, the 1222.Fn bus_space_read_region_N 1223and 1224.Fn bus_space_write_region_N 1225families of functions are provided. 1226.Pp 1227Drivers occasionally need to copy one region of a bus space to another, 1228or to set all locations in a region of bus space to contain a single 1229value. 1230The 1231.Fn bus_space_copy_region_N 1232family of functions and the 1233.Fn bus_space_set_region_N 1234family of functions allow drivers to perform these operations. 1235.Ss Fn bus_space_read_region_1 space handle offset datap count 1236.Ss Fn bus_space_read_region_2 space handle offset datap count 1237.Ss Fn bus_space_read_region_4 space handle offset datap count 1238.Ss Fn bus_space_read_region_8 space handle offset datap count 1239The 1240.Fn bus_space_read_region_N 1241family of functions reads 1242.Fa count 12431, 2, 4, or 8 byte data items from bus space 1244starting at byte offset 1245.Fa offset 1246in the region specified by 1247.Fa handle 1248of the bus space specified by 1249.Fa space 1250and writes them into the array specified by 1251.Fa datap . 1252Each successive data item is read from an offset 12531, 2, 4, or 8 bytes after the previous data item (depending on which 1254function is used). 1255All locations being read must lie within the bus 1256space region specified by 1257.Fa handle . 1258.Pp 1259For portability, the starting address of the region specified by 1260.Fa handle 1261plus the offset should be a multiple of the size of data items being 1262read and the data array pointer should be properly aligned. 1263On some 1264systems, not obeying these requirements may cause incorrect data to be 1265read, on others it may cause a system crash. 1266.Pp 1267Read operations done by the 1268.Fn bus_space_read_region_N 1269functions may be executed in any order. 1270They may also be executed out 1271of order with respect to other pending read and write operations unless 1272order is enforced by use of the 1273.Fn bus_space_barrier 1274function. 1275There is no way to insert barriers between reads of 1276individual bus space locations executed by the 1277.Fn bus_space_read_region_N 1278functions. 1279.Pp 1280These functions will never fail. 1281If they would fail (e.g.\& because of an 1282argument error), that indicates a software bug which should cause a 1283panic. 1284In that case, they will never return. 1285.Ss Fn bus_space_write_region_1 space handle offset datap count 1286.Ss Fn bus_space_write_region_2 space handle offset datap count 1287.Ss Fn bus_space_write_region_4 space handle offset datap count 1288.Ss Fn bus_space_write_region_8 space handle offset datap count 1289The 1290.Fn bus_space_write_region_N 1291family of functions reads 1292.Fa count 12931, 2, 4, or 8 byte data items from the array 1294specified by 1295.Fa datap 1296and writes them to bus space starting at byte offset 1297.Fa offset 1298in the region specified by 1299.Fa handle 1300of the bus space specified 1301by 1302.Fa space . 1303Each successive data item is written to an offset 1, 2, 4, 1304or 8 bytes after the previous data item (depending on which function is 1305used). 1306All locations being written must lie within the bus space region 1307specified by 1308.Fa handle . 1309.Pp 1310For portability, the starting address of the region specified by 1311.Fa handle 1312plus the offset should be a multiple of the size of data items being 1313written and the data array pointer should be properly aligned. 1314On some 1315systems, not obeying these requirements may cause incorrect data to be 1316written, on others it may cause a system crash. 1317.Pp 1318Write operations done by the 1319.Fn bus_space_write_region_N 1320functions may be 1321executed in any order. 1322They may also be executed out of order with 1323respect to other pending read and write operations unless order is 1324enforced by use of the 1325.Fn bus_space_barrier 1326function. 1327There is no way to insert barriers between writes of 1328individual bus space locations executed by the 1329.Fn bus_space_write_region_N 1330functions. 1331.Pp 1332These functions will never fail. 1333If they would fail (e.g.\& because of an 1334argument error), that indicates a software bug which should cause a 1335panic. 1336In that case, they will never return. 1337.Ss Fn bus_space_copy_region_1 space srchandle srcoffset dsthandle \ 1338dstoffset count 1339.Ss Fn bus_space_copy_region_2 space srchandle srcoffset dsthandle \ 1340dstoffset count 1341.Ss Fn bus_space_copy_region_4 space srchandle srcoffset dsthandle \ 1342dstoffset count 1343.Ss Fn bus_space_copy_region_8 space srchandle srcoffset dsthandle \ 1344dstoffset count 1345The 1346.Fn bus_space_copy_region_N 1347family of functions copies 1348.Fa count 13491, 2, 4, or 8 byte data items in bus space 1350from the area starting at byte offset 1351.Fa srcoffset 1352in the region specified by 1353.Fa srchandle 1354of the bus space specified by 1355.Fa space 1356to the area starting at byte offset 1357.Fa dstoffset 1358in the region specified by 1359.Fa dsthandle 1360in the same bus space. 1361Each successive data item read or written has 1362an offset 1, 2, 4, or 8 bytes after the previous data item (depending 1363on which function is used). 1364All locations being read and written must 1365lie within the bus space region specified by their respective handles. 1366.Pp 1367For portability, the starting addresses of the regions specified by the 1368each handle plus its respective offset should be a multiple of the size 1369of data items being copied. 1370On some systems, not obeying this 1371requirement may cause incorrect data to be copied, on others it may cause 1372a system crash. 1373.Pp 1374Read and write operations done by the 1375.Fn bus_space_copy_region_N 1376functions may be executed in any order. 1377They may also be executed out 1378of order with respect to other pending read and write operations unless 1379order is enforced by use of the 1380.Fn bus_space_barrier function . 1381There is no way to insert barriers between reads or writes of 1382individual bus space locations executed by the 1383.Fn bus_space_copy_region_N 1384functions. 1385.Pp 1386Overlapping copies between different subregions of a single region 1387of bus space are handled correctly by the 1388.Fn bus_space_copy_region_N 1389functions. 1390.Pp 1391These functions will never fail. 1392If they would fail (e.g.\& because of an 1393argument error), that indicates a software bug which should cause a 1394panic. 1395In that case, they will never return. 1396.Ss Fn bus_space_set_region_1 space handle offset value count 1397.Ss Fn bus_space_set_region_2 space handle offset value count 1398.Ss Fn bus_space_set_region_4 space handle offset value count 1399.Ss Fn bus_space_set_region_8 space handle offset value count 1400The 1401.Fn bus_space_set_region_N 1402family of functions writes the given 1403.Fa value 1404to 1405.Fa count 14061, 2, 4, or 8 byte 1407data items in bus space starting at byte offset 1408.Fa offset 1409in the region specified by 1410.Fa handle 1411of the bus space specified by 1412.Fa space . 1413Each successive data item has an offset 1, 2, 4, or 8 bytes after the 1414previous data item (depending on which function is used). 1415All 1416locations being written must lie within the bus space region specified 1417by 1418.Fa handle . 1419.Pp 1420For portability, the starting address of the region specified by 1421.Fa handle 1422plus the offset should be a multiple of the size of data items being 1423written. 1424On some systems, not obeying this requirement may cause 1425incorrect data to be written, on others it may cause a system crash. 1426.Pp 1427Write operations done by the 1428.Fn bus_space_set_region_N 1429functions may be 1430executed in any order. 1431They may also be executed out of order with 1432respect to other pending read and write operations unless order is 1433enforced by use of the 1434.Fn bus_space_barrier 1435function. 1436There is no way to insert barriers between writes of 1437individual bus space locations executed by the 1438.Fn bus_space_set_region_N 1439functions. 1440.Pp 1441These functions will never fail. 1442If they would fail (e.g.\& because of an 1443argument error), that indicates a software bug which should cause a 1444panic. 1445In that case, they will never return. 1446.Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES 1447Some devices implement single locations in bus space which are to be read 1448or written multiple times to communicate data, e.g.\& some ethernet 1449devices' packet buffer FIFOs. 1450In order to allow drivers to manipulate 1451these types of devices as efficiently as possible, the 1452.Fn bus_space_read_multi_N , 1453.Fn bus_space_set_multi_N , 1454and 1455.Fn bus_space_write_multi_N 1456families of functions are provided. 1457.Ss Fn bus_space_read_multi_1 space handle offset datap count 1458.Ss Fn bus_space_read_multi_2 space handle offset datap count 1459.Ss Fn bus_space_read_multi_4 space handle offset datap count 1460.Ss Fn bus_space_read_multi_8 space handle offset datap count 1461The 1462.Fn bus_space_read_multi_N 1463family of functions reads 1464.Fa count 14651, 2, 4, or 8 byte data items from bus space 1466at byte offset 1467.Fa offset 1468in the region specified by 1469.Fa handle 1470of the bus space specified by 1471.Fa space 1472and writes them into the array specified by 1473.Fa datap . 1474Each successive data item is read from the same location in bus 1475space. 1476The location being read must lie within the bus space region 1477specified by 1478.Fa handle . 1479.Pp 1480For portability, the starting address of the region specified by 1481.Fa handle 1482plus the offset should be a multiple of the size of data items being 1483read and the data array pointer should be properly aligned. 1484On some 1485systems, not obeying these requirements may cause incorrect data to be 1486read, on others it may cause a system crash. 1487.Pp 1488Read operations done by the 1489.Fn bus_space_read_multi_N 1490functions may be 1491executed out of order with respect to other pending read and write 1492operations unless order is enforced by use of the 1493.Fn bus_space_barrier 1494function. 1495Because the 1496.Fn bus_space_read_multi_N 1497functions read the same bus space location multiple times, they 1498place an implicit read barrier between each successive read of that bus 1499space location. 1500.Pp 1501These functions will never fail. 1502If they would fail (e.g.\& because of an 1503argument error), that indicates a software bug which should cause a 1504panic. 1505In that case, they will never return. 1506.Ss Fn bus_space_write_multi_1 space handle offset datap count 1507.Ss Fn bus_space_write_multi_2 space handle offset datap count 1508.Ss Fn bus_space_write_multi_4 space handle offset datap count 1509.Ss Fn bus_space_write_multi_8 space handle offset datap count 1510The 1511.Fn bus_space_write_multi_N 1512family of functions reads 1513.Fa count 15141, 2, 4, or 8 byte data items from the array 1515specified by 1516.Fa datap 1517and writes them into bus space at byte offset 1518.Fa offset 1519in the region specified by 1520.Fa handle 1521of the bus space specified by 1522.Fa space . 1523Each successive data item is written to the same location in 1524bus space. 1525The location being written must lie within the bus space 1526region specified by 1527.Fa handle . 1528.Pp 1529For portability, the starting address of the region specified by 1530.Fa handle 1531plus the offset should be a multiple of the size of data items being 1532written and the data array pointer should be properly aligned. 1533On some 1534systems, not obeying these requirements may cause incorrect data to be 1535written, on others it may cause a system crash. 1536.Pp 1537Write operations done by the 1538.Fn bus_space_write_multi_N 1539functions may be executed out of order with respect to other pending 1540read and write operations unless order is enforced by use of the 1541.Fn bus_space_barrier 1542function. 1543Because the 1544.Fn bus_space_write_multi_N 1545functions write the same bus space location multiple times, they 1546place an implicit write barrier between each successive write of that 1547bus space location. 1548.Pp 1549These functions will never fail. 1550If they would fail (e.g.\& because of an 1551argument error), that indicates a software bug which should cause a 1552panic. 1553In that case, they will never return. 1554.Ss Fn bus_space_set_multi_1 space handle offset value count 1555.Ss Fn bus_space_set_multi_2 space handle offset value count 1556.Ss Fn bus_space_set_multi_4 space handle offset value count 1557.Ss Fn bus_space_set_multi_8 space handle offset value count 1558The 1559.Fn bus_space_set_multi_N 1560writes 1561.Fa value 1562into bus space at byte offset 1563.Fa offset 1564in the region specified by 1565.Fa handle 1566of the bus space specified by 1567.Fa space , 1568.Fa count 1569times. 1570The location being written must lie within the bus space 1571region specified by 1572.Fa handle . 1573.Pp 1574For portability, the starting address of the region specified by 1575.Fa handle 1576plus the offset should be a multiple of the size of data items being 1577written and the data array pointer should be properly aligned. 1578On some 1579systems, not obeying these requirements may cause incorrect data to be 1580written, on others it may cause a system crash. 1581.Pp 1582Write operations done by the 1583.Fn bus_space_set_multi_N 1584functions may be executed out of order with respect to other pending 1585read and write operations unless order is enforced by use of the 1586.Fn bus_space_barrier 1587function. 1588Because the 1589.Fn bus_space_set_multi_N 1590functions write the same bus space location multiple times, they 1591place an implicit write barrier between each successive write of that 1592bus space location. 1593.Pp 1594These functions will never fail. 1595If they would fail (e.g.\& because of an 1596argument error), that indicates a software bug which should cause a 1597panic. 1598In that case, they will never return. 1599.Sh STREAM FUNCTIONS 1600Most of the 1601.Nm 1602functions imply a host byte-order and a bus byte-order and take care of 1603any translation for the caller. 1604In some cases, however, hardware may map a FIFO or some other memory region 1605for which the caller may want to use multi-word, yet untranslated access. 1606Access to these types of memory regions should be with the 1607.Fn bus_space_*_stream_N 1608functions. 1609.Pp 1610.Bl -tag -compact 1611.It Fn bus_space_read_stream_1 1612.It Fn bus_space_read_stream_2 1613.It Fn bus_space_read_stream_4 1614.It Fn bus_space_read_stream_8 1615.It Fn bus_space_read_multi_stream_1 1616.It Fn bus_space_read_multi_stream_2 1617.It Fn bus_space_read_multi_stream_4 1618.It Fn bus_space_read_multi_stream_8 1619.It Fn bus_space_read_region_stream_1 1620.It Fn bus_space_read_region_stream_2 1621.It Fn bus_space_read_region_stream_4 1622.It Fn bus_space_read_region_stream_8 1623.It Fn bus_space_write_stream_1 1624.It Fn bus_space_write_stream_2 1625.It Fn bus_space_write_stream_4 1626.It Fn bus_space_write_stream_8 1627.It Fn bus_space_write_multi_stream_1 1628.It Fn bus_space_write_multi_stream_2 1629.It Fn bus_space_write_multi_stream_4 1630.It Fn bus_space_write_multi_stream_8 1631.It Fn bus_space_write_region_stream_1 1632.It Fn bus_space_write_region_stream_2 1633.It Fn bus_space_write_region_stream_4 1634.It Fn bus_space_write_region_stream_8 1635.It Fn bus_space_copy_region_stream_1 1636.It Fn bus_space_copy_region_stream_2 1637.It Fn bus_space_copy_region_stream_4 1638.It Fn bus_space_copy_region_stream_8 1639.It Fn bus_space_set_multi_stream_1 1640.It Fn bus_space_set_multi_stream_2 1641.It Fn bus_space_set_multi_stream_4 1642.It Fn bus_space_set_multi_stream_8 1643.It Fn bus_space_set_region_stream_1 1644.It Fn bus_space_set_region_stream_2 1645.It Fn bus_space_set_region_stream_4 1646.It Fn bus_space_set_region_stream_8 1647.El 1648.Pp 1649These functions are defined just as their non-stream counterparts, 1650except that they provide no byte-order translation. 1651.Sh COMPATIBILITY 1652The current 1653.Nx 1654version of the 1655.Nm 1656interface specification differs slightly from the original 1657specification that came into wide use and 1658.Fx 1659adopted. 1660A few of the function names and arguments have changed 1661for consistency and increased functionality. 1662.Sh SEE ALSO 1663.Xr bus_dma 9 1664.Sh HISTORY 1665The 1666.Nm 1667functions were introduced in a different form (memory and I/O spaces 1668were accessed via different sets of functions) in 1669.Nx 1.2 . 1670The functions were merged to work on generic 1671.Dq spaces 1672early in the 1673.Nx 1.3 1674development cycle, and many drivers were converted to use them. 1675This document was written later during the 1676.Nx 1.3 1677development cycle, and the specification was updated to fix some 1678consistency problems and to add some missing functionality. 1679.Pp 1680The manual page was then adopted to the version of the interface that 1681.Fx 1682imported for the CAM SCSI drivers, plus subsequent evolution. 1683The 1684.Fx 1685.Nm 1686version was imported in 1687.Fx 3.0 . 1688.Sh AUTHORS 1689.An -nosplit 1690The 1691.Nm 1692interfaces were designed and implemented by the 1693.Nx 1694developer 1695community. 1696Primary contributors and implementors were 1697.An Chris Demetriou , 1698.An Jason Thorpe , 1699and 1700.An Charles Hannum , 1701but the rest of the 1702.Nx 1703developers and the user community played a significant role in development. 1704.Pp 1705.An Justin Gibbs 1706ported these interfaces to 1707.Fx . 1708.Pp 1709.An Chris Demetriou 1710wrote this manual page. 1711.Pp 1712.An Warner Losh 1713modified it for the 1714.Fx 1715implementation. 1716.Sh BUGS 1717This manual may not completely and accurately document the interface, 1718and many parts of the interface are unspecified. 1719