1 .\" $NetBSD: bus_space.9,v 1.9 1999/03/06 22:09:29 mycroft Exp $
3 .\" Copyright (c) 2005 M. Warner Losh <imp@FreeBSD.org>
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
26 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
27 .\" All rights reserved.
29 .\" This code is derived from software contributed to The NetBSD Foundation
30 .\" by Christopher G. Demetriou.
32 .\" Redistribution and use in source and binary forms, with or without
33 .\" modification, are permitted provided that the following conditions
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.
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.
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 ,
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"
150 .Fa "bus_space_tag_t space" "bus_addr_t address"
151 .Fa "bus_size_t size" "int flags" "bus_space_handle_t *handlep"
155 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size"
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"
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"
170 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size"
174 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
179 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
184 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
189 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
194 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
199 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
204 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
209 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
214 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
218 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
222 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
226 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
229 .Fo bus_space_read_stream_1
230 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
233 .Fo bus_space_read_stream_2
234 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
237 .Fo bus_space_read_stream_4
238 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
241 .Fo bus_space_read_stream_8
242 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
628 functions exist to allow device drivers
629 machine-independent access to bus memory and register areas.
631 functions and types described in this document can be used by including
636 Many common devices are used on multiple architectures, but are accessed
637 differently on each because of architectural constraints.
638 For instance, a device which is mapped in one system's I/O space may be
639 mapped in memory space on a second system.
640 On a third system, architectural
641 limitations might change the way registers need to be accessed (e.g.\&
642 creating a non-linear register space).
643 In some cases, a single
644 driver may need to access the same type of device in multiple ways in a
645 single system or architecture.
648 functions is to allow a single driver source file to manipulate a set
649 of devices on different system architectures, and to allow a single driver
650 object file to manipulate a set of devices on multiple bus types on a
653 Not all buses have to implement all functions described in this
654 document, though that is encouraged if the operations are logically
655 supported by the bus.
656 Unimplemented functions should cause
657 compile-time errors if possible.
659 All of the interface definitions described in this document are shown as
660 function prototypes and discussed as if they were required to be
662 Implementations are encouraged to implement prototyped
663 (type-checked) versions of these interfaces, but may implement them as
664 macros if appropriate.
665 Machine-dependent types, variables, and functions
666 should be marked clearly in
668 to avoid confusion with the
669 machine-independent types and functions, and, if possible, should be
670 given names which make the machine-dependence clear.
671 .Sh CONCEPTS AND GUIDELINES
672 Bus spaces are described by bus space tags, which can be created only by
673 machine-dependent code.
674 A given machine may have several different types
675 of bus space (e.g.\& memory space and I/O space), and thus may provide
676 multiple different bus space tags.
677 Individual buses or devices on a machine may use more than one bus space
679 For instance, ISA devices are
680 given an ISA memory space tag and an ISA I/O space tag.
682 may have several different tags which represent the same type of
683 space, for instance because of multiple different host bus interface
686 A range in bus space is described by a bus address and a bus size.
688 bus address describes the start of the range in bus space.
690 size describes the size of the range in bytes.
691 Buses which are not byte
692 addressable may require use of bus space ranges with appropriately
693 aligned addresses and properly rounded sizes.
695 Access to regions of bus space is facilitated by use of bus space handles,
696 which are usually created by mapping a specific range of a bus space.
697 Handles may also be created by allocating
698 and mapping a range of bus space, the actual location of which is picked
699 by the implementation within bounds specified by the caller of the
702 All of the bus space access functions require one bus space tag
703 argument, at least one handle argument, and at least one offset argument
705 The bus space tag specifies the space, each handle specifies a region in
706 the space, and each offset specifies the offset into the region of the
707 actual location(s) to be accessed.
708 Offsets are given in bytes, though buses
709 may impose alignment constraints.
710 The offset used to access data
711 relative to a given handle must be such that all of the data being
712 accessed is in the mapped region that the handle describes.
714 access data outside that region is an error.
716 Because some architectures' memory systems use buffering to improve
717 memory and device access performance, there is a mechanism which can be
720 in the bus space read and write stream.
722 are three types of barriers: read, write, and read/write.
724 started to the region before a read barrier must complete before any reads
725 after the read barrier are started.
726 (The analogous requirement is true for
728 Read/write barriers force all reads and writes started
729 before the barrier to complete before any reads or writes after the
731 Correctly-written drivers will include all
732 appropriate barriers, and assume only the read/write ordering imposed by
733 the barrier operations.
735 People trying to write portable drivers with the
738 try to make minimal assumptions about what the system allows.
740 they should expect that the system requires bus space addresses being
741 accessed to be naturally aligned (i.e., base address of handle added to
742 offset is a multiple of the access size), and that the system does
743 alignment checking on pointers (i.e., pointer to objects being read and
744 written must point to properly-aligned data).
746 The descriptions of the
748 functions given below all assume that
749 they are called with proper arguments.
750 If called with invalid arguments
751 or arguments that are out of range (e.g.\& trying to access data outside of
752 the region mapped when a given handle was created), undefined behaviour
754 In that case, they may cause the
755 system to halt, either intentionally (via panic) or unintentionally (by
756 causing a fatal trap of by some other means) or may cause improper
757 operation which is not immediately fatal.
758 Functions which return
760 or which return data read from bus space (i.e., functions which
761 do not obviously return an error code) do not fail.
763 if given invalid arguments, and in that case their behaviour is undefined.
764 Functions which take a count of bytes have undefined results if the specified
768 Several types are defined in
770 to facilitate use of the
772 functions by drivers.
776 type is used to describe bus addresses.
778 unsigned integral type
779 capable of holding the largest bus address usable by the architecture.
781 type is primarily used when mapping and unmapping bus space.
785 type is used to describe sizes of ranges in bus space.
787 unsigned integral type capable of holding the size of the largest bus
788 address range usable on the architecture.
789 This type is used by virtually all
792 functions, describing sizes when mapping regions and
793 offsets into regions when performing space access operations.
794 .Ss Vt bus_space_tag_t
797 type is used to describe a particular bus space on a machine.
799 contents are machine-dependent and should be considered opaque by
800 machine-independent code.
801 This type is used by all
803 functions to name the space on which they are operating.
804 .Ss Vt bus_space_handle_t
806 .Vt bus_space_handle_t
807 type is used to describe a mapping of a range of bus space.
809 contents are machine-dependent and should be considered opaque by
810 machine-independent code.
811 This type is used when performing bus space
813 .Sh MAPPING AND UNMAPPING BUS SPACE
814 This section is specific to the
816 version of these functions and may or may not apply to the
820 Bus space must be mapped before it can be used, and should be
821 unmapped when it is no longer needed.
826 functions provide these capabilities.
828 Some drivers need to be able to pass a subregion of already-mapped bus
829 space to another driver or module within a driver.
831 .Fn bus_space_subregion
832 function allows such subregions to be created.
833 .Ss Fn bus_space_map space address size flags handlep
836 function maps the region of bus space named by the
837 .Fa space , address ,
841 If successful, it returns zero
842 and fills in the bus space handle pointed to by
845 that can be used to access the mapped region.
847 it will return non-zero and leave the bus space handle pointed
850 in an undefined state.
854 argument controls how the space is to be mapped.
855 Supported flags include:
856 .Bl -tag -width ".Dv BUS_SPACE_MAP_CACHEABLE"
857 .It Dv BUS_SPACE_MAP_CACHEABLE
858 Try to map the space so that accesses can be cached and/or
859 prefetched by the system.
860 If this flag is not specified, the
861 implementation should map the space so that it will not be cached or
864 This flag must have a value of 1 on all implementations for backward
866 .It Dv BUS_SPACE_MAP_LINEAR
867 Try to map the space so that its contents can be accessed linearly via
868 normal memory access methods (e.g.\& pointer dereferencing and structure
870 This is useful when software wants to do direct access to a memory
871 device, e.g.\& a frame buffer.
872 If this flag is specified and linear
873 mapping is not possible, the
877 flag is not specified, the system may map the space in whatever way is
879 .It Dv BUS_SPACE_MAP_NONPOSTED
880 Try to map the space using non-posted device memory.
881 This is to support buses and devices where mapping with posted device
882 memory is unsupported or broken.
883 This flag is currently only available on arm64.
886 Not all combinations of flags make sense or are supported with all
889 .Dv BUS_SPACE_MAP_CACHEABLE
890 may be meaningless when
891 used on many systems' I/O port spaces, and on some systems
892 .Dv BUS_SPACE_MAP_LINEAR
894 .Dv BUS_SPACE_MAP_CACHEABLE
896 When the system hardware or firmware provides hints as to how spaces should be
897 mapped (e.g.\& the PCI memory mapping registers'
900 hints should be followed for maximum compatibility.
902 requesting a mapping that cannot be satisfied (e.g.\& requesting a
903 non-cacheable mapping when the system can only provide a cacheable one)
904 will cause the request to fail.
906 Some implementations may keep track of use of bus space for some or all
907 bus spaces and refuse to allow duplicate allocations.
909 for bus spaces which have no notion of slot-specific space addressing,
910 such 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
914 Mapped regions may contain areas for which there is no device on the
916 If space in those areas is accessed, the results are
918 .Ss Fn bus_space_unmap space handle size
921 function unmaps a region of bus space mapped with
923 When unmapping a region, the
926 the same as the size given to
928 when mapping that region.
932 is called on a handle, that handle is no longer
934 (If copies were made of the handle they are no longer valid,
937 This function will never fail.
938 If it would fail (e.g.\& because of an
939 argument error), that indicates a software bug which should cause a
944 .Ss Fn bus_space_subregion space handle offset size nhandlep
946 .Fn bus_space_subregion
947 function is a convenience function which makes a
948 new handle to some subregion of an already-mapped region of bus space.
949 The subregion described by the new handle starts at byte offset
951 into the region described by
953 with the size give by
955 and must be wholly contained within the original region.
958 .Fn bus_space_subregion
959 returns zero and fills in the bus
960 space handle pointed to by
962 If unsuccessful, it returns non-zero and leaves the bus space handle
967 In either case, the handle described by
969 remains valid and is unmodified.
971 When done with a handle created by
972 .Fn bus_space_subregion ,
975 Under no circumstances should
977 be used on the handle.
978 Doing so may confuse any resource management
979 being done on the space, and will result in undefined behaviour.
984 is called on a handle, all subregions of that handle become invalid.
985 .Sh ALLOCATING AND FREEING BUS SPACE
986 This section is specific to the
988 version of these functions and may or may not apply to the
992 Some devices require or allow bus space to be allocated by the operating
993 system for device use.
994 When the devices no longer need the space, the
995 operating system should free it for use by other devices.
1000 functions provide these capabilities.
1001 .Ss Fn bus_space_alloc space reg_start reg_end size alignment boundary \
1005 function allocates and maps a region of bus space with the size given by
1007 corresponding to the given constraints.
1008 If successful, it returns
1009 zero, fills in the bus address pointed to by
1011 with the bus space address of the allocated region, and fills in
1012 the bus space handle pointed to by
1014 with the handle that can be used to access that region.
1015 If unsuccessful, it returns non-zero and leaves the bus address pointed to by
1017 and the bus space handle pointed to by
1019 in an undefined state.
1021 Constraints on the allocation are given by the
1022 .Fa reg_start , reg_end , alignment ,
1026 The allocated region will start at or after
1028 and end before or at
1032 constraint must be a power of two, and the allocated region will start at
1033 an address that is an even multiple of that power of two.
1036 constraint, if non-zero, ensures that the region is allocated so that
1037 .Fa "first address in region"
1040 has the same value as
1041 .Fa "last address in region"
1044 If the constraints cannot be met,
1047 It is an error to specify a set of
1048 constraints that can never be met
1056 parameter is the same as the like-named parameter to
1058 the same flag values should be used, and they have the
1063 should only be freed with
1064 .Fn bus_space_free .
1067 on them causes undefined behaviour.
1069 .Fn bus_space_subregion
1070 function can be used on
1072 .Fn bus_space_alloc .
1073 .Ss Fn bus_space_free space handle size
1076 function unmaps and frees a region of bus space mapped
1078 .Fn bus_space_alloc .
1079 When unmapping a region, the
1081 specified should be the same as the size given to
1083 when allocating the region.
1087 is called on a handle, that handle is no longer valid.
1089 made of the handle, they are no longer valid, either.)
1091 This function will never fail.
1092 If it would fail (e.g.\& because of an
1093 argument error), that indicates a software bug which should cause a
1098 .Sh READING AND WRITING SINGLE DATA ITEMS
1099 The simplest way to access bus space is to read or write a single data
1102 .Fn bus_space_read_N
1104 .Fn bus_space_write_N
1105 families of functions provide
1106 the ability to read and write 1, 2, 4, and 8 byte data items on buses
1107 which 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
1113 .Fn bus_space_read_N
1114 family of functions reads a 1, 2, 4, or 8 byte data item from
1115 the offset specified by
1117 into the region specified by
1119 of the bus space specified by
1121 The location being read must lie within the bus space region specified by
1124 For portability, the starting address of the region specified by
1126 plus the offset should be a multiple of the size of data item being read.
1127 On some systems, not obeying this requirement may cause incorrect data to
1128 be read, on others it may cause a system crash.
1130 Read operations done by the
1131 .Fn bus_space_read_N
1132 functions may be executed out
1133 of order with respect to other pending read and write operations unless
1134 order is enforced by use of the
1135 .Fn bus_space_barrier
1138 These functions will never fail.
1139 If they would fail (e.g.\& because of an
1140 argument error), that indicates a software bug which should cause a
1142 In 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
1148 .Fn bus_space_write_N
1149 family of functions writes a 1, 2, 4, or 8 byte data item to the offset
1152 into the region specified by
1154 of the bus space specified by
1156 The location being written must lie within
1157 the bus space region specified by
1160 For portability, the starting address of the region specified by
1162 plus the offset should be a multiple of the size of data item being
1164 On some systems, not obeying this requirement may cause
1165 incorrect data to be written, on others it may cause a system crash.
1167 Write operations done by the
1168 .Fn bus_space_write_N
1169 functions may be executed
1170 out of order with respect to other pending read and write operations
1171 unless order is enforced by use of the
1172 .Fn bus_space_barrier
1175 These functions will never fail.
1176 If they would fail (e.g.\& because of an
1177 argument error), that indicates a software bug which should cause a
1179 In that case, they will never return.
1180 .Sh PROBING BUS SPACE FOR HARDWARE WHICH MAY NOT RESPOND
1181 One problem with the
1182 .Fn bus_space_read_N
1184 .Fn bus_space_write_N
1185 family of functions is that they provide no protection against
1186 exceptions which can occur when no physical hardware or
1187 device responds to the read or write cycles.
1188 In such a situation, the system typically would panic due to a kernel-mode
1191 .Fn bus_space_peek_N
1193 .Fn bus_space_poke_N
1194 family of functions provide a mechanism to handle these exceptions
1195 gracefully without the risk of crashing the system.
1198 .Fn bus_space_read_N
1200 .Fn bus_space_write_N ,
1201 the peek and poke functions provide the ability to read and
1202 write 1, 2, 4, and 8 byte data items on busses which support those
1204 All of the constraints specified in the descriptions of the
1205 .Fn bus_space_read_N
1207 .Fn bus_space_write_N
1208 functions also apply to
1209 .Fn bus_space_peek_N
1211 .Fn bus_space_poke_N .
1213 In addition, explicit calls to the
1214 .Fn bus_space_barrier
1215 function are not required as the implementation will ensure all
1216 pending operations complete before the peek or poke operation starts.
1217 The implementation will also ensure that the peek or poke operations
1218 complete before returning.
1220 The return value indicates the outcome of the peek or poke operation.
1221 A return value of zero implies that a hardware device is
1222 responding to the operation at the specified offset in the bus space.
1223 A non-zero return value indicates that the kernel intercepted a
1224 hardware exception (e.g., bus error) when the peek or poke operation
1226 Note that some busses are incapable of generating exceptions when
1227 non-existent hardware is accessed.
1228 In such cases, these functions will always return zero and the value of
1230 .Fn bus_space_peek_N
1231 will be unspecified.
1233 Finally, it should be noted that at this time the
1234 .Fn bus_space_peek_N
1236 .Fn bus_space_poke_N
1237 functions are not re-entrant and should not, therefore, be used
1238 from within an interrupt service routine.
1239 This constraint may be removed at some point in the future.
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"
1248 .Fn bus_space_peek_N
1249 family of functions cautiously read a 1, 2, 4, or 8 byte data item from
1250 the offset specified by
1252 in the region specified by
1254 of the bus space specified by
1256 The data item read is stored in the location pointed to by
1258 It is permissible for
1260 to be NULL, in which case the data item will be discarded after being read.
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"
1268 .Fn bus_space_poke_N
1269 family of functions cautiously write a 1, 2, 4, or 8 byte data item
1272 to the offset specified by
1274 in the region specified by
1276 of the bus space specified by
1280 In order to allow high-performance buffering implementations to avoid bus
1281 activity on every operation, read and write ordering should be specified
1282 explicitly by drivers when necessary.
1284 .Fn bus_space_barrier
1285 function provides that ability.
1286 .Ss Fn bus_space_barrier space handle offset length flags
1288 .Fn bus_space_barrier
1289 function enforces ordering of bus space read and write operations
1290 for the specified subregion (described by the
1294 parameters) of the region named by
1296 in the space named by
1301 argument controls what types of operations are to be ordered.
1302 Supported flags are:
1303 .Bl -tag -width ".Dv BUS_SPACE_BARRIER_WRITE"
1304 .It Dv BUS_SPACE_BARRIER_READ
1305 Synchronize read operations.
1306 .It Dv BUS_SPACE_BARRIER_WRITE
1307 Synchronize write operations.
1310 Those flags can be combined (or-ed together) to enforce ordering on both
1311 read and write operations.
1313 All of the specified type(s) of operation which are done to the region
1314 before the barrier operation are guaranteed to complete before any of the
1315 specified type(s) of operation done after the barrier.
1317 Example: Consider a hypothetical device with two single-byte ports, one
1318 write-only input port (at offset 0) and a read-only output port (at
1320 Operation of the device is as follows: data bytes are written
1321 to the input port, and are placed by the device on a stack, the top of
1322 which is read by reading from the output port.
1323 The sequence to correctly
1324 write two data bytes to the device then read those two data bytes back
1328 * t and h are the tag and handle for the mapped device's
1331 bus_space_write_1(t, h, 0, data0);
1332 bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE); /* 1 */
1333 bus_space_write_1(t, h, 0, data1);
1334 bus_space_barrier(t, h, 0, 2,
1335 BUS_SPACE_BARRIER_READ|BUS_SPACE_BARRIER_WRITE); /* 2 */
1336 ndata1 = bus_space_read_1(t, h, 1);
1337 bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ); /* 3 */
1338 ndata0 = bus_space_read_1(t, h, 1);
1339 /* data0 == ndata0, data1 == ndata1 */
1342 The first barrier makes sure that the first write finishes before the
1343 second write is issued, so that two writes to the input port are done
1344 in order and are not collapsed into a single write.
1346 the data bytes are written to the device correctly and in order.
1348 The second barrier makes sure that the writes to the output port finish
1349 before any of the reads to the input port are issued, thereby making sure
1350 that all of the writes are finished before data is read.
1352 that the first byte read from the device really is the last one that was
1355 The third barrier makes sure that the first read finishes before the
1356 second read is issued, ensuring that data is read correctly and in order.
1358 The barriers in the example above are specified to cover the absolute
1359 minimum number of bus space locations.
1360 It is correct (and often
1361 easier) to make barrier operations cover the device's whole range of bus
1362 space, that is, to specify an offset of zero and the size of the
1364 .Sh REGION OPERATIONS
1365 Some devices use buffers which are mapped as regions in bus space.
1366 Often, drivers want to copy the contents of those buffers to or from
1367 memory, e.g.\& into mbufs which can be passed to higher levels of the
1368 system or from mbufs to be output to a network.
1370 drivers to do this as efficiently as possible, the
1371 .Fn bus_space_read_region_N
1373 .Fn bus_space_write_region_N
1374 families of functions are provided.
1376 Drivers occasionally need to copy one region of a bus space to another,
1377 or to set all locations in a region of bus space to contain a single
1380 .Fn bus_space_copy_region_N
1381 family of functions and the
1382 .Fn bus_space_set_region_N
1383 family 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
1389 .Fn bus_space_read_region_N
1390 family of functions reads
1392 1, 2, 4, or 8 byte data items from bus space
1393 starting at byte offset
1395 in the region specified by
1397 of the bus space specified by
1399 and writes them into the array specified by
1401 Each successive data item is read from an offset
1402 1, 2, 4, or 8 bytes after the previous data item (depending on which
1404 All locations being read must lie within the bus
1405 space region specified by
1408 For portability, the starting address of the region specified by
1410 plus the offset should be a multiple of the size of data items being
1411 read and the data array pointer should be properly aligned.
1413 systems, not obeying these requirements may cause incorrect data to be
1414 read, on others it may cause a system crash.
1416 Read operations done by the
1417 .Fn bus_space_read_region_N
1418 functions may be executed in any order.
1419 They may also be executed out
1420 of order with respect to other pending read and write operations unless
1421 order is enforced by use of the
1422 .Fn bus_space_barrier
1424 There is no way to insert barriers between reads of
1425 individual bus space locations executed by the
1426 .Fn bus_space_read_region_N
1429 These functions will never fail.
1430 If they would fail (e.g.\& because of an
1431 argument error), that indicates a software bug which should cause a
1433 In 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
1439 .Fn bus_space_write_region_N
1440 family of functions reads
1442 1, 2, 4, or 8 byte data items from the array
1445 and writes them to bus space starting at byte offset
1447 in the region specified by
1449 of the bus space specified
1452 Each successive data item is written to an offset 1, 2, 4,
1453 or 8 bytes after the previous data item (depending on which function is
1455 All locations being written must lie within the bus space region
1459 For portability, the starting address of the region specified by
1461 plus the offset should be a multiple of the size of data items being
1462 written and the data array pointer should be properly aligned.
1464 systems, not obeying these requirements may cause incorrect data to be
1465 written, on others it may cause a system crash.
1467 Write operations done by the
1468 .Fn bus_space_write_region_N
1470 executed in any order.
1471 They may also be executed out of order with
1472 respect to other pending read and write operations unless order is
1473 enforced by use of the
1474 .Fn bus_space_barrier
1476 There is no way to insert barriers between writes of
1477 individual bus space locations executed by the
1478 .Fn bus_space_write_region_N
1481 These functions will never fail.
1482 If they would fail (e.g.\& because of an
1483 argument error), that indicates a software bug which should cause a
1485 In that case, they will never return.
1486 .Ss Fn bus_space_copy_region_1 space srchandle srcoffset dsthandle \
1488 .Ss Fn bus_space_copy_region_2 space srchandle srcoffset dsthandle \
1490 .Ss Fn bus_space_copy_region_4 space srchandle srcoffset dsthandle \
1492 .Ss Fn bus_space_copy_region_8 space srchandle srcoffset dsthandle \
1495 .Fn bus_space_copy_region_N
1496 family of functions copies
1498 1, 2, 4, or 8 byte data items in bus space
1499 from the area starting at byte offset
1501 in the region specified by
1503 of the bus space specified by
1505 to the area starting at byte offset
1507 in the region specified by
1509 in the same bus space.
1510 Each successive data item read or written has
1511 an offset 1, 2, 4, or 8 bytes after the previous data item (depending
1512 on which function is used).
1513 All locations being read and written must
1514 lie within the bus space region specified by their respective handles.
1516 For portability, the starting addresses of the regions specified by the
1517 each handle plus its respective offset should be a multiple of the size
1518 of data items being copied.
1519 On some systems, not obeying this
1520 requirement may cause incorrect data to be copied, on others it may cause
1523 Read and write operations done by the
1524 .Fn bus_space_copy_region_N
1525 functions may be executed in any order.
1526 They may also be executed out
1527 of order with respect to other pending read and write operations unless
1528 order is enforced by use of the
1529 .Fn bus_space_barrier
1531 There is no way to insert barriers between reads or writes of
1532 individual bus space locations executed by the
1533 .Fn bus_space_copy_region_N
1536 Overlapping copies between different subregions of a single region
1537 of bus space are handled correctly by the
1538 .Fn bus_space_copy_region_N
1541 These functions will never fail.
1542 If they would fail (e.g.\& because of an
1543 argument error), that indicates a software bug which should cause a
1545 In 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
1551 .Fn bus_space_set_region_N
1552 family of functions writes the given
1557 data items in bus space starting at byte offset
1559 in the region specified by
1561 of the bus space specified by
1563 Each successive data item has an offset 1, 2, 4, or 8 bytes after the
1564 previous data item (depending on which function is used).
1566 locations being written must lie within the bus space region specified
1570 For portability, the starting address of the region specified by
1572 plus the offset should be a multiple of the size of data items being
1574 On some systems, not obeying this requirement may cause
1575 incorrect data to be written, on others it may cause a system crash.
1577 Write operations done by the
1578 .Fn bus_space_set_region_N
1580 executed in any order.
1581 They may also be executed out of order with
1582 respect to other pending read and write operations unless order is
1583 enforced by use of the
1584 .Fn bus_space_barrier
1586 There is no way to insert barriers between writes of
1587 individual bus space locations executed by the
1588 .Fn bus_space_set_region_N
1591 These functions will never fail.
1592 If they would fail (e.g.\& because of an
1593 argument error), that indicates a software bug which should cause a
1595 In that case, they will never return.
1596 .Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES
1597 Some devices implement single locations in bus space which are to be read
1598 or written multiple times to communicate data, e.g.\& some ethernet
1599 devices' packet buffer FIFOs.
1600 In order to allow drivers to manipulate
1601 these types of devices as efficiently as possible, the
1602 .Fn bus_space_read_multi_N ,
1603 .Fn bus_space_set_multi_N ,
1605 .Fn bus_space_write_multi_N
1606 families 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
1612 .Fn bus_space_read_multi_N
1613 family of functions reads
1615 1, 2, 4, or 8 byte data items from bus space
1618 in the region specified by
1620 of the bus space specified by
1622 and writes them into the array specified by
1624 Each successive data item is read from the same location in bus
1626 The location being read must lie within the bus space region
1630 For portability, the starting address of the region specified by
1632 plus the offset should be a multiple of the size of data items being
1633 read and the data array pointer should be properly aligned.
1635 systems, not obeying these requirements may cause incorrect data to be
1636 read, on others it may cause a system crash.
1638 Read operations done by the
1639 .Fn bus_space_read_multi_N
1641 executed out of order with respect to other pending read and write
1642 operations unless order is enforced by use of the
1643 .Fn bus_space_barrier
1646 .Fn bus_space_read_multi_N
1647 functions read the same bus space location multiple times, they
1648 place an implicit read barrier between each successive read of that bus
1651 These functions will never fail.
1652 If they would fail (e.g.\& because of an
1653 argument error), that indicates a software bug which should cause a
1655 In 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
1661 .Fn bus_space_write_multi_N
1662 family of functions reads
1664 1, 2, 4, or 8 byte data items from the array
1667 and writes them into bus space at byte offset
1669 in the region specified by
1671 of the bus space specified by
1673 Each successive data item is written to the same location in
1675 The location being written must lie within the bus space
1679 For portability, the starting address of the region specified by
1681 plus the offset should be a multiple of the size of data items being
1682 written and the data array pointer should be properly aligned.
1684 systems, not obeying these requirements may cause incorrect data to be
1685 written, on others it may cause a system crash.
1687 Write operations done by the
1688 .Fn bus_space_write_multi_N
1689 functions may be executed out of order with respect to other pending
1690 read and write operations unless order is enforced by use of the
1691 .Fn bus_space_barrier
1694 .Fn bus_space_write_multi_N
1695 functions write the same bus space location multiple times, they
1696 place an implicit write barrier between each successive write of that
1699 These functions will never fail.
1700 If they would fail (e.g.\& because of an
1701 argument error), that indicates a software bug which should cause a
1703 In 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
1709 .Fn bus_space_set_multi_N
1712 into bus space at byte offset
1714 in the region specified by
1716 of the bus space specified by
1720 The location being written must lie within the bus space
1724 For portability, the starting address of the region specified by
1726 plus the offset should be a multiple of the size of data items being
1727 written and the data array pointer should be properly aligned.
1729 systems, not obeying these requirements may cause incorrect data to be
1730 written, on others it may cause a system crash.
1732 Write operations done by the
1733 .Fn bus_space_set_multi_N
1734 functions may be executed out of order with respect to other pending
1735 read and write operations unless order is enforced by use of the
1736 .Fn bus_space_barrier
1739 .Fn bus_space_set_multi_N
1740 functions write the same bus space location multiple times, they
1741 place an implicit write barrier between each successive write of that
1744 These functions will never fail.
1745 If they would fail (e.g.\& because of an
1746 argument error), that indicates a software bug which should cause a
1748 In that case, they will never return.
1749 .Sh STREAM FUNCTIONS
1752 functions imply a host byte-order and a bus byte-order and take care of
1753 any translation for the caller.
1754 In some cases, however, hardware may map a FIFO or some other memory region
1755 for which the caller may want to use multi-word, yet untranslated access.
1756 Access to these types of memory regions should be with the
1757 .Fn bus_space_*_stream_N
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
1799 These functions are defined just as their non-stream counterparts,
1800 except that they provide no byte-order translation.
1806 interface specification differs slightly from the original
1807 specification that came into wide use and
1810 A few of the function names and arguments have changed
1811 for consistency and increased functionality.
1817 functions were introduced in a different form (memory and I/O spaces
1818 were accessed via different sets of functions) in
1820 The functions were merged to work on generic
1824 development cycle, and many drivers were converted to use them.
1825 This document was written later during the
1827 development cycle, and the specification was updated to fix some
1828 consistency problems and to add some missing functionality.
1830 The manual page was then adapted to the version of the interface that
1832 imported for the CAM SCSI drivers, plus subsequent evolution.
1836 version was imported in
1842 interfaces were designed and implemented by the
1846 Primary contributors and implementors were
1847 .An Chris Demetriou ,
1850 .An Charles Hannum ,
1853 developers and the user community played a significant role in development.
1856 ported these interfaces to
1860 wrote this manual page.
1867 This manual may not completely and accurately document the interface,
1868 and many parts of the interface are unspecified.