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

Description

This section defines low-level declarations, macros, and functions for creating and maintaining MMU first and second level translation tables and their short descriptor entries.

The basic functions to enable/disable and configure the opertational state of the MMU are in this section.

The operations in this section are for users that want to exercise a fine degree of configuration and control over the MMU. It requires a more detailed understanding of the MMU, its different modes of operation, and puts more responsibility on the user for correct functioning.

Users desiring basic configuration and enablement of the MMU to support a virtual address space should use the operations in the section MMU Virtual Address Space Creation.

Members

 MMU Management Macros - First Level Translation Table
 
 MMU Management Macros - Second Level Translation Table
 
 MMU Management Data Structures - First Level Translation Table
 
 MMU Management Data Structures - Second Level Translation Table
 

Macros

#define ALT_MMU_SUPERSECTION_SIZE   (1UL << 24)
 
#define ALT_MMU_SECTION_SIZE   (1UL << 20)
 
#define ALT_MMU_LARGE_PAGE_SIZE   (1UL << 16)
 
#define ALT_MMU_SMALL_PAGE_SIZE   (1UL << 12)
 
#define ALT_MMU_TTB1_SIZE   16384
 
#define ALT_MMU_TTB2_SIZE   1024
 

Functions

ALT_STATUS_CODE alt_mmu_init (void)
 
ALT_STATUS_CODE alt_mmu_uninit (void)
 
ALT_STATUS_CODE alt_mmu_ttb1_init (uint32_t *ttb1)
 
ALT_STATUS_CODE alt_mmu_ttb1_desc_set (uint32_t *ttb1, const void *va, const uint32_t desc)
 
ALT_STATUS_CODE alt_mmu_ttb2_desc_set (const uint32_t *ttb1, const void *va, const uint32_t desc)
 
ALT_STATUS_CODE alt_mmu_disable (void)
 
ALT_STATUS_CODE alt_mmu_enable (void)
 
void * alt_mmu_TTBR0_get (void)
 
ALT_STATUS_CODE alt_mmu_TTBR0_set (const void *addr)
 
void * alt_mmu_TTBR1_get (void)
 
ALT_STATUS_CODE alt_mmu_TTBR1_set (const void *addr)
 
ALT_STATUS_CODE alt_mmu_TTBCR_set (const bool enable_ttbr0_walk, const bool enable_ttbr1_walk, const uint32_t base_addr_width)
 
ALT_STATUS_CODE alt_mmu_DACR_set (const ALT_MMU_DAP_t domain_ap[], const size_t num_elem)
 
ALT_STATUS_CODE alt_mmu_CONTEXTIDR_set (const uint32_t procid, const uint32_t asid)
 
ALT_STATUS_CODE alt_mmu_tlb_invalidate (void)
 
ALT_STATUS_CODE alt_mmu_tlb_invalidate_is (void)
 

Macro Definitions

#define ALT_MMU_SUPERSECTION_SIZE   (1UL << 24)

The size of a supersection in bytes is 16 MiB.

#define ALT_MMU_SECTION_SIZE   (1UL << 20)

The size of a section in bytes is 1 MiB.

#define ALT_MMU_LARGE_PAGE_SIZE   (1UL << 16)

The size of a large page in bytes is 64 KiB.

#define ALT_MMU_SMALL_PAGE_SIZE   (1UL << 12)

The size of a small page in bytes is 4 KiB.

#define ALT_MMU_TTB1_SIZE   16384

The size of a first level translation table for the short descriptor format in bytes.

#define ALT_MMU_TTB2_SIZE   1024

The size of a second level translation table for the short descriptor format in bytes.

Function Documentation

ALT_STATUS_CODE alt_mmu_init ( void  )

Initializes the processor MMU subsystem.

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

Uninitializes the processor MMU subsystem.

Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
ALT_STATUS_CODE alt_mmu_ttb1_init ( uint32_t *  ttb1)

Initialize a block of memory for use as a first level translation table.

The memory block is initialized for use as a first level translation table by setting all table entries to section fault entry values.

Parameters
ttb1A pointer to a block of memory to be initialized for use as a first level translation table. The memory block must be at least ALT_MMU_TTB1_SIZE bytes and the pointer aligned to 2^x bytes where x is (14 - TTBCR.N). TTBCR.N is configured using alt_mmu_TTBCR_set()'s base_addr_width argument.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
ALT_STATUS_CODE alt_mmu_ttb1_desc_set ( uint32_t *  ttb1,
const void *  va,
const uint32_t  desc 
)

Set the first level translation table descriptor entry for the virtual address va to the descriptor value desc.

Based on the virtual address parameter value va, this function computes the appropriate entry in the first level translation table specified by the base address value ttb1 to set.

If the descriptor type of desc is a fault, section, or page table descriptor then the virtual address value va must be a 1 MiB aligned address and the corresponding entry in the first level translation table specified by ttb1 is set to the desc value.

If the descriptor type of desc is a supersection descriptor then the virtual address value va must be a 16 MiB aligned address and the corresponding 16 entries in the first level translation table specified by ttb1 are set to desc values.

Parameters
ttb1The base address of the first level translation table.
vaThe virtual address of the first level translation table descriptor entry to set the descriptor entry value for. The va must be an appropriately aligned address (1 or 16 MiB aligned) value per type of the desc.
descThe short descriptor value to use for the virtual address entry in the first level translation table.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
ALT_STATUS_CODE alt_mmu_ttb2_desc_set ( const uint32_t *  ttb1,
const void *  va,
const uint32_t  desc 
)

Set the second level translation table descriptor entry for the virtual address va to the descriptor value desc.

Based on the virtual address parameter value va, this function computes the appropriate entry in the second level translation table to set. This requires the corresponding first level translation table page table descriptor entry to have been previously configured prior to setting up any second level translation table entries in that 1 MiB virtual address range.

If the descriptor type of desc is a fault or small page descriptor then the virtual address value va must be a 4 KiB aligned address and the appropriate entry in the second level translation table is set to the desc value.

If the descriptor type of desc is a large page descriptor then the virtual address value va must be a 64 KiB aligned address and the appropriate 16 entries in the second level translation table are set to the desc value.

Parameters
ttb1The base address of the first level translation table.
vaThe virtual address of the second level translation table descriptor entry to set the descriptor entry value for. The va must be an appropriately aligned address (4 or 64 KiB aligned) value per type of the desc.
descThe short descriptor value to use for the virtual address entry in the first level translation table.
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_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 table control register (TTBCR) configured.
  • The values of the TTBR0 (and TTBR1 if applicable) set to the translation table base addresses.
  • The domain access control register (DACR) configured.
  • The TLBs, caches, and branch predication buffers invalidated.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
void* alt_mmu_TTBR0_get ( void  )

Get the current address value in the Translation Table Base Register 0.

Returns
The address value in the Translation Table Base Register 0.
ALT_STATUS_CODE alt_mmu_TTBR0_set ( const void *  addr)

Set the address value in the Translation Table Base Register 0.

Parameters
addrThe base address of a first level translation table. The memory block must be aligned to 2^x bytes where x is (14 - TTBCR.N). TTBCR.N is configured using alt_mmu_TTBCR_set()'s base_addr_width argument.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
void* alt_mmu_TTBR1_get ( void  )

Get the current address value in the Translation Table Base Register 1.

Returns
The address value in the Translation Table Base Register 1.
ALT_STATUS_CODE alt_mmu_TTBR1_set ( const void *  addr)

Set the address value in the Translation Table Base Register 1.

Parameters
addrThe base address of a first level translation table. The memory block must be aligned to 2^14 bytes.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
ALT_STATUS_CODE alt_mmu_TTBCR_set ( const bool  enable_ttbr0_walk,
const bool  enable_ttbr1_walk,
const uint32_t  base_addr_width 
)

Sets the control options in the Translation Table Base Control Register (TTBCR).

Many APIs within the MMU module are designed to work with a base address width set to 0. Setting a value other than 0 will cause problems many APIs not specifically designed to work with a non-zero value. These include the following APIs:

Parameters
enable_ttbr0_walkA value of true enables translation table walks for TLB misses using TTBR0. A value of false causes a TLB miss on an address that is translated using TTBR0 to generate a translation fault and a translation table walk is performed.
enable_ttbr1_walkA value of true enables translation table walks for TLB misses using TTBR1. A value of false causes a TLB miss on an address that is translated using TTBR1 to generate a translation fault and a translation table walk is performed.
base_addr_widthSpecifies the width of the base address held in TTBR0. In TTBR0, the base address field is bits[31:14-N] where N is the value of the base_addr_width parameter. base_addr_width may be any value from 0 to 7.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
ALT_STATUS_CODE alt_mmu_DACR_set ( const ALT_MMU_DAP_t  domain_ap[],
const size_t  num_elem 
)

Sets the access permissions for the sixteen memory domains of the Domain Access Control Register (DACR).

Parameters
domain_apAn array of sixteen domain access permission settings for each of the respective sixteen memory domains.
num_elemThe number of domain access permission elements in domain_ap. This should always be 16.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
ALT_STATUS_CODE alt_mmu_CONTEXTIDR_set ( const uint32_t  procid,
const uint32_t  asid 
)

Sets the Context ID Register (CONTEXTIDR).

This function sets the the current Process Identifier (PROCID) and the Address Space Identifier (ASID) values of the Context ID Register (CONTEXTIDR).

Parameters
procidThe process identifier value. This field must be programmed with a unique value that identifies the current process should not exceed 22 bits in width.
asidThe address space identifier. This field is programmed with the value of the current ASID and should not exceed 8 bits in width.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
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