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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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" "u_int8_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" "u_int16_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" "u_int32_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" "u_int64_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.
723 Several types are defined in
725 to facilitate use of the
727 functions by drivers.
731 type is used to describe bus addresses.
733 unsigned integral type
734 capable of holding the largest bus address usable by the architecture.
736 type is primarily used when mapping and unmapping bus space.
740 type is used to describe sizes of ranges in bus space.
742 unsigned integral type capable of holding the size of the largest bus
743 address range usable on the architecture.
744 This type is used by virtually all
747 functions, describing sizes when mapping regions and
748 offsets into regions when performing space access operations.
749 .Ss Vt bus_space_tag_t
752 type is used to describe a particular bus space on a machine.
754 contents are machine-dependent and should be considered opaque by
755 machine-independent code.
756 This type is used by all
758 functions to name the space on which they are operating.
759 .Ss Vt bus_space_handle_t
761 .Vt bus_space_handle_t
762 type is used to describe a mapping of a range of bus space.
764 contents are machine-dependent and should be considered opaque by
765 machine-independent code.
766 This type is used when performing bus space
768 .Sh MAPPING AND UNMAPPING BUS SPACE
769 This section is specific to the
771 version of these functions and may or may not apply to the
775 Bus space must be mapped before it can be used, and should be
776 unmapped when it is no longer needed.
781 functions provide these capabilities.
783 Some drivers need to be able to pass a subregion of already-mapped bus
784 space to another driver or module within a driver.
786 .Fn bus_space_subregion
787 function allows such subregions to be created.
788 .Ss Fn bus_space_map space address size flags handlep
791 function maps the region of bus space named by the
792 .Fa space , address ,
796 If successful, it returns zero
797 and fills in the bus space handle pointed to by
800 that can be used to access the mapped region.
802 it will return non-zero and leave the bus space handle pointed
805 in an undefined state.
809 argument controls how the space is to be mapped.
810 Supported flags include:
811 .Bl -tag -width ".Dv BUS_SPACE_MAP_CACHEABLE"
812 .It Dv BUS_SPACE_MAP_CACHEABLE
813 Try to map the space so that accesses can be cached and/or
814 prefetched by the system.
815 If this flag is not specified, the
816 implementation should map the space so that it will not be cached or
819 This flag must have a value of 1 on all implementations for backward
821 .It Dv BUS_SPACE_MAP_LINEAR
822 Try to map the space so that its contents can be accessed linearly via
823 normal memory access methods (e.g.\& pointer dereferencing and structure
825 This is useful when software wants to do direct access to a memory
826 device, e.g.\& a frame buffer.
827 If this flag is specified and linear
828 mapping is not possible, the
832 flag is not specified, the system may map the space in whatever way is
836 Not all combinations of flags make sense or are supported with all
839 .Dv BUS_SPACE_MAP_CACHEABLE
840 may be meaningless when
841 used on many systems' I/O port spaces, and on some systems
842 .Dv BUS_SPACE_MAP_LINEAR
844 .Dv BUS_SPACE_MAP_CACHEABLE
846 When the system hardware or firmware provides hints as to how spaces should be
847 mapped (e.g.\& the PCI memory mapping registers'
850 hints should be followed for maximum compatibility.
852 requesting a mapping that cannot be satisfied (e.g.\& requesting a
853 non-cacheable mapping when the system can only provide a cacheable one)
854 will cause the request to fail.
856 Some implementations may keep track of use of bus space for some or all
857 bus spaces and refuse to allow duplicate allocations.
859 for bus spaces which have no notion of slot-specific space addressing,
860 such as ISA and VME, and for spaces which coexist with those spaces
861 (e.g.\& EISA and PCI memory and I/O spaces co-existing with ISA memory and
864 Mapped regions may contain areas for which there is no device on the
866 If space in those areas is accessed, the results are
868 .Ss Fn bus_space_unmap space handle size
871 function unmaps a region of bus space mapped with
873 When unmapping a region, the
876 the same as the size given to
878 when mapping that region.
882 is called on a handle, that handle is no longer
884 (If copies were made of the handle they are no longer valid,
887 This function will never fail.
888 If it would fail (e.g.\& because of an
889 argument error), that indicates a software bug which should cause a
894 .Ss Fn bus_space_subregion space handle offset size nhandlep
896 .Fn bus_space_subregion
897 function is a convenience function which makes a
898 new handle to some subregion of an already-mapped region of bus space.
899 The subregion described by the new handle starts at byte offset
901 into the region described by
903 with the size give by
905 and must be wholly contained within the original region.
908 .Fn bus_space_subregion
909 returns zero and fills in the bus
910 space handle pointed to by
912 If unsuccessful, it returns non-zero and leaves the bus space handle
917 In either case, the handle described by
919 remains valid and is unmodified.
921 When done with a handle created by
922 .Fn bus_space_subregion ,
925 Under no circumstances should
927 be used on the handle.
928 Doing so may confuse any resource management
929 being done on the space, and will result in undefined behaviour.
934 is called on a handle, all subregions of that handle become invalid.
935 .Sh ALLOCATING AND FREEING BUS SPACE
936 This section is specific to the
938 version of these functions and may or may not apply to the
942 Some devices require or allow bus space to be allocated by the operating
943 system for device use.
944 When the devices no longer need the space, the
945 operating system should free it for use by other devices.
950 functions provide these capabilities.
951 .Ss Fn bus_space_alloc space reg_start reg_end size alignment boundary \
955 function allocates and maps a region of bus space with the size given by
957 corresponding to the given constraints.
958 If successful, it returns
959 zero, fills in the bus address pointed to by
961 with the bus space address of the allocated region, and fills in
962 the bus space handle pointed to by
964 with the handle that can be used to access that region.
965 If unsuccessful, it returns non-zero and leaves the bus address pointed to by
967 and the bus space handle pointed to by
969 in an undefined state.
971 Constraints on the allocation are given by the
972 .Fa reg_start , reg_end , alignment ,
976 The allocated region will start at or after
982 constraint must be a power of two, and the allocated region will start at
983 an address that is an even multiple of that power of two.
986 constraint, if non-zero, ensures that the region is allocated so that
987 .Fa "first address in region"
990 has the same value as
991 .Fa "last address in region"
994 If the constraints cannot be met,
997 It is an error to specify a set of
998 constraints that can never be met
1006 parameter is the same as the like-named parameter to
1008 the same flag values should be used, and they have the
1013 should only be freed with
1014 .Fn bus_space_free .
1017 on them causes undefined behaviour.
1019 .Fn bus_space_subregion
1020 function can be used on
1022 .Fn bus_space_alloc .
1023 .Ss Fn bus_space_free space handle size
1026 function unmaps and frees a region of bus space mapped
1028 .Fn bus_space_alloc .
1029 When unmapping a region, the
1031 specified should be the same as the size given to
1033 when allocating the region.
1037 is called on a handle, that handle is no longer valid.
1039 made of the handle, they are no longer valid, either.)
1041 This function will never fail.
1042 If it would fail (e.g.\& because of an
1043 argument error), that indicates a software bug which should cause a
1048 .Sh READING AND WRITING SINGLE DATA ITEMS
1049 The simplest way to access bus space is to read or write a single data
1052 .Fn bus_space_read_N
1054 .Fn bus_space_write_N
1055 families of functions provide
1056 the ability to read and write 1, 2, 4, and 8 byte data items on busses
1057 which support those access sizes.
1058 .Ss Fn bus_space_read_1 space handle offset
1059 .Ss Fn bus_space_read_2 space handle offset
1060 .Ss Fn bus_space_read_4 space handle offset
1061 .Ss Fn bus_space_read_8 space handle offset
1063 .Fn bus_space_read_N
1064 family of functions reads a 1, 2, 4, or 8 byte data item from
1065 the offset specified by
1067 into the region specified by
1069 of the bus space specified by
1071 The location being read must lie within the bus space region specified by
1074 For portability, the starting address of the region specified by
1076 plus the offset should be a multiple of the size of data item being read.
1077 On some systems, not obeying this requirement may cause incorrect data to
1078 be read, on others it may cause a system crash.
1080 Read operations done by the
1081 .Fn bus_space_read_N
1082 functions may be executed out
1083 of order with respect to other pending read and write operations unless
1084 order is enforced by use of the
1085 .Fn bus_space_barrier
1088 These functions will never fail.
1089 If they would fail (e.g.\& because of an
1090 argument error), that indicates a software bug which should cause a
1092 In that case, they will never return.
1093 .Ss Fn bus_space_write_1 space handle offset value
1094 .Ss Fn bus_space_write_2 space handle offset value
1095 .Ss Fn bus_space_write_4 space handle offset value
1096 .Ss Fn bus_space_write_8 space handle offset value
1098 .Fn bus_space_write_N
1099 family of functions writes a 1, 2, 4, or 8 byte data item to the offset
1102 into the region specified by
1104 of the bus space specified by
1106 The location being written must lie within
1107 the bus space region specified by
1110 For portability, the starting address of the region specified by
1112 plus the offset should be a multiple of the size of data item being
1114 On some systems, not obeying this requirement may cause
1115 incorrect data to be written, on others it may cause a system crash.
1117 Write operations done by the
1118 .Fn bus_space_write_N
1119 functions may be executed
1120 out of order with respect to other pending read and write operations
1121 unless order is enforced by use of the
1122 .Fn bus_space_barrier
1125 These functions will never fail.
1126 If they would fail (e.g.\& because of an
1127 argument error), that indicates a software bug which should cause a
1129 In that case, they will never return.
1131 In order to allow high-performance buffering implementations to avoid bus
1132 activity on every operation, read and write ordering should be specified
1133 explicitly by drivers when necessary.
1135 .Fn bus_space_barrier
1136 function provides that ability.
1137 .Ss Fn bus_space_barrier space handle offset length flags
1139 .Fn bus_space_barrier
1140 function enforces ordering of bus space read and write operations
1141 for the specified subregion (described by the
1145 parameters) of the region named by
1147 in the space named by
1152 argument controls what types of operations are to be ordered.
1153 Supported flags are:
1154 .Bl -tag -width ".Dv BUS_SPACE_BARRIER_WRITE"
1155 .It Dv BUS_SPACE_BARRIER_READ
1156 Synchronize read operations.
1157 .It Dv BUS_SPACE_BARRIER_WRITE
1158 Synchronize write operations.
1161 Those flags can be combined (or-ed together) to enforce ordering on both
1162 read and write operations.
1164 All of the specified type(s) of operation which are done to the region
1165 before the barrier operation are guaranteed to complete before any of the
1166 specified type(s) of operation done after the barrier.
1168 Example: Consider a hypothetical device with two single-byte ports, one
1169 write-only input port (at offset 0) and a read-only output port (at
1171 Operation of the device is as follows: data bytes are written
1172 to the input port, and are placed by the device on a stack, the top of
1173 which is read by reading from the output port.
1174 The sequence to correctly
1175 write two data bytes to the device then read those two data bytes back
1179 * t and h are the tag and handle for the mapped device's
1182 bus_space_write_1(t, h, 0, data0);
1183 bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE); /* 1 */
1184 bus_space_write_1(t, h, 0, data1);
1185 bus_space_barrier(t, h, 0, 2,
1186 BUS_SPACE_BARRIER_READ|BUS_SPACE_BARRIER_WRITE); /* 2 */
1187 ndata1 = bus_space_read_1(t, h, 1);
1188 bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ); /* 3 */
1189 ndata0 = bus_space_read_1(t, h, 1);
1190 /* data0 == ndata0, data1 == ndata1 */
1193 The first barrier makes sure that the first write finishes before the
1194 second write is issued, so that two writes to the input port are done
1195 in order and are not collapsed into a single write.
1197 the data bytes are written to the device correctly and in order.
1199 The second barrier makes sure that the writes to the output port finish
1200 before any of the reads to the input port are issued, thereby making sure
1201 that all of the writes are finished before data is read.
1203 that the first byte read from the device really is the last one that was
1206 The third barrier makes sure that the first read finishes before the
1207 second read is issued, ensuring that data is read correctly and in order.
1209 The barriers in the example above are specified to cover the absolute
1210 minimum number of bus space locations.
1211 It is correct (and often
1212 easier) to make barrier operations cover the device's whole range of bus
1213 space, that is, to specify an offset of zero and the size of the
1215 .Sh REGION OPERATIONS
1216 Some devices use buffers which are mapped as regions in bus space.
1217 Often, drivers want to copy the contents of those buffers to or from
1218 memory, e.g.\& into mbufs which can be passed to higher levels of the
1219 system or from mbufs to be output to a network.
1221 drivers to do this as efficiently as possible, the
1222 .Fn bus_space_read_region_N
1224 .Fn bus_space_write_region_N
1225 families of functions are provided.
1227 Drivers occasionally need to copy one region of a bus space to another,
1228 or to set all locations in a region of bus space to contain a single
1231 .Fn bus_space_copy_region_N
1232 family of functions and the
1233 .Fn bus_space_set_region_N
1234 family of functions allow drivers to perform these operations.
1235 .Ss Fn bus_space_read_region_1 space handle offset datap count
1236 .Ss Fn bus_space_read_region_2 space handle offset datap count
1237 .Ss Fn bus_space_read_region_4 space handle offset datap count
1238 .Ss Fn bus_space_read_region_8 space handle offset datap count
1240 .Fn bus_space_read_region_N
1241 family of functions reads
1243 1, 2, 4, or 8 byte data items from bus space
1244 starting at byte offset
1246 in the region specified by
1248 of the bus space specified by
1250 and writes them into the array specified by
1252 Each successive data item is read from an offset
1253 1, 2, 4, or 8 bytes after the previous data item (depending on which
1255 All locations being read must lie within the bus
1256 space region specified by
1259 For portability, the starting address of the region specified by
1261 plus the offset should be a multiple of the size of data items being
1262 read and the data array pointer should be properly aligned.
1264 systems, not obeying these requirements may cause incorrect data to be
1265 read, on others it may cause a system crash.
1267 Read operations done by the
1268 .Fn bus_space_read_region_N
1269 functions may be executed in any order.
1270 They may also be executed out
1271 of order with respect to other pending read and write operations unless
1272 order is enforced by use of the
1273 .Fn bus_space_barrier
1275 There is no way to insert barriers between reads of
1276 individual bus space locations executed by the
1277 .Fn bus_space_read_region_N
1280 These functions will never fail.
1281 If they would fail (e.g.\& because of an
1282 argument error), that indicates a software bug which should cause a
1284 In that case, they will never return.
1285 .Ss Fn bus_space_write_region_1 space handle offset datap count
1286 .Ss Fn bus_space_write_region_2 space handle offset datap count
1287 .Ss Fn bus_space_write_region_4 space handle offset datap count
1288 .Ss Fn bus_space_write_region_8 space handle offset datap count
1290 .Fn bus_space_write_region_N
1291 family of functions reads
1293 1, 2, 4, or 8 byte data items from the array
1296 and writes them to bus space starting at byte offset
1298 in the region specified by
1300 of the bus space specified
1303 Each successive data item is written to an offset 1, 2, 4,
1304 or 8 bytes after the previous data item (depending on which function is
1306 All locations being written must lie within the bus space region
1310 For portability, the starting address of the region specified by
1312 plus the offset should be a multiple of the size of data items being
1313 written and the data array pointer should be properly aligned.
1315 systems, not obeying these requirements may cause incorrect data to be
1316 written, on others it may cause a system crash.
1318 Write operations done by the
1319 .Fn bus_space_write_region_N
1321 executed in any order.
1322 They may also be executed out of order with
1323 respect to other pending read and write operations unless order is
1324 enforced by use of the
1325 .Fn bus_space_barrier
1327 There is no way to insert barriers between writes of
1328 individual bus space locations executed by the
1329 .Fn bus_space_write_region_N
1332 These functions will never fail.
1333 If they would fail (e.g.\& because of an
1334 argument error), that indicates a software bug which should cause a
1336 In that case, they will never return.
1337 .Ss Fn bus_space_copy_region_1 space srchandle srcoffset dsthandle \
1339 .Ss Fn bus_space_copy_region_2 space srchandle srcoffset dsthandle \
1341 .Ss Fn bus_space_copy_region_4 space srchandle srcoffset dsthandle \
1343 .Ss Fn bus_space_copy_region_8 space srchandle srcoffset dsthandle \
1346 .Fn bus_space_copy_region_N
1347 family of functions copies
1349 1, 2, 4, or 8 byte data items in bus space
1350 from the area starting at byte offset
1352 in the region specified by
1354 of the bus space specified by
1356 to the area starting at byte offset
1358 in the region specified by
1360 in the same bus space.
1361 Each successive data item read or written has
1362 an offset 1, 2, 4, or 8 bytes after the previous data item (depending
1363 on which function is used).
1364 All locations being read and written must
1365 lie within the bus space region specified by their respective handles.
1367 For portability, the starting addresses of the regions specified by the
1368 each handle plus its respective offset should be a multiple of the size
1369 of data items being copied.
1370 On some systems, not obeying this
1371 requirement may cause incorrect data to be copied, on others it may cause
1374 Read and write operations done by the
1375 .Fn bus_space_copy_region_N
1376 functions may be executed in any order.
1377 They may also be executed out
1378 of order with respect to other pending read and write operations unless
1379 order is enforced by use of the
1380 .Fn bus_space_barrier function .
1381 There is no way to insert barriers between reads or writes of
1382 individual bus space locations executed by the
1383 .Fn bus_space_copy_region_N
1386 Overlapping copies between different subregions of a single region
1387 of bus space are handled correctly by the
1388 .Fn bus_space_copy_region_N
1391 These functions will never fail.
1392 If they would fail (e.g.\& because of an
1393 argument error), that indicates a software bug which should cause a
1395 In that case, they will never return.
1396 .Ss Fn bus_space_set_region_1 space handle offset value count
1397 .Ss Fn bus_space_set_region_2 space handle offset value count
1398 .Ss Fn bus_space_set_region_4 space handle offset value count
1399 .Ss Fn bus_space_set_region_8 space handle offset value count
1401 .Fn bus_space_set_region_N
1402 family of functions writes the given
1407 data items in bus space starting at byte offset
1409 in the region specified by
1411 of the bus space specified by
1413 Each successive data item has an offset 1, 2, 4, or 8 bytes after the
1414 previous data item (depending on which function is used).
1416 locations being written must lie within the bus space region specified
1420 For portability, the starting address of the region specified by
1422 plus the offset should be a multiple of the size of data items being
1424 On some systems, not obeying this requirement may cause
1425 incorrect data to be written, on others it may cause a system crash.
1427 Write operations done by the
1428 .Fn bus_space_set_region_N
1430 executed in any order.
1431 They may also be executed out of order with
1432 respect to other pending read and write operations unless order is
1433 enforced by use of the
1434 .Fn bus_space_barrier
1436 There is no way to insert barriers between writes of
1437 individual bus space locations executed by the
1438 .Fn bus_space_set_region_N
1441 These functions will never fail.
1442 If they would fail (e.g.\& because of an
1443 argument error), that indicates a software bug which should cause a
1445 In that case, they will never return.
1446 .Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES
1447 Some devices implement single locations in bus space which are to be read
1448 or written multiple times to communicate data, e.g.\& some ethernet
1449 devices' packet buffer FIFOs.
1450 In order to allow drivers to manipulate
1451 these types of devices as efficiently as possible, the
1452 .Fn bus_space_read_multi_N ,
1453 .Fn bus_space_set_multi_N ,
1455 .Fn bus_space_write_multi_N
1456 families of functions are provided.
1457 .Ss Fn bus_space_read_multi_1 space handle offset datap count
1458 .Ss Fn bus_space_read_multi_2 space handle offset datap count
1459 .Ss Fn bus_space_read_multi_4 space handle offset datap count
1460 .Ss Fn bus_space_read_multi_8 space handle offset datap count
1462 .Fn bus_space_read_multi_N
1463 family of functions reads
1465 1, 2, 4, or 8 byte data items from bus space
1468 in the region specified by
1470 of the bus space specified by
1472 and writes them into the array specified by
1474 Each successive data item is read from the same location in bus
1476 The location being read must lie within the bus space region
1480 For portability, the starting address of the region specified by
1482 plus the offset should be a multiple of the size of data items being
1483 read and the data array pointer should be properly aligned.
1485 systems, not obeying these requirements may cause incorrect data to be
1486 read, on others it may cause a system crash.
1488 Read operations done by the
1489 .Fn bus_space_read_multi_N
1491 executed out of order with respect to other pending read and write
1492 operations unless order is enforced by use of the
1493 .Fn bus_space_barrier
1496 .Fn bus_space_read_multi_N
1497 functions read the same bus space location multiple times, they
1498 place an implicit read barrier between each successive read of that bus
1501 These functions will never fail.
1502 If they would fail (e.g.\& because of an
1503 argument error), that indicates a software bug which should cause a
1505 In that case, they will never return.
1506 .Ss Fn bus_space_write_multi_1 space handle offset datap count
1507 .Ss Fn bus_space_write_multi_2 space handle offset datap count
1508 .Ss Fn bus_space_write_multi_4 space handle offset datap count
1509 .Ss Fn bus_space_write_multi_8 space handle offset datap count
1511 .Fn bus_space_write_multi_N
1512 family of functions reads
1514 1, 2, 4, or 8 byte data items from the array
1517 and writes them into bus space at byte offset
1519 in the region specified by
1521 of the bus space specified by
1523 Each successive data item is written to the same location in
1525 The location being written must lie within the bus space
1529 For portability, the starting address of the region specified by
1531 plus the offset should be a multiple of the size of data items being
1532 written and the data array pointer should be properly aligned.
1534 systems, not obeying these requirements may cause incorrect data to be
1535 written, on others it may cause a system crash.
1537 Write operations done by the
1538 .Fn bus_space_write_multi_N
1539 functions may be executed out of order with respect to other pending
1540 read and write operations unless order is enforced by use of the
1541 .Fn bus_space_barrier
1544 .Fn bus_space_write_multi_N
1545 functions write the same bus space location multiple times, they
1546 place an implicit write barrier between each successive write of that
1549 These functions will never fail.
1550 If they would fail (e.g.\& because of an
1551 argument error), that indicates a software bug which should cause a
1553 In that case, they will never return.
1554 .Ss Fn bus_space_set_multi_1 space handle offset value count
1555 .Ss Fn bus_space_set_multi_2 space handle offset value count
1556 .Ss Fn bus_space_set_multi_4 space handle offset value count
1557 .Ss Fn bus_space_set_multi_8 space handle offset value count
1559 .Fn bus_space_set_multi_N
1562 into bus space at byte offset
1564 in the region specified by
1566 of the bus space specified by
1570 The location being written must lie within the bus space
1574 For portability, the starting address of the region specified by
1576 plus the offset should be a multiple of the size of data items being
1577 written and the data array pointer should be properly aligned.
1579 systems, not obeying these requirements may cause incorrect data to be
1580 written, on others it may cause a system crash.
1582 Write operations done by the
1583 .Fn bus_space_set_multi_N
1584 functions may be executed out of order with respect to other pending
1585 read and write operations unless order is enforced by use of the
1586 .Fn bus_space_barrier
1589 .Fn bus_space_set_multi_N
1590 functions write the same bus space location multiple times, they
1591 place an implicit write barrier between each successive write of that
1594 These functions will never fail.
1595 If they would fail (e.g.\& because of an
1596 argument error), that indicates a software bug which should cause a
1598 In that case, they will never return.
1599 .Sh STREAM FUNCTIONS
1602 functions imply a host byte-order and a bus byte-order and take care of
1603 any translation for the caller.
1604 In some cases, however, hardware may map a FIFO or some other memory region
1605 for which the caller may want to use multi-word, yet untranslated access.
1606 Access to these types of memory regions should be with the
1607 .Fn bus_space_*_stream_N
1611 .It Fn bus_space_read_stream_1
1612 .It Fn bus_space_read_stream_2
1613 .It Fn bus_space_read_stream_4
1614 .It Fn bus_space_read_stream_8
1615 .It Fn bus_space_read_multi_stream_1
1616 .It Fn bus_space_read_multi_stream_2
1617 .It Fn bus_space_read_multi_stream_4
1618 .It Fn bus_space_read_multi_stream_8
1619 .It Fn bus_space_read_region_stream_1
1620 .It Fn bus_space_read_region_stream_2
1621 .It Fn bus_space_read_region_stream_4
1622 .It Fn bus_space_read_region_stream_8
1623 .It Fn bus_space_write_stream_1
1624 .It Fn bus_space_write_stream_2
1625 .It Fn bus_space_write_stream_4
1626 .It Fn bus_space_write_stream_8
1627 .It Fn bus_space_write_multi_stream_1
1628 .It Fn bus_space_write_multi_stream_2
1629 .It Fn bus_space_write_multi_stream_4
1630 .It Fn bus_space_write_multi_stream_8
1631 .It Fn bus_space_write_region_stream_1
1632 .It Fn bus_space_write_region_stream_2
1633 .It Fn bus_space_write_region_stream_4
1634 .It Fn bus_space_write_region_stream_8
1635 .It Fn bus_space_copy_region_stream_1
1636 .It Fn bus_space_copy_region_stream_2
1637 .It Fn bus_space_copy_region_stream_4
1638 .It Fn bus_space_copy_region_stream_8
1639 .It Fn bus_space_set_multi_stream_1
1640 .It Fn bus_space_set_multi_stream_2
1641 .It Fn bus_space_set_multi_stream_4
1642 .It Fn bus_space_set_multi_stream_8
1643 .It Fn bus_space_set_region_stream_1
1644 .It Fn bus_space_set_region_stream_2
1645 .It Fn bus_space_set_region_stream_4
1646 .It Fn bus_space_set_region_stream_8
1649 These functions are defined just as their non-stream counterparts,
1650 except that they provide no byte-order translation.
1656 interface specification differs slightly from the original
1657 specification that came into wide use and
1660 A few of the function names and arguments have changed
1661 for consistency and increased functionality.
1667 functions were introduced in a different form (memory and I/O spaces
1668 were accessed via different sets of functions) in
1670 The functions were merged to work on generic
1674 development cycle, and many drivers were converted to use them.
1675 This document was written later during the
1677 development cycle, and the specification was updated to fix some
1678 consistency problems and to add some missing functionality.
1680 The manual page was then adapted to the version of the interface that
1682 imported for the CAM SCSI drivers, plus subsequent evolution.
1686 version was imported in
1692 interfaces were designed and implemented by the
1696 Primary contributors and implementors were
1697 .An Chris Demetriou ,
1700 .An Charles Hannum ,
1703 developers and the user community played a significant role in development.
1706 ported these interfaces to
1710 wrote this manual page.
1717 This manual may not completely and accurately document the interface,
1718 and many parts of the interface are unspecified.