mmap_device_memory()

Map a device's physical memory into a process's address space

Synopsis:

#include <sys/mman.h>

void * mmap_device_memory( void * addr,
                           size_t len,
                           int prot,
                           int flags,
                           uint64_t physical );

Description:

The mmap_device_memory() function maps len bytes of a device's physical memory address into the caller's address space at the location returned by mmap_device_memory().

You should use this function instead of using mmap() with the MAP_PHYS flag.

The arguments are as follows:

addr

Where the object should be mapped in the calling process's address space (typically, you don't need to use addr, you can just pass NULL instead). If you set addr to a non-NULL value, whether the object is mapped depends if MAP_FIXED is set in flags.

MAP_FIXED is set: The object is mapped to the address in addr or the function fails.
MAP_FIXED isn't set: The value of addr is taken as a hint to where the object should be mapped in the calling process's address space. The mapped area won't overlay any current mapped areas.

len

Number of bytes to map into the caller's address space.

prot

Specifies the access capabilities for the memory region being mapped. At least the following protection bits may be combined, as defined in <sys/mman.h>:

Protection	Description
PROT_EXEC	The region can be executed.
PROT_NOCACHE	Disable caching of the region (e.g. can be used to access dual-ported memory).

Read the architecture guide for your processor -- you may need to add special instructions! For example, if you specify PROT_NOCACHE on a PPC device, you may need to issue special eieio() instructions to ensure that writes occur in a desired order.

PROT_NONE	The region can't be accessed.
PROT_READ	The region can be read.
PROT_WRITE	The region can be written.

flags

Specifies further information about handling the mapped region. The following flag may be used:

MAP_FIXED: Map object to the address specified by addr. If this area is already mapped, the call changes the existing mapping of the area. MAP_FIXED should be used with caution. Not all memory models will support it. In general, you should only assume that you can MAP_FIXED at an address (and size) which was returned by calling mmap() without MAP_FIXED in your code. These restrictions will be removed from the user-to-user protection model with the full VM (available with a later version of the QNX OS).
A memory area being mmap()'d with MAP_FIXED will first be munmap()'d by the system using the same memory area. See munmap() for details.

This function already uses MAP_SHARED ORed with MAP_PHYS (see mmap() for a description of these flags).

physical

The physical address of the memory to map into the caller's address space.

Returns:

The address of the mapped-in object, or MAP_FAILED if an error occurs (errno is set).

Errors:

EINVAL: Invalid flags type.
ENOMEM: The address range requested is outside of the allowed process address range, or there wasn't enough memory to satisfy the request.
ENXIO: The address from physical for len bytes is invalid for the requested object, or MAP_FIXED was specified and addr, len, and physical are invalid for the requested object.

Examples:

/* map in the physical memory, 0xb8000 is text mode VGA video memory */
    
ptr = mmap_device_memory( 0, len, PROT_READ|PROT_WRITE|PROT_NOCACHE, 0, 0xb8000 );
if ( ptr == MAP_FAILED ) {
    perror( "mmap_device_memory for physical address 0xb8000 failed" );
    exit( EXIT_FAILURE );
}

Classification:

QNX 6

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes