VxWorks API Reference : OS Libraries

vmLib

NAME

vmLib - architecture-independent virtual memory support library (VxVMI Option)

ROUTINES

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)

DESCRIPTION

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.

CONFIGURATION

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.

AVAILABILITY

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.

INCLUDE FILES

vmLib.h

SEE ALSO

sysLib, vmShow, VxWorks Programmer's Guide: Virtual Memory


OS Libraries : Routines

vmLibInit( )

NAME

vmLibInit( ) - initialize the virtual memory support module (VxVMI Option)

SYNOPSIS

STATUS vmLibInit
    (
    int pageSize              /* size of page */
    )

DESCRIPTION

This routine initializes the virtual memory context class. It is called only once during system initialization.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

OK.

SEE ALSO

vmLib


OS Libraries : Routines

vmGlobalMapInit( )

NAME

vmGlobalMapInit( ) - initialize global mapping (VxVMI Option)

SYNOPSIS

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 */
    )

DESCRIPTION

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:

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
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_MASK_VALID
 VM_STATE_MASK_WRITABLE
 VM_STATE_MASK_CACHEABLE

If the enable parameter is TRUE, the MMU is enabled upon return. The vmGlobalMapInit( ) routine should be called only after vmLibInit( ) has been called.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

A pointer to a newly created virtual memory context, or NULL if the memory cannot be mapped.

SEE ALSO

vmLib


OS Libraries : Routines

vmContextCreate( )

NAME

vmContextCreate( ) - create a new virtual memory context (VxVMI Option)

SYNOPSIS

VM_CONTEXT_ID vmContextCreate (void)

DESCRIPTION

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.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

A pointer to a new virtual memory context, or NULL if the allocation or initialization fails.

SEE ALSO

vmLib


OS Libraries : Routines

vmContextDelete( )

NAME

vmContextDelete( ) - delete a virtual memory context (VxVMI Option)

SYNOPSIS

STATUS vmContextDelete
    (
    VM_CONTEXT_ID context
    )

DESCRIPTION

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.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

OK, or ERROR if context is not a valid context descriptor or if an error occurs deleting the translation table.

SEE ALSO

vmLib


OS Libraries : Routines

vmStateSet( )

NAME

vmStateSet( ) - change the state of a block of virtual memory (VxVMI Option)

SYNOPSIS

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 */
    )

DESCRIPTION

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:

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
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_MASK_VALID
 VM_STATE_MASK_WRITABLE
 VM_STATE_MASK_CACHEABLE

If context is specified as NULL, the current context is used.

This routine is callable from interrupt level.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

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.

ERRNO

S_vmLib_NOT_PAGE_ALIGNED, S_vmLib_BAD_STATE_PARAM, S_vmLib_BAD_MASK_PARAM

SEE ALSO

vmLib


OS Libraries : Routines

vmStateGet( )

NAME

vmStateGet( ) - get the state of a page of virtual memory (VxVMI Option)

SYNOPSIS

STATUS vmStateGet
    (
    VM_CONTEXT_ID context,    /* context - NULL == currentContext */
    void *        pPageAddr,  /* virtual page addr */
    UINT *        pState      /* where to return state */
    )

DESCRIPTION

This routine extracts state bits with the following masks:

 VM_STATE_MASK_VALID
 VM_STATE_MASK_WRITABLE
 VM_STATE_MASK_CACHEABLE

Individual states may be identified with the following constants:

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
For example, to see if a page is writable, the following code would be used:

    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.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

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.

ERRNO

S_vmLib_NOT_PAGE_ALIGNED

SEE ALSO

vmLib


OS Libraries : Routines

vmMap( )

NAME

vmMap( ) - map physical space into virtual space (VxVMI Option)

SYNOPSIS

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 */
    )

DESCRIPTION

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.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

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.

ERRNO

S_vmLib_NOT_PAGE_ALIGNED, S_vmLib_ADDR_IN_GLOBAL_SPACE

SEE ALSO

vmLib


OS Libraries : Routines

vmGlobalMap( )

NAME

vmGlobalMap( ) - map physical pages to virtual space in shared global virtual memory (VxVMI Option)

SYNOPSIS

STATUS vmGlobalMap
    (
    void * virtualAddr,       /* virtual address */
    void * physicalAddr,      /* physical address */
    UINT   len                /* len of virtual and physical spaces */
    )

DESCRIPTION

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.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

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.

ERRNO

S_vmLib_NOT_PAGE_ALIGNED

SEE ALSO

vmLib


OS Libraries : Routines

vmGlobalInfoGet( )

NAME

vmGlobalInfoGet( ) - get global virtual memory information (VxVMI Option)

SYNOPSIS

UINT8 *vmGlobalInfoGet (void)

DESCRIPTION

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.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

A pointer to an array of UINT8.

SEE ALSO

vmLib, vmPageBlockSizeGet( )


OS Libraries : Routines

vmPageBlockSizeGet( )

NAME

vmPageBlockSizeGet( ) - get the architecture-dependent page block size (VxVMI Option)

SYNOPSIS

int vmPageBlockSizeGet (void)

DESCRIPTION

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.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

The page block size of the current architecture.

SEE ALSO

vmLib, vmGlobalInfoGet( )


OS Libraries : Routines

vmTranslate( )

NAME

vmTranslate( ) - translate a virtual address to a physical address (VxVMI Option)

SYNOPSIS

STATUS vmTranslate
    (
    VM_CONTEXT_ID context,      /* context - NULL == currentContext */
    void *        virtualAddr,  /* virtual address */
    void *        *physicalAddr /* place to put result */
    )

DESCRIPTION

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.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

OK, or ERROR if the validation or translation fails.

SEE ALSO

vmLib


OS Libraries : Routines

vmPageSizeGet( )

NAME

vmPageSizeGet( ) - return the page size (VxVMI Option)

SYNOPSIS

int vmPageSizeGet (void)

DESCRIPTION

This routine returns the architecture-dependent page size.

This routine is callable from interrupt level.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

The page size of the current architecture.

SEE ALSO

vmLib


OS Libraries : Routines

vmCurrentGet( )

NAME

vmCurrentGet( ) - get the current virtual memory context (VxVMI Option)

SYNOPSIS

VM_CONTEXT_ID vmCurrentGet (void)

DESCRIPTION

This routine returns the current virtual memory context.

This routine is callable from interrupt level.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

The current virtual memory context, or NULL if no virtual memory context is installed.

SEE ALSO

vmLib


OS Libraries : Routines

vmCurrentSet( )

NAME

vmCurrentSet( ) - set the current virtual memory context (VxVMI Option)

SYNOPSIS

STATUS vmCurrentSet
    (
    VM_CONTEXT_ID context     /* context to install */
    )

DESCRIPTION

This routine installs a specified virtual memory context.

This routine is callable from interrupt level.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

OK, or ERROR if the validation or context switch fails.

SEE ALSO

vmLib


OS Libraries : Routines

vmEnable( )

NAME

vmEnable( ) - enable or disable virtual memory (VxVMI Option)

SYNOPSIS

STATUS vmEnable
    (
    BOOL enable               /* TRUE == enable MMU, FALSE == disable MMU */
    )

DESCRIPTION

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.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

OK, or ERROR if the validation or architecture-dependent code fails.

SEE ALSO

vmLib


OS Libraries : Routines

vmTextProtect( )

NAME

vmTextProtect( ) - write-protect a text segment (VxVMI Option)

SYNOPSIS

STATUS vmTextProtect (void)

DESCRIPTION

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.

AVAILABILITY

This routine is distributed as a component of the unbundled virtual memory support option, VxVMI.

RETURNS

OK, or ERROR if the text segment cannot be write-protected.

ERRNO

S_vmLib_TEXT_PROTECTION_UNAVAILABLE

SEE ALSO

vmLib