ddi_mapdev(9F)

NAME

ddi_mapdev − create driver-controlled mapping of device

SYNOPSIS

#include <sys/ddi.h>
#include <sys/sunddi.h>

int ddi_mapdev(dev_t dev, off_t offset, struct as ∗as, caddr_t ∗addrp, off_t len,

u_int prot, u_int maxprot, u_int flags, cred_t ∗cred, struct ddi_mapdev_ctl ∗ctl,

ddi_mapdev_handle_t ∗handlep, void ∗devprivate);

INTERFACE LEVEL

Solaris DDI specific (Solaris DDI).

ARGUMENTS

dev The device whose memory is to be mapped.

offset The offset within device memory at which the mapping begins.

as An opaque pointer to the user address space into which the device memory should be mapped.

addrp Pointer to the starting address within the user address space to which the device memory should be mapped.

len Length (in bytes) of the memory to be mapped.

prot A bit field that specifies the protections. Some combinations of possible settings are:

PROT_READ Read access is desired.

PROT_WRITE
Write access is desired.

PROT_EXEC Execute access is desired.

PROT_USER User-level access is desired (the mapping is being done as a result of a mmap(2) system call).

PROT_ALL All access is desired.

maxprot Maximum protection flag possible for attempted mapping (the PROT_WRITE bit may be masked out if the user opened the special file read-only). If (maxprot & prot) != prot then there is an access violation.

flags Flags indicating type of mapping. Possible values are (other bits may be set):

MAP_PRIVATE Changes are private.

cred Pointer to the user credentials structure.

ctl A pointer to a ddi_mapdev_ctl(9S) structure. The structure contains pointers to device driver-supplied functions that manage events on the device mapping.

handlep An opaque pointer to a device mapping handle. A handle to the new device mapping is generated and placed into the location pointed to by ∗handlep. If the call fails, the value of ∗handlep is undefined.

devprivate Driver private mapping data. This value is passed into each mapping call back routine.

DESCRIPTION

ddi_mapdev() sets up user mappings to device space in the same manner as ddi_segmap(9F). However, unlike mappings created with ddi_segmap(), mappings created with ddi_mapdev() have a set of driver entry points and a mapping handle associated with them. The driver is notified via these entry points in response to user events on the mappings. The events defined on these mappings are:

access User has accessed an address in the mapping that has no translations.

duplication User has duplicated the mapping. Mappings are duplicated when the process calls fork(2).

unmapping User has called munmap(2) on the mapping or is exiting.

See mapdev_access(9E), mapdev_dup(9E), and mapdev_free(9E) for details on these entry points.

With the handle, device drivers can use ddi_mapdev_intercept(9F) and ddi_mapdev_nointercept(9F) to inform the system of whether or not they are interested in being notified when the user process accesses the mapping. By default, user accesses to newly created mappings will generate a call to the mapdev_access() entry point. The driver is always notified of duplications and unmaps.

The device driver can use these interfaces to implement a device context and control user accesses to the device space. Only mappings of type MAP_PRIVATE should be used with ddi_mapdev().

RETURN VALUES

ddi_mapdev() returns zero on success and non-zero on failure. The return value from ddi_mapdev() should be used as the return value for the drivers segmap() entry point.

CONTEXT

This routine can be called from user or kernel context only.

Museum

Related Articles