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 );
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.
-
PROT_NOCACHE — disable the caching of the
region (e.g. 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 (Enforce In-Order Execution of I/O) instructions to ensure that writes occur in a desired order. You'll find an eieio() macro in <ppc/inout.h>.
- 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 — map the object to the address
specified by addr.
If this area is already mapped, the call changes the existing mapping
of the area.
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).
-
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.
- 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.
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() .
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:
Safety: | |
---|---|
Cancellation point | No |
Interrupt handler | No |
Signal handler | Yes |
Thread | Yes |