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.
40 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
41 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
42 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
43 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
44 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
45 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
46 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
47 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
48 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
50 .\" POSSIBILITY OF SUCH DAMAGE.
59 .Nm bus_space_barrier ,
60 .Nm bus_space_copy_region_1 ,
61 .Nm bus_space_copy_region_2 ,
62 .Nm bus_space_copy_region_4 ,
63 .Nm bus_space_copy_region_8 ,
64 .Nm bus_space_copy_region_stream_1 ,
65 .Nm bus_space_copy_region_stream_2 ,
66 .Nm bus_space_copy_region_stream_4 ,
67 .Nm bus_space_copy_region_stream_8 ,
70 .Nm bus_space_read_1 ,
71 .Nm bus_space_read_2 ,
72 .Nm bus_space_read_4 ,
73 .Nm bus_space_read_8 ,
74 .Nm bus_space_read_multi_1 ,
75 .Nm bus_space_read_multi_2 ,
76 .Nm bus_space_read_multi_4 ,
77 .Nm bus_space_read_multi_8 ,
78 .Nm bus_space_read_multi_stream_1 ,
79 .Nm bus_space_read_multi_stream_2 ,
80 .Nm bus_space_read_multi_stream_4 ,
81 .Nm bus_space_read_multi_stream_8 ,
82 .Nm bus_space_read_region_1 ,
83 .Nm bus_space_read_region_2 ,
84 .Nm bus_space_read_region_4 ,
85 .Nm bus_space_read_region_8 ,
86 .Nm bus_space_read_region_stream_1 ,
87 .Nm bus_space_read_region_stream_2 ,
88 .Nm bus_space_read_region_stream_4 ,
89 .Nm bus_space_read_region_stream_8 ,
90 .Nm bus_space_read_stream_1 ,
91 .Nm bus_space_read_stream_2 ,
92 .Nm bus_space_read_stream_4 ,
93 .Nm bus_space_read_stream_8 ,
94 .Nm bus_space_set_multi_1 ,
95 .Nm bus_space_set_multi_2 ,
96 .Nm bus_space_set_multi_4 ,
97 .Nm bus_space_set_multi_8 ,
98 .Nm bus_space_set_multi_stream_1 ,
99 .Nm bus_space_set_multi_stream_2 ,
100 .Nm bus_space_set_multi_stream_4 ,
101 .Nm bus_space_set_multi_stream_8 ,
102 .Nm bus_space_set_region_1 ,
103 .Nm bus_space_set_region_2 ,
104 .Nm bus_space_set_region_4 ,
105 .Nm bus_space_set_region_8 ,
106 .Nm bus_space_set_region_stream_1 ,
107 .Nm bus_space_set_region_stream_2 ,
108 .Nm bus_space_set_region_stream_4 ,
109 .Nm bus_space_set_region_stream_8 ,
110 .Nm bus_space_subregion ,
111 .Nm bus_space_unmap ,
112 .Nm bus_space_write_1 ,
113 .Nm bus_space_write_2 ,
114 .Nm bus_space_write_4 ,
115 .Nm bus_space_write_8 ,
116 .Nm bus_space_write_multi_1 ,
117 .Nm bus_space_write_multi_2 ,
118 .Nm bus_space_write_multi_4 ,
119 .Nm bus_space_write_multi_8 ,
120 .Nm bus_space_write_multi_stream_1 ,
121 .Nm bus_space_write_multi_stream_2 ,
122 .Nm bus_space_write_multi_stream_4 ,
123 .Nm bus_space_write_multi_stream_8 ,
124 .Nm bus_space_write_region_1 ,
125 .Nm bus_space_write_region_2 ,
126 .Nm bus_space_write_region_4 ,
127 .Nm bus_space_write_region_8 ,
128 .Nm bus_space_write_region_stream_1 ,
129 .Nm bus_space_write_region_stream_2 ,
130 .Nm bus_space_write_region_stream_4 ,
131 .Nm bus_space_write_region_stream_8 ,
132 .Nm bus_space_write_stream_1 ,
133 .Nm bus_space_write_stream_2 ,
134 .Nm bus_space_write_stream_4 ,
135 .Nm bus_space_write_stream_8
136 .Nd "bus space manipulation functions"
141 .Fa "bus_space_tag_t space" "bus_addr_t address"
142 .Fa "bus_size_t size" "int flags" "bus_space_handle_t *handlep"
146 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size"
149 .Fo bus_space_subregion
150 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
151 .Fa "bus_size_t offset" "bus_size_t size" "bus_space_handle_t *nhandlep"
155 .Fa "bus_space_tag_t space" "bus_addr_t reg_start" "bus_addr_t reg_end"
156 .Fa "bus_size_t size" "bus_size_t alignment" "bus_size_t boundary"
157 .Fa "int flags" "bus_addr_t *addrp" "bus_space_handle_t *handlep"
161 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size"
165 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
169 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
173 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
177 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
180 .Fo bus_space_read_stream_1
181 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
184 .Fo bus_space_read_stream_2
185 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
188 .Fo bus_space_read_stream_4
189 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
192 .Fo bus_space_read_stream_8
193 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
196 .Fo bus_space_write_1
197 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
198 .Fa "bus_size_t offset" "uint8_t value"
201 .Fo bus_space_write_2
202 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
203 .Fa "bus_size_t offset" "uint16_t value"
206 .Fo bus_space_write_4
207 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
208 .Fa "bus_size_t offset" "uint32_t value"
211 .Fo bus_space_write_8
212 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
213 .Fa "bus_size_t offset" "uint64_t value"
216 .Fo bus_space_write_stream_1
217 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
218 .Fa "bus_size_t offset" "uint8_t value"
221 .Fo bus_space_write_stream_2
222 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
223 .Fa "bus_size_t offset" "uint16_t value"
226 .Fo bus_space_write_stream_4
227 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
228 .Fa "bus_size_t offset" "uint32_t value"
231 .Fo bus_space_write_stream_8
232 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
233 .Fa "bus_size_t offset" "uint64_t value"
236 .Fo bus_space_barrier
237 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
238 .Fa "bus_size_t offset" "bus_size_t length" "int flags"
241 .Fo bus_space_read_region_1
242 .Fa "bus_space_tag_t space"
243 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
244 .Fa "bus_size_t count"
247 .Fo bus_space_read_region_2
248 .Fa "bus_space_tag_t space"
249 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
250 .Fa "bus_size_t count"
253 .Fo bus_space_read_region_4
254 .Fa "bus_space_tag_t space"
255 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
256 .Fa "bus_size_t count"
259 .Fo bus_space_read_region_8
260 .Fa "bus_space_tag_t space"
261 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
262 .Fa "bus_size_t count"
265 .Fo bus_space_read_region_stream_1
266 .Fa "bus_space_tag_t space"
267 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
268 .Fa "bus_size_t count"
271 .Fo bus_space_read_region_stream_2
272 .Fa "bus_space_tag_t space"
273 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
274 .Fa "bus_size_t count"
277 .Fo bus_space_read_region_stream_4
278 .Fa "bus_space_tag_t space"
279 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
280 .Fa "bus_size_t count"
283 .Fo bus_space_read_region_stream_8
284 .Fa "bus_space_tag_t space"
285 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
286 .Fa "bus_size_t count"
289 .Fo bus_space_write_region_1
290 .Fa "bus_space_tag_t space"
291 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
292 .Fa "bus_size_t count"
295 .Fo bus_space_write_region_2
296 .Fa "bus_space_tag_t space"
297 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
298 .Fa "bus_size_t count"
301 .Fo bus_space_write_region_4
302 .Fa "bus_space_tag_t space"
303 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
304 .Fa "bus_size_t count"
307 .Fo bus_space_write_region_8
308 .Fa "bus_space_tag_t space"
309 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
310 .Fa "bus_size_t count"
313 .Fo bus_space_write_region_stream_1
314 .Fa "bus_space_tag_t space"
315 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
316 .Fa "bus_size_t count"
319 .Fo bus_space_write_region_stream_2
320 .Fa "bus_space_tag_t space"
321 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
322 .Fa "bus_size_t count"
325 .Fo bus_space_write_region_stream_4
326 .Fa "bus_space_tag_t space"
327 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
328 .Fa "bus_size_t count"
331 .Fo bus_space_write_region_stream_8
332 .Fa "bus_space_tag_t space"
333 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
334 .Fa "bus_size_t count"
337 .Fo bus_space_copy_region_1
338 .Fa "bus_space_tag_t space"
339 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
340 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
343 .Fo bus_space_copy_region_2
344 .Fa "bus_space_tag_t space"
345 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
346 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
349 .Fo bus_space_copy_region_4
350 .Fa "bus_space_tag_t space"
351 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
352 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
355 .Fo bus_space_copy_region_8
356 .Fa "bus_space_tag_t space"
357 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
358 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
361 .Fo bus_space_copy_region_stream_1
362 .Fa "bus_space_tag_t space"
363 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
364 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
367 .Fo bus_space_copy_region_stream_2
368 .Fa "bus_space_tag_t space"
369 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
370 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
373 .Fo bus_space_copy_region_stream_4
374 .Fa "bus_space_tag_t space"
375 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
376 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
379 .Fo bus_space_copy_region_stream_8
380 .Fa "bus_space_tag_t space"
381 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
382 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
385 .Fo bus_space_set_region_1
386 .Fa "bus_space_tag_t space"
387 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
388 .Fa "bus_size_t count"
391 .Fo bus_space_set_region_2
392 .Fa "bus_space_tag_t space"
393 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
394 .Fa "bus_size_t count"
397 .Fo bus_space_set_region_4
398 .Fa "bus_space_tag_t space"
399 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
400 .Fa "bus_size_t count"
403 .Fo bus_space_set_region_8
404 .Fa "bus_space_tag_t space"
405 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
406 .Fa "bus_size_t count"
409 .Fo bus_space_set_region_stream_1
410 .Fa "bus_space_tag_t space"
411 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
412 .Fa "bus_size_t count"
415 .Fo bus_space_set_region_stream_2
416 .Fa "bus_space_tag_t space"
417 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
418 .Fa "bus_size_t count"
421 .Fo bus_space_set_region_stream_4
422 .Fa "bus_space_tag_t space"
423 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
424 .Fa "bus_size_t count"
427 .Fo bus_space_set_region_stream_8
428 .Fa "bus_space_tag_t space"
429 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
430 .Fa "bus_size_t count"
433 .Fo bus_space_read_multi_1
434 .Fa "bus_space_tag_t space"
435 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
436 .Fa "bus_size_t count"
439 .Fo bus_space_read_multi_2
440 .Fa "bus_space_tag_t space"
441 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
442 .Fa "bus_size_t count"
445 .Fo bus_space_read_multi_4
446 .Fa "bus_space_tag_t space"
447 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
448 .Fa "bus_size_t count"
451 .Fo bus_space_read_multi_8
452 .Fa "bus_space_tag_t space"
453 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
454 .Fa "bus_size_t count"
457 .Fo bus_space_read_multi_stream_1
458 .Fa "bus_space_tag_t space"
459 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
460 .Fa "bus_size_t count"
463 .Fo bus_space_read_multi_stream_2
464 .Fa "bus_space_tag_t space"
465 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
466 .Fa "bus_size_t count"
469 .Fo bus_space_read_multi_stream_4
470 .Fa "bus_space_tag_t space"
471 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
472 .Fa "bus_size_t count"
475 .Fo bus_space_read_multi_stream_8
476 .Fa "bus_space_tag_t space"
477 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
478 .Fa "bus_size_t count"
481 .Fo bus_space_write_multi_1
482 .Fa "bus_space_tag_t space"
483 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
484 .Fa "bus_size_t count"
487 .Fo bus_space_write_multi_2
488 .Fa "bus_space_tag_t space"
489 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
490 .Fa "bus_size_t count"
493 .Fo bus_space_write_multi_4
494 .Fa "bus_space_tag_t space"
495 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
496 .Fa "bus_size_t count"
499 .Fo bus_space_write_multi_8
500 .Fa "bus_space_tag_t space"
501 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
502 .Fa "bus_size_t count"
505 .Fo bus_space_write_multi_stream_1
506 .Fa "bus_space_tag_t space"
507 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap"
508 .Fa "bus_size_t count"
511 .Fo bus_space_write_multi_stream_2
512 .Fa "bus_space_tag_t space"
513 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap"
514 .Fa "bus_size_t count"
517 .Fo bus_space_write_multi_stream_4
518 .Fa "bus_space_tag_t space"
519 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap"
520 .Fa "bus_size_t count"
523 .Fo bus_space_write_multi_stream_8
524 .Fa "bus_space_tag_t space"
525 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap"
526 .Fa "bus_size_t count"
529 .Fo bus_space_set_multi_1
530 .Fa "bus_space_tag_t space"
531 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
532 .Fa "bus_size_t count"
535 .Fo bus_space_set_multi_2
536 .Fa "bus_space_tag_t space"
537 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
538 .Fa "bus_size_t count"
541 .Fo bus_space_set_multi_4
542 .Fa "bus_space_tag_t space"
543 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
544 .Fa "bus_size_t count"
547 .Fo bus_space_set_multi_8
548 .Fa "bus_space_tag_t space"
549 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
550 .Fa "bus_size_t count"
553 .Fo bus_space_set_multi_stream_1
554 .Fa "bus_space_tag_t space"
555 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value"
556 .Fa "bus_size_t count"
559 .Fo bus_space_set_multi_stream_2
560 .Fa "bus_space_tag_t space"
561 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value"
562 .Fa "bus_size_t count"
565 .Fo bus_space_set_multi_stream_4
566 .Fa "bus_space_tag_t space"
567 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value"
568 .Fa "bus_size_t count"
571 .Fo bus_space_set_multi_stream_8
572 .Fa "bus_space_tag_t space"
573 .Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value"
574 .Fa "bus_size_t count"
579 functions exist to allow device drivers
580 machine-independent access to bus memory and register areas.
582 functions and types described in this document can be used by including
587 Many common devices are used on multiple architectures, but are accessed
588 differently on each because of architectural constraints.
589 For instance, a device which is mapped in one system's I/O space may be
590 mapped in memory space on a second system.
591 On a third system, architectural
592 limitations might change the way registers need to be accessed (e.g.\&
593 creating a non-linear register space).
594 In some cases, a single
595 driver may need to access the same type of device in multiple ways in a
596 single system or architecture.
599 functions is to allow a single driver source file to manipulate a set
600 of devices on different system architectures, and to allow a single driver
601 object file to manipulate a set of devices on multiple bus types on a
604 Not all busses have to implement all functions described in this
605 document, though that is encouraged if the operations are logically
606 supported by the bus.
607 Unimplemented functions should cause
608 compile-time errors if possible.
610 All of the interface definitions described in this document are shown as
611 function prototypes and discussed as if they were required to be
613 Implementations are encouraged to implement prototyped
614 (type-checked) versions of these interfaces, but may implement them as
615 macros if appropriate.
616 Machine-dependent types, variables, and functions
617 should be marked clearly in
619 to avoid confusion with the
620 machine-independent types and functions, and, if possible, should be
621 given names which make the machine-dependence clear.
622 .Sh CONCEPTS AND GUIDELINES
623 Bus spaces are described by bus space tags, which can be created only by
624 machine-dependent code.
625 A given machine may have several different types
626 of bus space (e.g.\& memory space and I/O space), and thus may provide
627 multiple different bus space tags.
628 Individual busses or devices on a machine may use more than one bus space
630 For instance, ISA devices are
631 given an ISA memory space tag and an ISA I/O space tag.
633 may have several different tags which represent the same type of
634 space, for instance because of multiple different host bus interface
637 A range in bus space is described by a bus address and a bus size.
639 bus address describes the start of the range in bus space.
641 size describes the size of the range in bytes.
642 Busses which are not byte
643 addressable may require use of bus space ranges with appropriately
644 aligned addresses and properly rounded sizes.
646 Access to regions of bus space is facilitated by use of bus space handles,
647 which are usually created by mapping a specific range of a bus space.
648 Handles may also be created by allocating
649 and mapping a range of bus space, the actual location of which is picked
650 by the implementation within bounds specified by the caller of the
653 All of the bus space access functions require one bus space tag
654 argument, at least one handle argument, and at least one offset argument
656 The bus space tag specifies the space, each handle specifies a region in
657 the space, and each offset specifies the offset into the region of the
658 actual location(s) to be accessed.
659 Offsets are given in bytes, though busses
660 may impose alignment constraints.
661 The offset used to access data
662 relative to a given handle must be such that all of the data being
663 accessed is in the mapped region that the handle describes.
665 access data outside that region is an error.
667 Because some architectures' memory systems use buffering to improve
668 memory and device access performance, there is a mechanism which can be
671 in the bus space read and write stream.
673 are three types of barriers: read, write, and read/write.
675 started to the region before a read barrier must complete before any reads
676 after the read barrier are started.
677 (The analogous requirement is true for
679 Read/write barriers force all reads and writes started
680 before the barrier to complete before any reads or writes after the
682 Correctly-written drivers will include all
683 appropriate barriers, and assume only the read/write ordering imposed by
684 the barrier operations.
686 People trying to write portable drivers with the
689 try to make minimal assumptions about what the system allows.
691 they should expect that the system requires bus space addresses being
692 accessed to be naturally aligned (i.e., base address of handle added to
693 offset is a multiple of the access size), and that the system does
694 alignment checking on pointers (i.e., pointer to objects being read and
695 written must point to properly-aligned data).
697 The descriptions of the
699 functions given below all assume that
700 they are called with proper arguments.
701 If called with invalid arguments
702 or arguments that are out of range (e.g.\& trying to access data outside of
703 the region mapped when a given handle was created), undefined behaviour
705 In that case, they may cause the
706 system to halt, either intentionally (via panic) or unintentionally (by
707 causing a fatal trap of by some other means) or may cause improper
708 operation which is not immediately fatal.
709 Functions which return
711 or which return data read from bus space (i.e., functions which
712 do not obviously return an error code) do not fail.
714 if given invalid arguments, and in that case their behaviour is undefined.
715 Functions which take a count of bytes have undefined results if the specified
719 Several types are defined in
721 to facilitate use of the
723 functions by drivers.
727 type is used to describe bus addresses.
729 unsigned integral type
730 capable of holding the largest bus address usable by the architecture.
732 type is primarily used when mapping and unmapping bus space.
736 type is used to describe sizes of ranges in bus space.
738 unsigned integral type capable of holding the size of the largest bus
739 address range usable on the architecture.
740 This type is used by virtually all
743 functions, describing sizes when mapping regions and
744 offsets into regions when performing space access operations.
745 .Ss Vt bus_space_tag_t
748 type is used to describe a particular bus space on a machine.
750 contents are machine-dependent and should be considered opaque by
751 machine-independent code.
752 This type is used by all
754 functions to name the space on which they are operating.
755 .Ss Vt bus_space_handle_t
757 .Vt bus_space_handle_t
758 type is used to describe a mapping of a range of bus space.
760 contents are machine-dependent and should be considered opaque by
761 machine-independent code.
762 This type is used when performing bus space
764 .Sh MAPPING AND UNMAPPING BUS SPACE
765 This section is specific to the
767 version of these functions and may or may not apply to the
771 Bus space must be mapped before it can be used, and should be
772 unmapped when it is no longer needed.
777 functions provide these capabilities.
779 Some drivers need to be able to pass a subregion of already-mapped bus
780 space to another driver or module within a driver.
782 .Fn bus_space_subregion
783 function allows such subregions to be created.
784 .Ss Fn bus_space_map space address size flags handlep
787 function maps the region of bus space named by the
788 .Fa space , address ,
792 If successful, it returns zero
793 and fills in the bus space handle pointed to by
796 that can be used to access the mapped region.
798 it will return non-zero and leave the bus space handle pointed
801 in an undefined state.
805 argument controls how the space is to be mapped.
806 Supported flags include:
807 .Bl -tag -width ".Dv BUS_SPACE_MAP_CACHEABLE"
808 .It Dv BUS_SPACE_MAP_CACHEABLE
809 Try to map the space so that accesses can be cached and/or
810 prefetched by the system.
811 If this flag is not specified, the
812 implementation should map the space so that it will not be cached or
815 This flag must have a value of 1 on all implementations for backward
817 .It Dv BUS_SPACE_MAP_LINEAR
818 Try to map the space so that its contents can be accessed linearly via
819 normal memory access methods (e.g.\& pointer dereferencing and structure
821 This is useful when software wants to do direct access to a memory
822 device, e.g.\& a frame buffer.
823 If this flag is specified and linear
824 mapping is not possible, the
828 flag is not specified, the system may map the space in whatever way is
832 Not all combinations of flags make sense or are supported with all
835 .Dv BUS_SPACE_MAP_CACHEABLE
836 may be meaningless when
837 used on many systems' I/O port spaces, and on some systems
838 .Dv BUS_SPACE_MAP_LINEAR
840 .Dv BUS_SPACE_MAP_CACHEABLE
842 When the system hardware or firmware provides hints as to how spaces should be
843 mapped (e.g.\& the PCI memory mapping registers'
846 hints should be followed for maximum compatibility.
848 requesting a mapping that cannot be satisfied (e.g.\& requesting a
849 non-cacheable mapping when the system can only provide a cacheable one)
850 will cause the request to fail.
852 Some implementations may keep track of use of bus space for some or all
853 bus spaces and refuse to allow duplicate allocations.
855 for bus spaces which have no notion of slot-specific space addressing,
856 such as ISA and VME, and for spaces which coexist with those spaces
857 (e.g.\& EISA and PCI memory and I/O spaces co-existing with ISA memory and
860 Mapped regions may contain areas for which there is no device on the
862 If space in those areas is accessed, the results are
864 .Ss Fn bus_space_unmap space handle size
867 function unmaps a region of bus space mapped with
869 When unmapping a region, the
872 the same as the size given to
874 when mapping that region.
878 is called on a handle, that handle is no longer
880 (If copies were made of the handle they are no longer valid,
883 This function will never fail.
884 If it would fail (e.g.\& because of an
885 argument error), that indicates a software bug which should cause a
890 .Ss Fn bus_space_subregion space handle offset size nhandlep
892 .Fn bus_space_subregion
893 function is a convenience function which makes a
894 new handle to some subregion of an already-mapped region of bus space.
895 The subregion described by the new handle starts at byte offset
897 into the region described by
899 with the size give by
901 and must be wholly contained within the original region.
904 .Fn bus_space_subregion
905 returns zero and fills in the bus
906 space handle pointed to by
908 If unsuccessful, it returns non-zero and leaves the bus space handle
913 In either case, the handle described by
915 remains valid and is unmodified.
917 When done with a handle created by
918 .Fn bus_space_subregion ,
921 Under no circumstances should
923 be used on the handle.
924 Doing so may confuse any resource management
925 being done on the space, and will result in undefined behaviour.
930 is called on a handle, all subregions of that handle become invalid.
931 .Sh ALLOCATING AND FREEING BUS SPACE
932 This section is specific to the
934 version of these functions and may or may not apply to the
938 Some devices require or allow bus space to be allocated by the operating
939 system for device use.
940 When the devices no longer need the space, the
941 operating system should free it for use by other devices.
946 functions provide these capabilities.
947 .Ss Fn bus_space_alloc space reg_start reg_end size alignment boundary \
951 function allocates and maps a region of bus space with the size given by
953 corresponding to the given constraints.
954 If successful, it returns
955 zero, fills in the bus address pointed to by
957 with the bus space address of the allocated region, and fills in
958 the bus space handle pointed to by
960 with the handle that can be used to access that region.
961 If unsuccessful, it returns non-zero and leaves the bus address pointed to by
963 and the bus space handle pointed to by
965 in an undefined state.
967 Constraints on the allocation are given by the
968 .Fa reg_start , reg_end , alignment ,
972 The allocated region will start at or after
978 constraint must be a power of two, and the allocated region will start at
979 an address that is an even multiple of that power of two.
982 constraint, if non-zero, ensures that the region is allocated so that
983 .Fa "first address in region"
986 has the same value as
987 .Fa "last address in region"
990 If the constraints cannot be met,
993 It is an error to specify a set of
994 constraints that can never be met
1002 parameter is the same as the like-named parameter to
1004 the same flag values should be used, and they have the
1009 should only be freed with
1010 .Fn bus_space_free .
1013 on them causes undefined behaviour.
1015 .Fn bus_space_subregion
1016 function can be used on
1018 .Fn bus_space_alloc .
1019 .Ss Fn bus_space_free space handle size
1022 function unmaps and frees a region of bus space mapped
1024 .Fn bus_space_alloc .
1025 When unmapping a region, the
1027 specified should be the same as the size given to
1029 when allocating the region.
1033 is called on a handle, that handle is no longer valid.
1035 made of the handle, they are no longer valid, either.)
1037 This function will never fail.
1038 If it would fail (e.g.\& because of an
1039 argument error), that indicates a software bug which should cause a
1044 .Sh READING AND WRITING SINGLE DATA ITEMS
1045 The simplest way to access bus space is to read or write a single data
1048 .Fn bus_space_read_N
1050 .Fn bus_space_write_N
1051 families of functions provide
1052 the ability to read and write 1, 2, 4, and 8 byte data items on busses
1053 which support those access sizes.
1054 .Ss Fn bus_space_read_1 space handle offset
1055 .Ss Fn bus_space_read_2 space handle offset
1056 .Ss Fn bus_space_read_4 space handle offset
1057 .Ss Fn bus_space_read_8 space handle offset
1059 .Fn bus_space_read_N
1060 family of functions reads a 1, 2, 4, or 8 byte data item from
1061 the offset specified by
1063 into the region specified by
1065 of the bus space specified by
1067 The location being read must lie within the bus space region specified by
1070 For portability, the starting address of the region specified by
1072 plus the offset should be a multiple of the size of data item being read.
1073 On some systems, not obeying this requirement may cause incorrect data to
1074 be read, on others it may cause a system crash.
1076 Read operations done by the
1077 .Fn bus_space_read_N
1078 functions may be executed out
1079 of order with respect to other pending read and write operations unless
1080 order is enforced by use of the
1081 .Fn bus_space_barrier
1084 These functions will never fail.
1085 If they would fail (e.g.\& because of an
1086 argument error), that indicates a software bug which should cause a
1088 In that case, they will never return.
1089 .Ss Fn bus_space_write_1 space handle offset value
1090 .Ss Fn bus_space_write_2 space handle offset value
1091 .Ss Fn bus_space_write_4 space handle offset value
1092 .Ss Fn bus_space_write_8 space handle offset value
1094 .Fn bus_space_write_N
1095 family of functions writes a 1, 2, 4, or 8 byte data item to the offset
1098 into the region specified by
1100 of the bus space specified by
1102 The location being written must lie within
1103 the bus space region specified by
1106 For portability, the starting address of the region specified by
1108 plus the offset should be a multiple of the size of data item being
1110 On some systems, not obeying this requirement may cause
1111 incorrect data to be written, on others it may cause a system crash.
1113 Write operations done by the
1114 .Fn bus_space_write_N
1115 functions may be executed
1116 out of order with respect to other pending read and write operations
1117 unless order is enforced by use of the
1118 .Fn bus_space_barrier
1121 These functions will never fail.
1122 If they would fail (e.g.\& because of an
1123 argument error), that indicates a software bug which should cause a
1125 In that case, they will never return.
1127 In order to allow high-performance buffering implementations to avoid bus
1128 activity on every operation, read and write ordering should be specified
1129 explicitly by drivers when necessary.
1131 .Fn bus_space_barrier
1132 function provides that ability.
1133 .Ss Fn bus_space_barrier space handle offset length flags
1135 .Fn bus_space_barrier
1136 function enforces ordering of bus space read and write operations
1137 for the specified subregion (described by the
1141 parameters) of the region named by
1143 in the space named by
1148 argument controls what types of operations are to be ordered.
1149 Supported flags are:
1150 .Bl -tag -width ".Dv BUS_SPACE_BARRIER_WRITE"
1151 .It Dv BUS_SPACE_BARRIER_READ
1152 Synchronize read operations.
1153 .It Dv BUS_SPACE_BARRIER_WRITE
1154 Synchronize write operations.
1157 Those flags can be combined (or-ed together) to enforce ordering on both
1158 read and write operations.
1160 All of the specified type(s) of operation which are done to the region
1161 before the barrier operation are guaranteed to complete before any of the
1162 specified type(s) of operation done after the barrier.
1164 Example: Consider a hypothetical device with two single-byte ports, one
1165 write-only input port (at offset 0) and a read-only output port (at
1167 Operation of the device is as follows: data bytes are written
1168 to the input port, and are placed by the device on a stack, the top of
1169 which is read by reading from the output port.
1170 The sequence to correctly
1171 write two data bytes to the device then read those two data bytes back
1175 * t and h are the tag and handle for the mapped device's
1178 bus_space_write_1(t, h, 0, data0);
1179 bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE); /* 1 */
1180 bus_space_write_1(t, h, 0, data1);
1181 bus_space_barrier(t, h, 0, 2,
1182 BUS_SPACE_BARRIER_READ|BUS_SPACE_BARRIER_WRITE); /* 2 */
1183 ndata1 = bus_space_read_1(t, h, 1);
1184 bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ); /* 3 */
1185 ndata0 = bus_space_read_1(t, h, 1);
1186 /* data0 == ndata0, data1 == ndata1 */
1189 The first barrier makes sure that the first write finishes before the
1190 second write is issued, so that two writes to the input port are done
1191 in order and are not collapsed into a single write.
1193 the data bytes are written to the device correctly and in order.
1195 The second barrier makes sure that the writes to the output port finish
1196 before any of the reads to the input port are issued, thereby making sure
1197 that all of the writes are finished before data is read.
1199 that the first byte read from the device really is the last one that was
1202 The third barrier makes sure that the first read finishes before the
1203 second read is issued, ensuring that data is read correctly and in order.
1205 The barriers in the example above are specified to cover the absolute
1206 minimum number of bus space locations.
1207 It is correct (and often
1208 easier) to make barrier operations cover the device's whole range of bus
1209 space, that is, to specify an offset of zero and the size of the
1211 .Sh REGION OPERATIONS
1212 Some devices use buffers which are mapped as regions in bus space.
1213 Often, drivers want to copy the contents of those buffers to or from
1214 memory, e.g.\& into mbufs which can be passed to higher levels of the
1215 system or from mbufs to be output to a network.
1217 drivers to do this as efficiently as possible, the
1218 .Fn bus_space_read_region_N
1220 .Fn bus_space_write_region_N
1221 families of functions are provided.
1223 Drivers occasionally need to copy one region of a bus space to another,
1224 or to set all locations in a region of bus space to contain a single
1227 .Fn bus_space_copy_region_N
1228 family of functions and the
1229 .Fn bus_space_set_region_N
1230 family of functions allow drivers to perform these operations.
1231 .Ss Fn bus_space_read_region_1 space handle offset datap count
1232 .Ss Fn bus_space_read_region_2 space handle offset datap count
1233 .Ss Fn bus_space_read_region_4 space handle offset datap count
1234 .Ss Fn bus_space_read_region_8 space handle offset datap count
1236 .Fn bus_space_read_region_N
1237 family of functions reads
1239 1, 2, 4, or 8 byte data items from bus space
1240 starting at byte offset
1242 in the region specified by
1244 of the bus space specified by
1246 and writes them into the array specified by
1248 Each successive data item is read from an offset
1249 1, 2, 4, or 8 bytes after the previous data item (depending on which
1251 All locations being read must lie within the bus
1252 space region specified by
1255 For portability, the starting address of the region specified by
1257 plus the offset should be a multiple of the size of data items being
1258 read and the data array pointer should be properly aligned.
1260 systems, not obeying these requirements may cause incorrect data to be
1261 read, on others it may cause a system crash.
1263 Read operations done by the
1264 .Fn bus_space_read_region_N
1265 functions may be executed in any order.
1266 They may also be executed out
1267 of order with respect to other pending read and write operations unless
1268 order is enforced by use of the
1269 .Fn bus_space_barrier
1271 There is no way to insert barriers between reads of
1272 individual bus space locations executed by the
1273 .Fn bus_space_read_region_N
1276 These functions will never fail.
1277 If they would fail (e.g.\& because of an
1278 argument error), that indicates a software bug which should cause a
1280 In that case, they will never return.
1281 .Ss Fn bus_space_write_region_1 space handle offset datap count
1282 .Ss Fn bus_space_write_region_2 space handle offset datap count
1283 .Ss Fn bus_space_write_region_4 space handle offset datap count
1284 .Ss Fn bus_space_write_region_8 space handle offset datap count
1286 .Fn bus_space_write_region_N
1287 family of functions reads
1289 1, 2, 4, or 8 byte data items from the array
1292 and writes them to bus space starting at byte offset
1294 in the region specified by
1296 of the bus space specified
1299 Each successive data item is written to an offset 1, 2, 4,
1300 or 8 bytes after the previous data item (depending on which function is
1302 All locations being written must lie within the bus space region
1306 For portability, the starting address of the region specified by
1308 plus the offset should be a multiple of the size of data items being
1309 written and the data array pointer should be properly aligned.
1311 systems, not obeying these requirements may cause incorrect data to be
1312 written, on others it may cause a system crash.
1314 Write operations done by the
1315 .Fn bus_space_write_region_N
1317 executed in any order.
1318 They may also be executed out of order with
1319 respect to other pending read and write operations unless order is
1320 enforced by use of the
1321 .Fn bus_space_barrier
1323 There is no way to insert barriers between writes of
1324 individual bus space locations executed by the
1325 .Fn bus_space_write_region_N
1328 These functions will never fail.
1329 If they would fail (e.g.\& because of an
1330 argument error), that indicates a software bug which should cause a
1332 In that case, they will never return.
1333 .Ss Fn bus_space_copy_region_1 space srchandle srcoffset dsthandle \
1335 .Ss Fn bus_space_copy_region_2 space srchandle srcoffset dsthandle \
1337 .Ss Fn bus_space_copy_region_4 space srchandle srcoffset dsthandle \
1339 .Ss Fn bus_space_copy_region_8 space srchandle srcoffset dsthandle \
1342 .Fn bus_space_copy_region_N
1343 family of functions copies
1345 1, 2, 4, or 8 byte data items in bus space
1346 from the area starting at byte offset
1348 in the region specified by
1350 of the bus space specified by
1352 to the area starting at byte offset
1354 in the region specified by
1356 in the same bus space.
1357 Each successive data item read or written has
1358 an offset 1, 2, 4, or 8 bytes after the previous data item (depending
1359 on which function is used).
1360 All locations being read and written must
1361 lie within the bus space region specified by their respective handles.
1363 For portability, the starting addresses of the regions specified by the
1364 each handle plus its respective offset should be a multiple of the size
1365 of data items being copied.
1366 On some systems, not obeying this
1367 requirement may cause incorrect data to be copied, on others it may cause
1370 Read and write operations done by the
1371 .Fn bus_space_copy_region_N
1372 functions may be executed in any order.
1373 They may also be executed out
1374 of order with respect to other pending read and write operations unless
1375 order is enforced by use of the
1376 .Fn bus_space_barrier
1378 There is no way to insert barriers between reads or writes of
1379 individual bus space locations executed by the
1380 .Fn bus_space_copy_region_N
1383 Overlapping copies between different subregions of a single region
1384 of bus space are handled correctly by the
1385 .Fn bus_space_copy_region_N
1388 These functions will never fail.
1389 If they would fail (e.g.\& because of an
1390 argument error), that indicates a software bug which should cause a
1392 In that case, they will never return.
1393 .Ss Fn bus_space_set_region_1 space handle offset value count
1394 .Ss Fn bus_space_set_region_2 space handle offset value count
1395 .Ss Fn bus_space_set_region_4 space handle offset value count
1396 .Ss Fn bus_space_set_region_8 space handle offset value count
1398 .Fn bus_space_set_region_N
1399 family of functions writes the given
1404 data items in bus space starting at byte offset
1406 in the region specified by
1408 of the bus space specified by
1410 Each successive data item has an offset 1, 2, 4, or 8 bytes after the
1411 previous data item (depending on which function is used).
1413 locations being written must lie within the bus space region specified
1417 For portability, the starting address of the region specified by
1419 plus the offset should be a multiple of the size of data items being
1421 On some systems, not obeying this requirement may cause
1422 incorrect data to be written, on others it may cause a system crash.
1424 Write operations done by the
1425 .Fn bus_space_set_region_N
1427 executed in any order.
1428 They may also be executed out of order with
1429 respect to other pending read and write operations unless order is
1430 enforced by use of the
1431 .Fn bus_space_barrier
1433 There is no way to insert barriers between writes of
1434 individual bus space locations executed by the
1435 .Fn bus_space_set_region_N
1438 These functions will never fail.
1439 If they would fail (e.g.\& because of an
1440 argument error), that indicates a software bug which should cause a
1442 In that case, they will never return.
1443 .Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES
1444 Some devices implement single locations in bus space which are to be read
1445 or written multiple times to communicate data, e.g.\& some ethernet
1446 devices' packet buffer FIFOs.
1447 In order to allow drivers to manipulate
1448 these types of devices as efficiently as possible, the
1449 .Fn bus_space_read_multi_N ,
1450 .Fn bus_space_set_multi_N ,
1452 .Fn bus_space_write_multi_N
1453 families of functions are provided.
1454 .Ss Fn bus_space_read_multi_1 space handle offset datap count
1455 .Ss Fn bus_space_read_multi_2 space handle offset datap count
1456 .Ss Fn bus_space_read_multi_4 space handle offset datap count
1457 .Ss Fn bus_space_read_multi_8 space handle offset datap count
1459 .Fn bus_space_read_multi_N
1460 family of functions reads
1462 1, 2, 4, or 8 byte data items from bus space
1465 in the region specified by
1467 of the bus space specified by
1469 and writes them into the array specified by
1471 Each successive data item is read from the same location in bus
1473 The location being read must lie within the bus space region
1477 For portability, the starting address of the region specified by
1479 plus the offset should be a multiple of the size of data items being
1480 read and the data array pointer should be properly aligned.
1482 systems, not obeying these requirements may cause incorrect data to be
1483 read, on others it may cause a system crash.
1485 Read operations done by the
1486 .Fn bus_space_read_multi_N
1488 executed out of order with respect to other pending read and write
1489 operations unless order is enforced by use of the
1490 .Fn bus_space_barrier
1493 .Fn bus_space_read_multi_N
1494 functions read the same bus space location multiple times, they
1495 place an implicit read barrier between each successive read of that bus
1498 These functions will never fail.
1499 If they would fail (e.g.\& because of an
1500 argument error), that indicates a software bug which should cause a
1502 In that case, they will never return.
1503 .Ss Fn bus_space_write_multi_1 space handle offset datap count
1504 .Ss Fn bus_space_write_multi_2 space handle offset datap count
1505 .Ss Fn bus_space_write_multi_4 space handle offset datap count
1506 .Ss Fn bus_space_write_multi_8 space handle offset datap count
1508 .Fn bus_space_write_multi_N
1509 family of functions reads
1511 1, 2, 4, or 8 byte data items from the array
1514 and writes them into bus space at byte offset
1516 in the region specified by
1518 of the bus space specified by
1520 Each successive data item is written to the same location in
1522 The location being written must lie within the bus space
1526 For portability, the starting address of the region specified by
1528 plus the offset should be a multiple of the size of data items being
1529 written and the data array pointer should be properly aligned.
1531 systems, not obeying these requirements may cause incorrect data to be
1532 written, on others it may cause a system crash.
1534 Write operations done by the
1535 .Fn bus_space_write_multi_N
1536 functions may be executed out of order with respect to other pending
1537 read and write operations unless order is enforced by use of the
1538 .Fn bus_space_barrier
1541 .Fn bus_space_write_multi_N
1542 functions write the same bus space location multiple times, they
1543 place an implicit write barrier between each successive write of that
1546 These functions will never fail.
1547 If they would fail (e.g.\& because of an
1548 argument error), that indicates a software bug which should cause a
1550 In that case, they will never return.
1551 .Ss Fn bus_space_set_multi_1 space handle offset value count
1552 .Ss Fn bus_space_set_multi_2 space handle offset value count
1553 .Ss Fn bus_space_set_multi_4 space handle offset value count
1554 .Ss Fn bus_space_set_multi_8 space handle offset value count
1556 .Fn bus_space_set_multi_N
1559 into bus space at byte offset
1561 in the region specified by
1563 of the bus space specified by
1567 The location being written must lie within the bus space
1571 For portability, the starting address of the region specified by
1573 plus the offset should be a multiple of the size of data items being
1574 written and the data array pointer should be properly aligned.
1576 systems, not obeying these requirements may cause incorrect data to be
1577 written, on others it may cause a system crash.
1579 Write operations done by the
1580 .Fn bus_space_set_multi_N
1581 functions may be executed out of order with respect to other pending
1582 read and write operations unless order is enforced by use of the
1583 .Fn bus_space_barrier
1586 .Fn bus_space_set_multi_N
1587 functions write the same bus space location multiple times, they
1588 place an implicit write barrier between each successive write of that
1591 These functions will never fail.
1592 If they would fail (e.g.\& because of an
1593 argument error), that indicates a software bug which should cause a
1595 In that case, they will never return.
1596 .Sh STREAM FUNCTIONS
1599 functions imply a host byte-order and a bus byte-order and take care of
1600 any translation for the caller.
1601 In some cases, however, hardware may map a FIFO or some other memory region
1602 for which the caller may want to use multi-word, yet untranslated access.
1603 Access to these types of memory regions should be with the
1604 .Fn bus_space_*_stream_N
1607 .Bl -tag -compact -width Fn
1608 .It Fn bus_space_read_stream_1
1609 .It Fn bus_space_read_stream_2
1610 .It Fn bus_space_read_stream_4
1611 .It Fn bus_space_read_stream_8
1612 .It Fn bus_space_read_multi_stream_1
1613 .It Fn bus_space_read_multi_stream_2
1614 .It Fn bus_space_read_multi_stream_4
1615 .It Fn bus_space_read_multi_stream_8
1616 .It Fn bus_space_read_region_stream_1
1617 .It Fn bus_space_read_region_stream_2
1618 .It Fn bus_space_read_region_stream_4
1619 .It Fn bus_space_read_region_stream_8
1620 .It Fn bus_space_write_stream_1
1621 .It Fn bus_space_write_stream_2
1622 .It Fn bus_space_write_stream_4
1623 .It Fn bus_space_write_stream_8
1624 .It Fn bus_space_write_multi_stream_1
1625 .It Fn bus_space_write_multi_stream_2
1626 .It Fn bus_space_write_multi_stream_4
1627 .It Fn bus_space_write_multi_stream_8
1628 .It Fn bus_space_write_region_stream_1
1629 .It Fn bus_space_write_region_stream_2
1630 .It Fn bus_space_write_region_stream_4
1631 .It Fn bus_space_write_region_stream_8
1632 .It Fn bus_space_copy_region_stream_1
1633 .It Fn bus_space_copy_region_stream_2
1634 .It Fn bus_space_copy_region_stream_4
1635 .It Fn bus_space_copy_region_stream_8
1636 .It Fn bus_space_set_multi_stream_1
1637 .It Fn bus_space_set_multi_stream_2
1638 .It Fn bus_space_set_multi_stream_4
1639 .It Fn bus_space_set_multi_stream_8
1640 .It Fn bus_space_set_region_stream_1
1641 .It Fn bus_space_set_region_stream_2
1642 .It Fn bus_space_set_region_stream_4
1643 .It Fn bus_space_set_region_stream_8
1646 These functions are defined just as their non-stream counterparts,
1647 except that they provide no byte-order translation.
1653 interface specification differs slightly from the original
1654 specification that came into wide use and
1657 A few of the function names and arguments have changed
1658 for consistency and increased functionality.
1664 functions were introduced in a different form (memory and I/O spaces
1665 were accessed via different sets of functions) in
1667 The functions were merged to work on generic
1671 development cycle, and many drivers were converted to use them.
1672 This document was written later during the
1674 development cycle, and the specification was updated to fix some
1675 consistency problems and to add some missing functionality.
1677 The manual page was then adapted to the version of the interface that
1679 imported for the CAM SCSI drivers, plus subsequent evolution.
1683 version was imported in
1689 interfaces were designed and implemented by the
1693 Primary contributors and implementors were
1694 .An Chris Demetriou ,
1697 .An Charles Hannum ,
1700 developers and the user community played a significant role in development.
1703 ported these interfaces to
1707 wrote this manual page.
1714 This manual may not completely and accurately document the interface,
1715 and many parts of the interface are unspecified.