# FLASH Module

The Flash driver provides functions to configure the fallback power modes and the active grace periods of flash banks and pump, and the pump wake-up time. This driver also provides functions to configure the flash wait-states, prefetch, cache and ECC features. It also provides functions to access the Flash ECC test mode registers and the Flash ECC error status registers.

group `flash_api`

  Defines

  `FLASH_FAIL_0_CLR` 0x1

    Fail-0 clear.

  `FLASH_FAIL_1_CLR` 0x2

    Fail-1 clear.

  `FLASH_UNC_ERR_CLR` 0x4

    Uncorrectable error Clear.

  `FLASH_NO_ERROR` 0x0

    No error.

  `FLASH_SINGLE_ERROR` 0x1

    Single bit error.

  `FLASH_UNC_ERROR` 0x2

    Uncorrectable error.

  `FLASH_DELAY_CONFIG` __asm(" RPT #7 || NOP")
  `FLASH_PUMP_KEY` 0x5A5A0000UL

    Pump semaphore key.

  Enums

  enum `Flash_BankNumber`

    Values that can be passed to Flash_setBankPowerMode() as the bank parameter.

    Values:

    enumerator `FLASH_BANK` = 0x0

      Bank.

  enum `Flash_PumpOwnership`

    Values that can be passed to Flash_claimPumpSemaphore() in order to claim the pump semaphore.

    Values:

    enumerator `FLASH_BANK0_WRAPPER` = 0x2

      Bank 0 Wrapper.

    enumerator `FLASH_BANK1_WRAPPER` = 0x1

      Bank 1 Wrapper.

  enum `Flash_BankPowerMode`

    Values that can be passed to Flash_setBankPowerMode() as the powerMode parameter.

    Values:

    enumerator `FLASH_BANK_PWR_SLEEP` = 0x0

      Sleep fallback mode.

    enumerator `FLASH_BANK_PWR_STANDBY` = 0x1

      Standby fallback mode.

    enumerator `FLASH_BANK_PWR_ACTIVE` = 0x3

      Active fallback mode.

  enum `Flash_PumpPowerMode`

    Values that can be passed to Flash_setPumpPowerMode() as the powerMode parameter.

    Values:

    enumerator `FLASH_PUMP_PWR_SLEEP` = 0x0

      Sleep fallback mode.

    enumerator `FLASH_PUMP_PWR_ACTIVE` = 0x1

      Active fallback mode.

  enum `Flash_ErrorStatus`

    Type that correspond to values returned from Flash_getLowErrorStatus() and Flash_getHighErrorStatus() determining the error status code.

    Values:

    enumerator `FLASH_NO_ERR` = 0x0

      No error.

    enumerator `FLASH_FAIL_0` = 0x1

      Fail on 0.

    enumerator `FLASH_FAIL_1` = 0x2

      Fail on 1.

    enumerator `FLASH_UNC_ERR` = 0x4

      Uncorrectable error.

  enum `Flash_ErrorType`

    Values that can be returned from Flash_getLowErrorType() and Flash_getHighErrorType() determining the error type.

    Values:

    enumerator `FLASH_DATA_ERR` = 0x0

      Data error.

    enumerator `FLASH_ECC_ERR` = 0x1

      ECC error.

  enum `Flash_SingleBitErrorIndicator`

    Values that can be returned from Flash_getECCTestSingleBitErrorType().

    Values:

    enumerator `FLASH_DATA_BITS` = 0x0

      Data bits.

    enumerator `FLASH_CHECK_BITS` = 0x1

      ECC bits.

  Functions

  void `Flash_setWaitstates`(uint32_t ctrlBase, uint16_t waitstates)

    Sets the random read wait state amount.

    This function sets the number of wait states for a flash read access. The

    waitstates parameter is a number between 0 and 15. It is important to look at your device’s datasheet for information about what the required minimum flash wait-state is for your selected SYSCLK frequency.
    Parameters

      - `ctrlBase`: is the base address of the flash wrapper control registers.

      - `waitstates`: is the wait-state value.

    By default the wait state amount is configured to the maximum 15.

    Return

      None.

  void `Flash_setBankPowerMode`(uint32_t ctrlBase, Flash_BankNumber bank, Flash_BankPowerMode powerMode)

    Sets the fallback power mode of a flash bank.

    This function sets the fallback power mode of the flash bank specified by them

    bank parameter. The power mode is specified by the powerMode parameter with one of the following values:
    Parameters

      - `ctrlBase`: is the base address of the flash wrapper registers.

      - `bank`: is the flash bank that is being configured.

      - `powerMode`: is the power mode to be entered.

    - FLASH_BANK_PWR_SLEEP - Sense amplifiers and sense reference disabled.

    - FLASH_BANK_PWR_STANDBY - Sense amplifiers disabled but sense reference enabled.

    - FLASH_BANK_PWR_ACTIVE - Sense amplifiers and sense reference enabled.

    Return

      None.

  void `Flash_setPumpPowerMode`(uint32_t ctrlBase, Flash_PumpPowerMode powerMode)

    Sets the fallback power mode of the charge pump.

    This function sets the fallback power mode flash charge pump.

    Parameters

      - `ctrlBase`: is the base address of the flash wrapper control registers.

      - `powerMode`: is the power mode to be entered.

    - FLASH_PUMP_PWR_SLEEP - All circuits disabled.

    - FLASH_PUMP_PWR_ACTIVE - All pump circuits active.

    Return

      None.

  void `Flash_enablePrefetch`(uint32_t ctrlBase)

    Enables prefetch mechanism.

    Return

      None.

    Parameters

      - `ctrlBase`: is the base address of the flash wrapper control registers.

  void `Flash_disablePrefetch`(uint32_t ctrlBase)

    Disables prefetch mechanism.

    Return

      None.

    Parameters

      - `ctrlBase`: is the base address of the flash wrapper control registers.

  void `Flash_enableCache`(uint32_t ctrlBase)

    Enables data cache.

    Return

      None.

    Parameters

      - `ctrlBase`: is the base address of the flash wrapper control registers.

  void `Flash_disableCache`(uint32_t ctrlBase)

    Disables data cache.

    Return

      None.

    Parameters

      - `ctrlBase`: is the base address of the flash wrapper control registers.

  void `Flash_enableECC`(uint32_t eccBase)

    Enables flash error correction code (ECC) protection.

    Return

      None.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

  void `Flash_disableECC`(uint32_t eccBase)

    Disables flash error correction code (ECC) protection.

    Return

      None.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

  void `Flash_setBankPowerUpDelay`(uint32_t ctrlBase, uint16_t delay)

    Sets the bank power up delay.

    This function sets the VREADST delay to ensure that the requisite delay is introduced for the flash pump/bank to come out of low-power mode, so that the flash/OTP is ready for CPU access.

    Parameters

      - `ctrlBase`: is the base address of the flash wrapper control registers.

      - `delay`: is the number of HCLK cycles.

    Note: Refer to TRM before configuring VREADST.

    Return

      None.

  void `Flash_setPumpWakeupTime`(uint32_t ctrlBase, uint16_t sysclkCycles)

    Sets the pump wake up time.

    This function sets the wakeup time with

    sysclkCycles parameter. The sysclkCycles is a value between 0 and 8190. When the charge pump exits sleep power mode, it will take sysclkCycles to wakeup.
    Parameters

      - `ctrlBase`: is the base address of the flash wrapper control registers.

      - `sysclkCycles`: is the number of SYSCLK cycles it takes for the pump to wakeup.

    Return

      None.

  bool `Flash_isBankReady`(uint32_t ctrlBase, Flash_BankNumber bank)

    Reads the bank active power state.

    Return

      Returns true if the Bank is in Active power state and false otherwise.

    Parameters

      - `ctrlBase`: is the base address of the flash wrapper control registers.

      - `bank`: is the flash bank that is being used.

  bool `Flash_isPumpReady`(uint32_t ctrlBase)

    Reads the pump active power state.

    Return

      Returns true if the Pump is in Active power state and false otherwise.

    Parameters

      - `ctrlBase`: is the base address of the flash wrapper control registers.

  uint32_t `Flash_getSingleBitErrorAddressLow`(uint32_t eccBase)

    Gets the single error address low.

    This function returns the 32-bit address of the single bit error that occurred in the lower 64-bits of a 128-bit memory-aligned data. The returned address is to that 64-bit aligned data.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

    Return

      Returns the 32 bits of a 64-bit aligned address where a single bit error occurred.

  uint32_t `Flash_getSingleBitErrorAddressHigh`(uint32_t eccBase)

    Gets the single error address high.

    This function returns the 32-bit address of the single bit error that occurred in the upper 64-bits of a 128-bit memory-aligned data. The returned address is to that 64-bit aligned data.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

    Return

      Returns the 32 bits of a 64-bit aligned address where a single bit error occurred.

  uint32_t `Flash_getUncorrectableErrorAddressLow`(uint32_t eccBase)

    Gets the uncorrectable error address low.

    This function returns the 32-bit address of the uncorrectable error that occurred in the lower 64-bits of a 128-bit memory-aligned data. The returned address is to that 64-bit aligned data.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

    Return

      Returns the 32 bits of a 64-bit aligned address where an uncorrectable error occurred.

  uint32_t `Flash_getUncorrectableErrorAddressHigh`(uint32_t eccBase)

    Gets the uncorrectable error address high.

    This function returns the 32-bit address of the uncorrectable error that occurred in the upper 64-bits of a 128-bit memory-aligned data. The returned address is to that 64-bit aligned data.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC base.

    Return

      Returns the 32 bits of a 64-bit aligned address where an uncorrectable error occurred.

  Flash_ErrorStatus `Flash_getLowErrorStatus`(uint32_t eccBase)

    Gets the error status of the Lower 64-bits.

    This function returns the error status of the lower 64-bits of a 128-bit aligned address.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

    Return

      Returns value of the low error status bits which can be used with Flash_ErrorStatus type.

  Flash_ErrorStatus `Flash_getHighErrorStatus`(uint32_t eccBase)

    Gets the error status of the Upper 64-bits.

    This function returns the error status of the upper 64-bits of a 128-bit aligned address.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

    Return

      Returns value of the high error status bits which can be used with Flash_ErrorStatus type.

  uint32_t `Flash_getLowErrorPosition`(uint32_t eccBase)

    Gets the error position of the lower 64-bits for a single bit error.

    This function returns the error position of the lower 64-bits. If the error type is FLASH_ECC_ERR, the position ranges from 0-7 else it ranges from 0-63 for FLASH_DATA_ERR.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

    Return

      Returns the position of the lower error bit.

  uint32_t `Flash_getHighErrorPosition`(uint32_t eccBase)

    Gets the error position of the upper 64-bits for a single bit error.

    This function returns the error position of the upper 64-bits. If the error type is FLASH_ECC_ERR, the position ranges from 0-7 else it ranges from 0-63 for FLASH_DATA_ERR.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

    Return

      Returns the position of the upper error bit.

  Flash_ErrorType `Flash_getLowErrorType`(uint32_t eccBase)

    Gets the error type of the lower 64-bits.

    This function returns the error type of the lower 64-bits. The error type can be FLASH_ECC_ERR or FLASH_DATA_ERR.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

    Return

      Returns the type of the lower 64-bit error.

  Flash_ErrorType `Flash_getHighErrorType`(uint32_t eccBase)

    Gets the error type of the upper 64-bits.

    This function returns the error type of the upper 64-bits. The error type can be FLASH_ECC_ERR or FLASH_DATA_ERR.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

    Return

      Returns the type of the upper 64-bit error.

  void `Flash_clearLowErrorStatus`(uint32_t eccBase, uint16_t errorStatus)

    Clears the errors status of the lower 64-bits.

    - FLASH_FAIL_0_CLR

    - FLASH_FAIL_1_CLR

    - FLASH_UNC_ERR_CLR

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

      - `errorStatus`: is the error status to clear. errorStatus is a uint16_t. errorStatus is a bitwise OR of the following value:

    Return

      None.

  void `Flash_clearHighErrorStatus`(uint32_t eccBase, uint16_t errorStatus)

    Clears the errors status of the upper 64-bits.

    - FLASH_FAIL_0_CLR

    - FLASH_FAIL_1_CLR

    - FLASH_UNC_ERR_CLR

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

      - `errorStatus`: is the error status to clear. errorStatus is a uint16_t. errorStatus is a bitwise OR of the following value:

    Return

      None.

  uint32_t `Flash_getErrorCount`(uint32_t eccBase)

    Gets the single bit error count.

    Return

      Returns the single bit error count.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

  void `Flash_setErrorThreshold`(uint32_t eccBase, uint16_t threshold)

    Sets the single bit error threshold.

    Return

      None.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

      - `threshold`: is the single bit error threshold. Valid ranges are from 0-65535.

  uint32_t `Flash_getInterruptFlag`(uint32_t eccBase)

    Gets the error interrupt.

    This function returns the type of error interrupt that occurred. The values can be used with

    - FLASH_NO_ERROR

    - FLASH_SINGLE_ERROR

    - FLASH_UNC_ERROR

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

    Return

      Returns the interrupt flag.

  void `Flash_clearSingleErrorInterruptFlag`(uint32_t eccBase)

    Clears the single error interrupt flag.

    Return

      None.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

  void `Flash_clearUncorrectableInterruptFlag`(uint32_t eccBase)

    Clears the uncorrectable error interrupt flag.

    Return

      None.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

  void `Flash_setDataLowECCTest`(uint32_t eccBase, uint32_t data)

    Sets the Data Low Test register for ECC testing.

    Return

      None.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

      - `data`: is a 32-bit value that is the low double word of selected 64-bit data

  void `Flash_setDataHighECCTest`(uint32_t eccBase, uint32_t data)

    Sets the Data High Test register for ECC testing.

    Return

      None.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

      - `data`: is a 32-bit value that is the high double word of selected 64-bit data

  void `Flash_setECCTestAddress`(uint32_t eccBase, uint32_t address)

    Sets the test address register for ECC testing.

    This function left shifts the address 1 bit to convert it to a byte address

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

      - `address`: is a 32-bit value containing an address. Bits 21-3 will be used as the flash word (128-bit) address.

    Return

      None.

  void `Flash_setECCTestECCBits`(uint32_t eccBase, uint16_t ecc)

    Sets the ECC test bits for ECC testing.

    Return

      None.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

      - `ecc`: is a 32-bit value. The least significant 8 bits are used as the ECC Control Bits in the ECC Test.

  void `Flash_enableECCTestMode`(uint32_t eccBase)

    Enables ECC Test mode.

    Return

      None.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

  void `Flash_disableECCTestMode`(uint32_t eccBase)

    Disables ECC Test mode.

    Return

      None.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

  void `Flash_selectLowECCBlock`(uint32_t eccBase)

    Selects the ECC block on bits [63:0] of bank data.

    Return

      None.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

  void `Flash_selectHighECCBlock`(uint32_t eccBase)

    Selects the ECC block on bits [127:64] of bank data.

    Return

      None.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

  void `Flash_performECCCalculation`(uint32_t eccBase)

    Performs the ECC calculation on the test block.

    Return

      None.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

  uint32_t `Flash_getTestDataOutHigh`(uint32_t eccBase)

    Gets the ECC Test data out high 63:32 bits.

    Return

      Returns the ECC TEst data out High.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

  uint32_t `Flash_getTestDataOutLow`(uint32_t eccBase)

    Gets the ECC Test data out low 31:0 bits.

    Return

      Returns the ECC Test data out Low.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

  uint32_t `Flash_getECCTestStatus`(uint32_t eccBase)

    Gets the ECC Test status.

    This function returns the ECC test status. The values can be used with

    - FLASH_NO_ERROR

    - FLASH_SINGLE_ERROR

    - FLASH_UNC_ERROR

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

    Return

      Returns the ECC test status.

  uint32_t `Flash_getECCTestErrorPosition`(uint32_t eccBase)

    Gets the ECC Test single bit error position.

    Return

      Returns the ECC Test single bit error position. If the error type is check bits than the position can range from 0 to 7. If the error type is data bits than the position can range from 0 to 63.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

  Flash_SingleBitErrorIndicator `Flash_getECCTestSingleBitErrorType`(uint32_t eccBase)

    Gets the single bit error type.

    Return

      Returns the single bit error type as a Flash_SingleBitErrorIndicator. FLASH_DATA_BITS and FLASH_CHECK_BITS indicate where the single bit error occurred.

    Parameters

      - `eccBase`: is the base address of the flash wrapper ECC registers.

  void `Flash_claimPumpSemaphore`(uint32_t pumpSemBase, Flash_PumpOwnership wrapper)

    Claim the flash pump semaphore.

    Return

      None.

    Parameters

      - `pumpSemBase`: is the base address of the flash pump semaphore.

      - `wrapper`: is the Flash_PumpOwnership wrapper claiming the pump semaphore.

  void `Flash_releasePumpSemaphore`(uint32_t pumpSemBase)

    Release the flash pump semaphore.

    Return

      None.

    Parameters

      - `pumpSemBase`: is the base address of the flash pump semaphore.

  void `Flash_initModule`(uint32_t ctrlBase, uint32_t eccBase, uint16_t waitstates)

    Initializes the flash control registers.

    This function initializes the flash control registers. At reset bank and pump are in sleep. A flash access will power up the bank and pump automatically. This function will power up Flash bank and pump and set the fallback mode of flash and pump as active.

    Parameters

      - `ctrlBase`: is the base address of the flash wrapper control registers.

      - `eccBase`: is the base address of the flash wrapper ECC registers.

      - `waitstates`: is the wait-state value.

    This function also sets the number of wait-states for a flash access (see Flash_setWaitstates() for more details), and enables cache, the prefetch mechanism, and ECC.

    Note: For this device, there are two flash wrappers with different base addresses corresponding to each of two banks. If you wish to initialize both flash wrappers, you will need to call this function for each wrapper.

    Return

      None.

  void `Flash_powerDown`(uint32_t ctrlBase)

    Powers down the flash.

    This function powers down the flash bank(s) and the flash pump.

    Parameters

      - `ctrlBase`: is the base address of the flash wrapper control registers.

    Note: For this device, you must claim the flash pump semaphore before calling this function and powering down the pump. Afterwards, you may want to relinquish the flash pump.

    Note: For this device, there are two flash wrappers corresponding to two banks with different base addresses. If you wish to power down both flash wrappers then you need to call this function each wrapper.

    Return

      None.

  void `Flash_wakeFromLPM`(uint32_t ctrlBase)

    Wakes the flash from low power mode.

    This function will power up Flash bank and pump and set the fallback mode of flash and pump as active.

    Parameters

      - `ctrlBase`: is the base address of the flash wrapper control registers.

    Return

      None.

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