Hardware Libraries
20.1
Stratix 10 SoC Hardware Manager
|
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) |
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 enum ALT_MMU_TTB_SH_e ALT_MMU_TTB_SH_t |
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.
typedef enum ALT_MMU_TTB_NS_e ALT_MMU_TTB_NS_t |
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.
typedef enum ALT_MMU_TTB_XN_e ALT_MMU_TTB_XN_t |
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 |
typedef struct ALT_MMU_MAIR_s ALT_MMU_MAIR_t |
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.
typedef struct ALT_MMU_MEM_REGION_s ALT_MMU_MEM_REGION_t |
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.
size | The 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. |
align | The size in bytes of the required alignment for the translation table granule being used. |
context | A user provided context for the allocator function. |
enum ALT_MMU_TTB_SH_e |
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.
enum ALT_MMU_TTB_NS_e |
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.
enum ALT_MMU_TTB_XN_e |
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.
enum ALT_MMU_AP_e |
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 |
ALT_STATUS_CODE alt_mmu_tlb_invalidate | ( | void | ) |
Invalidate the entire unified TLB.
ALT_E_SUCCESS | Successful status. |
ALT_E_ERROR | Details 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.
ALT_E_SUCCESS | Successful status. |
ALT_E_ERROR | Details 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:
ALT_E_SUCCESS | Successful status. |
ALT_E_ERROR | Details about error status code |
ALT_STATUS_CODE alt_mmu_disable | ( | void | ) |
Disable operation of the MMU.
ALT_E_SUCCESS | Successful status. |
ALT_E_ERROR | Details 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.
regions | A pointer to an array of memory region descriptors that define the virtual address space. |
regions_count | The number of memory region descriptors in the mem_regions array. |
granule_info | Pagetable configuration information conveyed in the Translation Table Base Control Register. |
ttb_config | Pagetable configuration information conveyed in the Translation Control Register. |
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.
regions | A pointer to an array of memory region descriptors that define the virtual address space. |
regions_count | The number of memory region descriptors in the regions array. |
granule_info | Pagetable configuration information conveyed in the Translation Table Base Control Register. (AArch32 only) |
ttbconfig | Pagetable configuration information conveyed in the Translation Control Register. (AArch64 only) |
ttb_alloc | A pointer to a user defined function used for allocating storage for translation tables. |
memPool | Pointer Pool of Available Memory to hold Dynamically Allocated Translation Tables |
ALT_E_SUCCESS | Successful status. |
ALT_E_ERROR | Details 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):
va | The 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. |