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