devmap_umem_setup(9F)
NAME
devmap_devmem_setup, devmap_umem_setup - set driver memory
mapping parameters
SYNOPSIS
#include <sys/ddi.h>
#include <sys/sunddi.h>
int devmap_devmem_setup(devmap_cookie_t dhp, dev_info_t
*dip, struct devmap_callback_ctl *callbackops, uint_t
rnumber, offset_t roff, size_t len, uint_t maxprot, uint_t
flags, ddi_device_acc_attr_t *accattrp);
int devmap_umem_setup(devmap_cookie_t dhp, dev_info_t *dip,
struct devmap_callback_ctl *callbackops, ddi_umem_cookie_t
cookie, offset_t koff, size_t len, uint_t maxprot, uint_t
flags, ddi_device_acc_attr_t *accattrp);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI).
PARAMETERS
devmap_devmem_setup() parameters:
dhp An opaque mapping handle that the system uses to
describe the mapping.
dip Pointer to the device's dev_info structure.
callbackops
Pointer to a devmap_callback_ctl(9S) structure. The
structure contains pointers to device driver-supplied
functions that manage events on the device mapping.
The framework will copy the structure to the system
private memory.
rnumber
Index number to the register address space set.
roff Offset into the register address space.
len Length (in bytes) of the mapping to be mapped.
maxprot
Maximum protection flag possible for attempted map-
ping. Some combinations of possible settings are:
PROT_READ
Read access is allowed.
PROT_WRITE
Write access is allowed.
PROT_EXEC
Execute access is allowed.
PROT_USER
User-level access is allowed (the mapping is
being done as a result of a mmap(2) system
call).
PROT_ALL
All access is allowed.
flags Must be set to 0.
accattrp
Pointer to a ddi_device_acc_attr(9S) structure. The
structure contains the device access attributes to be
applied to this range of memory.
devmap_umem_setup() parameters:
dhp An opaque data structure that the system uses to
describe the mapping.
dip Pointer to the device's dev_info structure.
callbackops
Pointer to a devmap_callback_ctl(9S) structure. The
structure contains pointers to device driver-supplied
functions that manage events on the device mapping.
cookie
A kernel memory cookie (see ddi_umem_alloc(9F)).
koff Offset into the kernel memory defined by cookie.
len Length (in bytes) of the mapping to be mapped.
maxprot
Maximum protection flag possible for attempted map-
ping. Some combinations of possible settings are:
PROT_READ
Read access is allowed.
PROT_WRITE
Write access is allowed.
PROT_EXEC
Execute access is allowed.
PROT_USER
User-level access is allowed (the mapping is
being done as a result of a mmap(2) system
call).
PROT_ALL
All access is allowed.
flags Must be set to 0.
accattrp
Pointer to a ddi_device_acc_attr(9S) structure.
Ignored in the current release. Reserved for future
use.
DESCRIPTION
devmap_devmem_setup() and devmap_umem_setup() are used in
the devmap(9E) entry point to pass mapping parameters from
the driver to the system.
dhp is a device mapping handle that the system uses to store
all mapping parameters of a physical contiguous memory. The
system copies the data pointed to by callbackops to a system
private memory. This allows the driver to free the data
after returning from either devmap_devmem_setup() or
devmap_umem_setup(). The driver is notified of user events
on the mappings via the entry points defined by
devmap_callback_ctl(9S). The driver is notified of the fol-
lowing user events:
Mapping Setup
User has called mmap(2) to create a mapping to the
device memory.
Access
User has accessed an address in the mapping that has
no translations.
Duplication
User has duplicated the mapping. Mappings are dupli-
cated when the process calls fork(2).
Unmapping
User has called munmap(2) on the mapping or is exit-
ing, exit(2).
See devmap_map(9E), devmap_access(9E), devmap_dup(9E), and
devmap_unmap(9E) for details on these entry points.
By specifying a valid callbackops to the system, device
drivers can manage events on a device mapping. For example,
the devmap_access(9E) entry point allows the drivers to
perform context switching by unloading the mappings of other
processes and to load the mapping of the calling process.
Device drivers may specify NULL to callbackops which means
the drivers do not want to be notified by the system.
The maximum protection allowed for the mapping is specified
in maxprot. accattrp defines the device access attributes.
See ddi_device_acc_attr(9S) for more details.
devmap_devmem_setup() is used for device memory to map in
the register set given by rnumber and the offset into the
register address space given by roff. The system uses
rnumber and roff to go up the device tree to get the physi-
cal address that corresponds to roff. The range to be
affected is defined by len and roff. The range from roff to
roff + len must be a physical contiguous memory and page
aligned.
Drivers use devmap_umem_setup() for kernel memory to map in
the kernel memory described by cookie and the offset into
the kernel memory space given by koff. cookie is a kernel
memory pointer obtained from ddi_umem_alloc(9F). If cookie
is NULL, devmap_umem_setup() returns -1. The range to be
affected is defined by len and koff. The range from koff to
koff + len must be within the limits of the kernel memory
described by koff + len and must be page aligned.
Drivers use devmap_umem_setup() to export the kernel memory
allocated by ddi_umem_alloc(9F) to user space. The system
selects a user virtual address that is aligned with the ker-
nel virtual address being mapped to avoid cache incoherence
if the mapping is not MAP_FIXED.
RETURN VALUES
0 Successful completion.
-1 An error occurred.
CONTEXT
devmap_devmem_setup() and devmap_umem_setup() can be called
from user, kernel, and interrupt context.
SEE ALSO
exit(2), fork(2), mmap(2), munmap(2), devmap(9E),
ddi_umem_alloc(9F), ddi_device_acc_attr(9S),
devmap_callback_ctl(9S)
Writing Device Drivers
Man(1) output converted with
man2html