IMAP(3)

HP-UX

NAME

imap − map a set or subset of memory space into a process’ data space. iunmap − unmap a memory space mapped with the imap call.

SYNOPSIS

#include <sicl.h>

char *imap (
   INST id,
   int map_space,
   unsigned int pagestart,
   unsigned int pagecnt,
   char *suggested );

int iunmap (
   INST id,
   char *addr,
   int map_space,
   unsigned int pagestart,
   unsigned int pagecnt );

DESCRIPTION

VXI and MXI provides a mechanism to map a set or subset of memory space into a process’ data space. This memory can be used to control a VXI/MXI device or access other memory or I/O devices on the VXIbus or MXIbus.

imap maps in a specified memory space. The memory space that is mapped in is dependant on the type of interface specified by the id parameter, as well as the value of the map_space parameter.

Once the specified memory space to map is chosen, the pagestart parameter is used to indicate what page, within the given memory space, the map should begin. The size off the memory pages is dependant on the address space. The pagecnt parameter specifies the number of pages to map.

The value returned from the map call is the location (in the user’s process space) where the mapped memory is now located. If an error occurs, a NULL is returned. If the suggested parameter is non-NULL, then the O.S will attempt to map the memory starting at the specified memory location (in the user’s process space). However, no guarantee is made as to whether this attempt will be successful or not. If the O.S. can not map at the given location, it will map wherever it is able to (effectively ignoring the suggested parameter).

iunmap unmaps a memory space mapped with an imap call. The parameters are simular to the imap call with the addr parameter being the value returned from the imap call (i.e. the address in user space of the map).

If the id parameter specifies a MXI or VXI device, then the following are legal values for the map_space parameter:

        I_MAP_A16 - Map in VXI/MXI A16 address space. This works on
        VXI device and interface sessions only. Note that for this
        map request, the pagestart and pagecnt parameters are
        ignored (therefore, only the entire A16 address space may be
        mapped in).

        I_MAP_A24 - Map in VXI/MXI A24 address space (page size is
        64Kbytes). This works on VXI device and interface sessions
        only.

        I_MAP_A32 - Map in VXI/MXI A32 address space (page size is
        64Kbytes). This works on VXI device and interface sessions
        only.

        I_MAP_VXIDEV - Map in the VXI Device Registers for a given
        device. The device registers for the given device are mapped
        (64 bytes only). This works on device sessions only. The
        pagestart and pagecnt parameters are ignored.

        I_MAP_EXTEND - Map in the section of A24/A32 memory space that
        is owned by the device corresponding to this device driver.
        The location of this memory is determined by the A16 registers
        for this device (i.e. it looks at the offset register and
        A24/A32 memory bit). The value of pagestart is the offset
        (in 64k pages) into this devices extended memory. The value
        of pagecnt is the amount of memory (in 64k pages) to map.
        This works on device sessions only.

Note that, due to hardware constraints on a given interface card and system architecture, not all of these address spaces may be available on any given system. In addition, a maximum number of pages mapped simultaneously may be applied, along with a maximum amount of page range (i.e. page1 may not be able to be mapped simultaneously with page 50, however, page 1 may be able to be mapped simultaneously with page 2). These restrictions are system wide and, therefore, may be under the influence of other processes (if it is a multiprocess system).

If a map request cannot be achieved due to resource constraints, the imap call will sleep (hang) until the desired resources are available (if the isetlockwait flag is set, then an I_ERR_LOCKED error is returned. Also, if timeouts are enabled and a timeout occurs, an I_ERR_TIMEOUT error is returned). Resource constraints may be either O.S. resources, or interface card resources.

RETURN VALUE

imap return NULL if successful, otherwise the value returned is the location of the mapped memory.

iunmap returns (0) if successful, or a non-zero error code if an error was encountered.

ERRORS

imap and iunmap fail under the following circumstances, and set the return value to one of the following:

[I_ERR_NORSRC] Out of system resources

[I_ERR_NOINTF] Interface is not active

[I_ERR_NODEV] Device is not active

[I_ERR_BADID] The INST id is invalid

[I_ERR_BADADDR] Invalid address (device/interface doesn’t exist)

AUTHOR

imap, iunmap were developed by HP.

Hewlett-Packard Company — September 29, 1999

Museum

Related Articles