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