mmap_device_memory()

Arguments:

addr

NULL, or a pointer to where you want to map the object in the calling process's address space.

len

The number of bytes you want to map into the caller's address space. It can't be 0.

prot

The access capabilities that you want to use for the memory region being mapped. You can use a combination of at least the following protection bits, as defined in <sys/mman.h>:

• PROT_EXEC — the region can be executed.
  Note:

  To successfully use this flag, your process must have the PROCMGR_AID_PROT_WRITE_AND_EXEC ability enabled. For more information, see procmgr_ability().
• PROT_NOCACHE — disable the caching of the region (e.g. to access dual-ported memory).
  Note:

  • Read the architecture guide for your processor; you may need to add special instructions.
  • On ARM targets, PROT_NOCACHE causes RAM to be mapped as normal noncached, but non-RAM to be mapped as strongly ordered device memory. For finer control, see shm_ctl_special().
• 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. You can use the following flag:

• MAP_FIXED

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.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

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(). It's a simple wrapper for mmap():

return mmap(addr, len, prot, (flags & ~MAP_TYPE) | MAP_PHYS|MAP_SHARED, NOFD, physical);

Typically, you don't need to use addr; you can just pass NULL instead. If addr isn't a NULL value, whether the object is mapped depends on whether you set MAP_FIXED in flags:

MAP_FIXED is set

The object is mapped to the address in addr, or the function fails. If this area is already mapped, the call changes the existing mapping of the area. A memory area being mapped with MAP_FIXED is first unmapped by the system using the same memory area. See munmap() for details.

Note:

• In order to use MAP_FIXED, your process must have the PROCMGR_AID_MAP_FIXED ability enabled. For more information, see procmgr_ability().
• Use MAP_FIXED with caution. Not all memory models support it. In general, you should assume that you can use MAP_FIXED only at an address (and size) that a call to mmap() without MAP_FIXED returned.

MAP_FIXED isn't set

The value of addr is taken as a hint as to where to map the object in the calling process's address space. The mapped area won't overlay any current mapped areas.

Refer to the MAP_BELOW description in mmap() for information on what happens if the hint in addr can't be followed.

Returns:

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

Errors:

EINVAL

Invalid flags type, or len is 0.

ENOMEM

The address range requested is outside of the allowed process address range, or there wasn't enough memory to satisfy the request.

EPERM

The calling process doesn't have the required permission (see procmgr_ability()), or it attempted to set PROT_EXEC for a region of memory covered by an untrusted memory-mapped file.

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 OS