Hardware Libraries  20.1
Stratix 10 SoC Hardware Manager
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
MMU Management API

Description

This module defines an API for configuring and managing the Cortex-A53 MMU.

For a complete understanding of the possible configurations and operation of the MMU, consult the following references:

Data Structures

struct  ALT_MMU_MAIR_s
 
struct  ALT_MMU_MEM_REGION_s
 

Typedefs

typedef enum ALT_MMU_TTB_SH_e ALT_MMU_TTB_SH_t
 
typedef enum ALT_MMU_TTB_NS_e ALT_MMU_TTB_NS_t
 
typedef enum ALT_MMU_TTB_XN_e ALT_MMU_TTB_XN_t
 
typedef enum ALT_MMU_AP_e ALT_MMU_AP_t
 
typedef uint8_t ALT_MMU_ATTR_t
 
typedef struct ALT_MMU_MAIR_s ALT_MMU_MAIR_t
 
typedef struct ALT_MMU_MEM_REGION_s ALT_MMU_MEM_REGION_t
 
typedef void *(* alt_mmu_ttb_alloc_t )(size_t size, size_t align, void *context)
 

ENUMS

enum  ALT_MMU_TTB_SH_e { ALT_MMU_TTB_SH_NON_SHAREABLE = 0, ALT_MMU_TTB_SH_OUTER_SHAREABLE = 2, ALT_MMU_TTB_SH_INNER_SHAREABLE = 3 }
 
enum  ALT_MMU_TTB_NS_e { ALT_MMU_TTB_NS_SECURE = 0, ALT_MMU_TTB_NS_NON_SECURE = 1 }
 
enum  ALT_MMU_TTB_XN_e { ALT_MMU_TTB_XN_DISABLE = 0, ALT_MMU_TTB_XN_ENABLE = 1 }
 
enum  ALT_MMU_AP_e { ALT_MMU_AP_RW_NONE = 0, ALT_MMU_AP_RW_RW = 1, ALT_MMU_AP_RO_NONE = 2, ALT_MMU_AP_RO_RO = 3 }
 

Functions

ALT_STATUS_CODE alt_mmu_tlb_invalidate (void)
 
ALT_STATUS_CODE alt_mmu_tlb_invalidate_is (void)
 
ALT_STATUS_CODE alt_mmu_enable (void)
 
ALT_STATUS_CODE alt_mmu_disable (void)
 
ALT_STATUS_CODE alt_mmu_configure_granule (const ALT_MMU_TCR_INFO_t *ttbconfig)
 
size_t alt_mmu_va_space_storage_required (const ALT_MMU_MEM_REGION_t *regions, size_t regions_count, const ALT_MMU_GRANULE_INFO_t *granule_info, const ALT_MMU_TCR_INFO_t *ttbconfig)
 
ALT_STATUS_CODE alt_mmu_va_space_create (const ALT_MMU_MEM_REGION_t *regions, size_t regions_count, const ALT_MMU_GRANULE_INFO_t *granule_info, const ALT_MMU_TCR_INFO_t *ttbconfig, alt_mmu_ttb_alloc_t ttb_alloc, void *memPool)
 
uint64_t alt_mmu_va_to_pa (const void *va, ALT_MMU_ATTR_t *attr, uint32_t *dfsc)
 

Data Structure Documentation

struct ALT_MMU_MAIR_s

This structure provides the MAIR values used for progrmaming the MMU. ALT_MMU_MEM_REGION_t::attrindex is an index into this array to provide the memory attributes.

Data Fields
ALT_MMU_ATTR_t mair The MAIR definition array.
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 the granule size used for the translation.
uint64_t pa The beginning physical address mapping for the virtual address of the memory region. The address must be aligned to the granule size used for the translation if the region is not a fault. If region is a fault, this parameter is ignored.
size_t size The size of the memory region in bytes. The size must be a multiple of tne granule size used for the translation.
bool fault If the region is a fault region.
ALT_MMU_AP_t access The access permissions for the memory region.
unsigned attrindex 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_SH_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 enumerates the options for Shareability (SH) properties in translation table descriptors. This control determines whether the addressed region is Shareable memory (and if so, which type) or not. Device memory is always outer shareable.

This type enumerates the options for Non-Secure (NS) controls in translation table descriptors. This control specifies whether memory accesses made from the secure state translate physical address in the secure or non-secure address map. The value of the NS bit in the first level page table descriptor applies to all entries in the corresponding second-level translation table.

This type enumerates the options for Execute Never (XN) controls in translation table descriptors that determine whether the processor can execute instructions from the addressed region.

typedef enum ALT_MMU_AP_e ALT_MMU_AP_t

This type enumerates the Access Permissions that can be specified for a memory region.

Memory access control is defined using access permission bits in translation table descriptors that control access to the corresponding memory region.

The HWLIB uses the long-descriptor translation table format for defining the access permissions where two bits, AP[2:1], define the access permissions. AP[0] defines the access flag, which is not used.

The following table provides a summary of the enumerations, AP bit encodings, and access permission descriptions for this type.

Enumeration AP Value Privileged Access Other Access
ALT_MMU_AP_RW_NONE 00x Read / Write Access No Access
ALT_MMU_AP_RW_RW 01x Read / Write Access Read / Write Access
ALT_MMU_AP_RO_NONE 10x Read-Only Access No Access
ALT_MMU_AP_RO_RO 11x Read-Only Access Read-Only Access
typedef uint8_t ALT_MMU_ATTR_t

This definition matches the MAIR (Memory Attribute Indirection Register).

When the top nibble of MAIR is 0000, the memory being described is Device Memory. Otherwise it is Normal Memory.

The following table provides the device memory attributes for the lower nibble. n is for the not prefix, G is for Gathering, R for Recombining, and E for Early write acknolwedgement. Please consult the ARMv8-A (ARM DDI 0487A) for more details of these parameters. Combinations not described have unpredictable behavior.

MAIR[3:0] Device Memory
0000 Device nGnRnE
0100 Device nGnRE
1000 Device nGRE
1100 Device GRE

When the top nibble of MAIR is not 0000, the memory being described is Normal Memory.

The following table provides the normal memory attributes for the upper nibble. When the bit definition mentions RW, the R and W bits applies to the outer Read and Write allocation policy respectively where 0 is no allocate and 1 is allocate. To complete the definition of MAIR, another table is provided for bottom nibble.

MAIR[7:4] Normal Memory Outer Attribute
00RW, RW not 00 Outer Write-Through transient
0100 Outer Non-Cacheable
01RW, RW not 00 OUter Write-Back transient
10RW Outer Write-Through non-transient
11RW Outer Write-Back non-transient

The following table provides the normal memory attributes for the lower nibble. When the bit definition mentions RW, the R and W bits applies to the inner Read and Write allocation policy respectively where 0 is no allocate and 1 is allocate.

MAIR[3:0] Normal Memory Inner Attribute
00RW, RW not 00 Inner Write-Through transient
0100 Inner Non-Cacheable
01RW, RW not 00 Inner Write-Back transient
1000 Inner Write-Through non-transient (RW=00)
10RW, RW not 00 Inner Write-Through non-transient
1100 Inner Write-Back non-transient (RW=00)
11RW, RW not 00 Inner Write-Back non-transient

This structure provides the MAIR values used for progrmaming the MMU. ALT_MMU_MEM_REGION_t::attrindex is an index into this array to provide the memory attributes.

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)(size_t size, size_t align, 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 TTBR0. 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 4 KiB (2^12), 16 KiB (2^14), or 64 KiB (2^16) for 4 KiB, 16 KiB, or 64 KiB granule sizes respectively.

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.
alignThe size in bytes of the required alignment for the translation table granule being used.
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.

Enumeration Type Documentation

This type enumerates the options for Shareability (SH) properties in translation table descriptors. This control determines whether the addressed region is Shareable memory (and if so, which type) or not. Device memory is always outer shareable.

Enumerator:
ALT_MMU_TTB_SH_NON_SHAREABLE 

Non-Shareable address map

ALT_MMU_TTB_SH_OUTER_SHAREABLE 

Outer Shareable address map

ALT_MMU_TTB_SH_INNER_SHAREABLE 

Inner Shareable address map

This type enumerates the options for Non-Secure (NS) controls in translation table descriptors. This control specifies whether memory accesses made from the secure state translate physical address in the secure or non-secure address map. The value of the NS bit in the first level page table descriptor applies to all entries in the corresponding second-level translation table.

Enumerator:
ALT_MMU_TTB_NS_SECURE 

Secure address map

ALT_MMU_TTB_NS_NON_SECURE 

Non-Secure address map

This type enumerates the options for Execute Never (XN) controls in translation table descriptors that determine whether the processor can execute instructions from the addressed region.

Enumerator:
ALT_MMU_TTB_XN_DISABLE 

Instructions can be executed from this memory region.

ALT_MMU_TTB_XN_ENABLE 

Instructions cannot be executed from this memory region. A permission fault is generated if an attempt to execute an instruction from this memory region. However, if using the short-descriptor translation table format, the fault is generated only if the access is to memory in the client domain.

This type enumerates the Access Permissions that can be specified for a memory region.

Memory access control is defined using access permission bits in translation table descriptors that control access to the corresponding memory region.

The HWLIB uses the long-descriptor translation table format for defining the access permissions where two bits, AP[2:1], define the access permissions. AP[0] defines the access flag, which is not used.

The following table provides a summary of the enumerations, AP bit encodings, and access permission descriptions for this type.

Enumeration AP Value Privileged Access Other Access
ALT_MMU_AP_RW_NONE 00x Read / Write Access No Access
ALT_MMU_AP_RW_RW 01x Read / Write Access Read / Write Access
ALT_MMU_AP_RO_NONE 10x Read-Only Access No Access
ALT_MMU_AP_RO_RO 11x Read-Only Access Read-Only Access
Enumerator:
ALT_MMU_AP_RW_NONE 

Access with Privileged RW, other no access.

ALT_MMU_AP_RW_RW 

Access with Privileged RW, other RW.

ALT_MMU_AP_RO_NONE 

Access with Privileged RO, other no access.

ALT_MMU_AP_RO_RO 

Access with Privileged RO, other RO.

Function Documentation

ALT_STATUS_CODE alt_mmu_tlb_invalidate ( void  )

Invalidate the entire unified TLB.

Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
ALT_STATUS_CODE alt_mmu_tlb_invalidate_is ( void  )

Invalidate the entire unified TLB in the inner shareable domain.

This function applies the unified TLB invalidation operation across all processors in the same inner shareable domain.

Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
ALT_STATUS_CODE alt_mmu_enable ( void  )

Enable operation of the MMU.

This function only enables the MMU. It does not perform any of the necessary prerequisite configuration of the MMU.

Before this function is called, the MMU configuration should have been established. This means:

  • The MMU translation table(s) configured.
  • The translation control register (TCR) configured.
  • The Memory Attribute Indirection Register (MAIR) configured.
  • The values of the TTRB0 (and TTBR1 if applicable) set to the translation table base addresses.
  • The TLBs, caches, and branch predication buffers invalidated.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
ALT_STATUS_CODE alt_mmu_disable ( void  )

Disable operation of the MMU.

Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
ALT_STATUS_CODE alt_mmu_configure_granule ( const ALT_MMU_TCR_INFO_t *  ttbconfig)

This type defines the typed used to define which structure defines the MMU Translation Table Control Register.

size_t alt_mmu_va_space_storage_required ( const ALT_MMU_MEM_REGION_t regions,
size_t  regions_count,
const ALT_MMU_GRANULE_INFO_t *  granule_info,
const ALT_MMU_TCR_INFO_t *  ttbconfig 
)

Returns the number of tables required for the 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
regionsA pointer to an array of memory region descriptors that define the virtual address space.
regions_countThe number of memory region descriptors in the mem_regions array.
granule_infoPagetable configuration information conveyed in the Translation Table Base Control Register.
ttb_configPagetable configuration information conveyed in the Translation Control Register.
Returns
The number of Translation Tables 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 ( const ALT_MMU_MEM_REGION_t regions,
size_t  regions_count,
const ALT_MMU_GRANULE_INFO_t *  granule_info,
const ALT_MMU_TCR_INFO_t *  ttbconfig,
alt_mmu_ttb_alloc_t  ttb_alloc,
void *  memPool 
)

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 describe the entire virtual address range configured by ttbcr_info (AArch32) or tcr_info (AArch64) and have no overlapping virtual address ranges.

In AArch32 mode, the largest region that can be specified by a single region is 2 GiB. Use multiple entries to describe a larger memory region.

In AArch64 mode, there is no equivalent restriction. The largest region that can be described is the physical address size parameter specified in tcr_info.

Parameters
regionsA pointer to an array of memory region descriptors that define the virtual address space.
regions_countThe number of memory region descriptors in the regions array.
granule_infoPagetable configuration information conveyed in the Translation Table Base Control Register. (AArch32 only)
ttbconfigPagetable configuration information conveyed in the Translation Control Register. (AArch64 only)
ttb_allocA pointer to a user defined function used for allocating storage for translation tables.
memPoolPointer Pool of Available Memory to hold Dynamically Allocated Translation Tables
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
uint64_t alt_mmu_va_to_pa ( const void *  va,
ALT_MMU_ATTR_t attr,
uint32_t *  dfsc 
)

Given a virtual address, this API attempts to determine the corresponding physical address and memory attribute. There are no alignment restrictions on the incoming virtual address.

If the translation succeeds, the corresponding physical address will be returned, attr will be populated with the memory attribute, and esr will be populated with 0.

If the translation is not possible, dfsc (Data Fault Status Code) will contain the reason for the translation failure and the other returned values will be undefined. dfsc is the long descriptor Data Fault (EC=100101b) ESR's ISS's DFSC.

For a complete understanding of the DFSC bit field assignments, consult the following reference(s):

  • ARM Architecture Reference Manual ARMv8-A (ARM DDI 0487A), section D7.2.27.
Parameters
vaThe virtual address to query.
attr[out] A pointer memory attribute associated with that virtual address.
dfsc[out] A pointer to the data fault status code value.
Returns
The physical address of the translation if it is successful.