cy_flash_8h

Provides the API declarations of the Flash driver.

Version

3.50.1

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0
Copyright

Copyright 2016-2020 Cypress Semiconductor Corporation SPDX-License-Identifier: Apache-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Defines

CY_FLASH_DRV_VERSION_MAJOR

Driver major version.

CY_FLASH_DRV_VERSION_MINOR

Driver minor version.

CY_FLASH_ID

FLASH PDL ID.

CY_FLASH_ID_INFO

Return prefix for FLASH driver function status codes.

CY_FLASH_ID_WARNING

Return prefix for FLASH driver function warning return values.

CY_FLASH_ID_ERROR

Return prefix for FLASH driver function error return values.

CY_FLASH_SIZEOF_ROW

Flash row size.

CY_FLASH_SIZEOF_ROW_LONG_UNITS

Long words flash row size.

Enums

enum cy_en_flashdrv_status_t

cy_en_flashdrv_status_t: This enum has the return values of the Flash driver.

Values:

enumerator CY_FLASH_DRV_SUCCESS

Success.

enumerator CY_FLASH_DRV_INV_PROT

Invalid device protection state.

enumerator CY_FLASH_DRV_INVALID_FM_PL

Invalid flash page latch address.

enumerator CY_FLASH_DRV_INVALID_FLASH_ADDR

Invalid flash address.

enumerator CY_FLASH_DRV_ROW_PROTECTED

Row is write protected.

enumerator CY_FLASH_DRV_IPC_BUSY

IPC structure is already locked by another process.

enumerator CY_FLASH_DRV_INVALID_INPUT_PARAMETERS

Input parameters passed to Flash API are not valid.

enumerator CY_FLASH_DRV_PL_ROW_COMP_FA

Comparison between Page Latches and FM row failed.

enumerator CY_FLASH_DRV_ERR_UNC

Unknown error code.

See Cy_Flash_GetExternalStatus()

enumerator CY_FLASH_DRV_PROGRESS_NO_ERROR

Command in progress; no error.

enumerator CY_FLASH_DRV_OPERATION_STARTED

Flash operation is successfully initiated.

enumerator CY_FLASH_DRV_OPCODE_BUSY

Flash is under operation.

Functions

void Cy_Flash_Init(void)

Initiates all needed prerequisites to support flash erase/write.

Should be called from each core.

Requires a call to Cy_IPC_Sema_Init(), Cy_IPC_Pipe_Config() and Cy_IPC_Pipe_Init() functions before use.

This function is called in the SystemInit() function, for proper flash write and erase operations. If the default startup file is not used, or the function SystemInit() is not called in your project, ensure to perform the following steps before any flash or EmEEPROM write/erase operations:


    /* 1. Allocate and initialize IPC semaphores for the system operations */
    static uint32_t ipcSemaArray[CY_IPC_SEMA_COUNT / CY_IPC_SEMA_PER_WORD];

    (void) Cy_IPC_Sema_Init(CY_IPC_CHAN_SEMA, CY_IPC_SEMA_COUNT, ipcSemaArray);

    /* 2. Create an array of endpoint structures and configure an IPC pipe infrastructure */
    static cy_stc_ipc_pipe_ep_t ipcPipeEpArray[CY_IPC_MAX_ENDPOINTS];

    Cy_IPC_Pipe_Config(ipcPipeEpArray);

    /* 3. Create an array of client callbacks and initialize a system pipe by a configuration structure */
    static cy_ipc_pipe_callback_ptr_t sysIpcPipeCbArray[CY_SYS_CYPIPE_CLIENT_CNT];

    static const cy_stc_ipc_pipe_config_t systemIpcPipeConfig =
    {
    /* .ep0ConfigData */
        {
            /* .ipcNotifierNumber    */  CY_IPC_INTR_CYPIPE_EP0,
            /* .ipcNotifierPriority  */  CY_SYS_INTR_CYPIPE_PRIOR_EP0,
            /* .ipcNotifierMuxNumber */  CY_SYS_INTR_CYPIPE_MUX_EP0,
            /* .epAddress            */  CY_IPC_EP_CYPIPE_CM0_ADDR,
            /* .epConfig             */  CY_SYS_CYPIPE_CONFIG_EP0
        },
    /* .ep1ConfigData */
        {
            /* .ipcNotifierNumber    */  CY_IPC_INTR_CYPIPE_EP1,
            /* .ipcNotifierPriority  */  CY_SYS_INTR_CYPIPE_PRIOR_EP1,
            /* .ipcNotifierMuxNumber */  0u,
            /* .epAddress            */  CY_IPC_EP_CYPIPE_CM4_ADDR,
            /* .epConfig             */  CY_SYS_CYPIPE_CONFIG_EP1
        },
    /* .endpointClientsCount     */  CY_SYS_CYPIPE_CLIENT_CNT,
    /* .endpointsCallbacksArray  */  sysIpcPipeCbArray,
    /* .systemPipeIsrHandler     */  &SysIpcPipeIsr
    };

    Cy_IPC_Pipe_Init(&systemIpcPipeConfig);

    /* 4. And finally initialize the flash */
    Cy_Flash_Init();

    /* Ensure to run these steps on all the MCU cores */

cy_en_flashdrv_status_t Cy_Flash_EraseRow(uint32_t rowAddr)

This function erases a single row of flash.

Reports success or a reason for failure. Does not return until the Write operation is complete. Returns immediately and reports a CY_FLASH_DRV_IPC_BUSY error in the case when another process is writing to flash or erasing the row. User firmware should not enter the Hibernate or Deep Sleep mode until flash Erase is complete. The Flash operation is allowed in Sleep mode. During the Flash operation, the device should not be reset, including the XRES pin, a software reset, and watchdog reset sources. Also, low-voltage detect circuits should be configured to generate an interrupt instead of a reset. Otherwise, portions of flash may undergo unexpected changes.

Return

Returns the status of the Flash operation, see cy_en_flashdrv_status_t.

Parameters
  • rowAddr: Address of the flash row number. The Read-while-Write violation occurs when the flash read operation is initiated in the same flash sector where the flash write operation is performing. Refer to the device datasheet for the details. Address must match row start address.

cy_en_flashdrv_status_t Cy_Flash_StartEraseRow(uint32_t rowAddr)

Starts erasing a single row of flash.

Returns immediately and reports a successful start or reason for failure. Reports a CY_FLASH_DRV_IPC_BUSY error in the case when IPC structure is locked by another process. User firmware should not enter the Hibernate or Deep Sleep mode until flash Erase is complete. The Flash operation is allowed in Sleep mode. During the flash operation, the device should not be reset, including the XRES pin, a software reset, and watchdog reset sources. Also, the low-voltage detect circuits should be configured to generate an interrupt instead of a reset. Otherwise, portions of flash may undergo unexpected changes.

note

To avoid situation of reading data from cache memory - before reading data from previously programmed/erased flash rows, the user must clear the flash cache with the Cy_SysLib_ClearFlashCacheAndBuffer() function.

Return

Returns the status of the Flash operation, see cy_en_flashdrv_status_t.

Parameters
  • rowAddr: Address of the flash row number. The Read-while-Write violation occurs when the flash read operation is initiated in the same flash sector where the flash erase operation is performing. Refer to the device datasheet for the details. Address must match row start address.

cy_en_flashdrv_status_t Cy_Flash_EraseSector(uint32_t sectorAddr)

This function erases a sector of flash.

Reports success or a reason for failure. Does not return until the Erase operation is complete. Returns immediately and reports a CY_FLASH_DRV_IPC_BUSY error in the case when another process is writing to flash or erasing the row. User firmware should not enter the Hibernate or Deep Sleep mode until flash Erase is complete. The Flash operation is allowed in Sleep mode. During the Flash operation, the device should not be reset, including the XRES pin, a software reset, and watchdog reset sources. Also, low-voltage detect circuits should be configured to generate an interrupt instead of a reset. Otherwise, portions of flash may undergo unexpected changes.

Return

Returns the status of the Flash operation, see cy_en_flashdrv_status_t.

Parameters
  • sectorAddr: Address of the flash row number. The Read-while-Write violation occurs when the flash read operation is initiated in the same flash sector where the flash write operation is performing. Refer to the device datasheet for the details. Address must match row start address.

cy_en_flashdrv_status_t Cy_Flash_StartEraseSector(uint32_t sectorAddr)

Starts erasing a sector of flash.

Returns immediately and reports a successful start or reason for failure. Reports a CY_FLASH_DRV_IPC_BUSY error in the case when IPC structure is locked by another process. User firmware should not enter the Hibernate or Deep Sleep mode until flash Erase is complete. The Flash operation is allowed in Sleep mode. During the flash operation, the device should not be reset, including the XRES pin, a software reset, and watchdog reset sources. Also, the low-voltage detect circuits should be configured to generate an interrupt instead of a reset. Otherwise, portions of flash may undergo unexpected changes.

note

Before reading data from previously programmed/erased flash rows, the user must clear the flash cache with the Cy_SysLib_ClearFlashCacheAndBuffer() function.

Return

Returns the status of the Flash operation, see cy_en_flashdrv_status_t.

Parameters
  • sectorAddr: Address of the flash row number. The Read-while-Write violation occurs when the flash read operation is initiated in the same flash sector where the flash erase operation is performing. Refer to the device datasheet for the details. Address must match row start address.

cy_en_flashdrv_status_t Cy_Flash_EraseSubsector(uint32_t subSectorAddr)

This function erases an 8-row subsector of flash.

Reports success or a reason for failure. Does not return until the Write operation is complete. Returns immediately and reports a CY_FLASH_DRV_IPC_BUSY error in the case when another process is writing to flash or erasing the row. User firmware should not enter the Hibernate or Deep-Sleep mode until flash Erase is complete. The Flash operation is allowed in Sleep mode. During the Flash operation, the device should not be reset, including the XRES pin, a software reset, and watchdog reset sources. Also, low-voltage detect circuits should be configured to generate an interrupt instead of a reset. Otherwise, portions of flash may undergo unexpected changes.

Return

Returns the status of the Flash operation, see cy_en_flashdrv_status_t.

Parameters
  • subSectorAddr: Address of the flash row number. The Read-while-Write violation occurs when the flash read operation is initiated in the same flash sector where the flash write operation is performing. Refer to the device datasheet for the details. Address must match row start address.

cy_en_flashdrv_status_t Cy_Flash_StartEraseSubsector(uint32_t subSectorAddr)

Starts erasing an 8-row subsector of flash.

Returns immediately and reports a successful start or reason for failure. Reports a CY_FLASH_DRV_IPC_BUSY error in the case when IPC structure is locked by another process. User firmware should not enter the Hibernate or Deep-Sleep mode until flash Erase is complete. The Flash operation is allowed in Sleep mode. During the flash operation, the device should not be reset, including the XRES pin, a software reset, and watchdog reset sources. Also, the low-voltage detect circuits should be configured to generate an interrupt instead of a reset. Otherwise, portions of flash may undergo unexpected changes.

note

Before reading data from previously programmed/erased flash rows, the user must clear the flash cache with the Cy_SysLib_ClearFlashCacheAndBuffer() function.

Return

Returns the status of the Flash operation, see cy_en_flashdrv_status_t.

Parameters
  • subSectorAddr: Address of the flash row number. The Read-while-Write violation occurs when the flash read operation is initiated in the same flash sector where the flash erase operation is performing. Refer to the device datasheet for the details. Address must match row start address.

cy_en_flashdrv_status_t Cy_Flash_ProgramRow(uint32_t rowAddr, const uint32_t *data)

This function writes an array of data to a single row of flash.

Reports success or a reason for failure. Does not return until the Program operation is complete. Returns immediately and reports a CY_FLASH_DRV_IPC_BUSY error in the case when another process is writing to flash. User firmware should not enter the Hibernate or Deep-sleep mode until flash Write is complete. The Flash operation is allowed in Sleep mode. During the Flash operation, the device should not be reset, including the XRES pin, a software reset, and watchdog reset sources. Also, low-voltage detect circuits should be configured to generate an interrupt instead of a reset. Otherwise, portions of flash may undergo unexpected changes.

Before calling this function, the target flash region must be erased by the StartErase/EraseRow function.

Data to be programmed must be located in the SRAM memory region.

note

Before reading data from previously programmed/erased flash rows, the user must clear the flash cache with the Cy_SysLib_ClearFlashCacheAndBuffer() function.

Return

Returns the status of the Flash operation, see cy_en_flashdrv_status_t.

Parameters
  • rowAddr: Address of the flash row number. The Read-while-Write violation occurs when the flash read operation is initiated in the same flash sector where the flash write operation is performing. Refer to the device datasheet for the details. Address must match row start address.

  • data: The pointer to the data which has to be written to flash. The size of the data array must be equal to the flash row size. The flash row size for the selected device is defined by the CY_FLASH_SIZEOF_ROW macro. Refer to the device datasheet for the details.

cy_en_flashdrv_status_t Cy_Flash_WriteRow(uint32_t rowAddr, const uint32_t *data)

This function writes an array of data to a single row of flash.

This is done in three steps - pre-program, erase and then program flash row with the input data. Reports success or a reason for failure. Does not return until the Write operation is complete. Returns immediately and reports a CY_FLASH_DRV_IPC_BUSY error in the case when another process is writing to flash. User firmware should not enter the Hibernate or Deep-sleep mode until flash Write is complete. The Flash operation is allowed in Sleep mode. During the Flash operation, the device should not be reset, including the XRES pin, a software reset, and watchdog reset sources. Also, low-voltage detect circuits should be configured to generate an interrupt instead of a reset. Otherwise, portions of flash may undergo unexpected changes.

Return

Returns the status of the Flash operation, see cy_en_flashdrv_status_t.

Parameters
  • rowAddr: Address of the flash row number. The Read-while-Write violation occurs when the flash read operation is initiated in the same flash sector where the flash write operation is performing. Refer to the device datasheet for the details. Address must match row start address.

  • data: The pointer to the data which has to be written to flash. The size of the data array must be equal to the flash row size. The flash row size for the selected device is defined by the CY_FLASH_SIZEOF_ROW macro. Refer to the device datasheet for the details.

cy_en_flashdrv_status_t Cy_Flash_StartWrite(uint32_t rowAddr, const uint32_t *data)

Performs pre-program, erase and then starts programming the flash row with the input data.

Returns immediately and reports a successful start or reason for failure. Reports a CY_FLASH_DRV_IPC_BUSY error in the case when another process is writing to flash. User firmware should not enter the Hibernate or Deep-Sleep mode until flash Write is complete. The Flash operation is allowed in Sleep mode. During the flash operation, the device should not be reset, including the XRES pin, a software reset, and watchdog reset sources. Also, the low-voltage detect circuits should be configured to generate an interrupt instead of a reset. Otherwise, portions of flash may undergo unexpected changes.

note

Before reading data from previously programmed/erased flash rows, the user must clear the flash cache with the Cy_SysLib_ClearFlashCacheAndBuffer() function.

Return

Returns the status of the Flash operation, see cy_en_flashdrv_status_t.

Parameters
  • rowAddr: Address of the flash row number. The Read-while-Write violation occurs when the flash read operation is initiated in the same flash sector where the flash write operation is performing. Refer to the device datasheet for the details. Address must match row start address.

  • data: The pointer to the data to be written to flash. The size of the data array must be equal to the flash row size. The flash row size for the selected device is defined by the CY_FLASH_SIZEOF_ROW macro. Refer to the device datasheet for the details.

cy_en_flashdrv_status_t Cy_Flash_StartProgram(uint32_t rowAddr, const uint32_t *data)

Starts writing an array of data to a single row of flash.

Returns immediately and reports a successful start or reason for failure. Reports a CY_FLASH_DRV_IPC_BUSY error if another process is writing to flash. The user firmware should not enter Hibernate or Deep-Sleep mode until flash Program is complete. The Flash operation is allowed in Sleep mode. During the Flash operation, the device should not be reset, including the XRES pin, a software reset, and watchdog reset sources. Also, the low-voltage detect circuits should be configured to generate an interrupt instead of a reset. Otherwise, portions of flash may undergo unexpected changes.

Before calling this function, the target flash region must be erased by the StartEraseRow/EraseRow function.

Data to be programmed must be located in the SRAM memory region.

note

Before reading data from previously programmed/erased flash rows, the user must clear the flash cache with the Cy_SysLib_ClearFlashCacheAndBuffer() function.

Return

Returns the status of the Flash operation, see cy_en_flashdrv_status_t.

Parameters
  • rowAddr: The address of the flash row number. The Read-while-Write violation occurs when the Flash Write operation is performing. Refer to the device datasheet for the details. The address must match the row start address.

  • data: The pointer to the data to be written to flash. The size of the data array must be equal to the flash row size. The flash row size for the selected device is defined by the CY_FLASH_SIZEOF_ROW macro. Refer to the device datasheet for the details.

cy_en_flashdrv_status_t Cy_Flash_IsOperationComplete(void)

Reports a successful operation result, reason of failure or busy status ( CY_FLASH_DRV_OPCODE_BUSY ).

Return

Returns the status of the Flash operation (see cy_en_flashdrv_status_t).

cy_en_flashdrv_status_t Cy_Flash_RowChecksum(uint32_t rowAddr, uint32_t *checksumPtr)

Returns a checksum value of the specified flash row.

note

Now Cy_Flash_RowChecksum() requires the row address (rowAddr) as a parameter. In previous versions of the driver, this function used the row number (rowNum) for this parameter.

Return

Returns the status of the Flash operation.

Parameters
  • rowAddr: The address of the flash row.

  • checksumPtr: The pointer to the address where checksum is to be stored

cy_en_flashdrv_status_t Cy_Flash_CalculateHash(const uint32_t *data, uint32_t numberOfBytes, uint32_t *hashPtr)

Returns a hash value of the specified region of flash.

Return

Returns the status of the Flash operation.

Parameters
  • data: Start the data address.

  • numberOfBytes: The hash value is calculated for the number of bytes after the start data address (0 - 1 byte, 1- 2 bytes etc).

  • hashPtr: The pointer to the address where hash is to be stored

uint32_t Cy_Flash_GetExternalStatus(void)

This function handles the case where a module such as security image captures a system call from this driver and reports its own status or error code, for example protection violation.

In that case, a function from this driver returns an unknown error (see cy_en_flashdrv_status_t). After receipt of an unknown error, the user may call this function to get the status of the capturing module.

The user is responsible for parsing the content of the returned value and casting it to the appropriate enumeration.

Return

The error code that was stored in the opcode variable.

void Cy_Flash_InitExt(cy_stc_flash_notify_t *ipcWaitMessageAddr)

Initiates all needed prerequisites to support flash erase/write.

Should be called from each core. Defines the address of the message structure.

Requires a call to Cy_IPC_Sema_Init(), Cy_IPC_Pipe_Config() and Cy_IPC_Pipe_Init() functions before use.

This function is called in the Cy_Flash_Init() function - see the Cy_Flash_Init usage considerations.

struct cy_stc_flash_notify_t
#include <cy_flash.h>

Flash notification configuration structure.

Public Members

uint8_t clientID

Client ID.

uint8_t pktType

Message Type.

uint16_t intrRelMask

Mask.