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