Functions

group group_dfu_functions

Functions

cy_en_dfu_status_t Cy_DFU_Complete(uint32_t *state, uint32_t timeout)

This function starts the application download and install operations.

It calls Cy_DFU_Init() and then continually calls Cy_DFU_Continue(). It does not return until the DFU operation is complete or an error is detected. This function provides an example of how to use the DFU SDK to quickly design a DFU system.

note

This function blocks, suspending all other tasks until the DFU operation is complete. To execute other tasks while updating, design your code to call Cy_DFU_Init() and Cy_DFU_Continue() directly. Only one updating operation can be done at a time - the user's code must ensure this.

note

The function set timeout field in cy_stc_dfu_params_t::timeout to 20 ms - enough for UART (at 115200 bps), I2C, SPI, USB-HID, and BLE OTA in most cases.

note

The function enables global interrupts.

Return

See cy_en_dfu_status_t.

Parameters
  • state: The pointer to a state variable, that is updated by the function. See DFU State.

  • timeout: The max amount of time (in milliseconds) for which the function is waiting for receiving of the Enter DFU command.

cy_en_dfu_status_t Cy_DFU_Init(uint32_t *state, cy_stc_dfu_params_t *params)

This function starts the application download and install operations.

Make subsequent calls to Cy_DFU_Continue() to continue the process.

Returns immediately, reporting success or failure.

Only one updating operation can be done at a time - the user’s code must ensure this.

    /*
    * Used to count seconds
    */
    uint32_t count = 0;

    /* Status codes for DFU API */
    cy_en_dfu_status_t status;

    /*
    * DFU state, one of the:
    * - CY_DFU_STATE_NONE
    * - CY_DFU_STATE_UPDATING
    * - CY_DFU_STATE_FINISHED
    * - CY_DFU_STATE_FAILED
    */
    uint32_t state;

    /* Timeout for Cy_DFU_Continue(), in milliseconds */
    const uint32_t paramsTimeout = 20u;
    
    /* Buffer to store DFU commands */
    CY_ALIGN(4) static uint8_t buffer[CY_DFU_SIZEOF_DATA_BUFFER];

    /* Buffer for DFU data packets for transport API */
    CY_ALIGN(4) static uint8_t packet[CY_DFU_SIZEOF_CMD_BUFFER ];

    /* DFU params, used to configure DFU */
    cy_stc_dfu_params_t dfuParams;

    /* Initialize dfuParams structure */
    dfuParams.timeout          = paramsTimeout;
    dfuParams.dataBuffer       = &buffer[0];
    dfuParams.packetBuffer     = &packet[0];

    status = Cy_DFU_Init(&state, &dfuParams);
    
    /* Stop program execution if DFU init failed */
    CY_ASSERT(CY_DFU_SUCCESS == status);
    
    /* Set up the device based on configurator selections */
    init_cycfg_all();

    /* enable interrupts */
    __enable_irq();
Return

See cy_en_dfu_status_t.

Parameters
  • state: The pointer to a state variable, that is updated by the function. See DFU State

  • params: The pointer to a DFU parameters structure See cy_stc_dfu_params_t

cy_en_dfu_status_t Cy_DFU_Continue(uint32_t *state, cy_stc_dfu_params_t *params)

The function processes Host Commands according to Host Command/Response Protocol.

The function waits for the Host data packet till timeout occurs. If valid packet is received, it decodes received command, processes it and transfer back a response if needed. See description of Host Command/Response Protocol in AN213924 DFU SDK User Guide.

Return

See cy_en_dfu_status_t

Parameters
  • state: The pointer to a state variable, that is updated by the function. See DFU State.

  • params: The pointer to a DFU parameters structure. See cy_stc_dfu_params_t.

void Cy_DFU_ExecuteApp(uint32_t appId)

This function transfers control from the current application to another application.

The function performs switching via software reset. In case if application need to switch without reset, for example if it needs to enable some peripheral during and after the application switching, use Cy_DFU_SwitchToApp(). The function does not return.

note

It is assumed appId is a valid application number.

Parameters
  • appId: An application number of the application to switch to.

cy_en_dfu_status_t Cy_DFU_SwitchToApp(uint32_t appId)

This function switches to the application through the jump instruction.

The function should be used when an application switching must be done without a software reset. Possible reason is a need to enable some peripheral during and after the application switching. In other case use Cy_DFU_ExecuteApp().

Before calling this function, ensure all the peripherals and bus masters are in a known state. User is responsible to disable peripherals and to set MCU internal state before or after an application switching.

note

It is assumed appId is a valid application number.

Return

It doesn’t return if succeeds. If failed, returns the status code. See cy_en_dfu_status_t.

Parameters
  • appId: An application number of the application to switch to.

uint32_t Cy_DFU_DataChecksum(const uint8_t *address, uint32_t length, cy_stc_dfu_params_t *params)

This function computes a CRC-32C for the provided number of bytes contained in the provided buffer.

This function is used to validate the Program Data and Verify Data DFU commands and a metadata row.

note

Ensure the Crypto block is properly initialized if CY_DFU_OPT_CRYPTO_HW is set.

Return

CRC-32C for the provided data.

Parameters
  • address: The pointer to a buffer containing the data to compute the checksum for.

  • length: The number of bytes in the buffer to compute the checksum for.

  • params: The pointer to a DFU parameters structure. See cy_stc_dfu_params_t .

cy_en_dfu_status_t Cy_DFU_ValidateMetadata(uint32_t metadataAddress, cy_stc_dfu_params_t *params)

The function checks if the DFU metadata is valid.

It calculates CRC-32C and compare with stored value at the end of metadata.

Return

See cy_en_dfu_status_t

cy_en_dfu_status_t Cy_DFU_ValidateApp(uint32_t appId, cy_stc_dfu_params_t *params)

This function reports whether or not metadata and the specified application is valid.

It checks:

  • checksum for applications without format;

  • application signature for Cypress Standard User Application format.

This is a weak function and the user may override it in the user’s code by providing a function with the same name.

note

It is assumed appId is a valid application number.

Return

See cy_en_dfu_status_t.

Parameters
  • appId: The application number of the application to be validated.

  • params: The pointer to a DFU parameters structure. See cy_stc_dfu_params_t .

uint32_t Cy_DFU_GetRunningApp(void)

This function reports the application number of the currently running application.

Return

application number

cy_en_dfu_status_t Cy_DFU_GetAppMetadata(uint32_t appId, uint32_t *verifyAddress, uint32_t *verifySize)

Reads application metadata to verifyAddress and verifySize.

The metadata is supposed to be located in internal flash.

This is a weak function and the user may override it in the user’s code by providing a function with the same name. This allows the user to place metadata in any NVM.

note

It is assumed appId is a valid application number.

Return

See cy_en_dfu_status_t.

Parameters
  • appId: The application number.

  • verifyAddress: The pointer to a variable where an application verified area start address is stored.

  • verifySize: The pointer to a variable where a size of verified application area is stored.

cy_en_dfu_status_t Cy_DFU_SetAppMetadata(uint32_t appId, uint32_t verifyAddress, uint32_t verifySize, cy_stc_dfu_params_t *params)

This is a helper function for Cy_DFU_Continue().

This function sets application metadata and updates a metadata checksum.

note

If the application metadata is the same as already present in the NVM, then the NVM is not rewritten and this function only exits.

note

This function uses params->dataBuffer for the read and write NVM.

Return

See cy_en_dfu_status_t

Parameters
  • appId: The application number to update metadata for.

  • verifyAddress: An application verified area start address

  • verifySize: The size of verified application area

  • params: The pointer to a DFU parameters structure. See cy_stc_dfu_params_t.

cy_en_dfu_status_t Cy_DFU_CopyApp(uint32_t destAddress, uint32_t srcAddress, uint32_t length, uint32_t rowSize, cy_stc_dfu_params_t *params)

This function copies an application from a temporary location in flash to its destination location in flash.

This function is typically called when updating an application used as part of an update process, for example updating a BLE stack.

note

This API is only for demonstration purpose, use it only when copying from internal flash to internal flash. For other user cases, implement a custom, more general function.

Return

See cy_en_dfu_status_t.

Parameters
  • destAddress: The start address of the application to copy to.

  • srcAddress: The start address of the copy of the application to be copied.

  • length: The number of bytes to copy.

  • rowSize: The size of a flash row in bytes.

  • params: The pointer to a DFU parameters structure. See cy_stc_dfu_params_t .

void Cy_DFU_OnResetApp0(void)

This function is used in an App0 firmware image in Reset_Handler() only.

Checks if switching to the other application is scheduled with Cy_DFU_ExecuteApp().

If the switch is scheduled, then it validates the application and transfers control to it.

cy_en_dfu_status_t Cy_DFU_ReadData(uint32_t address, uint32_t length, uint32_t ctl, cy_stc_dfu_params_t *params)

This function must be implemented in the user’s code.

Reads buffer from flash, QSPI flash, or any other external memory type with custom pre and post read commands.

Return

See cy_en_dfu_status_t

  • CY_DFU_SUCCESS - If successful.

  • CY_DFU_ERROR_LENGTH if The length value is invalid.

  • CY_DFU_ERROR_ADDRESS if The address is invalid.

Parameters
  • address: The address from where to read data, must be aligned to a flash row, QSPI flash page, etc.

  • length: The length in bytes of data to read, must be multiple of a flash row, QSPI flash page, etc.

  • ctl: Additional features of the read function:

    • CY_DFU_IOCTL_READ - Only read.

    • CY_DFU_IOCTL_COMPARE - Compare the data in the buffer with the data in memory.

    • CY_DFU_IOCTL_BHP - Decrypt data before comparing the buffer with memory, if the DFU Host provided encrypted data.

  • params: The pointer to a DFU parameters structure. See cy_stc_dfu_params_t .

cy_en_dfu_status_t Cy_DFU_WriteData(uint32_t address, uint32_t length, uint32_t ctl, cy_stc_dfu_params_t *params)

This function must be implemented in the user’s code.

Writes the buffer to flash, QSPI flash, or any other external memory type with custom pre and post write commands.

Return

See cy_en_dfu_status_t.

  • CY_DFU_SUCCESS - If successful.

  • CY_DFU_ERROR_LENGTH if The length value is invalid.

  • CY_DFU_ERROR_ADDRESS if The address is invalid.

Parameters
  • address: The address to write data to, must be aligned to a flash row, QSPI flash page, etc.

  • length: The length in bytes of data to be written, must be multiple of a flash row, QSPI flash page, etc.

  • ctl: Additional features of the write function:

    • CY_DFU_IOCTL_WRITE - Only write.

    • CY_DFU_IOCTL_ERASE - Erase the sector, the sector size can be bigger than the size of the page to write.

    • CY_DFU_IOCTL_BHP - Decrypt data before writing to memory, if the DFU Host provided encrypted data.

  • params: The pointer to a DFU parameters structure. See cy_stc_dfu_params_t .

cy_en_dfu_status_t Cy_DFU_TransportRead(uint8_t buffer[], uint32_t size, uint32_t *count, uint32_t timeout)

This function must be implemented in the user’s code.

This function receives a command packet from the DFU Host via the communication channel. The function waits for a timeout until all bytes are received.

Return

The status of the transmit operation:

  • CY_DFU_SUCCESS - If successful.

  • CY_DFU_ERROR_TIMEOUT - If no data is received.

  • See cy_en_dfu_status_t.

Parameters
  • buffer: The pointer to a buffer to store a received command.

  • size: The number of bytes to read.

  • count: The pointer to the variable that contains the number of received bytes.

  • timeout: The time to wait before the function returns because of a timeout, in milliseconds.

cy_en_dfu_status_t Cy_DFU_TransportWrite(uint8_t buffer[], uint32_t size, uint32_t *count, uint32_t timeout)

This function must be implemented in the user’s code.

This function transmits a response packet to the DFU host via the communication channel. The function waits for a timeout until all bytes are sent.

Return

See cy_en_dfu_status_t. The status of the transmit operation:

  • CY_DFU_SUCCESS - If successful.

  • CY_DFU_ERROR_TIMEOUT - If no data is transmitted.

Parameters
  • buffer: The pointer response packet buffer.

  • size: The number of bytes to transmit.

  • count: The pointer to the actual number of transmitted bytes.

  • timeout: The time to wait before the function returns because of a timeout, in milliseconds

void Cy_DFU_TransportReset(void)

This function must be implemented in the user’s code.

Resets the communication interface with clearing buffers, offsets, length, etc.

void Cy_DFU_TransportStart(void)

This function must be implemented in the user’s code.

Starts the communication interface through which updating will be working.

void Cy_DFU_TransportStop(void)

This function must be implemented in the user’s code.

Stops the communication interface through which updating will be working.