NAME | Synopsis | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | Allowed Calling Contexts | ATTRIBUTES | SEE ALSO
#include <dki/dki.h>KnError svPhysMap(KnPhMemChunk * chunk, PteCntlBits cntlBits);
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
DKI
Provides physical to virtual memory mapping services.
The microkernel provides services to allow device drivers to map physical space to virtual memory space. These services should be used mainly by primary bus drivers to map bus I/O space or DMA memory.
svPhysMap() allocates a range of virtual addresses within the supervisor address space and maps it to a given range of physical addresses.
The chunk argument points to the KnPhMemChunk structure shown below:
typedef struct { PhAddr paddr; /* physical start addree */ PhSize psize; /* size */ VmAddr vaddr; /* virtual start address */ } KnPhMemChunk;
The paddr and psize fields specify the chunk of physical memory being mapped.
The vaddr field is used by svPhysMap() to return the virtual address to which the physical one is mapped.
For family processors, the cntlBits argument should be constructed by performing a bit-wise OR operation on the following values:
The mapped memory allows you to perform write accesses.
The memory is mapped with Write-Through attribute (bit W). Thus, a store operation updates the cache if necessary, and in addition the update is written to memory.
The memory is mapped with Cache-Inhibited attribute (bit I). Thus, accesses are made to main memory, bypassing the caches.
The memory is mapped with Memory-Coherency attribute (bit M). This enforces coherency of memory shared between processors in a system. When performing an access to memory, there is a hardware indication to the rest of the system that the access is global. Other processors affected by the access must then respond to this global access. Typically, this is used for a snooping bus design.
The memory is mapped with Memory-Guarded attribute (bit G). This prevents the processor from making out-of-order access to that memory (that is, access not directly dictated by the program). This may be useful if there are holes in physical memory, or to prevent these accesses to certain peripheral devices.
If cntlBits is equal to zero, the memory is mapped as read-only, not guarded, with cache enabled in write-back mode, and no coherency is enforced.
Any combination where PTE_CACHE_WRITE_THROUGH and PTE_CACHE_DISABLE are both set is not supported.
On success, K_OK is returned. Otherwise, a negative error code is returned:
The system is out of memory.
The psize argument is equal to zero.
svPhysUnmap() unmaps the physical memory chunk previously mapped by svPhysMap() . The chunk argument points to the KnPhMemChunk structure, which specifies the virtual and physical chunk start addresses and the chunk size.
The paddr and psize fields must have the values previously specified in svPhysMap() . The vaddr field must have the value previously returned by svPhysMap() .
Typically, a driver uses the same KnPhMemChunk structure for the svPhysMap() and svPhysUnmap() calls and the structure fields are not modified by the driver once svPhysMap() has been done.
vmMapToPhys() maps a given physical memory chunk to the target actor address space. The actor argument specifies the target actor capability.
If actor is K_MYACTOR , the address space of the current actor is used.
If actor is K_SVACTOR , the supervisor address space is used.
The chunk argument points to the KnPhMemChunk structure, which specifies the physical and virtual chunk start addresses and the chunk size.
The specified virtual address range must be allocated using the K_RESERVED option (see rgnAllocate() (2K)) prior to the invocation of vmMapToPhys() .
The specified actor can be a supervisor actor as well as a user actor.
The mapping produced by vmMapToPhys() can only be invalidated by rgnFree() (2K).
vaddr , paddr , and psize must be page-aligned.
For family processors, the cntlBits is defined in the same way as for the svPhysMap() routine above.
On success, K_OK is returned. Otherwise, a negative error code is returned:
The actor argument points outside the caller's address space.
An inconsistent actor capability was provided.
actorcap does not specify a reachable actor.
The system is out of memory.
The psize argument is equal to zero.
vaddr , paddr , or psize is not page-aligned.
Some or all addresses from the target virtual address range are out of a region allocated with the K_RESERVED option.
For performance reasons, the current implementation does not guarantee that any attempt to map a physical address to a virtual address out of a region allocated with K_RESERVED option would effectively produce a K_EADDR error.
The following table specifies the contexts in which a caller is allowed to invoke each service.
Services | Base level | DKI thread | Interrupt | Blocking |
svPhysMap() | + | + | - | + |
svPhysUnmap() | + | + | - | + |
vmMapToPhys() | + | + | - | + |
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | Synopsis | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | Allowed Calling Contexts | ATTRIBUTES | SEE ALSO