1 .\" $NetBSD: bus_space.9,v 1.9 1999/03/06 22:09:29 mycroft Exp $
3 .\" Copyright (c) 2005 M. Warner Losh. All Rights Reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
13 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
14 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
15 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
16 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
17 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
18 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
19 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
20 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
21 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
22 .\" POSSIBILITY OF SUCH DAMAGE.
25 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
26 .\" All rights reserved.
28 .\" This code is derived from software contributed to The NetBSD Foundation
29 .\" by Christopher G. Demetriou.
31 .\" Redistribution and use in source and binary forms, with or without
32 .\" modification, are permitted provided that the following conditions
34 .\" 1. Redistributions of source code must retain the above copyright
35 .\" notice, this list of conditions and the following disclaimer.
36 .\" 2. Redistributions in binary form must reproduce the above copyright
37 .\" notice, this list of conditions and the following disclaimer in the
38 .\" documentation and/or other materials provided with the distribution.
39 .\" 3. All advertising materials mentioning features or use of this software
40 .\" must display the following acknowledgment:
41 .\" This product includes software developed by the NetBSD
42 .\" Foundation, Inc. and its contributors.
43 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
44 .\" contributors may be used to endorse or promote products derived
45 .\" from this software without specific prior written permission.
47 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
48 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
49 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
50 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
51 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
52 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
53 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
54 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
55 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
56 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
57 .\" POSSIBILITY OF SUCH DAMAGE.
66 .Nm bus_space_barrier ,
67 .Nm bus_space_copy_region_1 ,
68 .Nm bus_space_copy_region_2 ,
69 .Nm bus_space_copy_region_4 ,
70 .Nm bus_space_copy_region_8 ,
71 .Nm bus_space_copy_region_stream_1 ,
72 .Nm bus_space_copy_region_stream_2 ,
73 .Nm bus_space_copy_region_stream_4 ,
74 .Nm bus_space_copy_region_stream_8 ,
77 .Nm bus_space_read_1 ,
78 .Nm bus_space_read_2 ,
79 .Nm bus_space_read_4 ,
80 .Nm bus_space_read_8 ,
81 .Nm bus_space_read_multi_1 ,
82 .Nm bus_space_read_multi_2 ,
83 .Nm bus_space_read_multi_4 ,
84 .Nm bus_space_read_multi_8 ,
85 .Nm bus_space_read_multi_stream_1 ,
86 .Nm bus_space_read_multi_stream_2 ,
87 .Nm bus_space_read_multi_stream_4 ,
88 .Nm bus_space_read_multi_stream_8 ,
89 .Nm bus_space_read_region_1 ,
90 .Nm bus_space_read_region_2 ,
91 .Nm bus_space_read_region_4 ,
92 .Nm bus_space_read_region_8 ,
93 .Nm bus_space_read_region_stream_1 ,
94 .Nm bus_space_read_region_stream_2 ,
95 .Nm bus_space_read_region_stream_4 ,
96 .Nm bus_space_read_region_stream_8 ,
97 .Nm bus_space_read_stream_1 ,
98 .Nm bus_space_read_stream_2 ,
99 .Nm bus_space_read_stream_4 ,
100 .Nm bus_space_read_stream_8 ,
101 .Nm bus_space_set_multi_1 ,
102 .Nm bus_space_set_multi_2 ,
103 .Nm bus_space_set_multi_4 ,
104 .Nm bus_space_set_multi_8 ,
105 .Nm bus_space_set_multi_stream_1 ,
106 .Nm bus_space_set_multi_stream_2 ,
107 .Nm bus_space_set_multi_stream_4 ,
108 .Nm bus_space_set_multi_stream_8 ,
109 .Nm bus_space_set_region_1 ,
110 .Nm bus_space_set_region_2 ,
111 .Nm bus_space_set_region_4 ,
112 .Nm bus_space_set_region_8 ,
113 .Nm bus_space_set_region_stream_1 ,
114 .Nm bus_space_set_region_stream_2 ,
115 .Nm bus_space_set_region_stream_4 ,
116 .Nm bus_space_set_region_stream_8 ,
117 .Nm bus_space_subregion ,
118 .Nm bus_space_unmap ,
119 .Nm bus_space_write_1 ,
120 .Nm bus_space_write_2 ,
121 .Nm bus_space_write_4 ,
122 .Nm bus_space_write_8 ,
123 .Nm bus_space_write_multi_1 ,
124 .Nm bus_space_write_multi_2 ,
125 .Nm bus_space_write_multi_4 ,
126 .Nm bus_space_write_multi_8 ,
127 .Nm bus_space_write_multi_stream_1 ,
128 .Nm bus_space_write_multi_stream_2 ,
129 .Nm bus_space_write_multi_stream_4 ,
130 .Nm bus_space_write_multi_stream_8 ,
131 .Nm bus_space_write_region_1 ,
132 .Nm bus_space_write_region_2 ,
133 .Nm bus_space_write_region_4 ,
134 .Nm bus_space_write_region_8 ,
135 .Nm bus_space_write_region_stream_1 ,
136 .Nm bus_space_write_region_stream_2 ,
137 .Nm bus_space_write_region_stream_4 ,
138 .Nm bus_space_write_region_stream_8 ,
139 .Nm bus_space_write_stream_1 ,
140 .Nm bus_space_write_stream_2 ,
141 .Nm bus_space_write_stream_4 ,
142 .Nm bus_space_write_stream_8
143 .Nd "bus space manipulation functions"
148 .Fa "bus_space_tag_t space" "bus_addr_t address"
149 .Fa "bus_size_t size" "int flags" "bus_space_handle_t *handlep"
153 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size"
156 .Fo bus_space_subregion
157 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
158 .Fa "bus_size_t offset" "bus_size_t size" "bus_space_handle_t *nhandlep"
162 .Fa "bus_space_tag_t space" "bus_addr_t reg_start" "bus_addr_t reg_end"
163 .Fa "bus_size_t size" "bus_size_t alignment" "bus_size_t boundary"
164 .Fa "int flags" "bus_addr_t *addrp" "bus_space_handle_t *handlep"
168 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size"
172 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
176 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
180 .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"
187 .Fo bus_space_read_stream_1
188 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
191 .Fo bus_space_read_stream_2
192 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
195 .Fo bus_space_read_stream_4
196 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
199 .Fo bus_space_read_stream_8
200 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
203 .Fo bus_space_write_1
204 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
205 .Fa "bus_size_t offset" "uint8_t value"
208 .Fo bus_space_write_2
209 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
210 .Fa "bus_size_t offset" "uint16_t value"
213 .Fo bus_space_write_4
214 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
215 .Fa "bus_size_t offset" "uint32_t value"
218 .Fo bus_space_write_8
219 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
220 .Fa "bus_size_t offset" "uint64_t value"
223 .Fo bus_space_write_stream_1
224 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
225 .Fa "bus_size_t offset" "uint8_t value"
228 .Fo bus_space_write_stream_2
229 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
230 .Fa "bus_size_t offset" "uint16_t value"
233 .Fo bus_space_write_stream_4
234 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
235 .Fa "bus_size_t offset" "uint32_t value"
238 .Fo bus_space_write_stream_8
239 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
240 .Fa "bus_size_t offset" "uint64_t value"
243 .Fo bus_space_barrier
244 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
245 .Fa "bus_size_t offset" "bus_size_t length" "int flags"
248 .Fo bus_space_read_region_1
249 .Fa "bus_space_tag_t space"
250 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
251 .Fa "bus_size_t count"
254 .Fo bus_space_read_region_2
255 .Fa "bus_space_tag_t space"
256 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
257 .Fa "bus_size_t count"
260 .Fo bus_space_read_region_4
261 .Fa "bus_space_tag_t space"
262 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
263 .Fa "bus_size_t count"
266 .Fo bus_space_read_region_8
267 .Fa "bus_space_tag_t space"
268 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
269 .Fa "bus_size_t count"
272 .Fo bus_space_read_region_stream_1
273 .Fa "bus_space_tag_t space"
274 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
275 .Fa "bus_size_t count"
278 .Fo bus_space_read_region_stream_2
279 .Fa "bus_space_tag_t space"
280 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
281 .Fa "bus_size_t count"
284 .Fo bus_space_read_region_stream_4
285 .Fa "bus_space_tag_t space"
286 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
287 .Fa "bus_size_t count"
290 .Fo bus_space_read_region_stream_8
291 .Fa "bus_space_tag_t space"
292 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
293 .Fa "bus_size_t count"
296 .Fo bus_space_write_region_1
297 .Fa "bus_space_tag_t space"
298 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
299 .Fa "bus_size_t count"
302 .Fo bus_space_write_region_2
303 .Fa "bus_space_tag_t space"
304 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
305 .Fa "bus_size_t count"
308 .Fo bus_space_write_region_4
309 .Fa "bus_space_tag_t space"
310 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
311 .Fa "bus_size_t count"
314 .Fo bus_space_write_region_8
315 .Fa "bus_space_tag_t space"
316 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
317 .Fa "bus_size_t count"
320 .Fo bus_space_write_region_stream_1
321 .Fa "bus_space_tag_t space"
322 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
323 .Fa "bus_size_t count"
326 .Fo bus_space_write_region_stream_2
327 .Fa "bus_space_tag_t space"
328 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
329 .Fa "bus_size_t count"
332 .Fo bus_space_write_region_stream_4
333 .Fa "bus_space_tag_t space"
334 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
335 .Fa "bus_size_t count"
338 .Fo bus_space_write_region_stream_8
339 .Fa "bus_space_tag_t space"
340 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
341 .Fa "bus_size_t count"
344 .Fo bus_space_copy_region_1
345 .Fa "bus_space_tag_t space"
346 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
347 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
350 .Fo bus_space_copy_region_2
351 .Fa "bus_space_tag_t space"
352 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
353 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
356 .Fo bus_space_copy_region_4
357 .Fa "bus_space_tag_t space"
358 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
359 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
362 .Fo bus_space_copy_region_8
363 .Fa "bus_space_tag_t space"
364 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
365 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
368 .Fo bus_space_copy_region_stream_1
369 .Fa "bus_space_tag_t space"
370 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
371 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
374 .Fo bus_space_copy_region_stream_2
375 .Fa "bus_space_tag_t space"
376 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
377 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
380 .Fo bus_space_copy_region_stream_4
381 .Fa "bus_space_tag_t space"
382 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
383 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
386 .Fo bus_space_copy_region_stream_8
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_set_region_1
393 .Fa "bus_space_tag_t space"
394 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
395 .Fa "bus_size_t count"
398 .Fo bus_space_set_region_2
399 .Fa "bus_space_tag_t space"
400 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
401 .Fa "bus_size_t count"
404 .Fo bus_space_set_region_4
405 .Fa "bus_space_tag_t space"
406 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
407 .Fa "bus_size_t count"
410 .Fo bus_space_set_region_8
411 .Fa "bus_space_tag_t space"
412 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
413 .Fa "bus_size_t count"
416 .Fo bus_space_set_region_stream_1
417 .Fa "bus_space_tag_t space"
418 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
419 .Fa "bus_size_t count"
422 .Fo bus_space_set_region_stream_2
423 .Fa "bus_space_tag_t space"
424 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
425 .Fa "bus_size_t count"
428 .Fo bus_space_set_region_stream_4
429 .Fa "bus_space_tag_t space"
430 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
431 .Fa "bus_size_t count"
434 .Fo bus_space_set_region_stream_8
435 .Fa "bus_space_tag_t space"
436 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
437 .Fa "bus_size_t count"
440 .Fo bus_space_read_multi_1
441 .Fa "bus_space_tag_t space"
442 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
443 .Fa "bus_size_t count"
446 .Fo bus_space_read_multi_2
447 .Fa "bus_space_tag_t space"
448 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
449 .Fa "bus_size_t count"
452 .Fo bus_space_read_multi_4
453 .Fa "bus_space_tag_t space"
454 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
455 .Fa "bus_size_t count"
458 .Fo bus_space_read_multi_8
459 .Fa "bus_space_tag_t space"
460 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
461 .Fa "bus_size_t count"
464 .Fo bus_space_read_multi_stream_1
465 .Fa "bus_space_tag_t space"
466 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
467 .Fa "bus_size_t count"
470 .Fo bus_space_read_multi_stream_2
471 .Fa "bus_space_tag_t space"
472 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
473 .Fa "bus_size_t count"
476 .Fo bus_space_read_multi_stream_4
477 .Fa "bus_space_tag_t space"
478 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
479 .Fa "bus_size_t count"
482 .Fo bus_space_read_multi_stream_8
483 .Fa "bus_space_tag_t space"
484 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
485 .Fa "bus_size_t count"
488 .Fo bus_space_write_multi_1
489 .Fa "bus_space_tag_t space"
490 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
491 .Fa "bus_size_t count"
494 .Fo bus_space_write_multi_2
495 .Fa "bus_space_tag_t space"
496 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
497 .Fa "bus_size_t count"
500 .Fo bus_space_write_multi_4
501 .Fa "bus_space_tag_t space"
502 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
503 .Fa "bus_size_t count"
506 .Fo bus_space_write_multi_8
507 .Fa "bus_space_tag_t space"
508 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
509 .Fa "bus_size_t count"
512 .Fo bus_space_write_multi_stream_1
513 .Fa "bus_space_tag_t space"
514 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
515 .Fa "bus_size_t count"
518 .Fo bus_space_write_multi_stream_2
519 .Fa "bus_space_tag_t space"
520 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
521 .Fa "bus_size_t count"
524 .Fo bus_space_write_multi_stream_4
525 .Fa "bus_space_tag_t space"
526 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
527 .Fa "bus_size_t count"
530 .Fo bus_space_write_multi_stream_8
531 .Fa "bus_space_tag_t space"
532 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
533 .Fa "bus_size_t count"
536 .Fo bus_space_set_multi_1
537 .Fa "bus_space_tag_t space"
538 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
539 .Fa "bus_size_t count"
542 .Fo bus_space_set_multi_2
543 .Fa "bus_space_tag_t space"
544 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
545 .Fa "bus_size_t count"
548 .Fo bus_space_set_multi_4
549 .Fa "bus_space_tag_t space"
550 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
551 .Fa "bus_size_t count"
554 .Fo bus_space_set_multi_8
555 .Fa "bus_space_tag_t space"
556 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
557 .Fa "bus_size_t count"
560 .Fo bus_space_set_multi_stream_1
561 .Fa "bus_space_tag_t space"
562 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
563 .Fa "bus_size_t count"
566 .Fo bus_space_set_multi_stream_2
567 .Fa "bus_space_tag_t space"
568 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
569 .Fa "bus_size_t count"
572 .Fo bus_space_set_multi_stream_4
573 .Fa "bus_space_tag_t space"
574 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
575 .Fa "bus_size_t count"
578 .Fo bus_space_set_multi_stream_8
579 .Fa "bus_space_tag_t space"
580 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
581 .Fa "bus_size_t count"
586 functions exist to allow device drivers
587 machine-independent access to bus memory and register areas.
589 functions and types described in this document can be used by including
594 Many common devices are used on multiple architectures, but are accessed
595 differently on each because of architectural constraints.
596 For instance, a device which is mapped in one system's I/O space may be
597 mapped in memory space on a second system.
598 On a third system, architectural
599 limitations might change the way registers need to be accessed (e.g.\&
600 creating a non-linear register space).
601 In some cases, a single
602 driver may need to access the same type of device in multiple ways in a
603 single system or architecture.
606 functions is to allow a single driver source file to manipulate a set
607 of devices on different system architectures, and to allow a single driver
608 object file to manipulate a set of devices on multiple bus types on a
611 Not all busses have to implement all functions described in this
612 document, though that is encouraged if the operations are logically
613 supported by the bus.
614 Unimplemented functions should cause
615 compile-time errors if possible.
617 All of the interface definitions described in this document are shown as
618 function prototypes and discussed as if they were required to be
620 Implementations are encouraged to implement prototyped
621 (type-checked) versions of these interfaces, but may implement them as
622 macros if appropriate.
623 Machine-dependent types, variables, and functions
624 should be marked clearly in
626 to avoid confusion with the
627 machine-independent types and functions, and, if possible, should be
628 given names which make the machine-dependence clear.
629 .Sh CONCEPTS AND GUIDELINES
630 Bus spaces are described by bus space tags, which can be created only by
631 machine-dependent code.
632 A given machine may have several different types
633 of bus space (e.g.\& memory space and I/O space), and thus may provide
634 multiple different bus space tags.
635 Individual busses or devices on a machine may use more than one bus space
637 For instance, ISA devices are
638 given an ISA memory space tag and an ISA I/O space tag.
640 may have several different tags which represent the same type of
641 space, for instance because of multiple different host bus interface
644 A range in bus space is described by a bus address and a bus size.
646 bus address describes the start of the range in bus space.
648 size describes the size of the range in bytes.
649 Busses which are not byte
650 addressable may require use of bus space ranges with appropriately
651 aligned addresses and properly rounded sizes.
653 Access to regions of bus space is facilitated by use of bus space handles,
654 which are usually created by mapping a specific range of a bus space.
655 Handles may also be created by allocating
656 and mapping a range of bus space, the actual location of which is picked
657 by the implementation within bounds specified by the caller of the
660 All of the bus space access functions require one bus space tag
661 argument, at least one handle argument, and at least one offset argument
663 The bus space tag specifies the space, each handle specifies a region in
664 the space, and each offset specifies the offset into the region of the
665 actual location(s) to be accessed.
666 Offsets are given in bytes, though busses
667 may impose alignment constraints.
668 The offset used to access data
669 relative to a given handle must be such that all of the data being
670 accessed is in the mapped region that the handle describes.
672 access data outside that region is an error.
674 Because some architectures' memory systems use buffering to improve
675 memory and device access performance, there is a mechanism which can be
678 in the bus space read and write stream.
680 are three types of barriers: read, write, and read/write.
682 started to the region before a read barrier must complete before any reads
683 after the read barrier are started.
684 (The analogous requirement is true for
686 Read/write barriers force all reads and writes started
687 before the barrier to complete before any reads or writes after the
689 Correctly-written drivers will include all
690 appropriate barriers, and assume only the read/write ordering imposed by
691 the barrier operations.
693 People trying to write portable drivers with the
696 try to make minimal assumptions about what the system allows.
698 they should expect that the system requires bus space addresses being
699 accessed to be naturally aligned (i.e., base address of handle added to
700 offset is a multiple of the access size), and that the system does
701 alignment checking on pointers (i.e., pointer to objects being read and
702 written must point to properly-aligned data).
704 The descriptions of the
706 functions given below all assume that
707 they are called with proper arguments.
708 If called with invalid arguments
709 or arguments that are out of range (e.g.\& trying to access data outside of
710 the region mapped when a given handle was created), undefined behaviour
712 In that case, they may cause the
713 system to halt, either intentionally (via panic) or unintentionally (by
714 causing a fatal trap of by some other means) or may cause improper
715 operation which is not immediately fatal.
716 Functions which return
718 or which return data read from bus space (i.e., functions which
719 do not obviously return an error code) do not fail.
721 if given invalid arguments, and in that case their behaviour is undefined.
722 Functions which take a count of bytes have undefined results if the specified
726 Several types are defined in
728 to facilitate use of the
730 functions by drivers.
734 type is used to describe bus addresses.
736 unsigned integral type
737 capable of holding the largest bus address usable by the architecture.
739 type is primarily used when mapping and unmapping bus space.
743 type is used to describe sizes of ranges in bus space.
745 unsigned integral type capable of holding the size of the largest bus
746 address range usable on the architecture.
747 This type is used by virtually all
750 functions, describing sizes when mapping regions and
751 offsets into regions when performing space access operations.
752 .Ss Vt bus_space_tag_t
755 type is used to describe a particular bus space on a machine.
757 contents are machine-dependent and should be considered opaque by
758 machine-independent code.
759 This type is used by all
761 functions to name the space on which they are operating.
762 .Ss Vt bus_space_handle_t
764 .Vt bus_space_handle_t
765 type is used to describe a mapping of a range of bus space.
767 contents are machine-dependent and should be considered opaque by
768 machine-independent code.
769 This type is used when performing bus space
771 .Sh MAPPING AND UNMAPPING BUS SPACE
772 This section is specific to the
774 version of these functions and may or may not apply to the
778 Bus space must be mapped before it can be used, and should be
779 unmapped when it is no longer needed.
784 functions provide these capabilities.
786 Some drivers need to be able to pass a subregion of already-mapped bus
787 space to another driver or module within a driver.
789 .Fn bus_space_subregion
790 function allows such subregions to be created.
791 .Ss Fn bus_space_map space address size flags handlep
794 function maps the region of bus space named by the
795 .Fa space , address ,
799 If successful, it returns zero
800 and fills in the bus space handle pointed to by
803 that can be used to access the mapped region.
805 it will return non-zero and leave the bus space handle pointed
808 in an undefined state.
812 argument controls how the space is to be mapped.
813 Supported flags include:
814 .Bl -tag -width ".Dv BUS_SPACE_MAP_CACHEABLE"
815 .It Dv BUS_SPACE_MAP_CACHEABLE
816 Try to map the space so that accesses can be cached and/or
817 prefetched by the system.
818 If this flag is not specified, the
819 implementation should map the space so that it will not be cached or
822 This flag must have a value of 1 on all implementations for backward
824 .It Dv BUS_SPACE_MAP_LINEAR
825 Try to map the space so that its contents can be accessed linearly via
826 normal memory access methods (e.g.\& pointer dereferencing and structure
828 This is useful when software wants to do direct access to a memory
829 device, e.g.\& a frame buffer.
830 If this flag is specified and linear
831 mapping is not possible, the
835 flag is not specified, the system may map the space in whatever way is
839 Not all combinations of flags make sense or are supported with all
842 .Dv BUS_SPACE_MAP_CACHEABLE
843 may be meaningless when
844 used on many systems' I/O port spaces, and on some systems
845 .Dv BUS_SPACE_MAP_LINEAR
847 .Dv BUS_SPACE_MAP_CACHEABLE
849 When the system hardware or firmware provides hints as to how spaces should be
850 mapped (e.g.\& the PCI memory mapping registers'
853 hints should be followed for maximum compatibility.
855 requesting a mapping that cannot be satisfied (e.g.\& requesting a
856 non-cacheable mapping when the system can only provide a cacheable one)
857 will cause the request to fail.
859 Some implementations may keep track of use of bus space for some or all
860 bus spaces and refuse to allow duplicate allocations.
862 for bus spaces which have no notion of slot-specific space addressing,
863 such as ISA and VME, and for spaces which coexist with those spaces
864 (e.g.\& EISA and PCI memory and I/O spaces co-existing with ISA memory and
867 Mapped regions may contain areas for which there is no device on the
869 If space in those areas is accessed, the results are
871 .Ss Fn bus_space_unmap space handle size
874 function unmaps a region of bus space mapped with
876 When unmapping a region, the
879 the same as the size given to
881 when mapping that region.
885 is called on a handle, that handle is no longer
887 (If copies were made of the handle they are no longer valid,
890 This function will never fail.
891 If it would fail (e.g.\& because of an
892 argument error), that indicates a software bug which should cause a
897 .Ss Fn bus_space_subregion space handle offset size nhandlep
899 .Fn bus_space_subregion
900 function is a convenience function which makes a
901 new handle to some subregion of an already-mapped region of bus space.
902 The subregion described by the new handle starts at byte offset
904 into the region described by
906 with the size give by
908 and must be wholly contained within the original region.
911 .Fn bus_space_subregion
912 returns zero and fills in the bus
913 space handle pointed to by
915 If unsuccessful, it returns non-zero and leaves the bus space handle
920 In either case, the handle described by
922 remains valid and is unmodified.
924 When done with a handle created by
925 .Fn bus_space_subregion ,
928 Under no circumstances should
930 be used on the handle.
931 Doing so may confuse any resource management
932 being done on the space, and will result in undefined behaviour.
937 is called on a handle, all subregions of that handle become invalid.
938 .Sh ALLOCATING AND FREEING BUS SPACE
939 This section is specific to the
941 version of these functions and may or may not apply to the
945 Some devices require or allow bus space to be allocated by the operating
946 system for device use.
947 When the devices no longer need the space, the
948 operating system should free it for use by other devices.
953 functions provide these capabilities.
954 .Ss Fn bus_space_alloc space reg_start reg_end size alignment boundary \
958 function allocates and maps a region of bus space with the size given by
960 corresponding to the given constraints.
961 If successful, it returns
962 zero, fills in the bus address pointed to by
964 with the bus space address of the allocated region, and fills in
965 the bus space handle pointed to by
967 with the handle that can be used to access that region.
968 If unsuccessful, it returns non-zero and leaves the bus address pointed to by
970 and the bus space handle pointed to by
972 in an undefined state.
974 Constraints on the allocation are given by the
975 .Fa reg_start , reg_end , alignment ,
979 The allocated region will start at or after
985 constraint must be a power of two, and the allocated region will start at
986 an address that is an even multiple of that power of two.
989 constraint, if non-zero, ensures that the region is allocated so that
990 .Fa "first address in region"
993 has the same value as
994 .Fa "last address in region"
997 If the constraints cannot be met,
1000 It is an error to specify a set of
1001 constraints that can never be met
1009 parameter is the same as the like-named parameter to
1011 the same flag values should be used, and they have the
1016 should only be freed with
1017 .Fn bus_space_free .
1020 on them causes undefined behaviour.
1022 .Fn bus_space_subregion
1023 function can be used on
1025 .Fn bus_space_alloc .
1026 .Ss Fn bus_space_free space handle size
1029 function unmaps and frees a region of bus space mapped
1031 .Fn bus_space_alloc .
1032 When unmapping a region, the
1034 specified should be the same as the size given to
1036 when allocating the region.
1040 is called on a handle, that handle is no longer valid.
1042 made of the handle, they are no longer valid, either.)
1044 This function will never fail.
1045 If it would fail (e.g.\& because of an
1046 argument error), that indicates a software bug which should cause a
1051 .Sh READING AND WRITING SINGLE DATA ITEMS
1052 The simplest way to access bus space is to read or write a single data
1055 .Fn bus_space_read_N
1057 .Fn bus_space_write_N
1058 families of functions provide
1059 the ability to read and write 1, 2, 4, and 8 byte data items on busses
1060 which support those access sizes.
1061 .Ss Fn bus_space_read_1 space handle offset
1062 .Ss Fn bus_space_read_2 space handle offset
1063 .Ss Fn bus_space_read_4 space handle offset
1064 .Ss Fn bus_space_read_8 space handle offset
1066 .Fn bus_space_read_N
1067 family of functions reads a 1, 2, 4, or 8 byte data item from
1068 the offset specified by
1070 into the region specified by
1072 of the bus space specified by
1074 The location being read must lie within the bus space region specified by
1077 For portability, the starting address of the region specified by
1079 plus the offset should be a multiple of the size of data item being read.
1080 On some systems, not obeying this requirement may cause incorrect data to
1081 be read, on others it may cause a system crash.
1083 Read operations done by the
1084 .Fn bus_space_read_N
1085 functions may be executed out
1086 of order with respect to other pending read and write operations unless
1087 order is enforced by use of the
1088 .Fn bus_space_barrier
1091 These functions will never fail.
1092 If they would fail (e.g.\& because of an
1093 argument error), that indicates a software bug which should cause a
1095 In that case, they will never return.
1096 .Ss Fn bus_space_write_1 space handle offset value
1097 .Ss Fn bus_space_write_2 space handle offset value
1098 .Ss Fn bus_space_write_4 space handle offset value
1099 .Ss Fn bus_space_write_8 space handle offset value
1101 .Fn bus_space_write_N
1102 family of functions writes a 1, 2, 4, or 8 byte data item to the offset
1105 into the region specified by
1107 of the bus space specified by
1109 The location being written must lie within
1110 the bus space region specified by
1113 For portability, the starting address of the region specified by
1115 plus the offset should be a multiple of the size of data item being
1117 On some systems, not obeying this requirement may cause
1118 incorrect data to be written, on others it may cause a system crash.
1120 Write operations done by the
1121 .Fn bus_space_write_N
1122 functions may be executed
1123 out of order with respect to other pending read and write operations
1124 unless order is enforced by use of the
1125 .Fn bus_space_barrier
1128 These functions will never fail.
1129 If they would fail (e.g.\& because of an
1130 argument error), that indicates a software bug which should cause a
1132 In that case, they will never return.
1134 In order to allow high-performance buffering implementations to avoid bus
1135 activity on every operation, read and write ordering should be specified
1136 explicitly by drivers when necessary.
1138 .Fn bus_space_barrier
1139 function provides that ability.
1140 .Ss Fn bus_space_barrier space handle offset length flags
1142 .Fn bus_space_barrier
1143 function enforces ordering of bus space read and write operations
1144 for the specified subregion (described by the
1148 parameters) of the region named by
1150 in the space named by
1155 argument controls what types of operations are to be ordered.
1156 Supported flags are:
1157 .Bl -tag -width ".Dv BUS_SPACE_BARRIER_WRITE"
1158 .It Dv BUS_SPACE_BARRIER_READ
1159 Synchronize read operations.
1160 .It Dv BUS_SPACE_BARRIER_WRITE
1161 Synchronize write operations.
1164 Those flags can be combined (or-ed together) to enforce ordering on both
1165 read and write operations.
1167 All of the specified type(s) of operation which are done to the region
1168 before the barrier operation are guaranteed to complete before any of the
1169 specified type(s) of operation done after the barrier.
1171 Example: Consider a hypothetical device with two single-byte ports, one
1172 write-only input port (at offset 0) and a read-only output port (at
1174 Operation of the device is as follows: data bytes are written
1175 to the input port, and are placed by the device on a stack, the top of
1176 which is read by reading from the output port.
1177 The sequence to correctly
1178 write two data bytes to the device then read those two data bytes back
1182 * t and h are the tag and handle for the mapped device's
1185 bus_space_write_1(t, h, 0, data0);
1186 bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE); /* 1 */
1187 bus_space_write_1(t, h, 0, data1);
1188 bus_space_barrier(t, h, 0, 2,
1189 BUS_SPACE_BARRIER_READ|BUS_SPACE_BARRIER_WRITE); /* 2 */
1190 ndata1 = bus_space_read_1(t, h, 1);
1191 bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ); /* 3 */
1192 ndata0 = bus_space_read_1(t, h, 1);
1193 /* data0 == ndata0, data1 == ndata1 */
1196 The first barrier makes sure that the first write finishes before the
1197 second write is issued, so that two writes to the input port are done
1198 in order and are not collapsed into a single write.
1200 the data bytes are written to the device correctly and in order.
1202 The second barrier makes sure that the writes to the output port finish
1203 before any of the reads to the input port are issued, thereby making sure
1204 that all of the writes are finished before data is read.
1206 that the first byte read from the device really is the last one that was
1209 The third barrier makes sure that the first read finishes before the
1210 second read is issued, ensuring that data is read correctly and in order.
1212 The barriers in the example above are specified to cover the absolute
1213 minimum number of bus space locations.
1214 It is correct (and often
1215 easier) to make barrier operations cover the device's whole range of bus
1216 space, that is, to specify an offset of zero and the size of the
1218 .Sh REGION OPERATIONS
1219 Some devices use buffers which are mapped as regions in bus space.
1220 Often, drivers want to copy the contents of those buffers to or from
1221 memory, e.g.\& into mbufs which can be passed to higher levels of the
1222 system or from mbufs to be output to a network.
1224 drivers to do this as efficiently as possible, the
1225 .Fn bus_space_read_region_N
1227 .Fn bus_space_write_region_N
1228 families of functions are provided.
1230 Drivers occasionally need to copy one region of a bus space to another,
1231 or to set all locations in a region of bus space to contain a single
1234 .Fn bus_space_copy_region_N
1235 family of functions and the
1236 .Fn bus_space_set_region_N
1237 family of functions allow drivers to perform these operations.
1238 .Ss Fn bus_space_read_region_1 space handle offset datap count
1239 .Ss Fn bus_space_read_region_2 space handle offset datap count
1240 .Ss Fn bus_space_read_region_4 space handle offset datap count
1241 .Ss Fn bus_space_read_region_8 space handle offset datap count
1243 .Fn bus_space_read_region_N
1244 family of functions reads
1246 1, 2, 4, or 8 byte data items from bus space
1247 starting at byte offset
1249 in the region specified by
1251 of the bus space specified by
1253 and writes them into the array specified by
1255 Each successive data item is read from an offset
1256 1, 2, 4, or 8 bytes after the previous data item (depending on which
1258 All locations being read must lie within the bus
1259 space region specified by
1262 For portability, the starting address of the region specified by
1264 plus the offset should be a multiple of the size of data items being
1265 read and the data array pointer should be properly aligned.
1267 systems, not obeying these requirements may cause incorrect data to be
1268 read, on others it may cause a system crash.
1270 Read operations done by the
1271 .Fn bus_space_read_region_N
1272 functions may be executed in any order.
1273 They may also be executed out
1274 of order with respect to other pending read and write operations unless
1275 order is enforced by use of the
1276 .Fn bus_space_barrier
1278 There is no way to insert barriers between reads of
1279 individual bus space locations executed by the
1280 .Fn bus_space_read_region_N
1283 These functions will never fail.
1284 If they would fail (e.g.\& because of an
1285 argument error), that indicates a software bug which should cause a
1287 In that case, they will never return.
1288 .Ss Fn bus_space_write_region_1 space handle offset datap count
1289 .Ss Fn bus_space_write_region_2 space handle offset datap count
1290 .Ss Fn bus_space_write_region_4 space handle offset datap count
1291 .Ss Fn bus_space_write_region_8 space handle offset datap count
1293 .Fn bus_space_write_region_N
1294 family of functions reads
1296 1, 2, 4, or 8 byte data items from the array
1299 and writes them to bus space starting at byte offset
1301 in the region specified by
1303 of the bus space specified
1306 Each successive data item is written to an offset 1, 2, 4,
1307 or 8 bytes after the previous data item (depending on which function is
1309 All locations being written must lie within the bus space region
1313 For portability, the starting address of the region specified by
1315 plus the offset should be a multiple of the size of data items being
1316 written and the data array pointer should be properly aligned.
1318 systems, not obeying these requirements may cause incorrect data to be
1319 written, on others it may cause a system crash.
1321 Write operations done by the
1322 .Fn bus_space_write_region_N
1324 executed in any order.
1325 They may also be executed out of order with
1326 respect to other pending read and write operations unless order is
1327 enforced by use of the
1328 .Fn bus_space_barrier
1330 There is no way to insert barriers between writes of
1331 individual bus space locations executed by the
1332 .Fn bus_space_write_region_N
1335 These functions will never fail.
1336 If they would fail (e.g.\& because of an
1337 argument error), that indicates a software bug which should cause a
1339 In that case, they will never return.
1340 .Ss Fn bus_space_copy_region_1 space srchandle srcoffset dsthandle \
1342 .Ss Fn bus_space_copy_region_2 space srchandle srcoffset dsthandle \
1344 .Ss Fn bus_space_copy_region_4 space srchandle srcoffset dsthandle \
1346 .Ss Fn bus_space_copy_region_8 space srchandle srcoffset dsthandle \
1349 .Fn bus_space_copy_region_N
1350 family of functions copies
1352 1, 2, 4, or 8 byte data items in bus space
1353 from the area starting at byte offset
1355 in the region specified by
1357 of the bus space specified by
1359 to the area starting at byte offset
1361 in the region specified by
1363 in the same bus space.
1364 Each successive data item read or written has
1365 an offset 1, 2, 4, or 8 bytes after the previous data item (depending
1366 on which function is used).
1367 All locations being read and written must
1368 lie within the bus space region specified by their respective handles.
1370 For portability, the starting addresses of the regions specified by the
1371 each handle plus its respective offset should be a multiple of the size
1372 of data items being copied.
1373 On some systems, not obeying this
1374 requirement may cause incorrect data to be copied, on others it may cause
1377 Read and write operations done by the
1378 .Fn bus_space_copy_region_N
1379 functions may be executed in any order.
1380 They may also be executed out
1381 of order with respect to other pending read and write operations unless
1382 order is enforced by use of the
1383 .Fn bus_space_barrier
1385 There is no way to insert barriers between reads or writes of
1386 individual bus space locations executed by the
1387 .Fn bus_space_copy_region_N
1390 Overlapping copies between different subregions of a single region
1391 of bus space are handled correctly by the
1392 .Fn bus_space_copy_region_N
1395 These functions will never fail.
1396 If they would fail (e.g.\& because of an
1397 argument error), that indicates a software bug which should cause a
1399 In that case, they will never return.
1400 .Ss Fn bus_space_set_region_1 space handle offset value count
1401 .Ss Fn bus_space_set_region_2 space handle offset value count
1402 .Ss Fn bus_space_set_region_4 space handle offset value count
1403 .Ss Fn bus_space_set_region_8 space handle offset value count
1405 .Fn bus_space_set_region_N
1406 family of functions writes the given
1411 data items in bus space starting at byte offset
1413 in the region specified by
1415 of the bus space specified by
1417 Each successive data item has an offset 1, 2, 4, or 8 bytes after the
1418 previous data item (depending on which function is used).
1420 locations being written must lie within the bus space region specified
1424 For portability, the starting address of the region specified by
1426 plus the offset should be a multiple of the size of data items being
1428 On some systems, not obeying this requirement may cause
1429 incorrect data to be written, on others it may cause a system crash.
1431 Write operations done by the
1432 .Fn bus_space_set_region_N
1434 executed in any order.
1435 They may also be executed out of order with
1436 respect to other pending read and write operations unless order is
1437 enforced by use of the
1438 .Fn bus_space_barrier
1440 There is no way to insert barriers between writes of
1441 individual bus space locations executed by the
1442 .Fn bus_space_set_region_N
1445 These functions will never fail.
1446 If they would fail (e.g.\& because of an
1447 argument error), that indicates a software bug which should cause a
1449 In that case, they will never return.
1450 .Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES
1451 Some devices implement single locations in bus space which are to be read
1452 or written multiple times to communicate data, e.g.\& some ethernet
1453 devices' packet buffer FIFOs.
1454 In order to allow drivers to manipulate
1455 these types of devices as efficiently as possible, the
1456 .Fn bus_space_read_multi_N ,
1457 .Fn bus_space_set_multi_N ,
1459 .Fn bus_space_write_multi_N
1460 families of functions are provided.
1461 .Ss Fn bus_space_read_multi_1 space handle offset datap count
1462 .Ss Fn bus_space_read_multi_2 space handle offset datap count
1463 .Ss Fn bus_space_read_multi_4 space handle offset datap count
1464 .Ss Fn bus_space_read_multi_8 space handle offset datap count
1466 .Fn bus_space_read_multi_N
1467 family of functions reads
1469 1, 2, 4, or 8 byte data items from bus space
1472 in the region specified by
1474 of the bus space specified by
1476 and writes them into the array specified by
1478 Each successive data item is read from the same location in bus
1480 The location being read must lie within the bus space region
1484 For portability, the starting address of the region specified by
1486 plus the offset should be a multiple of the size of data items being
1487 read and the data array pointer should be properly aligned.
1489 systems, not obeying these requirements may cause incorrect data to be
1490 read, on others it may cause a system crash.
1492 Read operations done by the
1493 .Fn bus_space_read_multi_N
1495 executed out of order with respect to other pending read and write
1496 operations unless order is enforced by use of the
1497 .Fn bus_space_barrier
1500 .Fn bus_space_read_multi_N
1501 functions read the same bus space location multiple times, they
1502 place an implicit read barrier between each successive read of that bus
1505 These functions will never fail.
1506 If they would fail (e.g.\& because of an
1507 argument error), that indicates a software bug which should cause a
1509 In that case, they will never return.
1510 .Ss Fn bus_space_write_multi_1 space handle offset datap count
1511 .Ss Fn bus_space_write_multi_2 space handle offset datap count
1512 .Ss Fn bus_space_write_multi_4 space handle offset datap count
1513 .Ss Fn bus_space_write_multi_8 space handle offset datap count
1515 .Fn bus_space_write_multi_N
1516 family of functions reads
1518 1, 2, 4, or 8 byte data items from the array
1521 and writes them into bus space at byte offset
1523 in the region specified by
1525 of the bus space specified by
1527 Each successive data item is written to the same location in
1529 The location being written must lie within the bus space
1533 For portability, the starting address of the region specified by
1535 plus the offset should be a multiple of the size of data items being
1536 written and the data array pointer should be properly aligned.
1538 systems, not obeying these requirements may cause incorrect data to be
1539 written, on others it may cause a system crash.
1541 Write operations done by the
1542 .Fn bus_space_write_multi_N
1543 functions may be executed out of order with respect to other pending
1544 read and write operations unless order is enforced by use of the
1545 .Fn bus_space_barrier
1548 .Fn bus_space_write_multi_N
1549 functions write the same bus space location multiple times, they
1550 place an implicit write barrier between each successive write of that
1553 These functions will never fail.
1554 If they would fail (e.g.\& because of an
1555 argument error), that indicates a software bug which should cause a
1557 In that case, they will never return.
1558 .Ss Fn bus_space_set_multi_1 space handle offset value count
1559 .Ss Fn bus_space_set_multi_2 space handle offset value count
1560 .Ss Fn bus_space_set_multi_4 space handle offset value count
1561 .Ss Fn bus_space_set_multi_8 space handle offset value count
1563 .Fn bus_space_set_multi_N
1566 into bus space at byte offset
1568 in the region specified by
1570 of the bus space specified by
1574 The location being written must lie within the bus space
1578 For portability, the starting address of the region specified by
1580 plus the offset should be a multiple of the size of data items being
1581 written and the data array pointer should be properly aligned.
1583 systems, not obeying these requirements may cause incorrect data to be
1584 written, on others it may cause a system crash.
1586 Write operations done by the
1587 .Fn bus_space_set_multi_N
1588 functions may be executed out of order with respect to other pending
1589 read and write operations unless order is enforced by use of the
1590 .Fn bus_space_barrier
1593 .Fn bus_space_set_multi_N
1594 functions write the same bus space location multiple times, they
1595 place an implicit write barrier between each successive write of that
1598 These functions will never fail.
1599 If they would fail (e.g.\& because of an
1600 argument error), that indicates a software bug which should cause a
1602 In that case, they will never return.
1603 .Sh STREAM FUNCTIONS
1606 functions imply a host byte-order and a bus byte-order and take care of
1607 any translation for the caller.
1608 In some cases, however, hardware may map a FIFO or some other memory region
1609 for which the caller may want to use multi-word, yet untranslated access.
1610 Access to these types of memory regions should be with the
1611 .Fn bus_space_*_stream_N
1614 .Bl -tag -compact -width Fn
1615 .It Fn bus_space_read_stream_1
1616 .It Fn bus_space_read_stream_2
1617 .It Fn bus_space_read_stream_4
1618 .It Fn bus_space_read_stream_8
1619 .It Fn bus_space_read_multi_stream_1
1620 .It Fn bus_space_read_multi_stream_2
1621 .It Fn bus_space_read_multi_stream_4
1622 .It Fn bus_space_read_multi_stream_8
1623 .It Fn bus_space_read_region_stream_1
1624 .It Fn bus_space_read_region_stream_2
1625 .It Fn bus_space_read_region_stream_4
1626 .It Fn bus_space_read_region_stream_8
1627 .It Fn bus_space_write_stream_1
1628 .It Fn bus_space_write_stream_2
1629 .It Fn bus_space_write_stream_4
1630 .It Fn bus_space_write_stream_8
1631 .It Fn bus_space_write_multi_stream_1
1632 .It Fn bus_space_write_multi_stream_2
1633 .It Fn bus_space_write_multi_stream_4
1634 .It Fn bus_space_write_multi_stream_8
1635 .It Fn bus_space_write_region_stream_1
1636 .It Fn bus_space_write_region_stream_2
1637 .It Fn bus_space_write_region_stream_4
1638 .It Fn bus_space_write_region_stream_8
1639 .It Fn bus_space_copy_region_stream_1
1640 .It Fn bus_space_copy_region_stream_2
1641 .It Fn bus_space_copy_region_stream_4
1642 .It Fn bus_space_copy_region_stream_8
1643 .It Fn bus_space_set_multi_stream_1
1644 .It Fn bus_space_set_multi_stream_2
1645 .It Fn bus_space_set_multi_stream_4
1646 .It Fn bus_space_set_multi_stream_8
1647 .It Fn bus_space_set_region_stream_1
1648 .It Fn bus_space_set_region_stream_2
1649 .It Fn bus_space_set_region_stream_4
1650 .It Fn bus_space_set_region_stream_8
1653 These functions are defined just as their non-stream counterparts,
1654 except that they provide no byte-order translation.
1660 interface specification differs slightly from the original
1661 specification that came into wide use and
1664 A few of the function names and arguments have changed
1665 for consistency and increased functionality.
1671 functions were introduced in a different form (memory and I/O spaces
1672 were accessed via different sets of functions) in
1674 The functions were merged to work on generic
1678 development cycle, and many drivers were converted to use them.
1679 This document was written later during the
1681 development cycle, and the specification was updated to fix some
1682 consistency problems and to add some missing functionality.
1684 The manual page was then adapted to the version of the interface that
1686 imported for the CAM SCSI drivers, plus subsequent evolution.
1690 version was imported in
1696 interfaces were designed and implemented by the
1700 Primary contributors and implementors were
1701 .An Chris Demetriou ,
1704 .An Charles Hannum ,
1707 developers and the user community played a significant role in development.
1710 ported these interfaces to
1714 wrote this manual page.
1721 This manual may not completely and accurately document the interface,
1722 and many parts of the interface are unspecified.