segmap(D2DK) —

.IX \f4segmap\fP(D2DK)

NAME

segmap − map device memory into user space

SYNOPSIS

#include <sys/types.h>
#include <sys/mman.h>
#include <sys/param.h>
#include <sys/vm.h>
int prefixsegmap(dev_t dev, off_t off,struct as ∗asp, addr_t ∗addrp,
off_t len, unsigned int prot, unsigned int maxprot,
unsigned int flags, cred_t ∗cred_p);

ARGUMENTS

devDevice whose memory is to be mapped.

offOffset within device memory at which mapping begins.

∗aspPointer to the address space into which the device memory should be mapped.

∗addrpPointer to the address in the address space to which the device memory should be mapped.

lenLength (in bytes) of the memory to be mapped.

protProtection flag (from sys/mman.h) for example, PROT_WRITE, PROT_READ, PROT_USER (indicating the mapping is being done as a result of a mmap(2) system call).

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

flagsFlags indicating type of mmap (for example, MAP_SHARED vs. MAP_PRIVATE), whether the user specified an address (MAP_FIXED). Found in sys/mman.h.

∗cred_pPointer to a cred_t user credentials structure.

DESCRIPTION

The segmap entry point is an optional routine for character drivers that support memory mapping. The mmap(2) system call, when applied to a character special file, allows device memory to be mapped into user space for direct access by the user application (no kernel buffering overhead is required).

Typically, a character driver that needs to support the mmap(2) system call supplies either a single mmap(D2DK) entry point, or both an mmap and a segmap entry point routine (see the mmap(D2DK) reference page). If no segmap entry point is provided for the driver, the default kernel segmap routine is called to perform the mapping.

A driver for a memory-mapped device would provide a segmap entry point if it:

requires the mapping to be done through a virtual memory (VM) segment driver other than the default seg_dev driver provided by the kernel

needs to control the selection of the user address at which the mapping occurs in the case where the user did not specify an address in the mmap(2) system call

Among the responsibilities of a segmap entry point are:

Select a segment driver and check the memory map flags for appropriateness to the segment driver. For example, the seg_dev segment driver does not support memory maps that are marked MAP_PRIVATE (copy-on-write).

Verify that the range to be mapped makes sense in the context of the device (does the offset and length make sense for the device memory that is to be mapped). Typically, this task is performed by calling the mmap(D2DK) entry point.

If MAP_FIXED is not set in flags, obtain a user address at which to map. Otherwise, unmap any existing mappings at the user address specified.

Perform the mapping and return the error status if it fails.

RETURN VALUE

The routine returns 0 if the driver is successful in performing the memory map of its device address space into the specified address space. An error number should be returned on failure. For example, valid error numbers would be ENXIO if the offset/length pair specified exceeds the limits of the device memory, or EINVAL if the driver detects an invalid type of mapping attempted.