Altera HWLIB  16.0
The Altera HW Manager API Reference Manual
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups
MMU Virtual Address Space Creation

Description

This section provides functions to support the creation of a virtual address space from a set of high level memory region descriptions.

The virtual address space creation results in the allocation and initialization of a set of MMU first and second level translaction tables that can be used to actualize the virtual address space once the MMU is configured and enabled.

The virtual address space creation functions attempt to create a space optimal set of first and second level translation tables that represent the address space specified in the memory region descriptors.

The user is responsible for providing the storage required for the first and second level translation tables. The mechanism for allocating storage is via the user defined callback function as defined by the type alt_mmu_ttb_alloc_t.

The simplified virtual address space model is implemented by the following ARM Cortex-A9 MPCore configuration:

Data Structures

struct  ALT_MMU_MEM_REGION_s
 

Typedefs

typedef struct ALT_MMU_MEM_REGION_s ALT_MMU_MEM_REGION_t
 
typedef void *(* alt_mmu_ttb_alloc_t )(const size_t size, void *context)
 

Functions

size_t alt_mmu_va_space_storage_required (const ALT_MMU_MEM_REGION_t *mem_regions, const size_t num_mem_regions)
 
ALT_STATUS_CODE alt_mmu_va_space_create (uint32_t **ttb1, const ALT_MMU_MEM_REGION_t *mem_regions, const size_t num_mem_regions, alt_mmu_ttb_alloc_t ttb_alloc, void *ttb_alloc_context)
 
ALT_STATUS_CODE alt_mmu_va_space_enable (const uint32_t *ttb1)
 

Data Structure Documentation

struct ALT_MMU_MEM_REGION_s

This type defines a structure for specifying the properties of a virtual address range called a memory region. The structure defines fields to specify the virtual to physical address mapping, the access permissions, the shareability, the ordering, and the cacheability properties of a particular memory region that comprises a virtual address space.

Data Fields
void * va The beginning virtual address for the memory region. The address must be aligned to one of 4KiB, 64KiB, 1MiB, or 16MiB boundaries.
void * pa The beginning physical address mapping for the virtual address of the memory region. The address must be aligned to one of 4KiB, 64KiB, 1MiB, or 16MiB boundaries.
uint32_t size The size of the memory region in bytes. The size must be a multiple of 4KiB, 64KiB, 1MiB, or 16MiB sizes.
ALT_MMU_AP_t access The access permissions for the memory region.
ALT_MMU_ATTR_t attributes The memory region attributes. These attributes determine the memory type (ordering), cache policy, and as a possible side effect, the shareablity of the memory region.
ALT_MMU_TTB_S_t shareable The shareability of the memory region.
ALT_MMU_TTB_XN_t execute Whether instructions can be executed from this memory region.
ALT_MMU_TTB_NS_t security Controls whether address translations made from the secure state translate physical address in the secure or non-secure address map.

Typedef Documentation

This type defines a structure for specifying the properties of a virtual address range called a memory region. The structure defines fields to specify the virtual to physical address mapping, the access permissions, the shareability, the ordering, and the cacheability properties of a particular memory region that comprises a virtual address space.

typedef void*(* alt_mmu_ttb_alloc_t)(const size_t size, void *context)

Type definition for a user defined function that allocates storage for MMU translation tables. This memory is intended to be used by alt_mmu_va_space_create() to allocate the TTB1 and, if needed, TTB2. alt_mmu_va_space_create() allocates all the space required with one single call and divides the space up internally.

The function returns a size block of memory. The returned pointer must be a 16 KiB (2^14) aligned address.

Parameters
sizeThe size in bytes of the storage request. The value will be same reported by alt_mmu_va_space_storage_required() if non-zero, given the same set of memory regions.
contextA user provided context for the allocator function.
Returns
A 16 KiB aligned pointer to the allocated memory or NULL if the storage request cannot be satisfied.

Function Documentation

size_t alt_mmu_va_space_storage_required ( const ALT_MMU_MEM_REGION_t mem_regions,
const size_t  num_mem_regions 
)

Returns the cumulative size in bytes of the storage required for the first and second level translation tables that implement the virtual address space defined by the array of memory region descriptors.

This function does not allocate any actual storage but merely computes the amount of storage that would be required by the MMU translation tables created for the specified virtual address space.

Parameters
mem_regionsA pointer to an array of memory region descriptors that define the virtual address space.
num_mem_regionsThe number of memory region descriptors in the mem_regions array.
Returns
The number of storage bytes required for the MMU translation tables described by the virtual address space specfication, or zero if an error has occurred.
ALT_STATUS_CODE alt_mmu_va_space_create ( uint32_t **  ttb1,
const ALT_MMU_MEM_REGION_t mem_regions,
const size_t  num_mem_regions,
alt_mmu_ttb_alloc_t  ttb_alloc,
void *  ttb_alloc_context 
)

Creates the MMU translation tables needed to implement the virtual address space defined by the memory region descriptors.

The address space defined by the memory regions should have no overlapping virtual address ranges.

The largest region that can be specified by a single entry is 2 GiB. Use multiple entries to describe a memory region larger than 2 GiB.

Any address ranges in the potential 4 GiB virtual address space left unspecified in the mem_regions parameter default to fault descriptor entries in the generated translation tables.

Parameters
ttb1[out] A pointer to the MMU first level translation table created to implement the virtual address space.
mem_regionsA pointer to an array of memory region descriptors that define the virtual address space.
num_mem_regionsThe number of memory region descriptors in the mem_regions array.
ttb_allocA pointer to a user defined function used for allocating storage for first and second level translation tables.
ttb_alloc_contextA user provided context for the allocation function.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
ALT_STATUS_CODE alt_mmu_va_space_enable ( const uint32_t *  ttb1)

Enables the virtual address space described by the MMU translation table ttb1.

This function actualizes the virtual address space rooted a the MMU first level translation table ttb1. The function performs the following steps to enable the virtual address space:

  • Configure the Translation Table Control Register (TTBCR) to use a single table (i.e. TTBR0).
  • Set Translation Table Base Register (TTBR0) to ttb1.
  • Configure Domain Access Control Register (DACR) to the client domain.
  • Invalidate
    • TLBs
    • caches
    • branch prediction buffers (BTAC, etc.)
  • Enable MMU and branch prediction.
Parameters
ttb1The base address of a first level translation table.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code