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.
The io_map_init kernel service can be called from the process environment only.
| 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. |
io_map_clear Kernel Service, io_map Kernel Service, and io_unmap Kernel Service.
Programmed I/O (PIO) Kernel Services in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.