Manual Pages  — BUS_SPACE

Bus space must be mapped before it can be used, and should be unmapped when it is no longer needed. The bus_space_map() and bus_space_unmap() functions provide these capabilities.

The flags argument controls how the space is to be mapped. Supported flags include:

BUS MAP_CACHEABLE
	Try to map the space so that accesses can be cached and/or prefetched by the system. If this flag is not specified, the implementation should map the space so that it will not be cached or prefetched. This flag must have a value of 1 on all implementations for backward compatibility.
BUS MAP_LINEAR	Try to map the space so that its contents can be accessed linearly via normal memory access methods (e.g.amp; pointer dereferencing and structure accesses). This is useful when software wants to do direct access to a memory device, e.g.amp; a frame buffer. If this flag is specified and linear mapping is not possible, the bus_space_map() call should fail. If this flag is not specified, the system may map the space in whatever way is most convenient.

Not all combinations of flags make sense or are supported with all spaces. For instance, BUS MAP_CACHEABLE may be meaningless when used on many systems' I/O port spaces, and on some systems BUS MAP_LINEAR without BUS MAP_CACHEABLE may never work. When the system hardware or firmware provides hints as to how spaces should be mapped (e.g.amp; the PCI memory mapping registers' "prefetchable" bit), those hints should be followed for maximum compatibility. On some systems, requesting a mapping that cannot be satisfied (e.g.amp; requesting a non-cacheable mapping when the system can only provide a cacheable one) will cause the request to fail.

Some implementations may keep track of use of bus space for some or all bus spaces and refuse to allow duplicate allocations. This is encouraged for bus spaces which have no notion of slot-specific space addressing, such as ISA, and for spaces which coexist with those spaces (e.g.amp; PCI memory and I/O spaces co-existing with ISA memory and I/O spaces).

After bus_space_unmap() is called on a handle, that handle is no longer valid. (If copies were made of the handle they are no longer valid, either.)

If successful, bus_space_subregion() returns zero and fills in the bus space handle pointed to by nhandlep. If unsuccessful, it returns non-zero and leaves the bus space handle pointed to by nhandlep in an undefined state. In either case, the handle described by handle remains valid and is unmodified.

When done with a handle created by bus_space_subregion(), the handle should be thrown away. Under no circumstances should bus_space_unmap() be used on the handle. Doing so may confuse any resource management being done on the space, and will result in undefined behaviour. When bus_space_unmap() or bus_space_free() is called on a handle, all subregions of that handle become invalid.

Constraints on the allocation are given by the reg_start, ,, reg_end, ,, alignment, and boundary parameters. The allocated region will start at or after reg_start and end before or at reg_end. The alignment constraint must be a power of two, and the allocated region will start at an address that is an even multiple of that power of two. The boundary constraint, if non-zero, ensures that the region is allocated so that first address in region / boundary has the same value as last address in region / boundary. If the constraints cannot be met, bus_space_alloc() will fail. It is an error to specify a set of constraints that can never be met (for example, size greater than boundary).

The flags parameter is the same as the like-named parameter to bus_space_map(), the same flag values should be used, and they have the same meanings.

After bus_space_free() is called on a handle, that handle is no longer valid. (If copies were made of the handle, they are no longer valid, either.)

This function will never fail. If it would fail (e.g.amp; because of an argument error), that indicates a software bug which should cause a panic. In that case, bus_space_free() will never return.

bus_space_read_1(space, handle, offset)

bus_space_read_2(space, handle, offset)

bus_space_read_4(space, handle, offset)

bus_space_read_8(space, handle, offset)

For portability, the starting address of the region specified by handle plus the offset should be a multiple of the size of data item being read. On some systems, not obeying this requirement may cause incorrect data to be read, on others it may cause a system crash.

Read operations done by the bus_space_read_N() functions may be executed out of order with respect to other pending read and write operations unless order is enforced by use of the bus_space_barrier() function.

bus_space_write_2(space, handle, offset, value)

bus_space_write_4(space, handle, offset, value)

bus_space_write_8(space, handle, offset, value)

For portability, the starting address of the region specified by handle plus the offset should be a multiple of the size of data item being written. On some systems, not obeying this requirement may cause incorrect data to be written, on others it may cause a system crash.

Write operations done by the bus_space_write_N() functions may be executed out of order with respect to other pending read and write operations unless order is enforced by use of the bus_space_barrier() function.

These functions will never fail. If they would fail (e.g.amp; because of an argument error), that indicates a software bug which should cause a panic. In that case, they will never return.

bus_space_barrier(space, handle, offset, length, flags)

The flags argument controls what types of operations are to be ordered. Supported flags are:

BUS BARRIER_READ	Synchronize read operations.
BUS BARRIER_WRITE
	Synchronize write operations.

Those flags can be combined (or-ed together) to enforce ordering on both read and write operations.

All of the specified type(s) of operation which are done to the region before the barrier operation are guaranteed to complete before any of the specified type(s) of operation done after the barrier.

Example: Consider a hypothetical device with two single-byte ports, one write-only input port (at offset 0) and a read-only output port (at offset 1). Operation of the device is as follows: data bytes are written to the input port, and are placed by the device on a stack, the top of which is read by reading from the output port. The sequence to correctly write two data bytes to the device then read those two data bytes back would be:

/*
 * t and h are the tag and handle for the mapped device's
 * space.
 */
bus_space_write_1(t, h, 0, data0);
bus_space_barrier(t, h, 0, 1, BUS BARRIER_WRITE);  /* 1 */
bus_space_write_1(t, h, 0, data1);
bus_space_barrier(t, h, 0, 2,
    BUS BARRIER_READ|BUS BARRIER_WRITE);     /* 2 */
ndata1 = bus_space_read_1(t, h, 1);
bus_space_barrier(t, h, 1, 1, BUS BARRIER_READ);   /* 3 */
ndata0 = bus_space_read_1(t, h, 1);
/* data0 == ndata0, data1 == ndata1 */

The first barrier makes sure that the first write finishes before the second write is issued, so that two writes to the input port are done in order and are not collapsed into a single write. This ensures that the data bytes are written to the device correctly and in order.

The second barrier makes sure that the writes to the output port finish before any of the reads to the input port are issued, thereby making sure that all of the writes are finished before data is read. This ensures that the first byte read from the device really is the last one that was written.

The third barrier makes sure that the first read finishes before the second read is issued, ensuring that data is read correctly and in order.

The barriers in the example above are specified to cover the absolute minimum number of bus space locations. It is correct (and often easier) to make barrier operations cover the device's whole range of bus space, that is, to specify an offset of zero and the size of the whole region.

bus_space_read_region_2(space, handle, offset, datap, count)

bus_space_read_region_4(space, handle, offset, datap, count)

bus_space_read_region_8(space, handle, offset, datap, count)

For portability, the starting address of the region specified by handle plus the offset should be a multiple of the size of data items being read and the data array pointer should be properly aligned. On some systems, not obeying these requirements may cause incorrect data to be read, on others it may cause a system crash.

Read operations done by the bus_space_read_region_N() functions may be executed in any order. They may also be executed out of order with respect to other pending read and write operations unless order is enforced by use of the bus_space_barrier() function. There is no way to insert barriers between reads of individual bus space locations executed by the bus_space_read_region_N() functions.

bus_space_write_region_2(space, handle, offset, datap, count)

bus_space_write_region_4(space, handle, offset, datap, count)

bus_space_write_region_8(space, handle, offset, datap, count)

For portability, the starting address of the region specified by handle plus the offset should be a multiple of the size of data items being written and the data array pointer should be properly aligned. On some systems, not obeying these requirements may cause incorrect data to be written, on others it may cause a system crash.

Write operations done by the bus_space_write_region_N() functions may be executed in any order. They may also be executed out of order with respect to other pending read and write operations unless order is enforced by use of the bus_space_barrier() function. There is no way to insert barriers between writes of individual bus space locations executed by the bus_space_write_region_N() functions.

bus_space_copy_region_2(space, srchandle, srcoffset, dsthandle)

bus_space_copy_region_4(space, srchandle, srcoffset, dsthandle)

bus_space_copy_region_8(space, srchandle, srcoffset, dsthandle)

For portability, the starting addresses of the regions specified by the each handle plus its respective offset should be a multiple of the size of data items being copied. On some systems, not obeying this requirement may cause incorrect data to be copied, on others it may cause a system crash.

Read and write operations done by the bus_space_copy_region_N() functions may be executed in any order. They may also be executed out of order with respect to other pending read and write operations unless order is enforced by use of the bus_space_barrier() function. There is no way to insert barriers between reads or writes of individual bus space locations executed by the bus_space_copy_region_N() functions.

Overlapping copies between different subregions of a single region of bus space are handled correctly by the bus_space_copy_region_N() functions.

bus_space_set_region_2(space, handle, offset, value, count)

bus_space_set_region_4(space, handle, offset, value, count)

bus_space_set_region_8(space, handle, offset, value, count)

For portability, the starting address of the region specified by handle plus the offset should be a multiple of the size of data items being written. On some systems, not obeying this requirement may cause incorrect data to be written, on others it may cause a system crash.

Write operations done by the bus_space_set_region_N() functions may be executed in any order. They may also be executed out of order with respect to other pending read and write operations unless order is enforced by use of the bus_space_barrier() function. There is no way to insert barriers between writes of individual bus space locations executed by the bus_space_set_region_N() functions.

These functions will never fail. If they would fail (e.g.amp; because of an argument error), that indicates a software bug which should cause a panic. In that case, they will never return.

bus_space_read_multi_1(space, handle, offset, datap, count)

bus_space_read_multi_2(space, handle, offset, datap, count)

bus_space_read_multi_4(space, handle, offset, datap, count)

bus_space_read_multi_8(space, handle, offset, datap, count)

For portability, the starting address of the region specified by handle plus the offset should be a multiple of the size of data items being read and the data array pointer should be properly aligned. On some systems, not obeying these requirements may cause incorrect data to be read, on others it may cause a system crash.

Read operations done by the bus_space_read_multi_N() functions may be executed out of order with respect to other pending read and write operations unless order is enforced by use of the bus_space_barrier() function. Because the bus_space_read_multi_N() functions read the same bus space location multiple times, they place an implicit read barrier between each successive read of that bus space location.

bus_space_write_multi_2(space, handle, offset, datap, count)

bus_space_write_multi_4(space, handle, offset, datap, count)

bus_space_write_multi_8(space, handle, offset, datap, count)

For portability, the starting address of the region specified by handle plus the offset should be a multiple of the size of data items being written and the data array pointer should be properly aligned. On some systems, not obeying these requirements may cause incorrect data to be written, on others it may cause a system crash.

Write operations done by the bus_space_write_multi_N() functions may be executed out of order with respect to other pending read and write operations unless order is enforced by use of the bus_space_barrier() function. Because the bus_space_write_multi_N() functions write the same bus space location multiple times, they place an implicit write barrier between each successive write of that bus space location.

bus_space_set_multi_2(space, handle, offset, value, count)

bus_space_set_multi_4(space, handle, offset, value, count)

bus_space_set_multi_8(space, handle, offset, value, count)

For portability, the starting address of the region specified by handle plus the offset should be a multiple of the size of data items being written and the data array pointer should be properly aligned. On some systems, not obeying these requirements may cause incorrect data to be written, on others it may cause a system crash.

Write operations done by the bus_space_set_multi_N() functions may be executed out of order with respect to other pending read and write operations unless order is enforced by use of the bus_space_barrier() function. Because the bus_space_set_multi_N() functions write the same bus space location multiple times, they place an implicit write barrier between each successive write of that bus space location.

These functions will never fail. If they would fail (e.g.amp; because of an argument error), that indicates a software bug which should cause a panic. In that case, they will never return.