devmap_map(9e) [sunos man page]
devmap_map(9E) Driver Entry Points devmap_map(9E) NAME
devmap_map - device mapping create entry point SYNOPSIS
#include <sys/ddi.h> #include <sys/sunddi.h> int prefixdevmap_map(devmap_cookie_t dhp, dev_t dev, uint_t flags, offset_t off, size_t len, void **pvtp); INTERFACE LEVEL
Solaris DDI specific (Solaris DDI). ARGUMENTS
dhp An opaque mapping handle that the system uses to describe the mapping currently being created. dev The device whose memory is to be mapped. flags Flags indicating type of mapping. Possible values are: MAP_PRIVATE Changes are private. MAP_SHARED Changes should be shared. off User offset within the logical device memory at which the mapping begins. len Length (in bytes) of the memory to be mapped. pvtp A pointer to be filled in by device drivers with the driver private mapping data. DESCRIPTION
The devmap_map() entry point is an optional routine that allows drivers to perform additional processing or to allocate private resources during the mapping setup time. For example, in order for device drivers to support context switching, the drivers allocate private mapping data and associate the private data with the mapping parameters in the devmap_map() entry point. The system calls devmap_map() after the user mapping to device physical memory has been established. (For example, after the devmap(9E) entry point is called.) devmap_map() receives a pointer to the driver private data for this mapping in pvtp. The system expects the driver to allocate its private data and set *pvtp to the allocated data. The driver must store off and len, which define the range of the mapping, in its private data. Later, when the system calls devmap_unmap(9E), the driver will use the off and len stored in pvtp to check if the entire mapping, or just a part of it, is being unmapped. If only a part of the mapping is being unmapped, the driver must allocate a new private data for the remaining mapping before freeing the old private data. The driver will receive *pvtp in subsequent event notification callbacks. If the driver support context switching, it should store the mapping handle dhp in its private data *pvtp for later use in devmap_unload(9F). For a driver that supports context switching, flags indicates whether or not the driver should allocate a private context for the mapping. For example, a driver may allocate a memory region to store the device context if flags is set to MAP_PRIVATE. RETURN VALUES
devmap_map() returns the following values: 0 Successful completion. Non-zero An error occurred. EXAMPLES
Example 1: devmap_map()implementation The following shows an example implementation for devmap_map(). static int xxdevmap_map(devmap_cookie_t dhp, dev_t dev, uint_t flags, offset_t off, size_t len, void **pvtp) { struct xx_resources *pvt; struct xx_context *this_context; struct xx_softc *softc; softc = ddi_get_soft_state(statep, getminor(dev)); this_context = get_context(softc, off, len); /* allocate resources for the mapping - Device dependent */ pvt = kmem_zalloc(sizeof (struct xx_resources), KM_SLEEP); pvt->off = off; pvt->len = len; pvt->dhp = dhp; pvt->ctx = this_context; *pvtp = pvt; } SEE ALSO
devmap_unmap(9E), devmap_unload(9F), devmap_callback_ctl(9S) Writing Device Drivers SunOS 5.10 7 Jan 1997 devmap_map(9E)
Check Out this Related Man Page
devmap_unmap(9E) Driver Entry Points devmap_unmap(9E) NAME
devmap_unmap - device mapping unmap entry point SYNOPSIS
#include <sys/ddi.h> #include <sys/sunddi.h> void prefixdevmap_unmap(devmap_cookie_t dhp, void *pvtp, offset_t off, size_tlen, devmap_cookie_t new_dhp1, void **new_pvtp1, devmap_cookie_tnew_dhp2, void **new_pvtp2); INTERFACE LEVEL
Solaris DDI specific (Solaris DDI). ARGUMENTS
dhp An opaque mapping handle that the system uses to describe the mapping. pvtp Driver private mapping data. off User offset within the logical device memory at which the unmapping begins. len Length (in bytes) of the memory being unmapped. new_dhp1 The opaque mapping handle that the system uses to describe the new region that ends at (off - 1) . new_dhp1 may be NULL. new_pvtp1 A pointer to be filled in by the driver with the driver private mapping data for the new region that ends at (off - 1); ignored if new_dhp1 is NULL. new_dhp2 The opaque mapping handle that the system uses to describe the new region that begins at (off + len); new_dhp2 may be NULL. new_pvtp2 A pointer to be filled in by the driver with the driver private mapping data for the new region that begins at (off + len); ignored if new_dhp2 is NULL. DESCRIPTION
devmap_unmap() is called when the system removes the mapping in the range [ off, off + len ], such as in the munmap(2) or exit(2) system calls. Device drivers use devmap_unmap() to free up the resources allocated in devmap_map(9E). dhp is the mapping handle that uniquely identifies the mapping. The driver stores the mapping attributes in the driver's private data, pvtp, when the mapping is created. See devmap_map(9E) for details. off and len define the range to be affected by devmap_unmap(). This range is within the boundary of the mapping described by dhp. If the range [ off, off + len ] covers the entire mapping, the system passes NULL to new_dhp1, new_pvtp1, new_dhp2, and new_pvtp2. The system expects device drivers to free all resources allocated for this mapping. If off is at the beginning of the mapping and len does not cover the entire mapping, the system sets NULL to new_dhp1 and to new_pvtp1. The system expects the drivers to allocate new driver private data for the region that starts at off + len and to set *new_pvtp2 to point to it. new_dhp2 is the mapping handle of the newly mapped object. If off is not at the beginning of the mapping, but off + len is at the end of the mapping the system passes NULL to new_dhp2 and new_pvtp2. The system then expects the drivers to allocate new driver private data for the region that begins at the beginning of the map- ping (for example, stored in pvtp) and to set *new_pvtp1 to point to it. new_dhp1 is the mapping handle of the newly mapped object. The drivers should free up the driver private data, pvtp, previously allocated in devmap_map(9E) before returning to the system. EXAMPLES
Example 1: devmap_unmap() implementation static void xxdevmap_unmap(devmap_cookie_t dhp, void *pvtp, offset_t off, size_t len, devmap_cookie_t new_dhp1, void **new_pvtp1, devmap_cookie_t new_dhp2, void **new_pvtp2) { struct xxpvtdata *ptmp; struct xxpvtdata *p = (struct xxpvtdata *)pvtp; struct xx_softc *softc = p->softc; mutex_enter(&softc->mutex); /* * If new_dhp1 is not NULL, create a new driver private data * for the region from the beginning of old mapping to off. */ if (new_dhp1 != NULL) { ptmp = kmem_zalloc(sizeof (struct xxpvtdata), KM_SLEEP); ptmp->dhp = new_dhp1; ptmp->off = pvtp->off; ptmp->len = off - pvtp->off; *new_pvtp1 = ptmp; } /* * If new_dhp2 is not NULL, create a new driver private data * for the region from off+len to the end of the old mapping. */ if (new_dhp2 != NULL) { ptmp = kmem_zalloc(sizeof (struct xxpvtdata), KM_SLEEP); ptmp->off = off + len; ptmp->len = pvpt->len - (off + len - pvtp->off); ptmp->dhp = new_dhp2; *new_pvtp2 = ptmp; } /* Destroy the driver private data - Device dependent */ ... kmem_free(pvtp, sizeof (struct xxpvtdata)); mutex_exit(&softc->mutex); } SEE ALSO
exit(2), munmap(2), devmap_map(9E), devmap_callback_ctl(9S) Writing Device Drivers SunOS 5.10 21 Jan 1997 devmap_unmap(9E)