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 );
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>:
-
flags
- Specifies further information about handling the mapped region.
You can use the following flag:
-
MAP_FIXED — map the object to the address
specified by addr.
If this area is already mapped, the call changes the existing mapping
of the area.
Note:
Use MAP_FIXED with caution.
Not all memory models support it.
In general, you should assume that you can MAP_FIXED
only at an address (and size) that a call to
mmap() without MAP_FIXED returned.
A memory area being mapped with MAP_FIXED is first
unmapped 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.
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().
You should use this function instead of using
mmap()
with the
MAP_PHYS flag.
Note:
In order to map physical memory, your process must have the
PROCMGR_AID_MEM_PHYS ability enabled.
For more information, see
procmgr_ability()
.
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 on whether or not you set MAP_FIXED 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 as to where to
map the object
in the calling process's address space.
The mapped area won't overlay any current mapped areas.
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.
-
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.
-
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 Neutrino
| Safety: |
|
| Cancellation point |
No |
| Interrupt handler |
No |
| Signal handler |
Yes |
| Thread |
Yes |