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>
#include <sys/ddi.h>
#include <sys/sunddi.h>

int prefixsegmap(dev_t dev, off_t off, struct as * asp,caddr_t * addrp,off_t len, unsigned int prot, unsigned int maxprot, unsigned int flags, cred_t * cred_p);

ARGUMENTS

dev

Device whose memory is to be mapped.

off

Offset within device memory at which mapping begins.

asp

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

addrp

Pointer to the address in the 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. 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 re:

MAP_SHARED

Changes should be shared.

MAP_PRIVATE

Changes are private.

MAP_FIXED

The user specified an address in * addrprather than letting

the system pick an address.

cred_p

Pointer to the user credentials structure.

INTERFACE LEVEL

Architecture independent level 2 (DKI only).

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(9E) entry point, or both an mmap (9E) and a segmap( ) entry point routine (see the mmap(9E) 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 (do the offset and length make sense for the device memory that is to be mapped). Typically, this task is performed by calling the mmap(9E) 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 VALUES

The segmap () routine should return 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.

SEE ALSO

mmap(2), mmap(9E)

Writing Device Drivers