VxWorks Reference Manual : Libraries
vmLib - architecture-independent virtual memory support library (VxVMI Option)
vmLibInit( ) - initialize the virtual memory support module (VxVMI Option)
vmGlobalMapInit( ) - initialize global mapping (VxVMI Option)
vmContextCreate( ) - create a new virtual memory context (VxVMI Option)
vmContextDelete( ) - delete a virtual memory context (VxVMI Option)
vmStateSet( ) - change the state of a block of virtual memory (VxVMI Option)
vmStateGet( ) - get the state of a page of virtual memory (VxVMI Option)
vmMap( ) - map physical space into virtual space (VxVMI Option)
vmGlobalMap( ) - map physical pages to virtual space in shared global virtual memory (VxVMI Option)
vmGlobalInfoGet( ) - get global virtual memory information (VxVMI Option)
vmPageBlockSizeGet( ) - get the architecture-dependent page block size (VxVMI Option)
vmTranslate( ) - translate a virtual address to a physical address (VxVMI Option)
vmPageSizeGet( ) - return the page size (VxVMI Option)
vmCurrentGet( ) - get the current virtual memory context (VxVMI Option)
vmCurrentSet( ) - set the current virtual memory context (VxVMI Option)
vmEnable( ) - enable or disable virtual memory (VxVMI Option)
vmTextProtect( ) - write-protect a text segment (VxVMI Option)
This library provides an architecture-independent interface to the CPU's memory management unit (MMU). Although vmLib is implemented with architecture-specific libraries, application code need never reference directly the architecture-dependent code in these libraries.
A fundamental goal in the design of vmLib was to permit transparent backward compatibility with previous versions of VxWorks that did not use the MMU. System designers may opt to disable the MMU because of timing constraints, and some architectures do not support MMUs; therefore VxWorks functionality must not be dependent on the MMU. The resulting design permits a transparent configuration with no change in the programming environment (but the addition of several protection features, such as text segment protection) and the ability to disable virtual memory in systems that require it.
The vmLib library provides a mechanism for creating virtual memory contexts, vmContextCreate( ). These contexts are not automatically created for individual tasks, but may be created dynamically by tasks, and swapped in and out in an application specific manner.
All virtual memory contexts share a global transparent mapping of virtual to physical memory for all of local memory and the local hardware device space (defined in sysLib.c for each board port in the sysPhysMemDesc data structure). When the system is initialized, all of local physical memory is accessible at the same address in virtual memory (this is done with calls to vmGlobalMap( ).) Modifications made to this global mapping in one virtual memory context appear in all virtual memory contexts. For example, if the exception vector table (which resides at address 0 in physical memory) is made read only by calling vmStateSet( ) on virtual address 0, the vector table will be read only in all virtual memory contexts.
Private virtual memory can also be created. When physical pages are mapped to virtual memory that is not in the global transparent region, this memory becomes accessible only in the context in which it was mapped. (The physical pages will also be accessible in the transparent translation at the physical address, unless the virtual pages in the global transparent translation region are explicitly invalidated.) State changes (writability, validity, etc.) to a section of private virtual memory in a virtual memory context do not appear in other contexts. To facilitate the allocation of regions of virtual space, vmGlobalInfoGet( ) returns a pointer to an array of booleans describing which portions of the virtual address space are devoted to global memory. Each successive array element corresponds to contiguous regions of virtual memory the size of which is architecture-dependent and which may be obtained with a call to vmPageBlockSizeGet( ). If the boolean array element is true, the corresponding region of virtual memory, a "page block", is reserved for global virtual memory and should not be used for private virtual memory. (If vmMap( ) is called to map virtual memory previously defined as global, the routine will return an error.)
All the state information for a block of virtual memory can be set in a single call to vmStateSet( ). It performs parameter checking and checks the validity of the specified virtual memory context. It may also be used to set architecture-dependent state information. See vmLib.h for additional architecture-dependent state information.
The routine vmContextShow( ) in vmShow displays the virtual memory context for a specified context. For more information, see the manual entry for this routine.
Full MMU support (vmLib, and optionally, vmShow) is included in VxWorks when the configuration macro INCLUDE_MMU_FULL is defined. If the configuration macro INCLUDE_MMU_BASIC is also defined, the default is full MMU support (unbundled).
The sysLib.c library contains a data structure called sysPhysMemDesc, which is an array of PHYS_MEM_DESC structures. Each element of the array describes a contiguous section of physical memory. The description of this memory includes its physical address, the virtual address where it should be mapped (typically, this is the same as the physical address, but not necessarily so), an initial state for the memory, and a mask defining which state bits in the state value are to be set. Default configurations are defined for each board support package (BSP), but these mappings may be changed to suit user-specific system configurations. For example, the user may need to map additional VME space where the backplane network interface data structures appear.
This library and vmShow are distributed as the unbundled virtual memory support option, VxVMI. A scaled down version, vmBaseLib, is provided with VxWorks for systems that do not permit optional use of the MMU, or for architectures that require certain features of the MMU to perform optimally (in particular, architectures that rely heavily on caching, but do not support bus snooping, and thus require the ability to mark interprocessor communications buffers as non-cacheable.) Most routines in vmBaseLib are referenced internally by VxWorks; they are not callable by application code.
vmLib.h
vmLib, sysLib, vmShow, VxWorks Programmer's Guide: Virtual Memory
vmLibInit( ) - initialize the virtual memory support module (VxVMI Option)
STATUS vmLibInit ( int pageSize /* size of page */ )
This routine initializes the virtual memory context class. It is called only once during system initialization.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
OK.
vmGlobalMapInit( ) - initialize global mapping (VxVMI Option)
VM_CONTEXT_ID vmGlobalMapInit ( PHYS_MEM_DESC * pMemDescArray, /* pointer to array of mem descs */ int numDescArrayElements, /* num of elements in pMemDescArray */ BOOL enable /* enable virtual memory */ )
This routine is a convenience routine that creates and installs a virtual memory context with global mappings defined for each contiguous memory segment defined in the physical memory descriptor array passed as an argument. The context ID returned becomes the current virtual memory context.
The physical memory descriptor also contains state information used to initialize the state information in the MMU's translation table for that memory segment. The following state bits may be or'ed together:
Additionally, mask bits are or'ed together in the initialStateMask structure element to describe which state bits are being specified in the initialState structure element:
VM_STATE_VALID VM_STATE_VALID_NOT valid/invalid VM_STATE_WRITABLE VM_STATE_WRITABLE_NOT writable/write-protected VM_STATE_CACHEABLE VM_STATE_CACHEABLE_NOT cacheable/not-cacheable VM_STATE_MASK_VALID
VM_STATE_MASK_WRITABLE
VM_STATE_MASK_CACHEABLEIf the enable parameter is TRUE, the MMU is enabled upon return. The vmGlobalMapInit( ) routine should be called only after vmLibInit( ) has been called.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
A pointer to a newly created virtual memory context, or NULL if the memory cannot be mapped.
vmContextCreate( ) - create a new virtual memory context (VxVMI Option)
VM_CONTEXT_ID vmContextCreate (void)
This routine creates a new virtual memory context. The newly created context does not become the current context until explicitly installed by a call to vmCurrentSet( ). Modifications to the context state (mappings, state changes, etc.) may be performed on any virtual memory context, even if it is not the current context.
This routine should not be called from interrupt level.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
A pointer to a new virtual memory context, or NULL if the allocation or initialization fails.
vmContextDelete( ) - delete a virtual memory context (VxVMI Option)
STATUS vmContextDelete ( VM_CONTEXT_ID context )
This routine deallocates the underlying translation table associated with a virtual memory context. It does not free the physical memory already mapped into the virtual memory space.
This routine should not be called from interrupt level.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
OK, or ERROR if context is not a valid context descriptor or if an error occurs deleting the translation table.
vmStateSet( ) - change the state of a block of virtual memory (VxVMI Option)
STATUS vmStateSet ( VM_CONTEXT_ID context, /* context - NULL == currentContext */ void * pVirtual, /* virtual address to modify state of */ int len, /* len of virtual space to modify state of */ UINT stateMask, /* state mask */ UINT state /* state */ )
This routine changes the state of a block of virtual memory. Each page of virtual memory has at least three elements of state information: validity, writability, and cacheability. Specific architectures may define additional state information; see vmLib.h for additional architecture-specific states. Memory accesses to a page marked as invalid will result in an exception. Pages may be invalidated to prevent them from being corrupted by invalid references. Pages may be defined as read-only or writable, depending on the state of the writable bits. Memory accesses to pages marked as not-cacheable will always result in a memory cycle, bypassing the cache. This is useful for multiprocessing, multiple bus masters, and hardware control registers.
The following states are provided and may be or'ed together in the state parameter:
Additionally, the following masks are provided so that only specific states may be set. These may be or'ed together in the stateMask parameter.
VM_STATE_VALID VM_STATE_VALID_NOT valid/invalid VM_STATE_WRITABLE VM_STATE_WRITABLE_NOT writable/write-protected VM_STATE_CACHEABLE VM_STATE_CACHEABLE_NOT cacheable/not-cacheable VM_STATE_MASK_VALID
VM_STATE_MASK_WRITABLE
VM_STATE_MASK_CACHEABLEIf context is specified as NULL, the current context is used.
This routine is callable from interrupt level.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
OK or, ERROR if the validation fails, pVirtual is not on a page boundary, len is not a multiple of page size, or the architecture-dependent state set fails for the specified virtual address.
S_vmLib_NOT_PAGE_ALIGNED, S_vmLib_BAD_STATE_PARAM, S_vmLib_BAD_MASK_PARAM
vmStateGet( ) - get the state of a page of virtual memory (VxVMI Option)
STATUS vmStateGet ( VM_CONTEXT_ID context, /* context - NULL == currentContext */ void * pPageAddr, /* virtual page addr */ UINT * pState /* where to return state */ )
This routine extracts state bits with the following masks:
VM_STATE_MASK_VALID
VM_STATE_MASK_WRITABLE
VM_STATE_MASK_CACHEABLEIndividual states may be identified with the following constants:
For example, to see if a page is writable, the following code would be used:
VM_STATE_VALID VM_STATE_VALID_NOT valid/invalid VM_STATE_WRITABLE VM_STATE_WRITABLE_NOT writable/write-protected VM_STATE_CACHEABLE VM_STATE_CACHEABLE_NOT cacheable/not-cacheable
vmStateGet (vmContext, pageAddr, &state); if ((state & VM_STATE_MASK_WRITABLE) & VM_STATE_WRITABLE) ...If context is specified as NULL, the current virtual memory context is used.This routine is callable from interrupt level.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
OK, or ERROR if pageAddr is not on a page boundary, the validity check fails, or the architecture-dependent state get fails for the specified virtual address.
S_vmLib_NOT_PAGE_ALIGNED
vmMap( ) - map physical space into virtual space (VxVMI Option)
STATUS vmMap ( VM_CONTEXT_ID context, /* context - NULL == currentContext */ void * virtualAddr, /* virtual address */ void * physicalAddr, /* physical address */ UINT len /* len of virtual and physical spaces */ )
This routine maps physical pages into a contiguous block of virtual memory. virtualAddr and physicalAddr must be on page boundaries, and len must be evenly divisible by the page size. After the call to vmMap( ), the state of all pages in the the newly mapped virtual memory is valid, writable, and cacheable.
The vmMap( ) routine can fail if the specified virtual address space conflicts with the translation tables of the global virtual memory space. The global virtual address space is architecture-dependent and is initialized at boot time with calls to vmGlobalMap( ) by vmGlobalMapInit( ). If a conflict results, errno is set to S_vmLib_ADDR_IN_GLOBAL_SPACE. To avoid this conflict, use vmGlobalInfoGet( ) to ascertain which portions of the virtual address space are reserved for the global virtual address space. If context is specified as NULL, the current virtual memory context is used.
This routine should not be called from interrupt level.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
OK, or ERROR if virtualAddr or physicalAddr are not on page boundaries, len is not a multiple of the page size, the validation fails, or the mapping fails.
S_vmLib_NOT_PAGE_ALIGNED, S_vmLib_ADDR_IN_GLOBAL_SPACE
vmGlobalMap( ) - map physical pages to virtual space in shared global virtual memory (VxVMI Option)
STATUS vmGlobalMap ( void * virtualAddr, /* virtual address */ void * physicalAddr, /* physical address */ UINT len /* len of virtual and physical spaces */ )
This routine maps physical pages to virtual space that is shared by all virtual memory contexts. Calls to vmGlobalMap( ) should be made before any virtual memory contexts are created to insure that the shared global mappings are included in all virtual memory contexts. Mappings created with vmGlobalMap( ) after virtual memory contexts are created are not guaranteed to appear in all virtual memory contexts. After the call to vmGlobalMap( ), the state of all pages in the the newly mapped virtual memory is unspecified and must be set with a call to vmStateSet( ), once the initial virtual memory context is created.
This routine should not be called from interrupt level.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
OK, or ERROR if virtualAddr or physicalAddr are not on page boundaries, len is not a multiple of the page size, or the mapping fails.
S_vmLib_NOT_PAGE_ALIGNED
vmGlobalInfoGet( ) - get global virtual memory information (VxVMI Option)
UINT8 *vmGlobalInfoGet (void)
This routine provides a description of those parts of the virtual memory space dedicated to global memory. The routine returns a pointer to an array of UINT8. Each element of the array corresponds to a block of virtual memory, the size of which is architecture-dependent and can be obtained with a call to vmPageBlockSizeGet( ). To determine if a particular address is in global virtual memory, use the following code:
UINT8 *globalPageBlockArray = vmGlobalInfoGet (); int pageBlockSize = vmPageBlockSizeGet (); if (globalPageBlockArray[addr/pageBlockSize]) ...The array pointed to by the returned pointer is guaranteed to be static as long as no calls are made to vmGlobalMap( ) while the array is being examined. The information in the array can be used to determine what portions of the virtual memory space are available for use as private virtual memory within a virtual memory context.This routine is callable from interrupt level.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
A pointer to an array of UINT8.
vmPageBlockSizeGet( ) - get the architecture-dependent page block size (VxVMI Option)
int vmPageBlockSizeGet (void)
This routine returns the size of a page block for the current architecture. Each MMU architecture constructs translation tables such that a minimum number of pages are pre-defined when a new section of the translation table is built. This minimal group of pages is referred to as a "page block." This routine may be used in conjunction with vmGlobalInfoGet( ) to examine the layout of global virtual memory.
This routine is callable from interrupt level.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
The page block size of the current architecture.
vmLib, vmGlobalInfoGet( )
vmTranslate( ) - translate a virtual address to a physical address (VxVMI Option)
STATUS vmTranslate ( VM_CONTEXT_ID context, /* context - NULL == currentContext */ void * virtualAddr, /* virtual address */ void * *physicalAddr /* place to put result */ )
This routine retrieves mapping information for a virtual address from the page translation tables. If the specified virtual address has never been mapped, the returned status can be either OK or ERROR; however, if it is OK, then the returned physical address will be -1. If context is specified as NULL, the current context is used.
This routine is callable from interrupt level.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
OK, or ERROR if the validation or translation fails.
vmPageSizeGet( ) - return the page size (VxVMI Option)
int vmPageSizeGet (void)
This routine returns the architecture-dependent page size.
This routine is callable from interrupt level.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
The page size of the current architecture.
vmCurrentGet( ) - get the current virtual memory context (VxVMI Option)
VM_CONTEXT_ID vmCurrentGet (void)
This routine returns the current virtual memory context.
This routine is callable from interrupt level.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
The current virtual memory context, or NULL if no virtual memory context is installed.
vmCurrentSet( ) - set the current virtual memory context (VxVMI Option)
STATUS vmCurrentSet ( VM_CONTEXT_ID context /* context to install */ )
This routine installs a specified virtual memory context.
This routine is callable from interrupt level.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
OK, or ERROR if the validation or context switch fails.
vmEnable( ) - enable or disable virtual memory (VxVMI Option)
STATUS vmEnable ( BOOL enable /* TRUE == enable MMU, FALSE == disable MMU */ )
This routine turns virtual memory on and off. Memory management should not be turned off once it is turned on except in the case of system shutdown.
This routine is callable from interrupt level.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
OK, or ERROR if the validation or architecture-dependent code fails.
vmTextProtect( ) - write-protect a text segment (VxVMI Option)
STATUS vmTextProtect (void)
This routine write-protects the VxWorks text segment and sets a flag so that all text segments loaded by the incremental loader will be write-protected. The routine should be called after both vmLibInit( ) and vmGlobalMapInit( ) have been called.
This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.
OK, or ERROR if the text segment cannot be write-protected.
S_vmLib_TEXT_PROTECTION_UNAVAILABLE