1 .\" $NetBSD: bus_space.9,v 1.9 1999/03/06 22:09:29 mycroft Exp $
3 .\" Copyright (c) 2005 M. Warner Losh. All Rights Reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
13 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
14 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
15 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
16 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
17 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
18 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
19 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
20 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
21 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
22 .\" POSSIBILITY OF SUCH DAMAGE.
25 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
26 .\" All rights reserved.
28 .\" This code is derived from software contributed to The NetBSD Foundation
29 .\" by Christopher G. Demetriou.
31 .\" Redistribution and use in source and binary forms, with or without
32 .\" modification, are permitted provided that the following conditions
34 .\" 1. Redistributions of source code must retain the above copyright
35 .\" notice, this list of conditions and the following disclaimer.
36 .\" 2. Redistributions in binary form must reproduce the above copyright
37 .\" notice, this list of conditions and the following disclaimer in the
38 .\" documentation and/or other materials provided with the distribution.
39 .\" 3. All advertising materials mentioning features or use of this software
40 .\" must display the following acknowledgment:
41 .\" This product includes software developed by the NetBSD
42 .\" Foundation, Inc. and its contributors.
43 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
44 .\" contributors may be used to endorse or promote products derived
45 .\" from this software without specific prior written permission.
47 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
48 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
49 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
50 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
51 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
52 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
53 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
54 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
55 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
56 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
57 .\" POSSIBILITY OF SUCH DAMAGE.
66 .Nm bus_space_barrier ,
67 .Nm bus_space_copy_region_1 ,
68 .Nm bus_space_copy_region_2 ,
69 .Nm bus_space_copy_region_4 ,
70 .Nm bus_space_copy_region_8 ,
73 .Nm bus_space_read_1 ,
74 .Nm bus_space_read_2 ,
75 .Nm bus_space_read_4 ,
76 .Nm bus_space_read_8 ,
77 .Nm bus_space_read_multi_1 ,
78 .Nm bus_space_read_multi_2 ,
79 .Nm bus_space_read_multi_4 ,
80 .Nm bus_space_read_multi_8 ,
81 .Nm bus_space_read_region_1 ,
82 .Nm bus_space_read_region_2 ,
83 .Nm bus_space_read_region_4 ,
84 .Nm bus_space_read_region_8 ,
85 .Nm bus_space_set_region_1 ,
86 .Nm bus_space_set_region_2 ,
87 .Nm bus_space_set_region_4 ,
88 .Nm bus_space_set_region_8 ,
89 .Nm bus_space_subregion ,
91 .Nm bus_space_set_multi_1 ,
92 .Nm bus_space_set_multi_2 ,
93 .Nm bus_space_set_multi_4 ,
94 .Nm bus_space_set_multi_8 ,
95 .Nm bus_space_write_1 ,
96 .Nm bus_space_write_2 ,
97 .Nm bus_space_write_4 ,
98 .Nm bus_space_write_8 ,
99 .Nm bus_space_write_multi_1 ,
100 .Nm bus_space_write_multi_2 ,
101 .Nm bus_space_write_multi_4 ,
102 .Nm bus_space_write_multi_8 ,
103 .Nm bus_space_write_region_1 ,
104 .Nm bus_space_write_region_2 ,
105 .Nm bus_space_write_region_4 ,
106 .Nm bus_space_write_region_8
107 .Nd "bus space manipulation functions"
112 .Fa "bus_space_tag_t space" "bus_addr_t address"
113 .Fa "bus_size_t size" "int flags" "bus_space_handle_t *handlep"
117 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size"
120 .Fo bus_space_subregion
121 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
122 .Fa "bus_size_t offset" "bus_size_t size" "bus_space_handle_t *nhandlep"
126 .Fa "bus_space_tag_t space" "bus_addr_t reg_start" "bus_addr_t reg_end"
127 .Fa "bus_size_t size" "bus_size_t alignment" "bus_size_t boundary"
128 .Fa "int flags" "bus_addr_t *addrp" "bus_space_handle_t *handlep"
132 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size"
136 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
140 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
144 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
148 .Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset"
151 .Fo bus_space_write_1
152 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
153 .Fa "bus_size_t offset" "u_int8_t value"
156 .Fo bus_space_write_2
157 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
158 .Fa "bus_size_t offset" "u_int16_t value"
161 .Fo bus_space_write_4
162 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
163 .Fa "bus_size_t offset" "u_int32_t value"
166 .Fo bus_space_write_8
167 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
168 .Fa "bus_size_t offset" "u_int64_t value"
171 .Fo bus_space_barrier
172 .Fa "bus_space_tag_t space" "bus_space_handle_t handle"
173 .Fa "bus_size_t offset" "bus_size_t length" "int flags"
176 .Fo bus_space_read_region_1
177 .Fa "bus_space_tag_t space"
178 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap"
179 .Fa "bus_size_t count"
182 .Fo bus_space_read_region_2
183 .Fa "bus_space_tag_t space"
184 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap"
185 .Fa "bus_size_t count"
188 .Fo bus_space_read_region_4
189 .Fa "bus_space_tag_t space"
190 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap"
191 .Fa "bus_size_t count"
194 .Fo bus_space_read_region_8
195 .Fa "bus_space_tag_t space"
196 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap"
197 .Fa "bus_size_t count"
200 .Fo bus_space_write_region_1
201 .Fa "bus_space_tag_t space"
202 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap"
203 .Fa "bus_size_t count"
206 .Fo bus_space_write_region_2
207 .Fa "bus_space_tag_t space"
208 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap"
209 .Fa "bus_size_t count"
212 .Fo bus_space_write_region_4
213 .Fa "bus_space_tag_t space"
214 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap"
215 .Fa "bus_size_t count"
218 .Fo bus_space_write_region_8
219 .Fa "bus_space_tag_t space"
220 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap"
221 .Fa "bus_size_t count"
224 .Fo bus_space_copy_region_1
225 .Fa "bus_space_tag_t space"
226 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
227 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
230 .Fo bus_space_copy_region_2
231 .Fa "bus_space_tag_t space"
232 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
233 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
236 .Fo bus_space_copy_region_4
237 .Fa "bus_space_tag_t space"
238 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
239 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
242 .Fo bus_space_copy_region_8
243 .Fa "bus_space_tag_t space"
244 .Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset"
245 .Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count"
248 .Fo bus_space_set_region_1
249 .Fa "bus_space_tag_t space"
250 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t value"
251 .Fa "bus_size_t count"
254 .Fo bus_space_set_region_2
255 .Fa "bus_space_tag_t space"
256 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t value"
257 .Fa "bus_size_t count"
260 .Fo bus_space_set_region_4
261 .Fa "bus_space_tag_t space"
262 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t value"
263 .Fa "bus_size_t count"
266 .Fo bus_space_set_region_8
267 .Fa "bus_space_tag_t space"
268 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t value"
269 .Fa "bus_size_t count"
272 .Fo bus_space_read_multi_1
273 .Fa "bus_space_tag_t space"
274 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap"
275 .Fa "bus_size_t count"
278 .Fo bus_space_read_multi_2
279 .Fa "bus_space_tag_t space"
280 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap"
281 .Fa "bus_size_t count"
284 .Fo bus_space_read_multi_4
285 .Fa "bus_space_tag_t space"
286 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap"
287 .Fa "bus_size_t count"
290 .Fo bus_space_read_multi_8
291 .Fa "bus_space_tag_t space"
292 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap"
293 .Fa "bus_size_t count"
296 .Fo bus_space_write_multi_1
297 .Fa "bus_space_tag_t space"
298 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap"
299 .Fa "bus_size_t count"
302 .Fo bus_space_write_multi_2
303 .Fa "bus_space_tag_t space"
304 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap"
305 .Fa "bus_size_t count"
308 .Fo bus_space_write_multi_4
309 .Fa "bus_space_tag_t space"
310 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap"
311 .Fa "bus_size_t count"
314 .Fo bus_space_write_multi_8
315 .Fa "bus_space_tag_t space"
316 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap"
317 .Fa "bus_size_t count"
320 .Fo bus_space_set_multi_1
321 .Fa "bus_space_tag_t space"
322 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int8_t value"
323 .Fa "bus_size_t count"
326 .Fo bus_space_set_multi_2
327 .Fa "bus_space_tag_t space"
328 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int16_t value"
329 .Fa "bus_size_t count"
332 .Fo bus_space_set_multi_4
333 .Fa "bus_space_tag_t space"
334 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int32_t value"
335 .Fa "bus_size_t count"
338 .Fo bus_space_set_multi_8
339 .Fa "bus_space_tag_t space"
340 .Fa "bus_space_handle_t handle" "bus_size_t offset" "u_int64_t value"
341 .Fa "bus_size_t count"
346 functions exist to allow device drivers
347 machine-independent access to bus memory and register areas.
349 functions and types described in this document can be used by including
354 Many common devices are used on multiple architectures, but are accessed
355 differently on each because of architectural constraints.
356 For instance, a device which is mapped in one system's I/O space may be
357 mapped in memory space on a second system.
358 On a third system, architectural
359 limitations might change the way registers need to be accessed (e.g.\&
360 creating a non-linear register space).
361 In some cases, a single
362 driver may need to access the same type of device in multiple ways in a
363 single system or architecture.
366 functions is to allow a single driver source file to manipulate a set
367 of devices on different system architectures, and to allow a single driver
368 object file to manipulate a set of devices on multiple bus types on a
371 Not all busses have to implement all functions described in this
372 document, though that is encouraged if the operations are logically
373 supported by the bus.
374 Unimplemented functions should cause
375 compile-time errors if possible.
377 All of the interface definitions described in this document are shown as
378 function prototypes and discussed as if they were required to be
380 Implementations are encouraged to implement prototyped
381 (type-checked) versions of these interfaces, but may implement them as
382 macros if appropriate.
383 Machine-dependent types, variables, and functions
384 should be marked clearly in
386 to avoid confusion with the
387 machine-independent types and functions, and, if possible, should be
388 given names which make the machine-dependence clear.
389 .Sh CONCEPTS AND GUIDELINES
390 Bus spaces are described by bus space tags, which can be created only by
391 machine-dependent code.
392 A given machine may have several different types
393 of bus space (e.g.\& memory space and I/O space), and thus may provide
394 multiple different bus space tags.
395 Individual busses or devices on a machine may use more than one bus space
397 For instance, ISA devices are
398 given an ISA memory space tag and an ISA I/O space tag.
400 may have several different tags which represent the same type of
401 space, for instance because of multiple different host bus interface
404 A range in bus space is described by a bus address and a bus size.
406 bus address describes the start of the range in bus space.
408 size describes the size of the range in bytes.
409 Busses which are not byte
410 addressable may require use of bus space ranges with appropriately
411 aligned addresses and properly rounded sizes.
413 Access to regions of bus space is facilitated by use of bus space handles,
414 which are usually created by mapping a specific range of a bus space.
415 Handles may also be created by allocating
416 and mapping a range of bus space, the actual location of which is picked
417 by the implementation within bounds specified by the caller of the
420 All of the bus space access functions require one bus space tag
421 argument, at least one handle argument, and at least one offset argument
423 The bus space tag specifies the space, each handle specifies a region in
424 the space, and each offset specifies the offset into the region of the
425 actual location(s) to be accessed.
426 Offsets are given in bytes, though busses
427 may impose alignment constraints.
428 The offset used to access data
429 relative to a given handle must be such that all of the data being
430 accessed is in the mapped region that the handle describes.
432 access data outside that region is an error.
434 Because some architectures' memory systems use buffering to improve
435 memory and device access performance, there is a mechanism which can be
438 in the bus space read and write stream.
440 are three types of barriers: read, write, and read/write.
442 started to the region before a read barrier must complete before any reads
443 after the read barrier are started.
444 (The analogous requirement is true for
446 Read/write barriers force all reads and writes started
447 before the barrier to complete before any reads or writes after the
449 Correctly-written drivers will include all
450 appropriate barriers, and assume only the read/write ordering imposed by
451 the barrier operations.
453 People trying to write portable drivers with the
456 try to make minimal assumptions about what the system allows.
458 they should expect that the system requires bus space addresses being
459 accessed to be naturally aligned (i.e., base address of handle added to
460 offset is a multiple of the access size), and that the system does
461 alignment checking on pointers (i.e., pointer to objects being read and
462 written must point to properly-aligned data).
464 The descriptions of the
466 functions given below all assume that
467 they are called with proper arguments.
468 If called with invalid arguments
469 or arguments that are out of range (e.g.\& trying to access data outside of
470 the region mapped when a given handle was created), undefined behaviour
472 In that case, they may cause the
473 system to halt, either intentionally (via panic) or unintentionally (by
474 causing a fatal trap of by some other means) or may cause improper
475 operation which is not immediately fatal.
476 Functions which return
478 or which return data read from bus space (i.e., functions which
479 do not obviously return an error code) do not fail.
481 if given invalid arguments, and in that case their behaviour is undefined.
483 Several types are defined in
485 to facilitate use of the
487 functions by drivers.
491 type is used to describe bus addresses.
493 unsigned integral type
494 capable of holding the largest bus address usable by the architecture.
496 type is primarily used when mapping and unmapping bus space.
500 type is used to describe sizes of ranges in bus space.
502 unsigned integral type capable of holding the size of the largest bus
503 address range usable on the architecture.
504 This type is used by virtually all
507 functions, describing sizes when mapping regions and
508 offsets into regions when performing space access operations.
509 .Ss Vt bus_space_tag_t
512 type is used to describe a particular bus space on a machine.
514 contents are machine-dependent and should be considered opaque by
515 machine-independent code.
516 This type is used by all
518 functions to name the space on which they are operating.
519 .Ss Vt bus_space_handle_t
521 .Vt bus_space_handle_t
522 type is used to describe a mapping of a range of bus space.
524 contents are machine-dependent and should be considered opaque by
525 machine-independent code.
526 This type is used when performing bus space
528 .Sh MAPPING AND UNMAPPING BUS SPACE
529 This section is specific to the
531 version of these functions and may or may not apply to the
535 Bus space must be mapped before it can be used, and should be
536 unmapped when it is no longer needed.
541 functions provide these capabilities.
543 Some drivers need to be able to pass a subregion of already-mapped bus
544 space to another driver or module within a driver.
546 .Fn bus_space_subregion
547 function allows such subregions to be created.
548 .Ss Fn bus_space_map space address size flags handlep
551 function maps the region of bus space named by the
552 .Fa space , address ,
556 If successful, it returns zero
557 and fills in the bus space handle pointed to by
560 that can be used to access the mapped region.
562 it will return non-zero and leave the bus space handle pointed
565 in an undefined state.
569 argument controls how the space is to be mapped.
570 Supported flags include:
571 .Bl -tag -width ".Dv BUS_SPACE_MAP_CACHEABLE"
572 .It Dv BUS_SPACE_MAP_CACHEABLE
573 Try to map the space so that accesses can be cached and/or
574 prefetched by the system.
575 If this flag is not specified, the
576 implementation should map the space so that it will not be cached or
579 This flag must have a value of 1 on all implementations for backward
581 .It Dv BUS_SPACE_MAP_LINEAR
582 Try to map the space so that its contents can be accessed linearly via
583 normal memory access methods (e.g.\& pointer dereferencing and structure
585 This is useful when software wants to do direct access to a memory
586 device, e.g.\& a frame buffer.
587 If this flag is specified and linear
588 mapping is not possible, the
592 flag is not specified, the system may map the space in whatever way is
596 Not all combinations of flags make sense or are supported with all
599 .Dv BUS_SPACE_MAP_CACHEABLE
600 may be meaningless when
601 used on many systems' I/O port spaces, and on some systems
602 .Dv BUS_SPACE_MAP_LINEAR
604 .Dv BUS_SPACE_MAP_CACHEABLE
606 When the system hardware or firmware provides hints as to how spaces should be
607 mapped (e.g.\& the PCI memory mapping registers'
610 hints should be followed for maximum compatibility.
612 requesting a mapping that cannot be satisfied (e.g.\& requesting a
613 non-cacheable mapping when the system can only provide a cacheable one)
614 will cause the request to fail.
616 Some implementations may keep track of use of bus space for some or all
617 bus spaces and refuse to allow duplicate allocations.
619 for bus spaces which have no notion of slot-specific space addressing,
620 such as ISA and VME, and for spaces which coexist with those spaces
621 (e.g.\& EISA and PCI memory and I/O spaces co-existing with ISA memory and
624 Mapped regions may contain areas for which no there is no device on the
626 If space in those areas is accessed, the results are
628 .Ss Fn bus_space_unmap space handle size
631 function unmaps a region of bus space mapped with
633 When unmapping a region, the
636 the same as the size given to
638 when mapping that region.
642 is called on a handle, that handle is no longer
644 (If copies were made of the handle they are no longer valid,
647 This function will never fail.
648 If it would fail (e.g.\& because of an
649 argument error), that indicates a software bug which should cause a
654 .Ss Fn bus_space_subregion space handle offset size nhandlep
656 .Fn bus_space_subregion
657 function is a convenience function which makes a
658 new handle to some subregion of an already-mapped region of bus space.
659 The subregion described by the new handle starts at byte offset
661 into the region described by
663 with the size give by
665 and must be wholly contained within the original region.
668 .Fn bus_space_subregion
669 returns zero and fills in the bus
670 space handle pointed to by
672 If unsuccessful, it returns non-zero and leaves the bus space handle
677 In either case, the handle described by
679 remains valid and is unmodified.
681 When done with a handle created by
682 .Fn bus_space_subregion ,
685 Under no circumstances should
687 be used on the handle.
688 Doing so may confuse any resource management
689 being done on the space, and will result in undefined behaviour.
694 is called on a handle, all subregions of that handle become invalid.
695 .Sh ALLOCATING AND FREEING BUS SPACE
696 This section is specific to the
698 version of these functions and may or may not apply to the
702 Some devices require or allow bus space to be allocated by the operating
703 system for device use.
704 When the devices no longer need the space, the
705 operating system should free it for use by other devices.
710 functions provide these capabilities.
711 .Ss Fn bus_space_alloc space reg_start reg_end size alignment boundary \
715 function allocates and maps a region of bus space with the size given by
717 corresponding to the given constraints.
718 If successful, it returns
719 zero, fills in the bus address pointed to by
721 with the bus space address of the allocated region, and fills in
722 the bus space handle pointed to by
724 with the handle that can be used to access that region.
725 If unsuccessful, it returns non-zero and leaves the bus address pointed to by
727 and the bus space handle pointed to by
729 in an undefined state.
731 Constraints on the allocation are given by the
732 .Fa reg_start , reg_end , alignment ,
736 The allocated region will start at or after
742 constraint must be a power of two, and the allocated region will start at
743 an address that is an even multiple of that power of two.
746 constraint, if non-zero, ensures that the region is allocated so that
747 .Fa "first address in region"
750 has the same value as
751 .Fa "last address in region"
754 If the constraints cannot be met,
757 It is an error to specify a set of
758 constraints that can never be met
766 parameter is the same as the like-named parameter to
768 the same flag values should be used, and they have the
773 should only be freed with
777 on them causes undefined behaviour.
779 .Fn bus_space_subregion
780 function can be used on
782 .Fn bus_space_alloc .
783 .Ss Fn bus_space_free space handle size
786 function unmaps and frees a region of bus space mapped
788 .Fn bus_space_alloc .
789 When unmapping a region, the
791 specified should be the same as the size given to
793 when allocating the region.
797 is called on a handle, that handle is no longer valid.
799 made of the handle, they are no longer valid, either.)
801 This function will never fail.
802 If it would fail (e.g.\& because of an
803 argument error), that indicates a software bug which should cause a
808 .Sh READING AND WRITING SINGLE DATA ITEMS
809 The simplest way to access bus space is to read or write a single data
814 .Fn bus_space_write_N
815 families of functions provide
816 the ability to read and write 1, 2, 4, and 8 byte data items on busses
817 which support those access sizes.
818 .Ss Fn bus_space_read_1 space handle offset
819 .Ss Fn bus_space_read_2 space handle offset
820 .Ss Fn bus_space_read_4 space handle offset
821 .Ss Fn bus_space_read_8 space handle offset
824 family of functions reads a 1, 2, 4, or 8 byte data item from
825 the offset specified by
827 into the region specified by
829 of the bus space specified by
831 The location being read must lie within the bus space region specified by
834 For portability, the starting address of the region specified by
836 plus the offset should be a multiple of the size of data item being read.
837 On some systems, not obeying this requirement may cause incorrect data to
838 be read, on others it may cause a system crash.
840 Read operations done by the
842 functions may be executed out
843 of order with respect to other pending read and write operations unless
844 order is enforced by use of the
845 .Fn bus_space_barrier
848 These functions will never fail.
849 If they would fail (e.g.\& because of an
850 argument error), that indicates a software bug which should cause a
852 In that case, they will never return.
853 .Ss Fn bus_space_write_1 space handle offset value
854 .Ss Fn bus_space_write_2 space handle offset value
855 .Ss Fn bus_space_write_4 space handle offset value
856 .Ss Fn bus_space_write_8 space handle offset value
858 .Fn bus_space_write_N
859 family of functions writes a 1, 2, 4, or 8 byte data item to the offset
862 into the region specified by
864 of the bus space specified by
866 The location being written must lie within
867 the bus space region specified by
870 For portability, the starting address of the region specified by
872 plus the offset should be a multiple of the size of data item being
874 On some systems, not obeying this requirement may cause
875 incorrect data to be written, on others it may cause a system crash.
877 Write operations done by the
878 .Fn bus_space_write_N
879 functions may be executed
880 out of order with respect to other pending read and write operations
881 unless order is enforced by use of the
882 .Fn bus_space_barrier
885 These functions will never fail.
886 If they would fail (e.g.\& because of an
887 argument error), that indicates a software bug which should cause a
889 In that case, they will never return.
891 In order to allow high-performance buffering implementations to avoid bus
892 activity on every operation, read and write ordering should be specified
893 explicitly by drivers when necessary.
895 .Fn bus_space_barrier
896 function provides that ability.
897 .Ss Fn bus_space_barrier space handle offset length flags
899 .Fn bus_space_barrier
900 function enforces ordering of bus space read and write operations
901 for the specified subregion (described by the
905 parameters) of the region named by
907 in the space named by
912 argument controls what types of operations are to be ordered.
914 .Bl -tag -width ".Dv BUS_SPACE_BARRIER_WRITE"
915 .It Dv BUS_SPACE_BARRIER_READ
916 Synchronize read operations.
917 .It Dv BUS_SPACE_BARRIER_WRITE
918 Synchronize write operations.
921 Those flags can be combined (or-ed together) to enforce ordering on both
922 read and write operations.
924 All of the specified type(s) of operation which are done to the region
925 before the barrier operation are guaranteed to complete before any of the
926 specified type(s) of operation done after the barrier.
928 Example: Consider a hypothetical device with two single-byte ports, one
929 write-only input port (at offset 0) and a read-only output port (at
931 Operation of the device is as follows: data bytes are written
932 to the input port, and are placed by the device on a stack, the top of
933 which is read by reading from the output port.
934 The sequence to correctly
935 write two data bytes to the device then read those two data bytes back
939 * t and h are the tag and handle for the mapped device's
942 bus_space_write_1(t, h, 0, data0);
943 bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE); /* 1 */
944 bus_space_write_1(t, h, 0, data1);
945 bus_space_barrier(t, h, 0, 2,
946 BUS_SPACE_BARRIER_READ|BUS_SPACE_BARRIER_WRITE); /* 2 */
947 ndata1 = bus_space_read_1(t, h, 1);
948 bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ); /* 3 */
949 ndata0 = bus_space_read_1(t, h, 1);
950 /* data0 == ndata0, data1 == ndata1 */
953 The first barrier makes sure that the first write finishes before the
954 second write is issued, so that two writes to the input port are done
955 in order and are not collapsed into a single write.
957 the data bytes are written to the device correctly and in order.
959 The second barrier makes sure that the writes to the output port finish
960 before any of the reads to the input port are issued, thereby making sure
961 that all of the writes are finished before data is read.
963 that the first byte read from the device really is the last one that was
966 The third barrier makes sure that the first read finishes before the
967 second read is issued, ensuring that data is read correctly and in order.
969 The barriers in the example above are specified to cover the absolute
970 minimum number of bus space locations.
971 It is correct (and often
972 easier) to make barrier operations cover the device's whole range of bus
973 space, that is, to specify an offset of zero and the size of the
975 .Sh REGION OPERATIONS
976 Some devices use buffers which are mapped as regions in bus space.
977 Often, drivers want to copy the contents of those buffers to or from
978 memory, e.g.\& into mbufs which can be passed to higher levels of the
979 system or from mbufs to be output to a network.
981 drivers to do this as efficiently as possible, the
982 .Fn bus_space_read_region_N
984 .Fn bus_space_write_region_N
985 families of functions are provided.
987 Drivers occasionally need to copy one region of a bus space to another,
988 or to set all locations in a region of bus space to contain a single
991 .Fn bus_space_copy_region_N
992 family of functions and the
993 .Fn bus_space_set_region_N
994 family of functions allow drivers to perform these operations.
995 .Ss Fn bus_space_read_region_1 space handle offset datap count
996 .Ss Fn bus_space_read_region_2 space handle offset datap count
997 .Ss Fn bus_space_read_region_4 space handle offset datap count
998 .Ss Fn bus_space_read_region_8 space handle offset datap count
1000 .Fn bus_space_read_region_N
1001 family of functions reads
1003 1, 2, 4, or 8 byte data items from bus space
1004 starting at byte offset
1006 in the region specified by
1008 of the bus space specified by
1010 and writes them into the array specified by
1012 Each successive data item is read from an offset
1013 1, 2, 4, or 8 bytes after the previous data item (depending on which
1015 All locations being read must lie within the bus
1016 space region specified by
1019 For portability, the starting address of the region specified by
1021 plus the offset should be a multiple of the size of data items being
1022 read and the data array pointer should be properly aligned.
1024 systems, not obeying these requirements may cause incorrect data to be
1025 read, on others it may cause a system crash.
1027 Read operations done by the
1028 .Fn bus_space_read_region_N
1029 functions may be executed in any order.
1030 They may also be executed out
1031 of order with respect to other pending read and write operations unless
1032 order is enforced by use of the
1033 .Fn bus_space_barrier
1035 There is no way to insert barriers between reads of
1036 individual bus space locations executed by the
1037 .Fn bus_space_read_region_N
1040 These functions will never fail.
1041 If they would fail (e.g.\& because of an
1042 argument error), that indicates a software bug which should cause a
1044 In that case, they will never return.
1045 .Ss Fn bus_space_write_region_1 space handle offset datap count
1046 .Ss Fn bus_space_write_region_2 space handle offset datap count
1047 .Ss Fn bus_space_write_region_4 space handle offset datap count
1048 .Ss Fn bus_space_write_region_8 space handle offset datap count
1050 .Fn bus_space_write_region_N
1051 family of functions reads
1053 1, 2, 4, or 8 byte data items from the array
1056 and writes them to bus space starting at byte offset
1058 in the region specified by
1060 of the bus space specified
1063 Each successive data item is written to an offset 1, 2, 4,
1064 or 8 bytes after the previous data item (depending on which function is
1066 All locations being written must lie within the bus space region
1070 For portability, the starting address of the region specified by
1072 plus the offset should be a multiple of the size of data items being
1073 written and the data array pointer should be properly aligned.
1075 systems, not obeying these requirements may cause incorrect data to be
1076 written, on others it may cause a system crash.
1078 Write operations done by the
1079 .Fn bus_space_write_region_N
1081 executed in any order.
1082 They may also be executed out of order with
1083 respect to other pending read and write operations unless order is
1084 enforced by use of the
1085 .Fn bus_space_barrier
1087 There is no way to insert barriers between writes of
1088 individual bus space locations executed by the
1089 .Fn bus_space_write_region_N
1092 These functions will never fail.
1093 If they would fail (e.g.\& because of an
1094 argument error), that indicates a software bug which should cause a
1096 In that case, they will never return.
1097 .Ss Fn bus_space_copy_region_1 space srchandle srcoffset dsthandle \
1099 .Ss Fn bus_space_copy_region_2 space srchandle srcoffset dsthandle \
1101 .Ss Fn bus_space_copy_region_4 space srchandle srcoffset dsthandle \
1103 .Ss Fn bus_space_copy_region_8 space srchandle srcoffset dsthandle \
1106 .Fn bus_space_copy_region_N
1107 family of functions copies
1109 1, 2, 4, or 8 byte data items in bus space
1110 from the area starting at byte offset
1112 in the region specified by
1114 of the bus space specified by
1116 to the area starting at byte offset
1118 in the region specified by
1120 in the same bus space.
1121 Each successive data item read or written has
1122 an offset 1, 2, 4, or 8 bytes after the previous data item (depending
1123 on which function is used).
1124 All locations being read and written must
1125 lie within the bus space region specified by their respective handles.
1127 For portability, the starting addresses of the regions specified by the
1128 each handle plus its respective offset should be a multiple of the size
1129 of data items being copied.
1130 On some systems, not obeying this
1131 requirement may cause incorrect data to be copied, on others it may cause
1134 Read and write operations done by the
1135 .Fn bus_space_copy_region_N
1136 functions may be executed in any order.
1137 They may also be executed out
1138 of order with respect to other pending read and write operations unless
1139 order is enforced by use of the
1140 .Fn bus_space_barrier function .
1141 There is no way to insert barriers between reads or writes of
1142 individual bus space locations executed by the
1143 .Fn bus_space_copy_region_N
1146 Overlapping copies between different subregions of a single region
1147 of bus space are handled correctly by the
1148 .Fn bus_space_copy_region_N
1151 These functions will never fail.
1152 If they would fail (e.g.\& because of an
1153 argument error), that indicates a software bug which should cause a
1155 In that case, they will never return.
1156 .Ss Fn bus_space_set_region_1 space handle offset value count
1157 .Ss Fn bus_space_set_region_2 space handle offset value count
1158 .Ss Fn bus_space_set_region_4 space handle offset value count
1159 .Ss Fn bus_space_set_region_8 space handle offset value count
1161 .Fn bus_space_set_region_N
1162 family of functions writes the given
1167 data items in bus space starting at byte offset
1169 in the region specified by
1171 of the bus space specified by
1173 Each successive data item has an offset 1, 2, 4, or 8 bytes after the
1174 previous data item (depending on which function is used).
1176 locations being written must lie within the bus space region specified
1180 For portability, the starting address of the region specified by
1182 plus the offset should be a multiple of the size of data items being
1184 On some systems, not obeying this requirement may cause
1185 incorrect data to be written, on others it may cause a system crash.
1187 Write operations done by the
1188 .Fn bus_space_set_region_N
1190 executed in any order.
1191 They may also be executed out of order with
1192 respect to other pending read and write operations unless order is
1193 enforced by use of the
1194 .Fn bus_space_barrier
1196 There is no way to insert barriers between writes of
1197 individual bus space locations executed by the
1198 .Fn bus_space_set_region_N
1201 These functions will never fail.
1202 If they would fail (e.g.\& because of an
1203 argument error), that indicates a software bug which should cause a
1205 In that case, they will never return.
1206 .Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES
1207 Some devices implement single locations in bus space which are to be read
1208 or written multiple times to communicate data, e.g.\& some ethernet
1209 devices' packet buffer FIFOs.
1210 In order to allow drivers to manipulate
1211 these types of devices as efficiently as possible, the
1212 .Fn bus_space_read_multi_N ,
1213 .Fn bus_space_set_multi_N ,
1215 .Fn bus_space_write_multi_N
1216 families of functions are provided.
1217 .Ss Fn bus_space_read_multi_1 space handle offset datap count
1218 .Ss Fn bus_space_read_multi_2 space handle offset datap count
1219 .Ss Fn bus_space_read_multi_4 space handle offset datap count
1220 .Ss Fn bus_space_read_multi_8 space handle offset datap count
1222 .Fn bus_space_read_multi_N
1223 family of functions reads
1225 1, 2, 4, or 8 byte data items from bus space
1228 in the region specified by
1230 of the bus space specified by
1232 and writes them into the array specified by
1234 Each successive data item is read from the same location in bus
1236 The location being read must lie within the bus space region
1240 For portability, the starting address of the region specified by
1242 plus the offset should be a multiple of the size of data items being
1243 read and the data array pointer should be properly aligned.
1245 systems, not obeying these requirements may cause incorrect data to be
1246 read, on others it may cause a system crash.
1248 Read operations done by the
1249 .Fn bus_space_read_multi_N
1251 executed out of order with respect to other pending read and write
1252 operations unless order is enforced by use of the
1253 .Fn bus_space_barrier
1256 .Fn bus_space_read_multi_N
1257 functions read the same bus space location multiple times, they
1258 place an implicit read barrier between each successive read of that bus
1261 These functions will never fail.
1262 If they would fail (e.g.\& because of an
1263 argument error), that indicates a software bug which should cause a
1265 In that case, they will never return.
1266 .Ss Fn bus_space_write_multi_1 space handle offset datap count
1267 .Ss Fn bus_space_write_multi_2 space handle offset datap count
1268 .Ss Fn bus_space_write_multi_4 space handle offset datap count
1269 .Ss Fn bus_space_write_multi_8 space handle offset datap count
1271 .Fn bus_space_write_multi_N
1272 family of functions reads
1274 1, 2, 4, or 8 byte data items from the array
1277 and writes them into bus space at byte offset
1279 in the region specified by
1281 of the bus space specified by
1283 Each successive data item is written to the same location in
1285 The location being written must lie within the bus space
1289 For portability, the starting address of the region specified by
1291 plus the offset should be a multiple of the size of data items being
1292 written and the data array pointer should be properly aligned.
1294 systems, not obeying these requirements may cause incorrect data to be
1295 written, on others it may cause a system crash.
1297 Write operations done by the
1298 .Fn bus_space_write_multi_N
1299 functions may be executed out of order with respect to other pending
1300 read and write operations unless order is enforced by use of the
1301 .Fn bus_space_barrier
1304 .Fn bus_space_write_multi_N
1305 functions write the same bus space location multiple times, they
1306 place an implicit write barrier between each successive write of that
1309 These functions will never fail.
1310 If they would fail (e.g.\& because of an
1311 argument error), that indicates a software bug which should cause a
1313 In that case, they will never return.
1314 .Ss Fn bus_space_set_multi_1 space handle offset value count
1315 .Ss Fn bus_space_set_multi_2 space handle offset value count
1316 .Ss Fn bus_space_set_multi_4 space handle offset value count
1317 .Ss Fn bus_space_set_multi_8 space handle offset value count
1319 .Fn bus_space_set_multi_N
1322 into bus space at byte offset
1324 in the region specified by
1326 of the bus space specified by
1330 The location being written must lie within the bus space
1334 For portability, the starting address of the region specified by
1336 plus the offset should be a multiple of the size of data items being
1337 written and the data array pointer should be properly aligned.
1339 systems, not obeying these requirements may cause incorrect data to be
1340 written, on others it may cause a system crash.
1342 Write operations done by the
1343 .Fn bus_space_set_multi_N
1344 functions may be executed out of order with respect to other pending
1345 read and write operations unless order is enforced by use of the
1346 .Fn bus_space_barrier
1349 .Fn bus_space_set_multi_N
1350 functions write the same bus space location multiple times, they
1351 place an implicit write barrier between each successive write of that
1354 These functions will never fail.
1355 If they would fail (e.g.\& because of an
1356 argument error), that indicates a software bug which should cause a
1358 In that case, they will never return.
1364 interface specification differs slightly from the original
1365 specification that came into wide use and
1368 A few of the function names and arguments have changed
1369 for consistency and increased functionality.
1375 functions were introduced in a different form (memory and I/O spaces
1376 were accessed via different sets of functions) in
1378 The functions were merged to work on generic
1382 development cycle, and many drivers were converted to use them.
1383 This document was written later during the
1385 development cycle, and the specification was updated to fix some
1386 consistency problems and to add some missing functionality.
1388 The manual page was then adopted to the version of the interface that
1390 imported for the CAM SCSI drivers, plus subsequent evolution.
1394 version was imported in
1400 interfaces were designed and implemented by the
1404 Primary contributors and implementors were
1405 .An Chris Demetriou ,
1408 .An Charles Hannum ,
1411 developers and the user community played a significant role in development.
1414 ported these interfaces to
1418 wrote this manual page.
1425 This manual may not completely and accurately document the interface,
1426 and many parts of the interface are unspecified.