# 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_Bank`

    Values to distinguish which bank. These values can be passed to DCSM_getZone1FlashEXEStatus(), DCSM_getZone2FlashEXEStatus(), DCSM_getFlashSectorZone(), DCSM_getZone1LinkPointerError(), DCSM_getZone2LinkPointerError().

    Values:

    enumerator `DCSM_BANK0`

      Bank 0.

    enumerator `DCSM_BANK1`

      Bank 1.

  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` = 0

      RAMLS0.

    enumerator `DCSM_RAMLS1` = 1

      RAMLS1.

    enumerator `DCSM_RAMLS2` = 2

      RAMLS2.

    enumerator `DCSM_RAMLS3` = 3

      RAMLS3.

    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.

    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.

  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_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`(DCSM_Bank bank)

    Read Zone 1 Link Pointer Error

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

    Parameters

      - `bank`: is the DCSM_Bank to operate on.

    Return

      Returns the value of the Zone 1 Link Pointer error.

  uint32_t `DCSM_getZone2LinkPointerError`(DCSM_Bank bank)

    Read Zone 2 Link Pointer Error

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

    Parameters

      - `bank`: is the DCSM_Bank to operate on.

    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.

    Note

      This function should not be called in an actual application, should only be used for debugging/development. 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.

  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.

    Note

      This function should not be called in an actual application, should only be used for debugging/development. Ensure flash data cache is disabled before calling this function(Flash_disableCache).

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

    Parameters

      - `module`: is the RAM module value. Valid values are type DCSM_RAMModule

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