module ti.sysbios.hal.unicache.Cache

The unicache Cache module used by the omap4 Tesla and Ducati cores

The Tesla and Ducati UniCaches do not support separate program and data caches. Therefore none of the unique Cache_Type L1P/L1D/L2P/L2D operations can be precisely supported. The APIs in this module ignore the P/D and observe only the L1/L2 designations (ie Cache_Type_L1P is functionally equivalent to Cache_Type_L1D and Cache_Type_L1). [ more ... ]
C synopsis target-domain sourced in ti/sysbios/hal/unicache/Cache.xdc
#include <ti/sysbios/hal/unicache/Cache.h>
Functions
Void 
Void 
Cache_lock// Locks a memory block into the cache(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void 
Cache_preload// Loads a memory block into the cache(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void 
Cache_preloadLock// Loads and locks a memory block into the cache(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void 
Void 
Cache_unlock// Unlocks a cached memory block(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Functions common to all ICache modules
Void 
Void 
Void 
Void 
Void 
Cache_wb// Writes back a range of memory from all cache(s)(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void 
Void 
Void 
Functions common to all target modules
Typedefs
typedef struct
typedef struct
typedef struct
typedef enum
Constants
extern const Bool 
extern const Bool 
extern const Error_Id 
extern const SizeT 
Variables
 
DETAILS
The Tesla and Ducati UniCaches do not support separate program and data caches. Therefore none of the unique Cache_Type L1P/L1D/L2P/L2D operations can be precisely supported. The APIs in this module ignore the P/D and observe only the L1/L2 designations (ie Cache_Type_L1P is functionally equivalent to Cache_Type_L1D and Cache_Type_L1).
RESTRICTIONS
When used within a dual M3 core (Ducati arrangement), care must be taken when initializing this shared resource. The "Shared Resources" note provided in the ducati package discusses the management of the various hardware and software resources shared by the two M3 cores.
As the unicache is shared between the two M3 cores, it should only be initialized and enabled once. It is intended that Core 0 will configure the unicache at startup and then either enable it at that time or later on by manually invoking Cache_enable().
The unicache Cache module is a Gated module. In a dual M3 core (Ducati) environment, the unicache Cache module employs a GateDualCore gate to arbitrate the usage of the shared unicache registers. In a non shared environment such as the C64T core in an OMAP4 device, a GateHwi gate is used to avoid multi thread conflicts.

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
wb Y Y Y Y Y
wbInv Y Y Y Y Y
wait 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).
 
enum Cache_Type

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;
 
 
struct Cache_CACHE

Runtime representation of the Cache registers

C synopsis target-domain
typedef struct Cache_CACHE {
    UInt32 L1_INFO;
    UInt32 L1_CONFIG;
    UInt32 L1_INT;
    UInt32 L1_OCP;
    UInt32 L1_MAINT;
    Ptr L1_MTSTART;
    Ptr L1_MTEND;
    Ptr L1_CTADDR;
    UInt32 L1_CTDATA;
    UInt32 Reserved[0x77];
    UInt32 L2_INFO;
    UInt32 L2_CONFIG;
    UInt32 L2_INT;
    UInt32 L2_OCP;
    UInt32 L2_MAINT;
    Ptr L2_MTSTART;
    Ptr L2_MTEND;
    Ptr L2_CTADDR;
    UInt32 L2_CTDATA;
} Cache_CACHE;
 
 
struct Cache_OCPConfig

OCP Interface Configuration Register Settings

C synopsis target-domain
typedef struct Cache_OCPConfig {
    UInt8 wrap;
    UInt8 wrbuffer;
    UInt8 prefetch;
    UInt8 cleanbuf;
} Cache_OCPConfig;
 
 
struct Cache_SecurityConfig

CONFIG Configuration Register Settings

C synopsis target-domain
typedef struct Cache_SecurityConfig {
    UInt8 secure;
    UInt8 nbypass;
    UInt8 secint;
    UInt8 secport;
    UInt8 secmain;
} Cache_SecurityConfig;
 
 
config Cache_E_exception  // module-wide

Error raised when a Cache interrupt occurs Reason bits are contents of Cache Interrupt Register

C synopsis target-domain
extern const Error_Id Cache_E_exception;
 
 
config Cache_configureCache  // module-wide

Configure cache at startup?

C synopsis target-domain
extern const Bool Cache_configureCache;
 
DETAILS
It is possible to configure the Cache at startup and not enable it. However, it is not possible to enable the Cache at startup without configuring it.
Enabling the Cache will automatically enable configuring the Cache.
 
config Cache_enableCache  // module-wide

Enable cache at startup?

C synopsis target-domain
extern const Bool Cache_enableCache;
 
DETAILS
Enabling the Cache at startup will force configuring the Cache at startup.
 
config Cache_maxLineModeBufSize  // module-wide

Maximum buffer size to use discrete cache line operations with

C synopsis target-domain
extern const SizeT Cache_maxLineModeBufSize;
 
DETAILS
For buffers below a certain size, cache maintenance operations are more efficient if performed on single cache lines at a time rather than on an entire region.
For buffer sizes equal to or less than this setting, the inv, wb, and wbInv APIs will use a series of individual cache line operations. For buffer sizes large than this setting, a a single block mode operation will be performed.
For M3 cores, the default setting is 1024 bytes. For 64T cores, the default setting is 4096 bytes.
 
extern Cache_cache

This device's unicache register set address. Initialized internally according to build target/device

C synopsis target-domain
Cache_CACHE Cache_cache; // linked as extern ti_sysbios_hal_unicache_Cache_cache
 
 
Cache_disable()  // module-wide

Disables the 'type' cache(s)

C synopsis target-domain
Void Cache_disable(Bits16 type);
 
ARGUMENTS
type — bit mask of Cache type
 
Cache_enable()  // module-wide

Enables all cache(s)

C synopsis target-domain
Void Cache_enable(Bits16 type);
 
ARGUMENTS
type — bit mask of Cache type
 
Cache_inv()  // module-wide

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_invAll()  // module-wide

Invalidate all caches

C synopsis target-domain
Void Cache_invAll();
 
DETAILS
Perform a global invalidate. All cache lines are invalidated in L1 and L2 caches. Waits for completion.
 
Cache_lock()  // module-wide

Locks a memory block into the cache

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

Loads a memory block into the cache

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

Loads and locks a memory block into the cache

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

Read a block of memory from the cache. Only whole numbers of 32 bit words are transferred. byteCnt is divided by 4 to convert to number of words

C synopsis target-domain
Void Cache_read(Ptr blockPtr, SizeT byteCnt, Bits16 type, Ptr destBuf);
 
ARGUMENTS
blockPtr — start address of range to be loaded
byteCnt — number of bytes to be loaded
type — bit mask of Cache type
destBuf — address of destination buffer
 
Cache_unlock()  // module-wide

Unlocks a cached memory block

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

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

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

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.
Perform a global write back. All cache lines are left valid in L1 and L2 caches and the data in L1 cache is written back to L2 or external. All cache lines are left valid in L2 cache and the data in L2 cache is written back to external. Waits for completion.
 
Cache_wbInv()  // module-wide

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

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.
Perform a global write back. Then perform a global invalidate. All cache lines are invalidated in L1 and L2 caches. Waits for completion.
Module-Wide Built-Ins

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/hal/unicache/Cache.xdc
var Cache = xdc.useModule('ti.sysbios.hal.unicache.Cache');
module-wide constants & types
        const Cache.Type_L1D// Level 1 Data cache;
        const Cache.Type_L1// Level 1 caches;
        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;
 
        obj.L1_INFO = UInt32  ...
        obj.L1_CONFIG = UInt32  ...
        obj.L1_INT = UInt32  ...
        obj.L1_OCP = UInt32  ...
        obj.L1_MAINT = UInt32  ...
        obj.L1_MTSTART = Ptr  ...
        obj.L1_MTEND = Ptr  ...
        obj.L1_CTADDR = Ptr  ...
        obj.L1_CTDATA = UInt32  ...
        obj.Reserved = UInt32[0x77]  ...
        obj.L2_INFO = UInt32  ...
        obj.L2_CONFIG = UInt32  ...
        obj.L2_INT = UInt32  ...
        obj.L2_OCP = UInt32  ...
        obj.L2_MAINT = UInt32  ...
        obj.L2_MTSTART = Ptr  ...
        obj.L2_MTEND = Ptr  ...
        obj.L2_CTADDR = Ptr  ...
        obj.L2_CTDATA = UInt32  ...
 
        obj.wrap = UInt8  ...
        obj.wrbuffer = UInt8  ...
        obj.prefetch = UInt8  ...
        obj.cleanbuf = UInt8  ...
 
        obj.secure = UInt8  ...
        obj.nbypass = UInt8  ...
        obj.secint = UInt8  ...
        obj.secport = UInt8  ...
        obj.secmain = UInt8  ...
module-wide config parameters
        msg: "E_exception: L%d reason: 0x%x"
    };
 
        secure: 0,
        nbypass: 0,
        secint: 1,
        secport: 1,
        secmain: 1
    };
        secure: 0,
        nbypass: 0,
        secint: 1,
        secport: 1,
        secmain: 1
    };
        wrap: 0,
        wrbuffer: 0,
        prefetch: 0
    };
        wrap: 0,
        wrbuffer: 0,
        prefetch: 0,
        cleanbuf: 0
    };
 
 
enum Cache.Type

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
 
struct Cache.CACHE

Runtime representation of the Cache registers

Configuration settings
var obj = new Cache.CACHE;
 
    obj.L1_INFO = UInt32  ...
    obj.L1_CONFIG = UInt32  ...
    obj.L1_INT = UInt32  ...
    obj.L1_OCP = UInt32  ...
    obj.L1_MAINT = UInt32  ...
    obj.L1_MTSTART = Ptr  ...
    obj.L1_MTEND = Ptr  ...
    obj.L1_CTADDR = Ptr  ...
    obj.L1_CTDATA = UInt32  ...
    obj.Reserved = UInt32[0x77]  ...
    obj.L2_INFO = UInt32  ...
    obj.L2_CONFIG = UInt32  ...
    obj.L2_INT = UInt32  ...
    obj.L2_OCP = UInt32  ...
    obj.L2_MAINT = UInt32  ...
    obj.L2_MTSTART = Ptr  ...
    obj.L2_MTEND = Ptr  ...
    obj.L2_CTADDR = Ptr  ...
    obj.L2_CTDATA = UInt32  ...
 
C SYNOPSIS
 
struct Cache.OCPConfig

OCP Interface Configuration Register Settings

Configuration settings
var obj = new Cache.OCPConfig;
 
    obj.wrap = UInt8  ...
    obj.wrbuffer = UInt8  ...
    obj.prefetch = UInt8  ...
    obj.cleanbuf = UInt8  ...
 
C SYNOPSIS
 
struct Cache.SecurityConfig

CONFIG Configuration Register Settings

Configuration settings
var obj = new Cache.SecurityConfig;
 
    obj.secure = UInt8  ...
    obj.nbypass = UInt8  ...
    obj.secint = UInt8  ...
    obj.secport = UInt8  ...
    obj.secmain = UInt8  ...
 
C SYNOPSIS
 
config Cache.E_exception  // module-wide

Error raised when a Cache interrupt occurs Reason bits are contents of Cache Interrupt Register

Configuration settings
Cache.E_exception = Error.Desc {
    msg: "E_exception: L%d reason: 0x%x"
};
 
C SYNOPSIS
 
config Cache.configureCache  // module-wide

Configure cache at startup?

Configuration settings
Cache.configureCache = Bool false;
 
DETAILS
It is possible to configure the Cache at startup and not enable it. However, it is not possible to enable the Cache at startup without configuring it.
Enabling the Cache will automatically enable configuring the Cache.
C SYNOPSIS
 
config Cache.enableCache  // module-wide

Enable cache at startup?

Configuration settings
Cache.enableCache = Bool false;
 
DETAILS
Enabling the Cache at startup will force configuring the Cache at startup.
C SYNOPSIS
 
config Cache.maxLineModeBufSize  // module-wide

Maximum buffer size to use discrete cache line operations with

Configuration settings
Cache.maxLineModeBufSize = SizeT undefined;
 
DETAILS
For buffers below a certain size, cache maintenance operations are more efficient if performed on single cache lines at a time rather than on an entire region.
For buffer sizes equal to or less than this setting, the inv, wb, and wbInv APIs will use a series of individual cache line operations. For buffer sizes large than this setting, a a single block mode operation will be performed.
For M3 cores, the default setting is 1024 bytes. For 64T cores, the default setting is 4096 bytes.
C SYNOPSIS
 
metaonly config Cache.common$  // module-wide

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.
 
metaonly config Cache.configL1  // module-wide

L1_CONFIG register settings

Configuration settings
Cache.configL1 = Cache.SecurityConfig {
    secure: 0,
    nbypass: 0,
    secint: 1,
    secport: 1,
    secmain: 1
};
 
 
metaonly config Cache.configL2  // module-wide

L2_CONFIG register settings

Configuration settings
Cache.configL2 = Cache.SecurityConfig {
    secure: 0,
    nbypass: 0,
    secint: 1,
    secport: 1,
    secmain: 1
};
 
 
metaonly config Cache.l1InterruptHandler  // module-wide

L1 Interrupt Handler. Default is set to an internal L1 interrupt handler

Configuration settings
Cache.l1InterruptHandler = Void(*)(UArg) undefined;
 
 
metaonly config Cache.l1InterruptNumber  // module-wide

L1 Interrupt number. Default is device unique but can be set in the user config file

Configuration settings
Cache.l1InterruptNumber = UInt undefined;
 
 
metaonly config Cache.l1InterruptPriority  // module-wide

L1 Interrupt priority. Default is device unique but can be set in the user config file

Configuration settings
Cache.l1InterruptPriority = UInt undefined;
 
 
metaonly config Cache.l2InterruptHandler  // module-wide

L2 Interrupt Handler. Default is set to an internal L2 interrupt handler

Configuration settings
Cache.l2InterruptHandler = Void(*)(UArg) undefined;
 
 
metaonly config Cache.l2InterruptNumber  // module-wide

L2 Interrupt number. Default is device unique but can be set in the user config file

Configuration settings
Cache.l2InterruptNumber = UInt undefined;
 
 
metaonly config Cache.l2InterruptPriority  // module-wide

L2 Interrupt priority. Default is device unique but can be set in the user config file

Configuration settings
Cache.l2InterruptPriority = UInt undefined;
 
 
metaonly config Cache.ocpL1  // module-wide

L1_OCP register settings

Configuration settings
Cache.ocpL1 = Cache.OCPConfig {
    wrap: 0,
    wrbuffer: 0,
    prefetch: 0
};
 
 
metaonly config Cache.ocpL2  // module-wide

L2_OCP register settings

Configuration settings
Cache.ocpL2 = Cache.OCPConfig {
    wrap: 0,
    wrbuffer: 0,
    prefetch: 0,
    cleanbuf: 0
};
 
generated on Thu, 25 May 2017 22:09:08 GMT