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 July 7, 2020 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.El 880.Pp 881Not all combinations of flags make sense or are supported with all 882spaces. 883For instance, 884.Dv BUS_SPACE_MAP_CACHEABLE 885may be meaningless when 886used on many systems' I/O port spaces, and on some systems 887.Dv BUS_SPACE_MAP_LINEAR 888without 889.Dv BUS_SPACE_MAP_CACHEABLE 890may never work. 891When the system hardware or firmware provides hints as to how spaces should be 892mapped (e.g.\& the PCI memory mapping registers' 893.Dq prefetchable 894bit), those 895hints should be followed for maximum compatibility. 896On some systems, 897requesting a mapping that cannot be satisfied (e.g.\& requesting a 898non-cacheable mapping when the system can only provide a cacheable one) 899will cause the request to fail. 900.Pp 901Some implementations may keep track of use of bus space for some or all 902bus spaces and refuse to allow duplicate allocations. 903This is encouraged 904for bus spaces which have no notion of slot-specific space addressing, 905such as ISA, and for spaces which coexist with those spaces 906(e.g.\& PCI memory and I/O spaces co-existing with ISA memory and 907I/O spaces). 908.Pp 909Mapped regions may contain areas for which there is no device on the 910bus. 911If space in those areas is accessed, the results are 912bus-dependent. 913.Ss Fn bus_space_unmap space handle size 914The 915.Fn bus_space_unmap 916function unmaps a region of bus space mapped with 917.Fn bus_space_map . 918When unmapping a region, the 919.Fa size 920specified should be 921the same as the size given to 922.Fn bus_space_map 923when mapping that region. 924.Pp 925After 926.Fn bus_space_unmap 927is called on a handle, that handle is no longer 928valid. 929(If copies were made of the handle they are no longer valid, 930either.) 931.Pp 932This function will never fail. 933If it would fail (e.g.\& because of an 934argument error), that indicates a software bug which should cause a 935panic. 936In that case, 937.Fn bus_space_unmap 938will never return. 939.Ss Fn bus_space_subregion space handle offset size nhandlep 940The 941.Fn bus_space_subregion 942function is a convenience function which makes a 943new handle to some subregion of an already-mapped region of bus space. 944The subregion described by the new handle starts at byte offset 945.Fa offset 946into the region described by 947.Fa handle , 948with the size give by 949.Fa size , 950and must be wholly contained within the original region. 951.Pp 952If successful, 953.Fn bus_space_subregion 954returns zero and fills in the bus 955space handle pointed to by 956.Fa nhandlep . 957If unsuccessful, it returns non-zero and leaves the bus space handle 958pointed to by 959.Fa nhandlep 960in an 961undefined state. 962In either case, the handle described by 963.Fa handle 964remains valid and is unmodified. 965.Pp 966When done with a handle created by 967.Fn bus_space_subregion , 968the handle should 969be thrown away. 970Under no circumstances should 971.Fn bus_space_unmap 972be used on the handle. 973Doing so may confuse any resource management 974being done on the space, and will result in undefined behaviour. 975When 976.Fn bus_space_unmap 977or 978.Fn bus_space_free 979is called on a handle, all subregions of that handle become invalid. 980.Sh ALLOCATING AND FREEING BUS SPACE 981This section is specific to the 982.Nx 983version of these functions and may or may not apply to the 984.Fx 985version. 986.Pp 987Some devices require or allow bus space to be allocated by the operating 988system for device use. 989When the devices no longer need the space, the 990operating system should free it for use by other devices. 991The 992.Fn bus_space_alloc 993and 994.Fn bus_space_free 995functions provide these capabilities. 996.Ss Fn bus_space_alloc space reg_start reg_end size alignment boundary \ 997flags addrp handlep 998The 999.Fn bus_space_alloc 1000function allocates and maps a region of bus space with the size given by 1001.Fa size , 1002corresponding to the given constraints. 1003If successful, it returns 1004zero, fills in the bus address pointed to by 1005.Fa addrp 1006with the bus space address of the allocated region, and fills in 1007the bus space handle pointed to by 1008.Fa handlep 1009with the handle that can be used to access that region. 1010If unsuccessful, it returns non-zero and leaves the bus address pointed to by 1011.Fa addrp 1012and the bus space handle pointed to by 1013.Fa handlep 1014in an undefined state. 1015.Pp 1016Constraints on the allocation are given by the 1017.Fa reg_start , reg_end , alignment , 1018and 1019.Fa boundary 1020parameters. 1021The allocated region will start at or after 1022.Fa reg_start 1023and end before or at 1024.Fa reg_end . 1025The 1026.Fa alignment 1027constraint must be a power of two, and the allocated region will start at 1028an address that is an even multiple of that power of two. 1029The 1030.Fa boundary 1031constraint, if non-zero, ensures that the region is allocated so that 1032.Fa "first address in region" 1033/ 1034.Fa boundary 1035has the same value as 1036.Fa "last address in region" 1037/ 1038.Fa boundary . 1039If the constraints cannot be met, 1040.Fn bus_space_alloc 1041will fail. 1042It is an error to specify a set of 1043constraints that can never be met 1044(for example, 1045.Fa size 1046greater than 1047.Fa boundary ) . 1048.Pp 1049The 1050.Fa flags 1051parameter is the same as the like-named parameter to 1052.Fn bus_space_map , 1053the same flag values should be used, and they have the 1054same meanings. 1055.Pp 1056Handles created by 1057.Fn bus_space_alloc 1058should only be freed with 1059.Fn bus_space_free . 1060Trying to use 1061.Fn bus_space_unmap 1062on them causes undefined behaviour. 1063The 1064.Fn bus_space_subregion 1065function can be used on 1066handles created by 1067.Fn bus_space_alloc . 1068.Ss Fn bus_space_free space handle size 1069The 1070.Fn bus_space_free 1071function unmaps and frees a region of bus space mapped 1072and allocated with 1073.Fn bus_space_alloc . 1074When unmapping a region, the 1075.Fa size 1076specified should be the same as the size given to 1077.Fn bus_space_alloc 1078when allocating the region. 1079.Pp 1080After 1081.Fn bus_space_free 1082is called on a handle, that handle is no longer valid. 1083(If copies were 1084made of the handle, they are no longer valid, either.) 1085.Pp 1086This function will never fail. 1087If it would fail (e.g.\& because of an 1088argument error), that indicates a software bug which should cause a 1089panic. 1090In that case, 1091.Fn bus_space_free 1092will never return. 1093.Sh READING AND WRITING SINGLE DATA ITEMS 1094The simplest way to access bus space is to read or write a single data 1095item. 1096The 1097.Fn bus_space_read_N 1098and 1099.Fn bus_space_write_N 1100families of functions provide 1101the ability to read and write 1, 2, 4, and 8 byte data items on buses 1102which support those access sizes. 1103.Ss Fn bus_space_read_1 space handle offset 1104.Ss Fn bus_space_read_2 space handle offset 1105.Ss Fn bus_space_read_4 space handle offset 1106.Ss Fn bus_space_read_8 space handle offset 1107The 1108.Fn bus_space_read_N 1109family of functions reads a 1, 2, 4, or 8 byte data item from 1110the offset specified by 1111.Fa offset 1112into the region specified by 1113.Fa handle 1114of the bus space specified by 1115.Fa space . 1116The location being read must lie within the bus space region specified by 1117.Fa handle . 1118.Pp 1119For portability, the starting address of the region specified by 1120.Fa handle 1121plus the offset should be a multiple of the size of data item being read. 1122On some systems, not obeying this requirement may cause incorrect data to 1123be read, on others it may cause a system crash. 1124.Pp 1125Read operations done by the 1126.Fn bus_space_read_N 1127functions may be executed out 1128of order with respect to other pending read and write operations unless 1129order is enforced by use of the 1130.Fn bus_space_barrier 1131function. 1132.Pp 1133These functions will never fail. 1134If they would fail (e.g.\& because of an 1135argument error), that indicates a software bug which should cause a 1136panic. 1137In that case, they will never return. 1138.Ss Fn bus_space_write_1 space handle offset value 1139.Ss Fn bus_space_write_2 space handle offset value 1140.Ss Fn bus_space_write_4 space handle offset value 1141.Ss Fn bus_space_write_8 space handle offset value 1142The 1143.Fn bus_space_write_N 1144family of functions writes a 1, 2, 4, or 8 byte data item to the offset 1145specified by 1146.Fa offset 1147into the region specified by 1148.Fa handle 1149of the bus space specified by 1150.Fa space . 1151The location being written must lie within 1152the bus space region specified by 1153.Fa handle . 1154.Pp 1155For portability, the starting address of the region specified by 1156.Fa handle 1157plus the offset should be a multiple of the size of data item being 1158written. 1159On some systems, not obeying this requirement may cause 1160incorrect data to be written, on others it may cause a system crash. 1161.Pp 1162Write operations done by the 1163.Fn bus_space_write_N 1164functions may be executed 1165out of order with respect to other pending read and write operations 1166unless order is enforced by use of the 1167.Fn bus_space_barrier 1168function. 1169.Pp 1170These functions will never fail. 1171If they would fail (e.g.\& because of an 1172argument error), that indicates a software bug which should cause a 1173panic. 1174In that case, they will never return. 1175.Sh PROBING BUS SPACE FOR HARDWARE WHICH MAY NOT RESPOND 1176One problem with the 1177.Fn bus_space_read_N 1178and 1179.Fn bus_space_write_N 1180family of functions is that they provide no protection against 1181exceptions which can occur when no physical hardware or 1182device responds to the read or write cycles. 1183In such a situation, the system typically would panic due to a kernel-mode 1184bus error. 1185The 1186.Fn bus_space_peek_N 1187and 1188.Fn bus_space_poke_N 1189family of functions provide a mechanism to handle these exceptions 1190gracefully without the risk of crashing the system. 1191.Pp 1192As with 1193.Fn bus_space_read_N 1194and 1195.Fn bus_space_write_N , 1196the peek and poke functions provide the ability to read and 1197write 1, 2, 4, and 8 byte data items on busses which support those 1198access sizes. 1199All of the constraints specified in the descriptions of the 1200.Fn bus_space_read_N 1201and 1202.Fn bus_space_write_N 1203functions also apply to 1204.Fn bus_space_peek_N 1205and 1206.Fn bus_space_poke_N . 1207.Pp 1208In addition, explicit calls to the 1209.Fn bus_space_barrier 1210function are not required as the implementation will ensure all 1211pending operations complete before the peek or poke operation starts. 1212The implementation will also ensure that the peek or poke operations 1213complete before returning. 1214.Pp 1215The return value indicates the outcome of the peek or poke operation. 1216A return value of zero implies that a hardware device is 1217responding to the operation at the specified offset in the bus space. 1218A non-zero return value indicates that the kernel intercepted a 1219hardware exception (e.g., bus error) when the peek or poke operation 1220was attempted. 1221Note that some busses are incapable of generating exceptions when 1222non-existent hardware is accessed. 1223In such cases, these functions will always return zero and the value of 1224the data read by 1225.Fn bus_space_peek_N 1226will be unspecified. 1227.Pp 1228Finally, it should be noted that at this time the 1229.Fn bus_space_peek_N 1230and 1231.Fn bus_space_poke_N 1232functions are not re-entrant and should not, therefore, be used 1233from within an interrupt service routine. 1234This constraint may be removed at some point in the future. 1235.Pp 1236.Bl -ohang -compact 1237.It Fn bus_space_peek_1 "space" "handle" "offset" "datap" 1238.It Fn bus_space_peek_2 "space" "handle" "offset" "datap" 1239.It Fn bus_space_peek_4 "space" "handle" "offset" "datap" 1240.It Fn bus_space_peek_8 "space" "handle" "offset" "datap" 1241.Pp 1242The 1243.Fn bus_space_peek_N 1244family of functions cautiously read a 1, 2, 4, or 8 byte data item from 1245the offset specified by 1246.Fa offset 1247in the region specified by 1248.Fa handle 1249of the bus space specified by 1250.Fa space . 1251The data item read is stored in the location pointed to by 1252.Fa datap . 1253It is permissible for 1254.Fa datap 1255to be NULL, in which case the data item will be discarded after being read. 1256.Pp 1257.It Fn bus_space_poke_1 "space" "handle" "offset" "value" 1258.It Fn bus_space_poke_2 "space" "handle" "offset" "value" 1259.It Fn bus_space_poke_4 "space" "handle" "offset" "value" 1260.It Fn bus_space_poke_8 "space" "handle" "offset" "value" 1261.Pp 1262The 1263.Fn bus_space_poke_N 1264family of functions cautiously write a 1, 2, 4, or 8 byte data item 1265specified by 1266.Fa value 1267to the offset specified by 1268.Fa offset 1269in the region specified by 1270.Fa handle 1271of the bus space specified by 1272.Fa space . 1273.El 1274.Sh BARRIERS 1275In order to allow high-performance buffering implementations to avoid bus 1276activity on every operation, read and write ordering should be specified 1277explicitly by drivers when necessary. 1278The 1279.Fn bus_space_barrier 1280function provides that ability. 1281.Ss Fn bus_space_barrier space handle offset length flags 1282The 1283.Fn bus_space_barrier 1284function enforces ordering of bus space read and write operations 1285for the specified subregion (described by the 1286.Fa offset 1287and 1288.Fa length 1289parameters) of the region named by 1290.Fa handle 1291in the space named by 1292.Fa space . 1293.Pp 1294The 1295.Fa flags 1296argument controls what types of operations are to be ordered. 1297Supported flags are: 1298.Bl -tag -width ".Dv BUS_SPACE_BARRIER_WRITE" 1299.It Dv BUS_SPACE_BARRIER_READ 1300Synchronize read operations. 1301.It Dv BUS_SPACE_BARRIER_WRITE 1302Synchronize write operations. 1303.El 1304.Pp 1305Those flags can be combined (or-ed together) to enforce ordering on both 1306read and write operations. 1307.Pp 1308All of the specified type(s) of operation which are done to the region 1309before the barrier operation are guaranteed to complete before any of the 1310specified type(s) of operation done after the barrier. 1311.Pp 1312Example: Consider a hypothetical device with two single-byte ports, one 1313write-only input port (at offset 0) and a read-only output port (at 1314offset 1). 1315Operation of the device is as follows: data bytes are written 1316to the input port, and are placed by the device on a stack, the top of 1317which is read by reading from the output port. 1318The sequence to correctly 1319write two data bytes to the device then read those two data bytes back 1320would be: 1321.Bd -literal 1322/* 1323 * t and h are the tag and handle for the mapped device's 1324 * space. 1325 */ 1326bus_space_write_1(t, h, 0, data0); 1327bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE); /* 1 */ 1328bus_space_write_1(t, h, 0, data1); 1329bus_space_barrier(t, h, 0, 2, 1330 BUS_SPACE_BARRIER_READ|BUS_SPACE_BARRIER_WRITE); /* 2 */ 1331ndata1 = bus_space_read_1(t, h, 1); 1332bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ); /* 3 */ 1333ndata0 = bus_space_read_1(t, h, 1); 1334/* data0 == ndata0, data1 == ndata1 */ 1335.Ed 1336.Pp 1337The first barrier makes sure that the first write finishes before the 1338second write is issued, so that two writes to the input port are done 1339in order and are not collapsed into a single write. 1340This ensures that 1341the data bytes are written to the device correctly and in order. 1342.Pp 1343The second barrier makes sure that the writes to the output port finish 1344before any of the reads to the input port are issued, thereby making sure 1345that all of the writes are finished before data is read. 1346This ensures 1347that the first byte read from the device really is the last one that was 1348written. 1349.Pp 1350The third barrier makes sure that the first read finishes before the 1351second read is issued, ensuring that data is read correctly and in order. 1352.Pp 1353The barriers in the example above are specified to cover the absolute 1354minimum number of bus space locations. 1355It is correct (and often 1356easier) to make barrier operations cover the device's whole range of bus 1357space, that is, to specify an offset of zero and the size of the 1358whole region. 1359.Sh REGION OPERATIONS 1360Some devices use buffers which are mapped as regions in bus space. 1361Often, drivers want to copy the contents of those buffers to or from 1362memory, e.g.\& into mbufs which can be passed to higher levels of the 1363system or from mbufs to be output to a network. 1364In order to allow 1365drivers to do this as efficiently as possible, the 1366.Fn bus_space_read_region_N 1367and 1368.Fn bus_space_write_region_N 1369families of functions are provided. 1370.Pp 1371Drivers occasionally need to copy one region of a bus space to another, 1372or to set all locations in a region of bus space to contain a single 1373value. 1374The 1375.Fn bus_space_copy_region_N 1376family of functions and the 1377.Fn bus_space_set_region_N 1378family of functions allow drivers to perform these operations. 1379.Ss Fn bus_space_read_region_1 space handle offset datap count 1380.Ss Fn bus_space_read_region_2 space handle offset datap count 1381.Ss Fn bus_space_read_region_4 space handle offset datap count 1382.Ss Fn bus_space_read_region_8 space handle offset datap count 1383The 1384.Fn bus_space_read_region_N 1385family of functions reads 1386.Fa count 13871, 2, 4, or 8 byte data items from bus space 1388starting at byte offset 1389.Fa offset 1390in the region specified by 1391.Fa handle 1392of the bus space specified by 1393.Fa space 1394and writes them into the array specified by 1395.Fa datap . 1396Each successive data item is read from an offset 13971, 2, 4, or 8 bytes after the previous data item (depending on which 1398function is used). 1399All locations being read must lie within the bus 1400space region specified by 1401.Fa handle . 1402.Pp 1403For portability, the starting address of the region specified by 1404.Fa handle 1405plus the offset should be a multiple of the size of data items being 1406read and the data array pointer should be properly aligned. 1407On some 1408systems, not obeying these requirements may cause incorrect data to be 1409read, on others it may cause a system crash. 1410.Pp 1411Read operations done by the 1412.Fn bus_space_read_region_N 1413functions may be executed in any order. 1414They may also be executed out 1415of order with respect to other pending read and write operations unless 1416order is enforced by use of the 1417.Fn bus_space_barrier 1418function. 1419There is no way to insert barriers between reads of 1420individual bus space locations executed by the 1421.Fn bus_space_read_region_N 1422functions. 1423.Pp 1424These functions will never fail. 1425If they would fail (e.g.\& because of an 1426argument error), that indicates a software bug which should cause a 1427panic. 1428In that case, they will never return. 1429.Ss Fn bus_space_write_region_1 space handle offset datap count 1430.Ss Fn bus_space_write_region_2 space handle offset datap count 1431.Ss Fn bus_space_write_region_4 space handle offset datap count 1432.Ss Fn bus_space_write_region_8 space handle offset datap count 1433The 1434.Fn bus_space_write_region_N 1435family of functions reads 1436.Fa count 14371, 2, 4, or 8 byte data items from the array 1438specified by 1439.Fa datap 1440and writes them to bus space starting at byte offset 1441.Fa offset 1442in the region specified by 1443.Fa handle 1444of the bus space specified 1445by 1446.Fa space . 1447Each successive data item is written to an offset 1, 2, 4, 1448or 8 bytes after the previous data item (depending on which function is 1449used). 1450All locations being written must lie within the bus space region 1451specified by 1452.Fa handle . 1453.Pp 1454For portability, the starting address of the region specified by 1455.Fa handle 1456plus the offset should be a multiple of the size of data items being 1457written and the data array pointer should be properly aligned. 1458On some 1459systems, not obeying these requirements may cause incorrect data to be 1460written, on others it may cause a system crash. 1461.Pp 1462Write operations done by the 1463.Fn bus_space_write_region_N 1464functions may be 1465executed in any order. 1466They may also be executed out of order with 1467respect to other pending read and write operations unless order is 1468enforced by use of the 1469.Fn bus_space_barrier 1470function. 1471There is no way to insert barriers between writes of 1472individual bus space locations executed by the 1473.Fn bus_space_write_region_N 1474functions. 1475.Pp 1476These functions will never fail. 1477If they would fail (e.g.\& because of an 1478argument error), that indicates a software bug which should cause a 1479panic. 1480In that case, they will never return. 1481.Ss Fn bus_space_copy_region_1 space srchandle srcoffset dsthandle \ 1482dstoffset count 1483.Ss Fn bus_space_copy_region_2 space srchandle srcoffset dsthandle \ 1484dstoffset count 1485.Ss Fn bus_space_copy_region_4 space srchandle srcoffset dsthandle \ 1486dstoffset count 1487.Ss Fn bus_space_copy_region_8 space srchandle srcoffset dsthandle \ 1488dstoffset count 1489The 1490.Fn bus_space_copy_region_N 1491family of functions copies 1492.Fa count 14931, 2, 4, or 8 byte data items in bus space 1494from the area starting at byte offset 1495.Fa srcoffset 1496in the region specified by 1497.Fa srchandle 1498of the bus space specified by 1499.Fa space 1500to the area starting at byte offset 1501.Fa dstoffset 1502in the region specified by 1503.Fa dsthandle 1504in the same bus space. 1505Each successive data item read or written has 1506an offset 1, 2, 4, or 8 bytes after the previous data item (depending 1507on which function is used). 1508All locations being read and written must 1509lie within the bus space region specified by their respective handles. 1510.Pp 1511For portability, the starting addresses of the regions specified by the 1512each handle plus its respective offset should be a multiple of the size 1513of data items being copied. 1514On some systems, not obeying this 1515requirement may cause incorrect data to be copied, on others it may cause 1516a system crash. 1517.Pp 1518Read and write operations done by the 1519.Fn bus_space_copy_region_N 1520functions may be executed in any order. 1521They may also be executed out 1522of order with respect to other pending read and write operations unless 1523order is enforced by use of the 1524.Fn bus_space_barrier 1525function. 1526There is no way to insert barriers between reads or writes of 1527individual bus space locations executed by the 1528.Fn bus_space_copy_region_N 1529functions. 1530.Pp 1531Overlapping copies between different subregions of a single region 1532of bus space are handled correctly by the 1533.Fn bus_space_copy_region_N 1534functions. 1535.Pp 1536These functions will never fail. 1537If they would fail (e.g.\& because of an 1538argument error), that indicates a software bug which should cause a 1539panic. 1540In that case, they will never return. 1541.Ss Fn bus_space_set_region_1 space handle offset value count 1542.Ss Fn bus_space_set_region_2 space handle offset value count 1543.Ss Fn bus_space_set_region_4 space handle offset value count 1544.Ss Fn bus_space_set_region_8 space handle offset value count 1545The 1546.Fn bus_space_set_region_N 1547family of functions writes the given 1548.Fa value 1549to 1550.Fa count 15511, 2, 4, or 8 byte 1552data items in bus space starting at byte offset 1553.Fa offset 1554in the region specified by 1555.Fa handle 1556of the bus space specified by 1557.Fa space . 1558Each successive data item has an offset 1, 2, 4, or 8 bytes after the 1559previous data item (depending on which function is used). 1560All 1561locations being written must lie within the bus space region specified 1562by 1563.Fa handle . 1564.Pp 1565For portability, the starting address of the region specified by 1566.Fa handle 1567plus the offset should be a multiple of the size of data items being 1568written. 1569On some systems, not obeying this requirement may cause 1570incorrect data to be written, on others it may cause a system crash. 1571.Pp 1572Write operations done by the 1573.Fn bus_space_set_region_N 1574functions may be 1575executed in any order. 1576They may also be executed out of order with 1577respect to other pending read and write operations unless order is 1578enforced by use of the 1579.Fn bus_space_barrier 1580function. 1581There is no way to insert barriers between writes of 1582individual bus space locations executed by the 1583.Fn bus_space_set_region_N 1584functions. 1585.Pp 1586These functions will never fail. 1587If they would fail (e.g.\& because of an 1588argument error), that indicates a software bug which should cause a 1589panic. 1590In that case, they will never return. 1591.Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES 1592Some devices implement single locations in bus space which are to be read 1593or written multiple times to communicate data, e.g.\& some ethernet 1594devices' packet buffer FIFOs. 1595In order to allow drivers to manipulate 1596these types of devices as efficiently as possible, the 1597.Fn bus_space_read_multi_N , 1598.Fn bus_space_set_multi_N , 1599and 1600.Fn bus_space_write_multi_N 1601families of functions are provided. 1602.Ss Fn bus_space_read_multi_1 space handle offset datap count 1603.Ss Fn bus_space_read_multi_2 space handle offset datap count 1604.Ss Fn bus_space_read_multi_4 space handle offset datap count 1605.Ss Fn bus_space_read_multi_8 space handle offset datap count 1606The 1607.Fn bus_space_read_multi_N 1608family of functions reads 1609.Fa count 16101, 2, 4, or 8 byte data items from bus space 1611at byte offset 1612.Fa offset 1613in the region specified by 1614.Fa handle 1615of the bus space specified by 1616.Fa space 1617and writes them into the array specified by 1618.Fa datap . 1619Each successive data item is read from the same location in bus 1620space. 1621The location being read must lie within the bus space region 1622specified by 1623.Fa handle . 1624.Pp 1625For portability, the starting address of the region specified by 1626.Fa handle 1627plus the offset should be a multiple of the size of data items being 1628read and the data array pointer should be properly aligned. 1629On some 1630systems, not obeying these requirements may cause incorrect data to be 1631read, on others it may cause a system crash. 1632.Pp 1633Read operations done by the 1634.Fn bus_space_read_multi_N 1635functions may be 1636executed out of order with respect to other pending read and write 1637operations unless order is enforced by use of the 1638.Fn bus_space_barrier 1639function. 1640Because the 1641.Fn bus_space_read_multi_N 1642functions read the same bus space location multiple times, they 1643place an implicit read barrier between each successive read of that bus 1644space location. 1645.Pp 1646These functions will never fail. 1647If they would fail (e.g.\& because of an 1648argument error), that indicates a software bug which should cause a 1649panic. 1650In that case, they will never return. 1651.Ss Fn bus_space_write_multi_1 space handle offset datap count 1652.Ss Fn bus_space_write_multi_2 space handle offset datap count 1653.Ss Fn bus_space_write_multi_4 space handle offset datap count 1654.Ss Fn bus_space_write_multi_8 space handle offset datap count 1655The 1656.Fn bus_space_write_multi_N 1657family of functions reads 1658.Fa count 16591, 2, 4, or 8 byte data items from the array 1660specified by 1661.Fa datap 1662and writes them into bus space at byte offset 1663.Fa offset 1664in the region specified by 1665.Fa handle 1666of the bus space specified by 1667.Fa space . 1668Each successive data item is written to the same location in 1669bus space. 1670The location being written must lie within the bus space 1671region specified by 1672.Fa handle . 1673.Pp 1674For portability, the starting address of the region specified by 1675.Fa handle 1676plus the offset should be a multiple of the size of data items being 1677written and the data array pointer should be properly aligned. 1678On some 1679systems, not obeying these requirements may cause incorrect data to be 1680written, on others it may cause a system crash. 1681.Pp 1682Write operations done by the 1683.Fn bus_space_write_multi_N 1684functions may be executed out of order with respect to other pending 1685read and write operations unless order is enforced by use of the 1686.Fn bus_space_barrier 1687function. 1688Because the 1689.Fn bus_space_write_multi_N 1690functions write the same bus space location multiple times, they 1691place an implicit write barrier between each successive write of that 1692bus space location. 1693.Pp 1694These functions will never fail. 1695If they would fail (e.g.\& because of an 1696argument error), that indicates a software bug which should cause a 1697panic. 1698In that case, they will never return. 1699.Ss Fn bus_space_set_multi_1 space handle offset value count 1700.Ss Fn bus_space_set_multi_2 space handle offset value count 1701.Ss Fn bus_space_set_multi_4 space handle offset value count 1702.Ss Fn bus_space_set_multi_8 space handle offset value count 1703The 1704.Fn bus_space_set_multi_N 1705writes 1706.Fa value 1707into bus space at byte offset 1708.Fa offset 1709in the region specified by 1710.Fa handle 1711of the bus space specified by 1712.Fa space , 1713.Fa count 1714times. 1715The location being written must lie within the bus space 1716region specified by 1717.Fa handle . 1718.Pp 1719For portability, the starting address of the region specified by 1720.Fa handle 1721plus the offset should be a multiple of the size of data items being 1722written and the data array pointer should be properly aligned. 1723On some 1724systems, not obeying these requirements may cause incorrect data to be 1725written, on others it may cause a system crash. 1726.Pp 1727Write operations done by the 1728.Fn bus_space_set_multi_N 1729functions may be executed out of order with respect to other pending 1730read and write operations unless order is enforced by use of the 1731.Fn bus_space_barrier 1732function. 1733Because the 1734.Fn bus_space_set_multi_N 1735functions write the same bus space location multiple times, they 1736place an implicit write barrier between each successive write of that 1737bus space location. 1738.Pp 1739These functions will never fail. 1740If they would fail (e.g.\& because of an 1741argument error), that indicates a software bug which should cause a 1742panic. 1743In that case, they will never return. 1744.Sh STREAM FUNCTIONS 1745Most of the 1746.Nm 1747functions imply a host byte-order and a bus byte-order and take care of 1748any translation for the caller. 1749In some cases, however, hardware may map a FIFO or some other memory region 1750for which the caller may want to use multi-word, yet untranslated access. 1751Access to these types of memory regions should be with the 1752.Fn bus_space_*_stream_N 1753functions. 1754.Pp 1755.Bl -tag -compact -width Fn 1756.It Fn bus_space_read_stream_1 1757.It Fn bus_space_read_stream_2 1758.It Fn bus_space_read_stream_4 1759.It Fn bus_space_read_stream_8 1760.It Fn bus_space_read_multi_stream_1 1761.It Fn bus_space_read_multi_stream_2 1762.It Fn bus_space_read_multi_stream_4 1763.It Fn bus_space_read_multi_stream_8 1764.It Fn bus_space_read_region_stream_1 1765.It Fn bus_space_read_region_stream_2 1766.It Fn bus_space_read_region_stream_4 1767.It Fn bus_space_read_region_stream_8 1768.It Fn bus_space_write_stream_1 1769.It Fn bus_space_write_stream_2 1770.It Fn bus_space_write_stream_4 1771.It Fn bus_space_write_stream_8 1772.It Fn bus_space_write_multi_stream_1 1773.It Fn bus_space_write_multi_stream_2 1774.It Fn bus_space_write_multi_stream_4 1775.It Fn bus_space_write_multi_stream_8 1776.It Fn bus_space_write_region_stream_1 1777.It Fn bus_space_write_region_stream_2 1778.It Fn bus_space_write_region_stream_4 1779.It Fn bus_space_write_region_stream_8 1780.It Fn bus_space_copy_region_stream_1 1781.It Fn bus_space_copy_region_stream_2 1782.It Fn bus_space_copy_region_stream_4 1783.It Fn bus_space_copy_region_stream_8 1784.It Fn bus_space_set_multi_stream_1 1785.It Fn bus_space_set_multi_stream_2 1786.It Fn bus_space_set_multi_stream_4 1787.It Fn bus_space_set_multi_stream_8 1788.It Fn bus_space_set_region_stream_1 1789.It Fn bus_space_set_region_stream_2 1790.It Fn bus_space_set_region_stream_4 1791.It Fn bus_space_set_region_stream_8 1792.El 1793.Pp 1794These functions are defined just as their non-stream counterparts, 1795except that they provide no byte-order translation. 1796.Sh COMPATIBILITY 1797The current 1798.Nx 1799version of the 1800.Nm 1801interface specification differs slightly from the original 1802specification that came into wide use and 1803.Fx 1804adopted. 1805A few of the function names and arguments have changed 1806for consistency and increased functionality. 1807.Sh SEE ALSO 1808.Xr bus_dma 9 1809.Sh HISTORY 1810The 1811.Nm 1812functions were introduced in a different form (memory and I/O spaces 1813were accessed via different sets of functions) in 1814.Nx 1.2 . 1815The functions were merged to work on generic 1816.Dq spaces 1817early in the 1818.Nx 1.3 1819development cycle, and many drivers were converted to use them. 1820This document was written later during the 1821.Nx 1.3 1822development cycle, and the specification was updated to fix some 1823consistency problems and to add some missing functionality. 1824.Pp 1825The manual page was then adapted to the version of the interface that 1826.Fx 1827imported for the CAM SCSI drivers, plus subsequent evolution. 1828The 1829.Fx 1830.Nm 1831version was imported in 1832.Fx 3.0 . 1833.Sh AUTHORS 1834.An -nosplit 1835The 1836.Nm 1837interfaces were designed and implemented by the 1838.Nx 1839developer 1840community. 1841Primary contributors and implementors were 1842.An Chris Demetriou , 1843.An Jason Thorpe , 1844and 1845.An Charles Hannum , 1846but the rest of the 1847.Nx 1848developers and the user community played a significant role in development. 1849.Pp 1850.An Justin Gibbs 1851ported these interfaces to 1852.Fx . 1853.Pp 1854.An Chris Demetriou 1855wrote this manual page. 1856.Pp 1857.An Warner Losh 1858modified it for the 1859.Fx 1860implementation. 1861.Sh BUGS 1862This manual may not completely and accurately document the interface, 1863and many parts of the interface are unspecified. 1864