io_map_init Kernel Service

Purpose

Creates and initializes an I/O mapping segment.

Syntax

#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 */
};

Description

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.

Parameters

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.

Execution Environment

The io_map_init kernel service can be called from the process environment only.

Return Values

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.