1 .\" $NetBSD: bus_space.9,v 1.9 1999/03/06 22:09:29 mycroft Exp $
3 .\" Copyright (c) 2005 M. Warner Losh.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
14 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
15 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
17 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
19 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
20 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
21 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
22 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
23 .\" POSSIBILITY OF SUCH DAMAGE.
26 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
27 .\" All rights reserved.
29 .\" This code is derived from software contributed to The NetBSD Foundation
30 .\" by Christopher G. Demetriou.
32 .\" Redistribution and use in source and binary forms, with or without
33 .\" modification, are permitted provided that the following conditions
35 .\" 1. Redistributions of source code must retain the above copyright
36 .\" notice, this list of conditions and the following disclaimer.
37 .\" 2. Redistributions in binary form must reproduce the above copyright
38 .\" notice, this list of conditions and the following disclaimer in the
39 .\" documentation and/or other materials provided with the distribution.
41 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
42 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
43 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
44 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
45 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
46 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
47 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
48 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
49 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
50 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
51 .\" POSSIBILITY OF SUCH DAMAGE.
60 .Nm bus_space_barrier ,
61 .Nm bus_space_copy_region_1 ,
62 .Nm bus_space_copy_region_2 ,
63 .Nm bus_space_copy_region_4 ,
64 .Nm bus_space_copy_region_8 ,
65 .Nm bus_space_copy_region_stream_1 ,
66 .Nm bus_space_copy_region_stream_2 ,
67 .Nm bus_space_copy_region_stream_4 ,
68 .Nm bus_space_copy_region_stream_8 ,
71 .Nm bus_space_read_1 ,
72 .Nm bus_space_read_2 ,
73 .Nm bus_space_read_4 ,
74 .Nm bus_space_read_8 ,
75 .Nm bus_space_read_multi_1 ,
76 .Nm bus_space_read_multi_2 ,
77 .Nm bus_space_read_multi_4 ,
78 .Nm bus_space_read_multi_8 ,
79 .Nm bus_space_read_multi_stream_1 ,
80 .Nm bus_space_read_multi_stream_2 ,
81 .Nm bus_space_read_multi_stream_4 ,
82 .Nm bus_space_read_multi_stream_8 ,
83 .Nm bus_space_read_region_1 ,
84 .Nm bus_space_read_region_2 ,
85 .Nm bus_space_read_region_4 ,
86 .Nm bus_space_read_region_8 ,
87 .Nm bus_space_read_region_stream_1 ,
88 .Nm bus_space_read_region_stream_2 ,
89 .Nm bus_space_read_region_stream_4 ,
90 .Nm bus_space_read_region_stream_8 ,
91 .Nm bus_space_read_stream_1 ,
92 .Nm bus_space_read_stream_2 ,
93 .Nm bus_space_read_stream_4 ,
94 .Nm bus_space_read_stream_8 ,
95 .Nm bus_space_set_multi_1 ,
96 .Nm bus_space_set_multi_2 ,
97 .Nm bus_space_set_multi_4 ,
98 .Nm bus_space_set_multi_8 ,
99 .Nm bus_space_set_multi_stream_1 ,
100 .Nm bus_space_set_multi_stream_2 ,
101 .Nm bus_space_set_multi_stream_4 ,
102 .Nm bus_space_set_multi_stream_8 ,
103 .Nm bus_space_set_region_1 ,
104 .Nm bus_space_set_region_2 ,
105 .Nm bus_space_set_region_4 ,
106 .Nm bus_space_set_region_8 ,
107 .Nm bus_space_set_region_stream_1 ,
108 .Nm bus_space_set_region_stream_2 ,
109 .Nm bus_space_set_region_stream_4 ,
110 .Nm bus_space_set_region_stream_8 ,
111 .Nm bus_space_subregion ,
112 .Nm bus_space_unmap ,
113 .Nm bus_space_write_1 ,
114 .Nm bus_space_write_2 ,
115 .Nm bus_space_write_4 ,
116 .Nm bus_space_write_8 ,
117 .Nm bus_space_write_multi_1 ,
118 .Nm bus_space_write_multi_2 ,
119 .Nm bus_space_write_multi_4 ,
120 .Nm bus_space_write_multi_8 ,
121 .Nm bus_space_write_multi_stream_1 ,
122 .Nm bus_space_write_multi_stream_2 ,
123 .Nm bus_space_write_multi_stream_4 ,
124 .Nm bus_space_write_multi_stream_8 ,
125 .Nm bus_space_write_region_1 ,
126 .Nm bus_space_write_region_2 ,
127 .Nm bus_space_write_region_4 ,
128 .Nm bus_space_write_region_8 ,
129 .Nm bus_space_write_region_stream_1 ,
130 .Nm bus_space_write_region_stream_2 ,
131 .Nm bus_space_write_region_stream_4 ,
132 .Nm bus_space_write_region_stream_8 ,
133 .Nm bus_space_write_stream_1 ,
134 .Nm bus_space_write_stream_2 ,
135 .Nm bus_space_write_stream_4 ,
136 .Nm bus_space_write_stream_8
137 .Nd "bus space manipulation functions"
142 .Fa "bus_space_tag_t space" "bus_addr_t address"
143 .Fa "bus_size_t size" "int flags" "bus_space_handle_t *handlep"
147 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size"
150 .Fo bus_space_subregion
151 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
152 .Fa "bus_size_t offset" "bus_size_t size" "bus_space_handle_t *nhandlep"
156 .Fa "bus_space_tag_t space" "bus_addr_t reg_start" "bus_addr_t reg_end"
157 .Fa "bus_size_t size" "bus_size_t alignment" "bus_size_t boundary"
158 .Fa "int flags" "bus_addr_t *addrp" "bus_space_handle_t *handlep"
162 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size"
166 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
170 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
174 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
178 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
181 .Fo bus_space_read_stream_1
182 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
185 .Fo bus_space_read_stream_2
186 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
189 .Fo bus_space_read_stream_4
190 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
193 .Fo bus_space_read_stream_8
194 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
197 .Fo bus_space_write_1
198 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
199 .Fa "bus_size_t offset" "uint8_t value"
202 .Fo bus_space_write_2
203 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
204 .Fa "bus_size_t offset" "uint16_t value"
207 .Fo bus_space_write_4
208 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
209 .Fa "bus_size_t offset" "uint32_t value"
212 .Fo bus_space_write_8
213 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
214 .Fa "bus_size_t offset" "uint64_t value"
217 .Fo bus_space_write_stream_1
218 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
219 .Fa "bus_size_t offset" "uint8_t value"
222 .Fo bus_space_write_stream_2
223 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
224 .Fa "bus_size_t offset" "uint16_t value"
227 .Fo bus_space_write_stream_4
228 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
229 .Fa "bus_size_t offset" "uint32_t value"
232 .Fo bus_space_write_stream_8
233 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
234 .Fa "bus_size_t offset" "uint64_t value"
237 .Fo bus_space_barrier
238 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
239 .Fa "bus_size_t offset" "bus_size_t length" "int flags"
242 .Fo bus_space_read_region_1
243 .Fa "bus_space_tag_t space"
244 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
245 .Fa "bus_size_t count"
248 .Fo bus_space_read_region_2
249 .Fa "bus_space_tag_t space"
250 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
251 .Fa "bus_size_t count"
254 .Fo bus_space_read_region_4
255 .Fa "bus_space_tag_t space"
256 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
257 .Fa "bus_size_t count"
260 .Fo bus_space_read_region_8
261 .Fa "bus_space_tag_t space"
262 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
263 .Fa "bus_size_t count"
266 .Fo bus_space_read_region_stream_1
267 .Fa "bus_space_tag_t space"
268 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
269 .Fa "bus_size_t count"
272 .Fo bus_space_read_region_stream_2
273 .Fa "bus_space_tag_t space"
274 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
275 .Fa "bus_size_t count"
278 .Fo bus_space_read_region_stream_4
279 .Fa "bus_space_tag_t space"
280 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
281 .Fa "bus_size_t count"
284 .Fo bus_space_read_region_stream_8
285 .Fa "bus_space_tag_t space"
286 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
287 .Fa "bus_size_t count"
290 .Fo bus_space_write_region_1
291 .Fa "bus_space_tag_t space"
292 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
293 .Fa "bus_size_t count"
296 .Fo bus_space_write_region_2
297 .Fa "bus_space_tag_t space"
298 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
299 .Fa "bus_size_t count"
302 .Fo bus_space_write_region_4
303 .Fa "bus_space_tag_t space"
304 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
305 .Fa "bus_size_t count"
308 .Fo bus_space_write_region_8
309 .Fa "bus_space_tag_t space"
310 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
311 .Fa "bus_size_t count"
314 .Fo bus_space_write_region_stream_1
315 .Fa "bus_space_tag_t space"
316 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
317 .Fa "bus_size_t count"
320 .Fo bus_space_write_region_stream_2
321 .Fa "bus_space_tag_t space"
322 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
323 .Fa "bus_size_t count"
326 .Fo bus_space_write_region_stream_4
327 .Fa "bus_space_tag_t space"
328 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
329 .Fa "bus_size_t count"
332 .Fo bus_space_write_region_stream_8
333 .Fa "bus_space_tag_t space"
334 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
335 .Fa "bus_size_t count"
338 .Fo bus_space_copy_region_1
339 .Fa "bus_space_tag_t space"
340 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
341 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
344 .Fo bus_space_copy_region_2
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_4
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_8
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_stream_1
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_2
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_4
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_8
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_set_region_1
387 .Fa "bus_space_tag_t space"
388 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
389 .Fa "bus_size_t count"
392 .Fo bus_space_set_region_2
393 .Fa "bus_space_tag_t space"
394 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
395 .Fa "bus_size_t count"
398 .Fo bus_space_set_region_4
399 .Fa "bus_space_tag_t space"
400 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
401 .Fa "bus_size_t count"
404 .Fo bus_space_set_region_8
405 .Fa "bus_space_tag_t space"
406 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
407 .Fa "bus_size_t count"
410 .Fo bus_space_set_region_stream_1
411 .Fa "bus_space_tag_t space"
412 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
413 .Fa "bus_size_t count"
416 .Fo bus_space_set_region_stream_2
417 .Fa "bus_space_tag_t space"
418 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
419 .Fa "bus_size_t count"
422 .Fo bus_space_set_region_stream_4
423 .Fa "bus_space_tag_t space"
424 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
425 .Fa "bus_size_t count"
428 .Fo bus_space_set_region_stream_8
429 .Fa "bus_space_tag_t space"
430 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
431 .Fa "bus_size_t count"
434 .Fo bus_space_read_multi_1
435 .Fa "bus_space_tag_t space"
436 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
437 .Fa "bus_size_t count"
440 .Fo bus_space_read_multi_2
441 .Fa "bus_space_tag_t space"
442 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
443 .Fa "bus_size_t count"
446 .Fo bus_space_read_multi_4
447 .Fa "bus_space_tag_t space"
448 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
449 .Fa "bus_size_t count"
452 .Fo bus_space_read_multi_8
453 .Fa "bus_space_tag_t space"
454 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
455 .Fa "bus_size_t count"
458 .Fo bus_space_read_multi_stream_1
459 .Fa "bus_space_tag_t space"
460 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
461 .Fa "bus_size_t count"
464 .Fo bus_space_read_multi_stream_2
465 .Fa "bus_space_tag_t space"
466 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
467 .Fa "bus_size_t count"
470 .Fo bus_space_read_multi_stream_4
471 .Fa "bus_space_tag_t space"
472 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
473 .Fa "bus_size_t count"
476 .Fo bus_space_read_multi_stream_8
477 .Fa "bus_space_tag_t space"
478 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
479 .Fa "bus_size_t count"
482 .Fo bus_space_write_multi_1
483 .Fa "bus_space_tag_t space"
484 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
485 .Fa "bus_size_t count"
488 .Fo bus_space_write_multi_2
489 .Fa "bus_space_tag_t space"
490 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
491 .Fa "bus_size_t count"
494 .Fo bus_space_write_multi_4
495 .Fa "bus_space_tag_t space"
496 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
497 .Fa "bus_size_t count"
500 .Fo bus_space_write_multi_8
501 .Fa "bus_space_tag_t space"
502 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
503 .Fa "bus_size_t count"
506 .Fo bus_space_write_multi_stream_1
507 .Fa "bus_space_tag_t space"
508 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
509 .Fa "bus_size_t count"
512 .Fo bus_space_write_multi_stream_2
513 .Fa "bus_space_tag_t space"
514 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
515 .Fa "bus_size_t count"
518 .Fo bus_space_write_multi_stream_4
519 .Fa "bus_space_tag_t space"
520 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
521 .Fa "bus_size_t count"
524 .Fo bus_space_write_multi_stream_8
525 .Fa "bus_space_tag_t space"
526 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
527 .Fa "bus_size_t count"
530 .Fo bus_space_set_multi_1
531 .Fa "bus_space_tag_t space"
532 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
533 .Fa "bus_size_t count"
536 .Fo bus_space_set_multi_2
537 .Fa "bus_space_tag_t space"
538 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
539 .Fa "bus_size_t count"
542 .Fo bus_space_set_multi_4
543 .Fa "bus_space_tag_t space"
544 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
545 .Fa "bus_size_t count"
548 .Fo bus_space_set_multi_8
549 .Fa "bus_space_tag_t space"
550 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
551 .Fa "bus_size_t count"
554 .Fo bus_space_set_multi_stream_1
555 .Fa "bus_space_tag_t space"
556 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
557 .Fa "bus_size_t count"
560 .Fo bus_space_set_multi_stream_2
561 .Fa "bus_space_tag_t space"
562 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
563 .Fa "bus_size_t count"
566 .Fo bus_space_set_multi_stream_4
567 .Fa "bus_space_tag_t space"
568 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
569 .Fa "bus_size_t count"
572 .Fo bus_space_set_multi_stream_8
573 .Fa "bus_space_tag_t space"
574 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
575 .Fa "bus_size_t count"
580 functions exist to allow device drivers
581 machine-independent access to bus memory and register areas.
583 functions and types described in this document can be used by including
588 Many common devices are used on multiple architectures, but are accessed
589 differently on each because of architectural constraints.
590 For instance, a device which is mapped in one system's I/O space may be
591 mapped in memory space on a second system.
592 On a third system, architectural
593 limitations might change the way registers need to be accessed (e.g.\&
594 creating a non-linear register space).
595 In some cases, a single
596 driver may need to access the same type of device in multiple ways in a
597 single system or architecture.
600 functions is to allow a single driver source file to manipulate a set
601 of devices on different system architectures, and to allow a single driver
602 object file to manipulate a set of devices on multiple bus types on a
605 Not all buses have to implement all functions described in this
606 document, though that is encouraged if the operations are logically
607 supported by the bus.
608 Unimplemented functions should cause
609 compile-time errors if possible.
611 All of the interface definitions described in this document are shown as
612 function prototypes and discussed as if they were required to be
614 Implementations are encouraged to implement prototyped
615 (type-checked) versions of these interfaces, but may implement them as
616 macros if appropriate.
617 Machine-dependent types, variables, and functions
618 should be marked clearly in
620 to avoid confusion with the
621 machine-independent types and functions, and, if possible, should be
622 given names which make the machine-dependence clear.
623 .Sh CONCEPTS AND GUIDELINES
624 Bus spaces are described by bus space tags, which can be created only by
625 machine-dependent code.
626 A given machine may have several different types
627 of bus space (e.g.\& memory space and I/O space), and thus may provide
628 multiple different bus space tags.
629 Individual buses or devices on a machine may use more than one bus space
631 For instance, ISA devices are
632 given an ISA memory space tag and an ISA I/O space tag.
634 may have several different tags which represent the same type of
635 space, for instance because of multiple different host bus interface
638 A range in bus space is described by a bus address and a bus size.
640 bus address describes the start of the range in bus space.
642 size describes the size of the range in bytes.
643 Buses which are not byte
644 addressable may require use of bus space ranges with appropriately
645 aligned addresses and properly rounded sizes.
647 Access to regions of bus space is facilitated by use of bus space handles,
648 which are usually created by mapping a specific range of a bus space.
649 Handles may also be created by allocating
650 and mapping a range of bus space, the actual location of which is picked
651 by the implementation within bounds specified by the caller of the
654 All of the bus space access functions require one bus space tag
655 argument, at least one handle argument, and at least one offset argument
657 The bus space tag specifies the space, each handle specifies a region in
658 the space, and each offset specifies the offset into the region of the
659 actual location(s) to be accessed.
660 Offsets are given in bytes, though buses
661 may impose alignment constraints.
662 The offset used to access data
663 relative to a given handle must be such that all of the data being
664 accessed is in the mapped region that the handle describes.
666 access data outside that region is an error.
668 Because some architectures' memory systems use buffering to improve
669 memory and device access performance, there is a mechanism which can be
672 in the bus space read and write stream.
674 are three types of barriers: read, write, and read/write.
676 started to the region before a read barrier must complete before any reads
677 after the read barrier are started.
678 (The analogous requirement is true for
680 Read/write barriers force all reads and writes started
681 before the barrier to complete before any reads or writes after the
683 Correctly-written drivers will include all
684 appropriate barriers, and assume only the read/write ordering imposed by
685 the barrier operations.
687 People trying to write portable drivers with the
690 try to make minimal assumptions about what the system allows.
692 they should expect that the system requires bus space addresses being
693 accessed to be naturally aligned (i.e., base address of handle added to
694 offset is a multiple of the access size), and that the system does
695 alignment checking on pointers (i.e., pointer to objects being read and
696 written must point to properly-aligned data).
698 The descriptions of the
700 functions given below all assume that
701 they are called with proper arguments.
702 If called with invalid arguments
703 or arguments that are out of range (e.g.\& trying to access data outside of
704 the region mapped when a given handle was created), undefined behaviour
706 In that case, they may cause the
707 system to halt, either intentionally (via panic) or unintentionally (by
708 causing a fatal trap of by some other means) or may cause improper
709 operation which is not immediately fatal.
710 Functions which return
712 or which return data read from bus space (i.e., functions which
713 do not obviously return an error code) do not fail.
715 if given invalid arguments, and in that case their behaviour is undefined.
716 Functions which take a count of bytes have undefined results if the specified
720 Several types are defined in
722 to facilitate use of the
724 functions by drivers.
728 type is used to describe bus addresses.
730 unsigned integral type
731 capable of holding the largest bus address usable by the architecture.
733 type is primarily used when mapping and unmapping bus space.
737 type is used to describe sizes of ranges in bus space.
739 unsigned integral type capable of holding the size of the largest bus
740 address range usable on the architecture.
741 This type is used by virtually all
744 functions, describing sizes when mapping regions and
745 offsets into regions when performing space access operations.
746 .Ss Vt bus_space_tag_t
749 type is used to describe a particular bus space on a machine.
751 contents are machine-dependent and should be considered opaque by
752 machine-independent code.
753 This type is used by all
755 functions to name the space on which they are operating.
756 .Ss Vt bus_space_handle_t
758 .Vt bus_space_handle_t
759 type is used to describe a mapping of a range of bus space.
761 contents are machine-dependent and should be considered opaque by
762 machine-independent code.
763 This type is used when performing bus space
765 .Sh MAPPING AND UNMAPPING BUS SPACE
766 This section is specific to the
768 version of these functions and may or may not apply to the
772 Bus space must be mapped before it can be used, and should be
773 unmapped when it is no longer needed.
778 functions provide these capabilities.
780 Some drivers need to be able to pass a subregion of already-mapped bus
781 space to another driver or module within a driver.
783 .Fn bus_space_subregion
784 function allows such subregions to be created.
785 .Ss Fn bus_space_map space address size flags handlep
788 function maps the region of bus space named by the
789 .Fa space , address ,
793 If successful, it returns zero
794 and fills in the bus space handle pointed to by
797 that can be used to access the mapped region.
799 it will return non-zero and leave the bus space handle pointed
802 in an undefined state.
806 argument controls how the space is to be mapped.
807 Supported flags include:
808 .Bl -tag -width ".Dv BUS_SPACE_MAP_CACHEABLE"
809 .It Dv BUS_SPACE_MAP_CACHEABLE
810 Try to map the space so that accesses can be cached and/or
811 prefetched by the system.
812 If this flag is not specified, the
813 implementation should map the space so that it will not be cached or
816 This flag must have a value of 1 on all implementations for backward
818 .It Dv BUS_SPACE_MAP_LINEAR
819 Try to map the space so that its contents can be accessed linearly via
820 normal memory access methods (e.g.\& pointer dereferencing and structure
822 This is useful when software wants to do direct access to a memory
823 device, e.g.\& a frame buffer.
824 If this flag is specified and linear
825 mapping is not possible, the
829 flag is not specified, the system may map the space in whatever way is
833 Not all combinations of flags make sense or are supported with all
836 .Dv BUS_SPACE_MAP_CACHEABLE
837 may be meaningless when
838 used on many systems' I/O port spaces, and on some systems
839 .Dv BUS_SPACE_MAP_LINEAR
841 .Dv BUS_SPACE_MAP_CACHEABLE
843 When the system hardware or firmware provides hints as to how spaces should be
844 mapped (e.g.\& the PCI memory mapping registers'
847 hints should be followed for maximum compatibility.
849 requesting a mapping that cannot be satisfied (e.g.\& requesting a
850 non-cacheable mapping when the system can only provide a cacheable one)
851 will cause the request to fail.
853 Some implementations may keep track of use of bus space for some or all
854 bus spaces and refuse to allow duplicate allocations.
856 for bus spaces which have no notion of slot-specific space addressing,
857 such as ISA, and for spaces which coexist with those spaces
858 (e.g.\& PCI memory and I/O spaces co-existing with ISA memory and
861 Mapped regions may contain areas for which there is no device on the
863 If space in those areas is accessed, the results are
865 .Ss Fn bus_space_unmap space handle size
868 function unmaps a region of bus space mapped with
870 When unmapping a region, the
873 the same as the size given to
875 when mapping that region.
879 is called on a handle, that handle is no longer
881 (If copies were made of the handle they are no longer valid,
884 This function will never fail.
885 If it would fail (e.g.\& because of an
886 argument error), that indicates a software bug which should cause a
891 .Ss Fn bus_space_subregion space handle offset size nhandlep
893 .Fn bus_space_subregion
894 function is a convenience function which makes a
895 new handle to some subregion of an already-mapped region of bus space.
896 The subregion described by the new handle starts at byte offset
898 into the region described by
900 with the size give by
902 and must be wholly contained within the original region.
905 .Fn bus_space_subregion
906 returns zero and fills in the bus
907 space handle pointed to by
909 If unsuccessful, it returns non-zero and leaves the bus space handle
914 In either case, the handle described by
916 remains valid and is unmodified.
918 When done with a handle created by
919 .Fn bus_space_subregion ,
922 Under no circumstances should
924 be used on the handle.
925 Doing so may confuse any resource management
926 being done on the space, and will result in undefined behaviour.
931 is called on a handle, all subregions of that handle become invalid.
932 .Sh ALLOCATING AND FREEING BUS SPACE
933 This section is specific to the
935 version of these functions and may or may not apply to the
939 Some devices require or allow bus space to be allocated by the operating
940 system for device use.
941 When the devices no longer need the space, the
942 operating system should free it for use by other devices.
947 functions provide these capabilities.
948 .Ss Fn bus_space_alloc space reg_start reg_end size alignment boundary \
952 function allocates and maps a region of bus space with the size given by
954 corresponding to the given constraints.
955 If successful, it returns
956 zero, fills in the bus address pointed to by
958 with the bus space address of the allocated region, and fills in
959 the bus space handle pointed to by
961 with the handle that can be used to access that region.
962 If unsuccessful, it returns non-zero and leaves the bus address pointed to by
964 and the bus space handle pointed to by
966 in an undefined state.
968 Constraints on the allocation are given by the
969 .Fa reg_start , reg_end , alignment ,
973 The allocated region will start at or after
979 constraint must be a power of two, and the allocated region will start at
980 an address that is an even multiple of that power of two.
983 constraint, if non-zero, ensures that the region is allocated so that
984 .Fa "first address in region"
987 has the same value as
988 .Fa "last address in region"
991 If the constraints cannot be met,
994 It is an error to specify a set of
995 constraints that can never be met
1003 parameter is the same as the like-named parameter to
1005 the same flag values should be used, and they have the
1010 should only be freed with
1011 .Fn bus_space_free .
1014 on them causes undefined behaviour.
1016 .Fn bus_space_subregion
1017 function can be used on
1019 .Fn bus_space_alloc .
1020 .Ss Fn bus_space_free space handle size
1023 function unmaps and frees a region of bus space mapped
1025 .Fn bus_space_alloc .
1026 When unmapping a region, the
1028 specified should be the same as the size given to
1030 when allocating the region.
1034 is called on a handle, that handle is no longer valid.
1036 made of the handle, they are no longer valid, either.)
1038 This function will never fail.
1039 If it would fail (e.g.\& because of an
1040 argument error), that indicates a software bug which should cause a
1045 .Sh READING AND WRITING SINGLE DATA ITEMS
1046 The simplest way to access bus space is to read or write a single data
1049 .Fn bus_space_read_N
1051 .Fn bus_space_write_N
1052 families of functions provide
1053 the ability to read and write 1, 2, 4, and 8 byte data items on buses
1054 which support those access sizes.
1055 .Ss Fn bus_space_read_1 space handle offset
1056 .Ss Fn bus_space_read_2 space handle offset
1057 .Ss Fn bus_space_read_4 space handle offset
1058 .Ss Fn bus_space_read_8 space handle offset
1060 .Fn bus_space_read_N
1061 family of functions reads a 1, 2, 4, or 8 byte data item from
1062 the offset specified by
1064 into the region specified by
1066 of the bus space specified by
1068 The location being read must lie within the bus space region specified by
1071 For portability, the starting address of the region specified by
1073 plus the offset should be a multiple of the size of data item being read.
1074 On some systems, not obeying this requirement may cause incorrect data to
1075 be read, on others it may cause a system crash.
1077 Read operations done by the
1078 .Fn bus_space_read_N
1079 functions may be executed out
1080 of order with respect to other pending read and write operations unless
1081 order is enforced by use of the
1082 .Fn bus_space_barrier
1085 These functions will never fail.
1086 If they would fail (e.g.\& because of an
1087 argument error), that indicates a software bug which should cause a
1089 In that case, they will never return.
1090 .Ss Fn bus_space_write_1 space handle offset value
1091 .Ss Fn bus_space_write_2 space handle offset value
1092 .Ss Fn bus_space_write_4 space handle offset value
1093 .Ss Fn bus_space_write_8 space handle offset value
1095 .Fn bus_space_write_N
1096 family of functions writes a 1, 2, 4, or 8 byte data item to the offset
1099 into the region specified by
1101 of the bus space specified by
1103 The location being written must lie within
1104 the bus space region specified by
1107 For portability, the starting address of the region specified by
1109 plus the offset should be a multiple of the size of data item being
1111 On some systems, not obeying this requirement may cause
1112 incorrect data to be written, on others it may cause a system crash.
1114 Write operations done by the
1115 .Fn bus_space_write_N
1116 functions may be executed
1117 out of order with respect to other pending read and write operations
1118 unless order is enforced by use of the
1119 .Fn bus_space_barrier
1122 These functions will never fail.
1123 If they would fail (e.g.\& because of an
1124 argument error), that indicates a software bug which should cause a
1126 In that case, they will never return.
1128 In order to allow high-performance buffering implementations to avoid bus
1129 activity on every operation, read and write ordering should be specified
1130 explicitly by drivers when necessary.
1132 .Fn bus_space_barrier
1133 function provides that ability.
1134 .Ss Fn bus_space_barrier space handle offset length flags
1136 .Fn bus_space_barrier
1137 function enforces ordering of bus space read and write operations
1138 for the specified subregion (described by the
1142 parameters) of the region named by
1144 in the space named by
1149 argument controls what types of operations are to be ordered.
1150 Supported flags are:
1151 .Bl -tag -width ".Dv BUS_SPACE_BARRIER_WRITE"
1152 .It Dv BUS_SPACE_BARRIER_READ
1153 Synchronize read operations.
1154 .It Dv BUS_SPACE_BARRIER_WRITE
1155 Synchronize write operations.
1158 Those flags can be combined (or-ed together) to enforce ordering on both
1159 read and write operations.
1161 All of the specified type(s) of operation which are done to the region
1162 before the barrier operation are guaranteed to complete before any of the
1163 specified type(s) of operation done after the barrier.
1165 Example: Consider a hypothetical device with two single-byte ports, one
1166 write-only input port (at offset 0) and a read-only output port (at
1168 Operation of the device is as follows: data bytes are written
1169 to the input port, and are placed by the device on a stack, the top of
1170 which is read by reading from the output port.
1171 The sequence to correctly
1172 write two data bytes to the device then read those two data bytes back
1176 * t and h are the tag and handle for the mapped device's
1179 bus_space_write_1(t, h, 0, data0);
1180 bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE); /* 1 */
1181 bus_space_write_1(t, h, 0, data1);
1182 bus_space_barrier(t, h, 0, 2,
1183 BUS_SPACE_BARRIER_READ|BUS_SPACE_BARRIER_WRITE); /* 2 */
1184 ndata1 = bus_space_read_1(t, h, 1);
1185 bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ); /* 3 */
1186 ndata0 = bus_space_read_1(t, h, 1);
1187 /* data0 == ndata0, data1 == ndata1 */
1190 The first barrier makes sure that the first write finishes before the
1191 second write is issued, so that two writes to the input port are done
1192 in order and are not collapsed into a single write.
1194 the data bytes are written to the device correctly and in order.
1196 The second barrier makes sure that the writes to the output port finish
1197 before any of the reads to the input port are issued, thereby making sure
1198 that all of the writes are finished before data is read.
1200 that the first byte read from the device really is the last one that was
1203 The third barrier makes sure that the first read finishes before the
1204 second read is issued, ensuring that data is read correctly and in order.
1206 The barriers in the example above are specified to cover the absolute
1207 minimum number of bus space locations.
1208 It is correct (and often
1209 easier) to make barrier operations cover the device's whole range of bus
1210 space, that is, to specify an offset of zero and the size of the
1212 .Sh REGION OPERATIONS
1213 Some devices use buffers which are mapped as regions in bus space.
1214 Often, drivers want to copy the contents of those buffers to or from
1215 memory, e.g.\& into mbufs which can be passed to higher levels of the
1216 system or from mbufs to be output to a network.
1218 drivers to do this as efficiently as possible, the
1219 .Fn bus_space_read_region_N
1221 .Fn bus_space_write_region_N
1222 families of functions are provided.
1224 Drivers occasionally need to copy one region of a bus space to another,
1225 or to set all locations in a region of bus space to contain a single
1228 .Fn bus_space_copy_region_N
1229 family of functions and the
1230 .Fn bus_space_set_region_N
1231 family of functions allow drivers to perform these operations.
1232 .Ss Fn bus_space_read_region_1 space handle offset datap count
1233 .Ss Fn bus_space_read_region_2 space handle offset datap count
1234 .Ss Fn bus_space_read_region_4 space handle offset datap count
1235 .Ss Fn bus_space_read_region_8 space handle offset datap count
1237 .Fn bus_space_read_region_N
1238 family of functions reads
1240 1, 2, 4, or 8 byte data items from bus space
1241 starting at byte offset
1243 in the region specified by
1245 of the bus space specified by
1247 and writes them into the array specified by
1249 Each successive data item is read from an offset
1250 1, 2, 4, or 8 bytes after the previous data item (depending on which
1252 All locations being read must lie within the bus
1253 space region specified by
1256 For portability, the starting address of the region specified by
1258 plus the offset should be a multiple of the size of data items being
1259 read and the data array pointer should be properly aligned.
1261 systems, not obeying these requirements may cause incorrect data to be
1262 read, on others it may cause a system crash.
1264 Read operations done by the
1265 .Fn bus_space_read_region_N
1266 functions may be executed in any order.
1267 They may also be executed out
1268 of order with respect to other pending read and write operations unless
1269 order is enforced by use of the
1270 .Fn bus_space_barrier
1272 There is no way to insert barriers between reads of
1273 individual bus space locations executed by the
1274 .Fn bus_space_read_region_N
1277 These functions will never fail.
1278 If they would fail (e.g.\& because of an
1279 argument error), that indicates a software bug which should cause a
1281 In that case, they will never return.
1282 .Ss Fn bus_space_write_region_1 space handle offset datap count
1283 .Ss Fn bus_space_write_region_2 space handle offset datap count
1284 .Ss Fn bus_space_write_region_4 space handle offset datap count
1285 .Ss Fn bus_space_write_region_8 space handle offset datap count
1287 .Fn bus_space_write_region_N
1288 family of functions reads
1290 1, 2, 4, or 8 byte data items from the array
1293 and writes them to bus space starting at byte offset
1295 in the region specified by
1297 of the bus space specified
1300 Each successive data item is written to an offset 1, 2, 4,
1301 or 8 bytes after the previous data item (depending on which function is
1303 All locations being written must lie within the bus space region
1307 For portability, the starting address of the region specified by
1309 plus the offset should be a multiple of the size of data items being
1310 written and the data array pointer should be properly aligned.
1312 systems, not obeying these requirements may cause incorrect data to be
1313 written, on others it may cause a system crash.
1315 Write operations done by the
1316 .Fn bus_space_write_region_N
1318 executed in any order.
1319 They may also be executed out of order with
1320 respect to other pending read and write operations unless order is
1321 enforced by use of the
1322 .Fn bus_space_barrier
1324 There is no way to insert barriers between writes of
1325 individual bus space locations executed by the
1326 .Fn bus_space_write_region_N
1329 These functions will never fail.
1330 If they would fail (e.g.\& because of an
1331 argument error), that indicates a software bug which should cause a
1333 In that case, they will never return.
1334 .Ss Fn bus_space_copy_region_1 space srchandle srcoffset dsthandle \
1336 .Ss Fn bus_space_copy_region_2 space srchandle srcoffset dsthandle \
1338 .Ss Fn bus_space_copy_region_4 space srchandle srcoffset dsthandle \
1340 .Ss Fn bus_space_copy_region_8 space srchandle srcoffset dsthandle \
1343 .Fn bus_space_copy_region_N
1344 family of functions copies
1346 1, 2, 4, or 8 byte data items in bus space
1347 from the area starting at byte offset
1349 in the region specified by
1351 of the bus space specified by
1353 to the area starting at byte offset
1355 in the region specified by
1357 in the same bus space.
1358 Each successive data item read or written has
1359 an offset 1, 2, 4, or 8 bytes after the previous data item (depending
1360 on which function is used).
1361 All locations being read and written must
1362 lie within the bus space region specified by their respective handles.
1364 For portability, the starting addresses of the regions specified by the
1365 each handle plus its respective offset should be a multiple of the size
1366 of data items being copied.
1367 On some systems, not obeying this
1368 requirement may cause incorrect data to be copied, on others it may cause
1371 Read and write operations done by the
1372 .Fn bus_space_copy_region_N
1373 functions may be executed in any order.
1374 They may also be executed out
1375 of order with respect to other pending read and write operations unless
1376 order is enforced by use of the
1377 .Fn bus_space_barrier
1379 There is no way to insert barriers between reads or writes of
1380 individual bus space locations executed by the
1381 .Fn bus_space_copy_region_N
1384 Overlapping copies between different subregions of a single region
1385 of bus space are handled correctly by the
1386 .Fn bus_space_copy_region_N
1389 These functions will never fail.
1390 If they would fail (e.g.\& because of an
1391 argument error), that indicates a software bug which should cause a
1393 In that case, they will never return.
1394 .Ss Fn bus_space_set_region_1 space handle offset value count
1395 .Ss Fn bus_space_set_region_2 space handle offset value count
1396 .Ss Fn bus_space_set_region_4 space handle offset value count
1397 .Ss Fn bus_space_set_region_8 space handle offset value count
1399 .Fn bus_space_set_region_N
1400 family of functions writes the given
1405 data items in bus space starting at byte offset
1407 in the region specified by
1409 of the bus space specified by
1411 Each successive data item has an offset 1, 2, 4, or 8 bytes after the
1412 previous data item (depending on which function is used).
1414 locations being written must lie within the bus space region specified
1418 For portability, the starting address of the region specified by
1420 plus the offset should be a multiple of the size of data items being
1422 On some systems, not obeying this requirement may cause
1423 incorrect data to be written, on others it may cause a system crash.
1425 Write operations done by the
1426 .Fn bus_space_set_region_N
1428 executed in any order.
1429 They may also be executed out of order with
1430 respect to other pending read and write operations unless order is
1431 enforced by use of the
1432 .Fn bus_space_barrier
1434 There is no way to insert barriers between writes of
1435 individual bus space locations executed by the
1436 .Fn bus_space_set_region_N
1439 These functions will never fail.
1440 If they would fail (e.g.\& because of an
1441 argument error), that indicates a software bug which should cause a
1443 In that case, they will never return.
1444 .Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES
1445 Some devices implement single locations in bus space which are to be read
1446 or written multiple times to communicate data, e.g.\& some ethernet
1447 devices' packet buffer FIFOs.
1448 In order to allow drivers to manipulate
1449 these types of devices as efficiently as possible, the
1450 .Fn bus_space_read_multi_N ,
1451 .Fn bus_space_set_multi_N ,
1453 .Fn bus_space_write_multi_N
1454 families of functions are provided.
1455 .Ss Fn bus_space_read_multi_1 space handle offset datap count
1456 .Ss Fn bus_space_read_multi_2 space handle offset datap count
1457 .Ss Fn bus_space_read_multi_4 space handle offset datap count
1458 .Ss Fn bus_space_read_multi_8 space handle offset datap count
1460 .Fn bus_space_read_multi_N
1461 family of functions reads
1463 1, 2, 4, or 8 byte data items from bus space
1466 in the region specified by
1468 of the bus space specified by
1470 and writes them into the array specified by
1472 Each successive data item is read from the same location in bus
1474 The location being read must lie within the bus space region
1478 For portability, the starting address of the region specified by
1480 plus the offset should be a multiple of the size of data items being
1481 read and the data array pointer should be properly aligned.
1483 systems, not obeying these requirements may cause incorrect data to be
1484 read, on others it may cause a system crash.
1486 Read operations done by the
1487 .Fn bus_space_read_multi_N
1489 executed out of order with respect to other pending read and write
1490 operations unless order is enforced by use of the
1491 .Fn bus_space_barrier
1494 .Fn bus_space_read_multi_N
1495 functions read the same bus space location multiple times, they
1496 place an implicit read barrier between each successive read of that bus
1499 These functions will never fail.
1500 If they would fail (e.g.\& because of an
1501 argument error), that indicates a software bug which should cause a
1503 In that case, they will never return.
1504 .Ss Fn bus_space_write_multi_1 space handle offset datap count
1505 .Ss Fn bus_space_write_multi_2 space handle offset datap count
1506 .Ss Fn bus_space_write_multi_4 space handle offset datap count
1507 .Ss Fn bus_space_write_multi_8 space handle offset datap count
1509 .Fn bus_space_write_multi_N
1510 family of functions reads
1512 1, 2, 4, or 8 byte data items from the array
1515 and writes them into bus space at byte offset
1517 in the region specified by
1519 of the bus space specified by
1521 Each successive data item is written to the same location in
1523 The location being written must lie within the bus space
1527 For portability, the starting address of the region specified by
1529 plus the offset should be a multiple of the size of data items being
1530 written and the data array pointer should be properly aligned.
1532 systems, not obeying these requirements may cause incorrect data to be
1533 written, on others it may cause a system crash.
1535 Write operations done by the
1536 .Fn bus_space_write_multi_N
1537 functions may be executed out of order with respect to other pending
1538 read and write operations unless order is enforced by use of the
1539 .Fn bus_space_barrier
1542 .Fn bus_space_write_multi_N
1543 functions write the same bus space location multiple times, they
1544 place an implicit write barrier between each successive write of that
1547 These functions will never fail.
1548 If they would fail (e.g.\& because of an
1549 argument error), that indicates a software bug which should cause a
1551 In that case, they will never return.
1552 .Ss Fn bus_space_set_multi_1 space handle offset value count
1553 .Ss Fn bus_space_set_multi_2 space handle offset value count
1554 .Ss Fn bus_space_set_multi_4 space handle offset value count
1555 .Ss Fn bus_space_set_multi_8 space handle offset value count
1557 .Fn bus_space_set_multi_N
1560 into bus space at byte offset
1562 in the region specified by
1564 of the bus space specified by
1568 The location being written must lie within the bus space
1572 For portability, the starting address of the region specified by
1574 plus the offset should be a multiple of the size of data items being
1575 written and the data array pointer should be properly aligned.
1577 systems, not obeying these requirements may cause incorrect data to be
1578 written, on others it may cause a system crash.
1580 Write operations done by the
1581 .Fn bus_space_set_multi_N
1582 functions may be executed out of order with respect to other pending
1583 read and write operations unless order is enforced by use of the
1584 .Fn bus_space_barrier
1587 .Fn bus_space_set_multi_N
1588 functions write the same bus space location multiple times, they
1589 place an implicit write barrier between each successive write of that
1592 These functions will never fail.
1593 If they would fail (e.g.\& because of an
1594 argument error), that indicates a software bug which should cause a
1596 In that case, they will never return.
1597 .Sh STREAM FUNCTIONS
1600 functions imply a host byte-order and a bus byte-order and take care of
1601 any translation for the caller.
1602 In some cases, however, hardware may map a FIFO or some other memory region
1603 for which the caller may want to use multi-word, yet untranslated access.
1604 Access to these types of memory regions should be with the
1605 .Fn bus_space_*_stream_N
1608 .Bl -tag -compact -width Fn
1609 .It Fn bus_space_read_stream_1
1610 .It Fn bus_space_read_stream_2
1611 .It Fn bus_space_read_stream_4
1612 .It Fn bus_space_read_stream_8
1613 .It Fn bus_space_read_multi_stream_1
1614 .It Fn bus_space_read_multi_stream_2
1615 .It Fn bus_space_read_multi_stream_4
1616 .It Fn bus_space_read_multi_stream_8
1617 .It Fn bus_space_read_region_stream_1
1618 .It Fn bus_space_read_region_stream_2
1619 .It Fn bus_space_read_region_stream_4
1620 .It Fn bus_space_read_region_stream_8
1621 .It Fn bus_space_write_stream_1
1622 .It Fn bus_space_write_stream_2
1623 .It Fn bus_space_write_stream_4
1624 .It Fn bus_space_write_stream_8
1625 .It Fn bus_space_write_multi_stream_1
1626 .It Fn bus_space_write_multi_stream_2
1627 .It Fn bus_space_write_multi_stream_4
1628 .It Fn bus_space_write_multi_stream_8
1629 .It Fn bus_space_write_region_stream_1
1630 .It Fn bus_space_write_region_stream_2
1631 .It Fn bus_space_write_region_stream_4
1632 .It Fn bus_space_write_region_stream_8
1633 .It Fn bus_space_copy_region_stream_1
1634 .It Fn bus_space_copy_region_stream_2
1635 .It Fn bus_space_copy_region_stream_4
1636 .It Fn bus_space_copy_region_stream_8
1637 .It Fn bus_space_set_multi_stream_1
1638 .It Fn bus_space_set_multi_stream_2
1639 .It Fn bus_space_set_multi_stream_4
1640 .It Fn bus_space_set_multi_stream_8
1641 .It Fn bus_space_set_region_stream_1
1642 .It Fn bus_space_set_region_stream_2
1643 .It Fn bus_space_set_region_stream_4
1644 .It Fn bus_space_set_region_stream_8
1647 These functions are defined just as their non-stream counterparts,
1648 except that they provide no byte-order translation.
1654 interface specification differs slightly from the original
1655 specification that came into wide use and
1658 A few of the function names and arguments have changed
1659 for consistency and increased functionality.
1665 functions were introduced in a different form (memory and I/O spaces
1666 were accessed via different sets of functions) in
1668 The functions were merged to work on generic
1672 development cycle, and many drivers were converted to use them.
1673 This document was written later during the
1675 development cycle, and the specification was updated to fix some
1676 consistency problems and to add some missing functionality.
1678 The manual page was then adapted to the version of the interface that
1680 imported for the CAM SCSI drivers, plus subsequent evolution.
1684 version was imported in
1690 interfaces were designed and implemented by the
1694 Primary contributors and implementors were
1695 .An Chris Demetriou ,
1698 .An Charles Hannum ,
1701 developers and the user community played a significant role in development.
1704 ported these interfaces to
1708 wrote this manual page.
1715 This manual may not completely and accurately document the interface,
1716 and many parts of the interface are unspecified.