DCSM Module¶

The DCSM driver accesses the DCSM COMMON registers. In order to configure the Dual Code Security Module, the user must program the Linkpointer in DCSM OTP as well as the security configuration registers of the Zone Select Blocks in DCSM OTP. The DCSM driver provides functions which secure and unsecure each zone and return the ownership, security status, EXEONLY status of specific RAM modules or Flash sectors. Included are two functions which can claim and release the Flash pump to operate on a specific zone.

group dcsm_api

Defines

DCSM_O_Z1_CSMPSWD0 0x00U¶: Z1 CSMPSWD0 offset.

DCSM_O_Z1_CSMPSWD1 0x02U¶: Z1 CSMPSWD1 offset.

DCSM_O_Z1_CSMPSWD2 0x04U¶: Z1 CSMPSWD2 offset.

DCSM_O_Z1_CSMPSWD3 0x06U¶: Z1 CSMPSWD3 offset.

DCSM_O_Z2_CSMPSWD0 0x00U¶: Z2 CSMPSWD0 offset.

DCSM_O_Z2_CSMPSWD1 0x02U¶: Z2 CSMPSWD1 offset.

DCSM_O_Z2_CSMPSWD2 0x04U¶: Z2 CSMPSWD2 offset.

DCSM_O_Z2_CSMPSWD3 0x06U¶: Z2 CSMPSWD3 offset.

FLSEM_KEY 0xA5U¶: Zone semaphore key.

DCSM_FORCE_SECERR_KEY 0x5A5AU¶

DCSM_ALLZERO 0x08U¶: CSM Passwords all zeros.

DCSM_ALLONE 0x10U¶: CSM Passwords all ones.

DCSM_UNSECURE 0x20U¶: Zone is secure/unsecure.

DCSM_ARMED 0x40U¶: CSM is armed.

DCSM_EXEONLYSECTR_M 0x0000FFFFU¶

DCSM_EXEONLYSECTR_S 16U¶

DCSM_ZX_CR_S 16U¶

DCSM_Z1_OTPSECLOCK_JTAGLOCK_M 0x1U¶

DCSM_Z1_OTPSECLOCK_JTAGLOCK_S 0U¶

DCSM_OTPSECLOCK_INVALID 0xFFFFU¶

Enums

enum DCSM_MemoryStatus¶

Values to distinguish the status of RAM or FLASH sectors. These values describe which zone the memory location belongs too. These values can be returned from DCSM_getRAMZone(), DCSM_getFlashSectorZone().

Values:

enumerator DCSM_MEMORY_INACCESSIBLE¶: Inaccessible.

enumerator DCSM_MEMORY_ZONE1¶: Zone 1.

enumerator DCSM_MEMORY_ZONE2¶: Zone 2.

enumerator DCSM_MEMORY_FULL_ACCESS¶: Full access.

enum DCSM_SemaphoreZone¶

Values to pass to DCSM_claimZoneSemaphore(). These values are used to describe the zone that can write to Flash Wrapper registers.

Values:

enumerator DCSM_FLSEM_ZONE1 = 0x01U¶: Flash semaphore Zone 1.

enumerator DCSM_FLSEM_ZONE2 = 0x02U¶: Flash semaphore Zone 2.

enum DCSM_SecurityStatus¶

Values to distinguish the security status of the zones. These values can be returned from DCSM_getZone1CSMSecurityStatus(), DCSM_getZone2CSMSecurityStatus().

Values:

enumerator DCSM_STATUS_SECURE¶: Secure.

enumerator DCSM_STATUS_UNSECURE¶: Unsecure.

enumerator DCSM_STATUS_LOCKED¶: Locked.

enumerator DCSM_STATUS_BLOCKED¶: Blocked.

enum DCSM_EXEOnlyStatus¶

Values to decribe the EXEONLY Status. These values are returned from to DCSM_getZone1RAMEXEStatus(), DCSM_getZone2RAMEXEStatus(), DCSM_getZone1FlashEXEStatus(), DCSM_getZone2FlashEXEStatus().

Values:

enumerator DCSM_PROTECTED¶: Protected.

enumerator DCSM_UNPROTECTED¶: Unprotected.

enumerator DCSM_INCORRECT_ZONE¶: Incorrect Zone.

enum DCSM_RAMModule¶

Values to distinguish RAM Module. These values can be passed to DCSM_getZone1RAMEXEStatus() DCSM_getZone2RAMEXEStatus(), DCSM_getRAMZone().

Values:

enumerator DCSM_RAMLS0¶: RAMLS0.

enumerator DCSM_RAMLS1¶: RAMLS1.

enumerator DCSM_RAMLS2¶: RAMLS2.

enumerator DCSM_RAMLS3¶: RAMLS3.

enumerator DCSM_RAMLS4¶: RAMLS4.

enumerator DCSM_RAMLS5¶: RAMLS5.

enumerator DCSM_RAMLS6¶: RAMLS6.

enumerator DCSM_RAMLS7¶: RAMLS7.

enumerator DCSM_CLA = 14U¶: Offset of CLA field in in RAMSTAT divided by two.

enum DCSM_Sector¶

Values to distinguish Flash Sector. These values can be passed to DCSM_getZone1FlashEXEStatus() DCSM_getZone2FlashEXEStatus(), DCSM_getFlashSectorZone().

Values:

enumerator DCSM_BANK0_SECTOR0¶: Bank 0 - Sector 0.

enumerator DCSM_BANK0_SECTOR1¶: Bank 0 - Sector 1.

enumerator DCSM_BANK0_SECTOR2¶: Bank 0 - Sector 2.

enumerator DCSM_BANK0_SECTOR3¶: Bank 0 - Sector 3.

enumerator DCSM_BANK0_SECTOR4¶: Bank 0 - Sector 4.

enumerator DCSM_BANK0_SECTOR5¶: Bank 0 - Sector 5.

enumerator DCSM_BANK0_SECTOR6¶: Bank 0 - Sector 6.

enumerator DCSM_BANK0_SECTOR7¶: Bank 0 - Sector 7.

enumerator DCSM_BANK0_SECTOR8¶: Bank 0 - Sector 8.

enumerator DCSM_BANK0_SECTOR9¶: Bank 0 - Sector 9.

enumerator DCSM_BANK0_SECTOR10¶: Bank 0 - Sector 10.

enumerator DCSM_BANK0_SECTOR11¶: Bank 0 - Sector 11.

enumerator DCSM_BANK0_SECTOR12¶: Bank 0 - Sector 12.

enumerator DCSM_BANK0_SECTOR13¶: Bank 0 - Sector 13.

enumerator DCSM_BANK0_SECTOR14¶: Bank 0 - Sector 14.

enumerator DCSM_BANK0_SECTOR15¶: Bank 0 - Sector 15.

enumerator DCSM_BANK1_SECTOR0¶: Bank 1 - Sector 0.

enumerator DCSM_BANK1_SECTOR1¶: Bank 1 - Sector 1.

enumerator DCSM_BANK1_SECTOR2¶: Bank 1 - Sector 2.

enumerator DCSM_BANK1_SECTOR3¶: Bank 1 - Sector 3.

enumerator DCSM_BANK1_SECTOR4¶: Bank 1 - Sector 4.

enumerator DCSM_BANK1_SECTOR5¶: Bank 1 - Sector 5.

enumerator DCSM_BANK1_SECTOR6¶: Bank 1 - Sector 6.

enumerator DCSM_BANK1_SECTOR7¶: Bank 1 - Sector 7.

enumerator DCSM_BANK1_SECTOR8¶: Bank 1 - Sector 8.

enumerator DCSM_BANK1_SECTOR9¶: Bank 1 - Sector 9.

enumerator DCSM_BANK1_SECTOR10¶: Bank 1 - Sector 10.

enumerator DCSM_BANK1_SECTOR11¶: Bank 1 - Sector 11.

enumerator DCSM_BANK1_SECTOR12¶: Bank 1 - Sector 12.

enumerator DCSM_BANK1_SECTOR13¶: Bank 1 - Sector 13.

enumerator DCSM_BANK1_SECTOR14¶: Bank 1 - Sector 14.

enumerator DCSM_BANK1_SECTOR15¶: Bank 1 - Sector 15.

enumerator DCSM_BANK2_SECTOR0¶: Bank 2 - Sector 0.

enumerator DCSM_BANK2_SECTOR1¶: Bank 2 - Sector 1.

enumerator DCSM_BANK2_SECTOR2¶: Bank 2 - Sector 2.

enumerator DCSM_BANK2_SECTOR3¶: Bank 2 - Sector 3.

enumerator DCSM_BANK2_SECTOR4¶: Bank 2 - Sector 4.

enumerator DCSM_BANK2_SECTOR5¶: Bank 2 - Sector 5.

enumerator DCSM_BANK2_SECTOR6¶: Bank 2 - Sector 6.

enumerator DCSM_BANK2_SECTOR7¶: Bank 2 - Sector 7.

enumerator DCSM_BANK2_SECTOR8¶: Bank 2 - Sector 8.

enumerator DCSM_BANK2_SECTOR9¶: Bank 2 - Sector 9.

enumerator DCSM_BANK2_SECTOR10¶: Bank 2 - Sector 10.

enumerator DCSM_BANK2_SECTOR11¶: Bank 2 - Sector 11.

enumerator DCSM_BANK2_SECTOR12¶: Bank 2 - Sector 12.

enumerator DCSM_BANK2_SECTOR13¶: Bank 2 - Sector 13.

enumerator DCSM_BANK2_SECTOR14¶: Bank 2 - Sector 14.

enumerator DCSM_BANK2_SECTOR15¶: Bank 2 - Sector 15.

enum DCSM_OTPLock¶

The following are values that can be passed to DCSM_getRAMZone(), DCSM_getZone2FlashEXEStatus() ,DCSM_getZone1FlashEXEStatus() & DCSM_getFlashSectorZone() as cpuInst parameter. The following are values that can be passed to DCSM_getZone1OTPSecureLockStatus() & DCSM_getZone2OTPSecureLockStatus() as lockType parameter.

Values:

enumerator DCSM_OTPSECLOCK_JTAG = 0x0U¶: JTAG Lock Status.

enumerator DCSM_OTPSECLOCK_PSWDLOCK = 0x1U¶: Zone Password Lock.

enumerator DCSM_OTPSECLOCK_CRCLOCK = 0x2U¶: Zone CRC Lock.

Functions

void DCSM_secureZone1(void)¶

Secures zone 1 by setting the FORCESEC bit of Z1_CR register

This function resets the state of the zone. If the zone is unlocked, it will lock(secure) the zone and also reset all the bits in the Control Register.

Return: None.

void DCSM_secureZone2(void)¶

Secures zone 2 by setting the FORCESEC bit of Z2_CR register

This function resets the state of the zone. If the zone is unlocked, it will lock(secure) the zone and also reset all the bits in the Control Register.

Return: None.

DCSM_SecurityStatus DCSM_getZone1CSMSecurityStatus(void)¶

Returns the CSM security status of zone 1

This function returns the security status of zone 1 CSM

Return: Returns security status as an enumerated type DCSM_SecurityStatus.

DCSM_SecurityStatus DCSM_getZone2CSMSecurityStatus(void)¶

Returns the CSM security status of zone 2

This function returns the security status of zone 2 CSM

Return: Returns security status as an enumerated type DCSM_SecurityStatus.

uint16_t DCSM_getZone1ControlStatus(void)¶

Returns the Control Status of zone 1

This function returns the Control Status of zone 1 CSM

Return: Returns the contents of the Control Register which can be used with provided defines.

uint16_t DCSM_getZone2ControlStatus(void)¶

Returns the Control Status of zone 2

This function returns the Control Status of zone 2 CSM

Return: Returns the contents of the Control Register which can be used with the provided defines.

DCSM_MemoryStatus DCSM_getRAMZone(DCSM_RAMModule module)¶

Returns the security zone a RAM section belongs to

This function returns the security zone a RAM section belongs to.

Parameters

module: is the RAM module value. Valid values are type DCSM_RAMModule C28x RAMs :
- DCSM_RAMLS0
- DCSM_RAMLS1
- DCSM_RAMLS2
- DCSM_RAMLS3
- DCSM_RAMLS4
- DCSM_RAMLS5
- DCSM_RAMLS6
- DCSM_RAMLS7

Return: Returns DCSM_MEMORY_INACCESSIBLE if the section is inaccessible, DCSM_MEMORY_ZONE1 if the section belongs to zone 1, DCSM_MEMORY_ZONE2 if the section belongs to zone 2 and DCSM_MEMORY_FULL_ACCESS if the section doesn’t belong to any zone (or if the section is unsecure).

DCSM_MemoryStatus DCSM_getFlashSectorZone(DCSM_Sector sector)¶

Returns the security zone a flash sector belongs to

This function returns the security zone a flash sector belongs to.

Parameters

sector: is the flash sector value. Use DCSM_Sector type.

Return: Returns DCSM_MEMORY_INACCESSIBLE if the section is inaccessible , DCSM_MEMORY_ZONE1 if the section belongs to zone 1, DCSM_MEMORY_ZONE2 if the section belongs to zone 2 and DCSM_MEMORY_FULL_ACCESS if the section doesn’t belong to any zone (or if the section is unsecure)..

uint32_t DCSM_getZone1LinkPointerError(void)¶

Read Zone 1 Link Pointer Error

A non-zero value indicates an error on the bit position that is set to 1.

Return: Returns the value of the Zone 1 Link Pointer error.

uint32_t DCSM_getZone2LinkPointerError(void)¶

Read Zone 2 Link Pointer Error

A non-zero value indicates an error on the bit position that is set to 1.

Return: Returns the value of the Zone 2 Link Pointer error.

bool DCSM_getFlashErrorStatus(void)¶

Get the status of the security configuration load from USER-OTP or sector error status

Return: Returns 0 if no error in loading security information from USER-OTP, 1 if an error has occurred in the load from USER-OTP.

void DCSM_clearFlashErrorStatus(void)¶

Clear the Flash Error Status bit

Write a ‘1’ to the clear bit to clear the sector error status bit.

Return: None.

void DCSM_forceFlashErrorStatus(void)¶

Set the force Flash Error Status bit

Write a ‘1’ to force bit to set the sector error status bit.

Return: None.

uint32_t DCSM_getZone1OTPSecureLockStatus(DCSM_OTPLock lockType)¶

Returns the OTP secure Lock status of zone 1

The

lockType parameter can have one of the following values of the DCSM_CPUSel type:

DCSM_OTPSECLOCK_JTAG - JTAG Lock Status
DCSM_OTPSECLOCK_CRCLOCK - Zone CRC Lock
DCSM_OTPSECLOCK_PSWDLOCK - Zone Password Lock

Parameters

lockType: is the OTP secure Lock feature type .

This function takes in a valid OTP secure Lock feature type and returns the status of zone 1 lock feature

For Zone Password Lock : 1111 - CSM Pwd locations in the OTP are not protected and can be read from the debugger as well as code running from anywhere. Other Value : CSM Pwd locations in the OTP are protected and can’t be read without unlocking CSM of that zone.

Return: Returns security lock status can be: For JTAG lock : 0 - JTAG is not locked , 1 - JTAG is locked

For Zone CRC Lock : 1111 : VCU has ability to calculate CRC on secure memories. Other Value : VCU doesn’t have the ability to calculate CRC on secure memories.

uint32_t DCSM_getZone2OTPSecureLockStatus(DCSM_OTPLock lockType)¶

Returns the OTP secure Lock status of zone 2

The

lockType parameter can have one of the following values of the DCSM_CPUSel type:

DCSM_OTPSECLOCK_CRCLOCK - Zone CRC Lock
DCSM_OTPSECLOCK_PSWDLOCK - Zone Password Lock

Parameters

lockType: is the OTP secure Lock feature type .

This function takes in a valid OTP secure Lock feature type and returns the status of zone 2 lock feature

For Zone Password Lock : 1111 - CSM Pwd locations in the OTP are not protected and can be read from the debugger as well as code running from anywhere. Other Value : CSM Pwd locations in the OTP are protected and can’t be read without unlocking CSM of that zone.

Return: Returns security lock status can be:

For Zone CRC Lock : 1111 : VCU has ability to calculate CRC on secure memories. Other Value : VCU doesn’t have the ability to calculate CRC on secure memories.

void DCSM_unlockZone1CSM(const DCSM_CSMPasswordKey *const psCMDKey)¶

Unlocks Zone 1 CSM.

This function unlocks the CSM password. It first reads the four password locations in the User OTP. If any of the password values is different from 0xFFFFFFFF, it unlocks the device by writing the provided passwords into CSM Key registers

Parameters

psCMDKey: is a pointer to the DCSM_CSMPasswordKey struct that has the CSM password for zone 1.

Return: None.
Note: This function should not be called in an actual application, should only be used for once to program the OTP memory. Ensure flash data cache is disabled before calling this function(Flash_disableCache).

void DCSM_unlockZone2CSM(const DCSM_CSMPasswordKey *const psCMDKey)¶

Unlocks Zone 2 CSM.

This function unlocks the CSM password. It first reads the four password locations in the User OTP. If any of the password values is different from 0xFFFFFFFF, it unlocks the device by writing the provided passwords into CSM Key registers

Parameters

psCMDKey: is a pointer to the CSMPSWDKEY that has the CSM password for zone 2.

Return: None.
Note: This function should not be called in an actual application, should only be used for once to program the OTP memory. Ensure flash data cache is disabled before calling this function(Flash_disableCache).

void DCSM_writeZone1CSM(const DCSM_CSMPasswordKey *const psCMDKey)¶

Write Zone 1 CSM.

Password match flow is essentially a sequence of dummy reads from password locations (PWL) followed by writes to CSMKEY registers. This function helps writing the provided passwords into the CSM Key registers. The

DCSM_readZone1CSMPwd() should be called by CPU1 before calling this API.

Parameters

psCMDKey: is a pointer to the CSMPSWDKEY that has the CSM password for zone 1.

Return: None.

void DCSM_writeZone2CSM(const DCSM_CSMPasswordKey *const psCMDKey)¶

Write Zone 2 CSM.

Password match flow is essentially a sequence of dummy reads from password locations (PWL) followed by writes to CSMKEY registers. This function helps writing the provided passwords into the CSM Key registers. The

DCSM_readZone2CSMPwd() should be called by CPU1 before calling this API.

Parameters

psCMDKey: is a pointer to the CSMPSWDKEY that has the CSM password for zone 2.

Return: None.

DCSM_EXEOnlyStatus DCSM_getZone1FlashEXEStatus(DCSM_Sector sector)¶

Returns the EXE-ONLY status of zone 1 for a flash sector

This function takes in a valid sector value and returns the status of EXE ONLY security protection for the sector.

Parameters

sector: is the flash sector value. Use DCSM_Sector type.

Return: Returns DCSM_PROTECTED if the sector is EXE-ONLY protected, DCSM_UNPROTECTED if the sector is not EXE-ONLY protected, DCSM_INCORRECT_ZONE if sector does not belong to this zone.

DCSM_EXEOnlyStatus DCSM_getZone1RAMEXEStatus(DCSM_RAMModule module)¶

Returns the EXE-ONLY status of zone 1 for a RAM module

This function takes in a valid module value and returns the status of EXE ONLY security protection for that module. DCSM_CLA is an invalid module value. There is no EXE-ONLY available for DCSM_CLA.

Parameters

module: is the RAM module value. Valid values are type DCSM_RAMModule C28x RAMs :
- DCSM_RAMLS0
- DCSM_RAMLS1
- DCSM_RAMLS2
- DCSM_RAMLS3
- DCSM_RAMLS4
- DCSM_RAMLS5
- DCSM_RAMLS6
- DCSM_RAMLS7

Return: Returns DCSM_PROTECTED if the module is EXE-ONLY protected, DCSM_UNPROTECTED if the module is not EXE-ONLY protected, DCSM_INCORRECT_ZONE if module does not belong to this zone.

DCSM_EXEOnlyStatus DCSM_getZone2FlashEXEStatus(DCSM_Sector sector)¶

Returns the EXE-ONLY status of zone 2 for a flash sector

This function takes in a valid sector value and returns the status of EXE ONLY security protection for the sector.

Parameters

sector: is the flash sector value. Use DCSM_Sector type.

Return: Returns DCSM_PROTECTED if the sector is EXE-ONLY protected, DCSM_UNPROTECTED if the sector is not EXE-ONLY protected, DCSM_INCORRECT_ZONE if sector does not belong to this zone.

DCSM_EXEOnlyStatus DCSM_getZone2RAMEXEStatus(DCSM_RAMModule module)¶

Returns the EXE-ONLY status of zone 2 for a RAM module

This function takes in a valid module value and returns the status of EXE ONLY security protection for that module. DCSM_CLA is an invalid module value. There is no EXE-ONLY available for DCSM_CLA.

Parameters

module: is the RAM module value. Valid values are type DCSM_RAMModule C28x RAMs :
- DCSM_RAMLS0
- DCSM_RAMLS1
- DCSM_RAMLS2
- DCSM_RAMLS3
- DCSM_RAMLS4
- DCSM_RAMLS5
- DCSM_RAMLS6
- DCSM_RAMLS7

Return: Returns DCSM_PROTECTED if the module is EXE-ONLY protected, DCSM_UNPROTECTED if the module is not EXE-ONLY protected, DCSM_INCORRECT_ZONE if module does not belong to this zone.

bool DCSM_claimZoneSemaphore(DCSM_SemaphoreZone zone)¶

Claims the zone semaphore which allows access to the Flash Wrapper register for that zone.

Return

Returns true for a successful semaphore capture, false if it was unable to capture the semaphore.

Parameters

zone: is the zone which is trying to claim the semaphore which allows access to the Flash Wrapper registers.

bool DCSM_releaseZoneSemaphore(void)¶

Releases the zone semaphore.

Return: Returns true if it was successful in releasing the zone semaphore and false if it was unsuccessful in releasing the zone semaphore.
Note: If the calling function is not in the right zone to be able to access this register, it will return a false.

void DCSM_readZone1CSMPwd(void)¶

Perform dummy reads on the 128-bit Zone 1 CSM password.

This function reads the four password locations in the User OTP needed to be done as part of the Password Match Flow before writes to the CSMKEY registers. This would need to be done before a DCSM_writeZone1CSM().

Return: None.
Note: This API to be called from CPU1.

void DCSM_readZone2CSMPwd(void)¶

Perform dummy reads on the 128-bit Zone 2 CSM password.

This function reads the four password locations in the User OTP needed to be done as part of the Password Match Flow before writes to the CSMKEY registers. This would need to be done before a DCSM_writeZone2CSM().

Return: None.
Note: This API to be called from CPU1.

struct DCSM_CSMPasswordKey¶: #include <dcsm.h>
Data structures to hold password keys.

The code for this module is contained in driverlib/dcsm.c, with driverlib/dcsm.h containing the API declarations for use by applications.