xref: /illumos-gate/usr/src/man/man9f/ddi_segmap.9f (revision bbf21555)
te
Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
DDI_SEGMAP 9F "Nov 17, 2003"
NAME
ddi_segmap, ddi_segmap_setup - set up a user mapping using seg_dev
SYNOPSIS

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



int ddi_segmap(dev_t dev, off_t offset, struct as *asp,
 caddr_t *addrp, off_t len, uint_t prot,
 uint_t maxprot, uint_t flags, cred_t *credp);

int ddi_segmap_setup(dev_t dev, off_t offset, struct as *asp,
 caddr_t *addrp, off_t len, uint_t prot,
 uint_t maxprot, uint_t flags, cred_t *credp,
 ddi_device_acc_attr_t *accattrp, uint_t rnumber);
INTERFACE LEVEL

These interfaces are obsolete. See devmap(9E) for an alternative to ddi_segmap(). Use devmap_setup(9F) instead of ddi_segmap_setup().

PARAMETERS
dev

The device whose memory is to be mapped.

offset

The offset within device memory at which the mapping begins.

asp

An opaque pointer to the user address space into which the device memory should be mapped.

addrp

Pointer to the starting address within the user 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. Some combinations of 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 are (other bits may be set): MAP_PRIVATE

Changes are private.

MAP_SHARED

Changes should be shared.

MAP_FIXED

The user specified an address in *addrp rather than letting the system pick and address.

credp

Pointer to user credential structure.

"ddi_segmap_setup(\|)"
dev_acc_attr

Pointer to a ddi_device_acc_attr(9S) structure which contains the device access attributes to apply to this mapping.

rnumber

Index number to the register address space set.

DESCRIPTION

Future releases of Solaris will provide this function for binary and source compatibility. However, for increased functionality, use ddi_devmap_segmap(9F) instead. See ddi_devmap_segmap(9F) for details.

ddi_segmap(\|) and ddi_segmap_setup() set up user mappings to device space. When setting up the mapping, the ddi_segmap(\|) and ddi_segmap_setup() routines call the mmap(9E) entry point to validate the range to be mapped. When a user process accesses the mapping, the drivers mmap(9E) entry point is again called to retrieve the page frame number that needs to be loaded. The mapping translations for that page are then loaded on behalf of the driver by the DDI framework.

ddi_segmap() is typically used as the segmap(9E) entry in the cb_ops(9S) structure for those devices that do not choose to provide their own segmap(9E) entry point. However, some drivers may have their own segmap(9E) entry point to do some initial processing on the parameters and then call ddi_segmap() to establish the default memory mapping.

ddi_segmap_setup() is used in the drivers segmap(9E) entry point to set up the mapping and assign device access attributes to that mapping. rnumber specifies the register set representing the range of device memory being mapped. See ddi_device_acc_attr(9S) for details regarding what device access attributes are available.

ddi_segmap_setup() cannot be used directly in the cb_ops(9S) structure and requires a driver to have a segmap(9E) entry point.

RETURN VALUES

ddi_segmap() and ddi_segmap_setup() return the following values: 0

Successful completion.

Non-zero

An error occurred. In particular, they return ENXIO if the range to be mapped is invalid.

CONTEXT

ddi_segmap() and ddi_segmap_setup() can be called from user or kernel context only.

ATTRIBUTES

See attributes(7) for a description of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE
Stability Level Obsolete
SEE ALSO

mmap (2), attributes (7), devmap (9E), mmap (9E), segmap (9E), devmap_setup (9F), cb_ops (9S), ddi_device_acc_attr (9S)

Writing Device Drivers