module ti.sysbios.family.arm.a15.smp.Cache
index URL

ARM Cache Module

This module manages the data and instruction caches on Cortex A15 processors. It provides a list of functions that perform cache operations. The functions operate on a per cache line except for the 'All' functions which operate on the entire cache specified. Any Address that is not aligned to a cache line gets rounded down to the address of the nearest cache line. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/a15/smp/Cache.xdc
#include <ti/sysbios/family/arm/a15/smp/Cache.h>
Functions
Void 
Cache_disableBP// Disable Branch Prediction();
Void 
Cache_enableBP// Enable Branch Prediction();
Void 
Cache_invL1pAll// Invalidate all of L1 program cache();
Void 
Cache_preLoad// Loads a memory block into the L2 cache(Ptr blockPtr, SizeT byteCnt);
Void 
Cache_wbAllLoUIS// Write back data cache to PoU for an Inner Shareable domain();
Void 
Cache_wbInvAllLoUIS// Write back invalidate data cache to PoU for an Inner Shareable domain();
Functions common to all ICache modules
Void 
Cache_disable// Disables the 'type' cache(s)(Bits16 type);
Void 
Cache_enable// Enables all cache(s)(Bits16 type);
Void 
Cache_inv// Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void 
Cache_wait// Wait for a previous cache operation to complete();
Void 
Cache_wb// Writes back a range of memory from all cache(s)(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void 
Cache_wbAll// Write back all caches();
Void 
Cache_wbInv// Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void 
Cache_wbInvAll// Write back invalidate all caches();
Functions common to all target modules
Cache_Module_getMask// Returns the diagnostics mask for this module, Cache_Module_hasMask// Test whether this module has a diagnostics mask, Cache_Module_heap// The heap from which this module allocates memory, Cache_Module_id// Get this module's unique id, Cache_Module_setMask// Set the diagnostics mask for this module, Cache_Module_startupDone// Test if this module has completed startup
Defines
#define
Cache_sizeL1dCacheLine// Size of L1 data cache Line in bytes (UInt)64
#define
Cache_sizeL1pCacheLine// Size of L1 program cache Line in bytes (UInt)64
#define
Cache_sizeL2CacheLine// Size of L2 cache Line in bytes (UInt)64
Typedefs
typedef enum
Cache_Type// Lists of bitmask cache types ...
Constants
extern const Assert_Id 
Cache_A_badBlockLength// Asserted in Cache_lock;
extern const Assert_Id 
Cache_A_blockCrossesPage// Asserted in Cache_lock;
extern const Assert_Id 
Cache_A_cacheDisableUnsupported// Assert raised when attempting to disable L1 data or L2 unified cache;
extern const Assert_Id 
Cache_A_cacheEnableUnsupported// Assert raised when attempting to enable L1 data or L2 unified cache;
extern const Bool 
Cache_branchPredictionEnabled// Enable Branch Prediction at startup, default is true;
extern const Bool 
Cache_enableCache// Enable L1 and L2 data and program caches;
extern const Bool 
Cache_errata798870// Enable workaround for ARM errata 798870;
 
DETAILS
This module manages the data and instruction caches on Cortex A15 processors. It provides a list of functions that perform cache operations. The functions operate on a per cache line except for the 'All' functions which operate on the entire cache specified. Any Address that is not aligned to a cache line gets rounded down to the address of the nearest cache line.
The L1 data and program caches as well as the L2 cache are enabled by default early during the startup sequence (prior to any Module_startup()s). Data caching requires the MMU to be enabled and the cacheable attribute of the section/page descriptor for a corresponding memory region to be enabled. Program caching does not require the MMU to be enabled and therefore occurs when the L1 program cache is enabled.
(See the ti.sysbios.family.arm.a15.Mmu module for information about the MMU.)
Note: The invalidate instruction is implemented as a clean/invalidate instruction on A15. Therefore, calls to Cache_inv()/Cache_invAll() will behave like Cache_wbInv()/Cache_wbInvAll() on A15.
Unconstrained Functions All functions

Calling Context

Function Hwi Swi Task Main Startup
disable Y Y Y Y Y
enable Y Y Y Y Y
inv Y Y Y Y Y
invL1pAll Y Y Y Y Y
wait Y Y Y Y Y
wb Y Y Y Y Y
wbInv Y Y Y Y Y
wbInvAll Y Y Y Y Y
wbAll Y Y Y Y Y
wbInvAllLoUIS Y Y Y Y Y
wbAllLoUIS Y Y Y Y Y
preLoad Y Y Y Y Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).
 
const Cache_sizeL1dCacheLine
index URL

Size of L1 data cache Line in bytes

C synopsis target-domain
#define Cache_sizeL1dCacheLine (UInt)64
 
 
const Cache_sizeL1pCacheLine
index URL

Size of L1 program cache Line in bytes

C synopsis target-domain
#define Cache_sizeL1pCacheLine (UInt)64
 
 
const Cache_sizeL2CacheLine
index URL

Size of L2 cache Line in bytes

C synopsis target-domain
#define Cache_sizeL2CacheLine (UInt)64
 
 
enum Cache_Type
index URL

Lists of bitmask cache types

C synopsis target-domain
typedef enum Cache_Type {
    Cache_Type_L1P,
    // Level 1 Program cache
    Cache_Type_L1D,
    // Level 1 Data cache
    Cache_Type_L1,
    // Level 1 caches
    Cache_Type_L2P,
    // Level 2 Program cache
    Cache_Type_L2D,
    // Level 2 Data cache
    Cache_Type_L2,
    // Level 2 caches
    Cache_Type_ALLP,
    // All Program caches
    Cache_Type_ALLD,
    // All Data caches
    Cache_Type_ALL
    // All caches
} Cache_Type;
 
 
config Cache_A_badBlockLength  // module-wide
index URL

Asserted in Cache_lock

C synopsis target-domain
extern const Assert_Id Cache_A_badBlockLength;
 
 
config Cache_A_blockCrossesPage  // module-wide
index URL

Asserted in Cache_lock

C synopsis target-domain
extern const Assert_Id Cache_A_blockCrossesPage;
 
 
config Cache_A_cacheDisableUnsupported  // module-wide
index URL

Assert raised when attempting to disable L1 data or L2 unified cache

C synopsis target-domain
extern const Assert_Id Cache_A_cacheDisableUnsupported;
 
DETAILS
When running in SMP mode, the inter-core lock is implemented using ldrex/strex instructions and requires the hardware to implement a global monitor to work. Some devices like Keystone 2, do not implement a global monitor (only a local monitor). On such devices, the cache coherency logic (snoop control unit) along with the local monitors can effectively work like a global monitor. Therefore, it is important that the caches are not disabled as that would disable cache coherency on the particular core and cause the inter-core lock to not work.
 
config Cache_A_cacheEnableUnsupported  // module-wide
index URL

Assert raised when attempting to enable L1 data or L2 unified cache

C synopsis target-domain
extern const Assert_Id Cache_A_cacheEnableUnsupported;
 
DETAILS
It is not recommended for the user code to anable/disable the caches when running in SMP mode. Please see the documentation here for more details.
 
config Cache_branchPredictionEnabled  // module-wide
index URL

Enable Branch Prediction at startup, default is true

C synopsis target-domain
extern const Bool Cache_branchPredictionEnabled;
 
DETAILS
This flag controls whether Branch Prediction should be automatically enabled or disabled during system startup.
NOTE
Upon reset, the A15's Program Flow Prediction (Branch Prediction) feature is disabled.
 
config Cache_enableCache  // module-wide
index URL

Enable L1 and L2 data and program caches

C synopsis target-domain
extern const Bool Cache_enableCache;
 
DETAILS
Not implemented by all architectures. Refer to specific architecture Cache module for details.
To enable a subset of the caches, set this parameter to 'false' and call Cache_enable() within main, passing it only the Cache_Type(s) to be enabled.
Data caching requires the MMU and the memory section/page descriptor cacheable attribute to be enabled.
 
config Cache_errata798870  // module-wide
index URL

Enable workaround for ARM errata 798870

C synopsis target-domain
extern const Bool Cache_errata798870;
 
DETAILS
Errata 798870 brief description: A memory read can stall indefinitely in the L2 cache
 
Cache_disable()  // module-wide
index URL

Disables the 'type' cache(s)

C synopsis target-domain
Void Cache_disable(Bits16 type);
 
ARGUMENTS
type — bit mask of Cache type
DETAILS
This function is not fully supported when running in SMP mode. Only L1 program cache disable is supported. Attempting to disable the L1 data and/or L2 cache will cause an assertion failure.
Here's a brief explanation of why caches should not be disabled. When running in SMP mode, the inter-core lock is implemented using ldrex/strex instructions and requires the hardware to implement a global monitor to work properly. Some devices like Keystone 2, do not implement a global monitor (only a local monitor). On such devices, the cache coherency logic (snoop control unit) along with the local monitors can effectively work like a global monitor. Therefore, it is important that the caches are not disabled as that would disable cache coherency on the particular core and cause the inter-core lock to not work.
 
Cache_disableBP()  // module-wide
index URL

Disable Branch Prediction

C synopsis target-domain
Void Cache_disableBP();
 
DETAILS
Calling this API will disable branch prediction.
NOTE
Upon reset, the A15's Program Flow Prediction (Branch Prediction) feature is disabled.
 
Cache_enable()  // module-wide
index URL

Enables all cache(s)

C synopsis target-domain
Void Cache_enable(Bits16 type);
 
ARGUMENTS
type — bit mask of Cache type
DETAILS
This function is not fully supported when running in SMP mode. Only L1 program cache enable is supported. Attempting to enable the L1 data and/or L2 cache will cause an assertion failure. The caches are enabled during the startup sequence if enableCache config param is set to true. Since disabling the caches at runtime is not fully supported, the cache enable function is not fully supported.
Please see Cache_disable() cdoc for more a detailed explanation of why disabling the caches is harmful and not supported.
 
Cache_enableBP()  // module-wide
index URL

Enable Branch Prediction

C synopsis target-domain
Void Cache_enableBP();
 
DETAILS
Calling this API will enable branch prediction.
NOTE
Upon reset, the A15's Program Flow Prediction (Branch Prediction) feature is disabled.
 
Cache_inv()  // module-wide
index URL

Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches

C synopsis target-domain
Void Cache_inv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
 
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
 
Cache_invL1pAll()  // module-wide
index URL

Invalidate all of L1 program cache

C synopsis target-domain
Void Cache_invL1pAll();
 
 
Cache_preLoad()  // module-wide
index URL

Loads a memory block into the L2 cache

C synopsis target-domain
Void Cache_preLoad(Ptr blockPtr, SizeT byteCnt);
 
ARGUMENTS
blockPtr — start address of range to be loaded
byteCnt — number of bytes to be loaded
DETAILS
A block of memory is loaded into the L2 cache.
The memory block is loaded into cache one L2 cache line at time.
The byteCnt argument must be less than or equal to an L2 cache size. An assert is generated if this rule is violated.
Except for the normal L1 instruction cache behavior during code execution, the L1 instruction cache is unaffected by this API. The L1 data cache will be temporarily polluted by the contents of the referenced memory block.
NOTE
Interrupts are disabled for the entire time the memory block is being loaded into cache. For this reason, use of this API is probably best at system intialization time (ie: within 'main()').
 
Cache_wait()  // module-wide
index URL

Wait for a previous cache operation to complete

C synopsis target-domain
Void Cache_wait();
 
DETAILS
Wait for the cache wb/wbInv/inv operation to complete. A cache operation is not truly complete until it has worked its way through all buffering and all memory writes have landed in the source memory.
 
Cache_wb()  // module-wide
index URL

Writes back a range of memory from all cache(s)

C synopsis target-domain
Void Cache_wb(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
 
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
DETAILS
Writes back the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are left valid in the 'type' caches and the data within the range will be written back to the source memory.
 
Cache_wbAll()  // module-wide
index URL

Write back all caches

C synopsis target-domain
Void Cache_wbAll();
 
DETAILS
Perform a global write back. There is no effect on program cache. All data cache lines are left valid.
This function writes back the data cache to the point of coherency. On a Cortex-A15, point of coherency is the main memory implying that this function will write back the L1 data cache (on this core) followed by the L2 unified cache that is shared by all cores in the MPCore sub-system.
When running in SMP mode, it is not recommended to call this function as it does not guarantee that the L1 data caches on all other cores will be written back before writing back the unified L2 cache. This function should only be called if all other cores are in a power down state or if their local L1 caches are disabled i.e. they do not have any dirty L1 cache lines.
 
Cache_wbAllLoUIS()  // module-wide
index URL

Write back data cache to PoU for an Inner Shareable domain

C synopsis target-domain
Void Cache_wbAllLoUIS();
 
DETAILS
This function writes back the L1 data cache. There is no effect on program cache. All data cache lines are left valid.
On Cortex-A15, this function will write back the local CPU's L1 data cache to the L2 cache but not beyond. Calling this function has no affect on the local L1 caches of all other cores in the MPCore sub-system. This API should be called with Hwis and/or Tasking disabled to guarantee the write back operation is complete.
 
Cache_wbInv()  // module-wide
index URL

Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches

C synopsis target-domain
Void Cache_wbInv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
 
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
 
Cache_wbInvAll()  // module-wide
index URL

Write back invalidate all caches

C synopsis target-domain
Void Cache_wbInvAll();
 
DETAILS
Performs a global write back and invalidate. All cache lines are written out to physical memory and then invalidated.
This function writes back and invalidates the data cache to the point of coherency. On a Cortex-A15, point of coherency is the main memory implying that this function will write back and invalidate the L1 data cache (on this core) followed by the L2 unified cache that is shared by all cores in the MPCore sub-system.
When running in SMP mode, it is not recommended to call this function as it does not guarantee that the L1 data caches on all other cores will be flushed before flushing the unified L2 cache. This function should only be called if all other cores are in a power down state or if their local L1 caches are disabled i.e. they do not have any dirty L1 cache lines.
 
Cache_wbInvAllLoUIS()  // module-wide
index URL

Write back invalidate data cache to PoU for an Inner Shareable domain

C synopsis target-domain
Void Cache_wbInvAllLoUIS();
 
DETAILS
On Cortex-A15, this function will write back and invalidate the local CPU's L1 data cache to the L2 cache but not beyond. Calling this function has no affect on the local L1 caches of all other cores in the MPCore sub-system. This API should be called with Hwis and/or Tasking disabled to guarantee the write back invalidate operation is complete.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Cache_Module_id();
// Get this module's unique id
 
Bool Cache_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Cache_Module_heap();
// The heap from which this module allocates memory
 
Bool Cache_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 Cache_Module_getMask();
// Returns the diagnostics mask for this module
 
Void Cache_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
Configuration settings sourced in ti/sysbios/family/arm/a15/smp/Cache.xdc
var Cache = xdc.useModule('ti.sysbios.family.arm.a15.smp.Cache');
module-wide constants & types
    const Cache.sizeL1dCacheLine// Size of L1 data cache Line in bytes = 64;
    const Cache.sizeL1pCacheLine// Size of L1 program cache Line in bytes = 64;
    const Cache.sizeL2CacheLine// Size of L2 cache Line in bytes = 64;
 
    values of type Cache.Type// Lists of bitmask cache types
        const Cache.Type_L1P// Level 1 Program cache;
        const Cache.Type_L1D// Level 1 Data cache;
        const Cache.Type_L1// Level 1 caches;
        const Cache.Type_L2P// Level 2 Program cache;
        const Cache.Type_L2D// Level 2 Data cache;
        const Cache.Type_L2// Level 2 caches;
        const Cache.Type_ALLP// All Program caches;
        const Cache.Type_ALLD// All Data caches;
        const Cache.Type_ALL// All caches;
module-wide config parameters
    Cache.A_badBlockLength// Asserted in Cache_lock = Assert.Desc {
        msg: "A_badBlockLength: Block length too large. Must be <= L2 way size."
    };
    Cache.A_blockCrossesPage// Asserted in Cache_lock = Assert.Desc {
        msg: "A_blockCrossesPage: Memory block crosses L2 way page boundary."
    };
    Cache.A_cacheDisableUnsupported// Assert raised when attempting to disable L1 data or L2 unified cache = Assert.Desc {
        msg: "A_cacheDisableUnsupported: Disabling the L1 data or L2 unified cache from user code is not supported. Cache disable/enable is internally managed by the kernel."
    };
    Cache.A_cacheEnableUnsupported// Assert raised when attempting to enable L1 data or L2 unified cache = Assert.Desc {
        msg: "A_cacheEnableUnsupported: Enabling the L1 data or L2 unified cache from user code is not supported. Cache disable/enable is internally managed by the kernel."
    };
    Cache.branchPredictionEnabled// Enable Branch Prediction at startup, default is true = Bool true;
    Cache.enableCache// Enable L1 and L2 data and program caches = Bool true;
    Cache.errata798870// Enable workaround for ARM errata 798870 = Bool false;
 
    Cache.common$// Common module configuration parameters = Types.Common$ undefined;
 
 
const Cache.sizeL1dCacheLine
index URL

Size of L1 data cache Line in bytes

Configuration settings
const Cache.sizeL1dCacheLine = 64;
 
C SYNOPSIS
Cache_sizeL1dCacheLine
 
const Cache.sizeL1pCacheLine
index URL

Size of L1 program cache Line in bytes

Configuration settings
const Cache.sizeL1pCacheLine = 64;
 
C SYNOPSIS
Cache_sizeL1pCacheLine
 
const Cache.sizeL2CacheLine
index URL

Size of L2 cache Line in bytes

Configuration settings
const Cache.sizeL2CacheLine = 64;
 
C SYNOPSIS
Cache_sizeL2CacheLine
 
enum Cache.Type
index URL

Lists of bitmask cache types

Configuration settings
values of type Cache.Type
    const Cache.Type_L1P;
    // Level 1 Program cache
    const Cache.Type_L1D;
    // Level 1 Data cache
    const Cache.Type_L1;
    // Level 1 caches
    const Cache.Type_L2P;
    // Level 2 Program cache
    const Cache.Type_L2D;
    // Level 2 Data cache
    const Cache.Type_L2;
    // Level 2 caches
    const Cache.Type_ALLP;
    // All Program caches
    const Cache.Type_ALLD;
    // All Data caches
    const Cache.Type_ALL;
    // All caches
 
C SYNOPSIS
Cache_Type
 
config Cache.A_badBlockLength  // module-wide
index URL

Asserted in Cache_lock

Configuration settings
Cache.A_badBlockLength = Assert.Desc {
    msg: "A_badBlockLength: Block length too large. Must be <= L2 way size."
};
 
C SYNOPSIS
Cache_A_badBlockLength
 
config Cache.A_blockCrossesPage  // module-wide
index URL

Asserted in Cache_lock

Configuration settings
Cache.A_blockCrossesPage = Assert.Desc {
    msg: "A_blockCrossesPage: Memory block crosses L2 way page boundary."
};
 
C SYNOPSIS
Cache_A_blockCrossesPage
 
config Cache.A_cacheDisableUnsupported  // module-wide
index URL

Assert raised when attempting to disable L1 data or L2 unified cache

Configuration settings
Cache.A_cacheDisableUnsupported = Assert.Desc {
    msg: "A_cacheDisableUnsupported: Disabling the L1 data or L2 unified cache from user code is not supported. Cache disable/enable is internally managed by the kernel."
};
 
DETAILS
When running in SMP mode, the inter-core lock is implemented using ldrex/strex instructions and requires the hardware to implement a global monitor to work. Some devices like Keystone 2, do not implement a global monitor (only a local monitor). On such devices, the cache coherency logic (snoop control unit) along with the local monitors can effectively work like a global monitor. Therefore, it is important that the caches are not disabled as that would disable cache coherency on the particular core and cause the inter-core lock to not work.
C SYNOPSIS
Cache_A_cacheDisableUnsupported
 
config Cache.A_cacheEnableUnsupported  // module-wide
index URL

Assert raised when attempting to enable L1 data or L2 unified cache

Configuration settings
Cache.A_cacheEnableUnsupported = Assert.Desc {
    msg: "A_cacheEnableUnsupported: Enabling the L1 data or L2 unified cache from user code is not supported. Cache disable/enable is internally managed by the kernel."
};
 
DETAILS
It is not recommended for the user code to anable/disable the caches when running in SMP mode. Please see the documentation here for more details.
C SYNOPSIS
Cache_A_cacheEnableUnsupported
 
config Cache.branchPredictionEnabled  // module-wide
index URL

Enable Branch Prediction at startup, default is true

Configuration settings
Cache.branchPredictionEnabled = Bool true;
 
DETAILS
This flag controls whether Branch Prediction should be automatically enabled or disabled during system startup.
NOTE
Upon reset, the A15's Program Flow Prediction (Branch Prediction) feature is disabled.
C SYNOPSIS
Cache_branchPredictionEnabled
 
config Cache.enableCache  // module-wide
index URL

Enable L1 and L2 data and program caches

Configuration settings
Cache.enableCache = Bool true;
 
DETAILS
Not implemented by all architectures. Refer to specific architecture Cache module for details.
To enable a subset of the caches, set this parameter to 'false' and call Cache_enable() within main, passing it only the Cache_Type(s) to be enabled.
Data caching requires the MMU and the memory section/page descriptor cacheable attribute to be enabled.
C SYNOPSIS
Cache_enableCache
 
config Cache.errata798870  // module-wide
index URL

Enable workaround for ARM errata 798870

Configuration settings
Cache.errata798870 = Bool false;
 
DETAILS
Errata 798870 brief description: A memory read can stall indefinitely in the L2 cache
C SYNOPSIS
Cache_errata798870
 
metaonly config Cache.common$  // module-wide
index URL

Common module configuration parameters

Configuration settings
Cache.common$ = Types.Common$ undefined;
 
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Thu, 23 May 2019 00:22:35 GMT