'\"macro stdmacro
.if n .pH ddi_dki.segmap @(#)segmap	40.6 of 10/10/89
.\" Copyright 1989 AT&T
.de IX
.ie '\\n(.z'' .tm .Index: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9	\\n%
.el \\!.IX \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..
.nr X
.if \nX=0 .ds x} segmap D2K "" "DKI" "\&"
.if \nX=1 .ds x} segmap D2K "" "DKI"
.if \nX=2 .ds x} segmap D2K "" "\&"
.if \nX=3 .ds x} segmap "" "" "\&"
.TH \*(x}
.IX "\f4segmap\fP(D2K)"
.SH "NAME"
\f4segmap\f1 \- map device memory into user space
.SH "SYNOPSIS"
.nf
.na
\f4
#include <sys/types.h>
#include <sys/mman.h>
#include <sys/param.h>
#include <sys/vm.h>
.sp 0.5
int \f2prefix\f4segmap(\f4dev_t \f2dev, \f4off_t\f1 \f2off,\f4struct as *\f2asp, \f4addr_t *\f1\f2addrp,
	\f4off_t\f1 \f2len, \f4unsigned int\f1 \f2prot, \f4unsigned int\f1 \f2maxprot,
	\f4unsigned int\f1 \f2flags, \f4cred_t *\f1\f2cred_p);\f1
.ad
.fi
.SH ARGUMENTS
.RS 0n
.IP "\f2dev\f1" 10n
Device whose memory is to be mapped.
.IP "\f2off\f1" 10n
Offset within device memory at which mapping begins.
.IP "\f2*asp\f1" 10n
Pointer to the address space into which the device
memory should be mapped.
.IP "\f2*addrp\f1" 10n
Pointer to the address in the address space to which
the device memory should be mapped.
.IP "\f2len\f1" 10n
Length (in bytes) of the memory to be mapped.
.IP "\f2prot\f1" 10n
Protection flag (from \f4sys/mman.h\f1) for example, \f4PROT_WRITE,
PROT_READ, PROT_USER\f1 (indicating the mapping is 
being done as a result of a \f4mmap\f1(2) system call).
.IP "\f2maxprot\f1" 10n
Maximum protection flag possible for attempted map
(\f4PROT_WRITE\f1 may be masked out if the user opened the
special file read-only). If \f4(maxprot & prot\f1) != prot\f1
then there is an access violation.
.IP  "\f2flags\f1" 10n
Flags indicating type of mmap (for example, \f4MAP_SHARED\f1 vs.
\f4MAP_PRIVATE\f1), whether the user specified an address
(\f4MAP_FIXED\f1). Found in \f4sys/mman.h\f1.
.IP "\f2*cred_p\f1" 10n
Pointer to the \f4cred\f1(D4DK) user credentials structure.
.RE
.SH DESCRIPTION
The \f4segmap\f1 entry point is an optional routine for character
drivers that support memory mapping.  The \f4mmap\f1(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).
.P
Typically, a character driver that needs to support the \f4mmap\f1(2)
system call supplies either a single \f4mmap\f1(D2K) entry point, or both
an \f4mmap\f1 and a \f4segmap\f1 entry point routine (see the
\f4mmap\f1(D2K) reference page).  If no \f4segmap\f1 entry point is
provided for the driver, the default kernel \f4segmap\f1 routine is
called to perform the mapping.
.P
A driver for a memory-mapped device would provide a \f4segmap\f1
entry point if it:
.IP
requires the mapping to be done through a virtual memory (VM)
segment driver other than the default \f4seg_dev\f1 driver provided
by the kernel
.IP
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 \f4mmap\f1(2) system call
.P
Among the responsibilities of a \f4segmap\f1 entry point are:
.IP
Select a segment driver and check the memory map flags for appropriateness
to the segment driver.  For example, the \f4seg_dev\f1 segment driver does
not support memory maps that are marked \f4MAP_PRIVATE\f1 (copy-on-write).
.IP
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 \f4mmap\f1(D2K) entry point.
.IP
If \f4MAP_FIXED\f1 is not set in \f2flags\f1, obtain a user address at which
to map.  Otherwise, unmap any existing mappings at the user address specified. 
.IP
Perform the mapping and return the error status if it fails.
.SH RETURN VALUE
The routine returns \f40\f1 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 \f4ENXIO\f1 if the
offset/length pair specified exceeds the limits of the device
memory, or \f4EINVAL\f1 if the driver detects an invalid type of
mapping attempted. 
.SH SEE ALSO
.na
\f4mmap\f1(D2K)
.ad
