SVR5

mmap(D2)

mmap -- support virtual mapping for memory-mapped device

Synopsis

   #include <sys/types.h>
   #include <sys/mman.h>
   #include <sys/vm.h>
   #include <sys/ddi.h>
   
   ppid_t prefixmmap(void *idata, channel_t channel,
                     size_t offset, int prot);

Description

The driver's mmap( ) entry point is called to provide direct user access to memory for memory-mapped devices. A memory-mapped device has memory that can be mapped into a process's address space. The mmap system call, when applied to a device special file, allows this device memory to be mapped into user space for direct access by the user application. This avoids overhead from kernel buffering and system calls.

This entry point maps one page, at the specified relative logical offset within the device's memory. This offset space may be different from offsets used for normal I/O; therefore, it is the driver's responsibility to validate offsets.

Arguments

idata: For hardware drivers, a pointer to the device-specific instance as returned by the CFG_ADD subfunction of the config(D2) entry point routine. For software-only drivers, idata is unused and undefined. See ``Device instance'' in HDK Technical Reference.
channel: Channel number used to select subcomponents and/or operating modes of this device instance. See ``Channel number'' in HDK Technical Reference.
offset: Byte offset within the driver's mappable memory for this device instance. Page aligned. This value must be a multiple of ptob(1) (the ptob(D3) function passed the value of 1, which returns the size of a page, in bytes).
prot: Protection flags.

Return values

If the protection and offset are valid for the device, the driver should return the physical page ID as returned by devmem_ppid(D3) or kvtoppid(D3). Otherwise, NOPAGE should be returned.

Usage

This entry point is optional. If it is not provided, mmap attempts fail with the ENODEV error number. This entry point is called only when the device is open.

Valid values for prot are:

PROT_READ: Page can be read.
PROT_WRITE: Page can be written.
PROT_EXEC: Page can be executed.
PROT_USER: Page is accessible from user-level.
PROT_ALL: All of the above.

A physical page ID is a machine-specific token that uniquely identifies a page of physical memory in the system (either kernel memory or device memory). To get the physical page ID for a given virtual address, use the kvtoppid(D3) function. To get the physical page ID for a given physical address, use the devmem_ppid(D3) function.

No assumptions should be made about the format of a physical page ID.

After mmap( ) returns successfully, the mapping remains in use until the device instance is closed, which is the next last close for this device instance. Any memory so mapped must not be freed until after the device instance is closed.

Context and synchronization

User context. The driver can block and can do operations such as copyout(D3) that require access to the requesting process's user-level address space.

Hardware applicability

All

Version applicability

ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp

Differences between versions

The syntax for mmap( ) in DDI versions prior to version 8 is:

   int prefixmmap(dev_t dev, off_t offset, int prot);

dev is the device number for the device to be mapped.

In DDI versions prior to version 8, mmap( ) is only available to character device drivers and is a named entry point, so must be defined as a global symbol.

External dependencies

For DDI 8 and later versions, drivers must declare this entry point routine in the d_mmap member of their drvops(D4) structure.

Named entry point routines must be declared in the driver's Master(DSP/4dsp) file. The declaration for this entry point is $entry mmap. This applies only to non-STREAMS drivers that use DDI versions prior to version 8.

References

devmem_ppid(D3), hat_getkpfnum(D3), hat_getppfnum(D3), kvtoppid(D3), mmap, phystoppid(D3), ptob(D3)

``Memory-mapped I/O'' in HDK Technical Reference