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