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 0x08U¶: Z1 CSMPSWD0 offset.

DCSM_O_Z1_CSMPSWD1 0x0AU¶: Z1 CSMPSWD1 offset.

DCSM_O_Z1_CSMPSWD2 0x0CU¶: Z1 CSMPSWD2 offset.

DCSM_O_Z1_CSMPSWD3 0x0EU¶: Z1 CSMPSWD3 offset.

DCSM_O_Z2_CSMPSWD0 0x08U¶: Z2 CSMPSWD0 offset.

DCSM_O_Z2_CSMPSWD1 0x0AU¶: Z2 CSMPSWD1 offset.

DCSM_O_Z2_CSMPSWD2 0x0CU¶: Z2 CSMPSWD2 offset.

DCSM_O_Z2_CSMPSWD3 0x0EU¶: Z2 CSMPSWD3 offset.

FLSEM_KEY 0xA5U¶: Zone semaphore key.

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.

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_RAMLS4 = 4¶: RAMLS4.

enumerator DCSM_RAMLS5 = 5¶: RAMLS5.

enumerator DCSM_RAMLS6 = 6¶: RAMLS6.

enumerator DCSM_RAMLS7 = 7¶: RAMLS7.

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.

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
- 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.

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.

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.

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.

Parameters

module: is the RAM module value. Valid values are type DCSM_RAMModule
- 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.

Parameters

module: is the RAM module value. Valid values are type DCSM_RAMModule
- 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 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.

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.