Creates and initializes an I/O mapping segment.
#include <sys/adspace.h>
#include <sys/vm_types.h>
io_handle_t io_map_init (io_map_ptr, page_offset, io_handle)
struct io_map *io_map_ptr;
vpn_t page_offset;
io_handle_t io_handle;
struct io_map {
int key; /* structure version number */
int flags; /* flags for mapping */
int32long64_t size; /* size of address space needed */
int bid; /* bus ID */
long long busaddr; /* bus address */
};The io_map_init kernel service will create a segment to establish a cache-inhibited virtual-to-real translation for the bus address region defined by the contents of the io_map struct. The flags parameter of the io_map structure can be used to customize the mapping such as making the region read-only, using the IOM_RDONLY flag.
The io_map_init kernel service returns a handle of an opaque type io_handle_t to be used on future io_map or io_unmap calls. All services that use the io_handle returned by io_map_init must use the handle from the most recent call. Using an old handle is a programming error.
The vpn_t type parameter represents the virtual page number offset to allow the caller to specify where, in the virtual segment, to map this region. The offset must not conflict with a previous mapping in the segment. The caller should map the most frequently accessed and performance critical I/O region at vpn_t offset 0 into the segment. This is due to the fact that the subsequent io_map calls using this io_handle will return an effective address representing the start of the segment (that is, page offset 0). The device driver is responsible for managing various offsets into the segment. A single bus memory address page can be mapped multiple times at different vpn_t offsets within the segment.
The io_handle_t parameter is useful when the caller wants to append a new mapping to an existing segment. For the initial creation of a new I/O segment, this parameter must be NULL. For appended mappings to the same segment, this parameter is the io_handle_t returned from the last successful io_map_init call. If the mapping fails for any reason (offset conflicts with prior mapping, or no more room in the segment), NULL is returned. In this case, the previous io_handle_t is still valid. If successful, the io_handle_t returned should be used on all future calls. In this way, a device driver can manage multiple I/O address spaces of a single adapter within a single virtual address segment, requiring the driver to do only a single attach, io_map, to gain addressibility to all of the mappings.
| Item | Description |
|---|---|
| io_map_ptr | Pointer to io_map structure describing the address region to map. |
| page_offset | Page offset at which to map the specified region into the virtual address segment. |
| io_handle | For the first call, this parameter should be NULL. When adding to an existing mapping, this parameter is the io_handle received on a prior successful call to io_map_init. |
The io_map_init kernel service can be called from the process environment only.
| Item | Description |
|---|---|
| io_handle_t | An opaque handle to the mapped I/O segment in the virtual memory that must be used in subsequent calls to this service. |
| NULL | Failed to create or append mapping. |