Tribblix: manual page: devmap

DEVMAP_MAP(9E) Driver Entry Points DEVMAP_MAP(9E)

NAME

devmap_map - device mapping create entry point

SYNOPSIS

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

int prefixdevmap_map(devmap_cookie_t dhp, dev_t dev,
uint_t flags, offset_t off, size_t len, void **pvtp);

INTERFACE LEVEL

illumos DDI specific (illumos DDI).

ARGUMENTS

dhp
An opaque mapping handle that the system uses to describe
the mapping currently being created.

dev
The device whose memory is to be mapped.

flags
Flags indicating type of mapping. Possible values are:

MAP_PRIVATE
Changes are private.

MAP_SHARED
Changes should be shared.

off
User offset within the logical device memory at which the
mapping begins.

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

pvtp
A pointer to be filled in by device drivers with the driver
private mapping data.

DESCRIPTION

The devmap_map() entry point is an optional routine that allows
drivers to perform additional processing or to allocate private
resources during the mapping setup time. For example, in order for
device drivers to support context switching, the drivers allocate
private mapping data and associate the private data with the mapping
parameters in the devmap_map() entry point.

The system calls devmap_map() after the user mapping to device
physical memory has been established. (For example, after the
devmap(9E) entry point is called.)

devmap_map() receives a pointer to the driver private data for this
mapping in pvtp. The system expects the driver to allocate its
private data and set *pvtp to the allocated data. The driver must
store off and len, which define the range of the mapping, in its
private data. Later, when the system calls devmap_unmap(9E), the
driver will use the off and len stored in pvtp to check if the
entire mapping, or just a part of it, is being unmapped. If only a
part of the mapping is being unmapped, the driver must allocate a
new private data for the remaining mapping before freeing the old
private data. The driver will receive *pvtp in subsequent event
notification callbacks.

If the driver support context switching, it should store the mapping
handle dhp in its private data *pvtp for later use in
devmap_unload(9F).

For a driver that supports context switching, flags indicates whether
or not the driver should allocate a private context for the mapping.
For example, a driver may allocate a memory region to store the
device context if flags is set to MAP_PRIVATE.

RETURN VALUES

devmap_map() returns the following values:

0
Successful completion.

Non-zero
An error occurred.

EXAMPLES

Example 1 devmap_map()implementation

The following shows an example implementation for devmap_map().

static int
xxdevmap_map(devmap_cookie_t dhp, dev_t dev, uint_t flags, \
offset_t off,size_t len, void **pvtp)
{
struct xx_resources *pvt;
struct xx_context *this_context;
struct xx_softc *softc;
softc = ddi_get_soft_state(statep, getminor(dev));

this_context = get_context(softc, off, len);

/* allocate resources for the mapping - Device dependent */
pvt = kmem_zalloc(sizeof (struct xx_resources), KM_SLEEP);

pvt->off = off;
pvt->len = len;
pvt->dhp = dhp;
pvt->ctx = this_context;
*pvtp = pvt;
}