Bootloader Support Functions

General Description

Functions for handling and installing firmware updates.

Bootloader based storage interface APIs for handling downloaded UPGRADE image of OTA application.

OTA Bootloader support library flash operation APIs.

Storage Interface APIs call these flash operation APIs to store downloaded UPGRADE image on Internal or External Flash based on target platforms.

These callbacks are defind in ota-update library and expected to register these callbacks during OTA agent start. ota-bootloader-abstraction library has implementation of these bootloader specific storage interface APIs.

Functions
cy_rslt_t	cy_ota_mem_init (void)
	Initializes flash, QSPI flash, or any other external memory type. More...
cy_rslt_t	cy_ota_mem_read (cy_ota_mem_type_t mem_type, uint32_t addr, void *data, size_t len)
	Read from flash, QSPI flash, or any other external memory type. More...
cy_rslt_t	cy_ota_mem_write (cy_ota_mem_type_t mem_type, uint32_t addr, void *data, size_t len)
	Write to flash, QSPI flash, or any other external memory type. More...
cy_rslt_t	cy_ota_mem_erase (cy_ota_mem_type_t mem_type, uint32_t addr, size_t len)
	Erase flash, QSPI flash, or any other external memory type. More...
size_t	cy_ota_mem_get_prog_size (cy_ota_mem_type_t mem_type, uint32_t addr)
	To get page size for programming flash, QSPI flash, or any other external memory type. More...
size_t	cy_ota_mem_get_erase_size (cy_ota_mem_type_t mem_type, uint32_t addr)
	To get sector size of flash, QSPI flash, or any other external memory type. More...
cy_rslt_t	cy_ota_storage_init (void)
	Initialize Storage area. More...
cy_rslt_t	cy_ota_storage_open (cy_ota_storage_context_t *storage_ptr)
	Open storage area for storing OTA UPGRADE images. More...
cy_rslt_t	cy_ota_storage_read (cy_ota_storage_context_t *storage_ptr, cy_ota_storage_read_info_t *chunk_info)
	Read data from storage area. More...
cy_rslt_t	cy_ota_storage_write (cy_ota_storage_context_t *storage_ptr, cy_ota_storage_write_info_t *chunk_info)
	Write data to configured storage area. More...
cy_rslt_t	cy_ota_storage_close (cy_ota_storage_context_t *storage_ptr)
	Close Storage area for download. More...
cy_rslt_t	cy_ota_storage_verify (cy_ota_storage_context_t *storage_ptr)
	Verify downloaded UPGRADE OTA image. More...
cy_rslt_t	cy_ota_storage_set_boot_pending (cy_ota_storage_context_t *storage_ptr)
	Set boot pending. More...
cy_rslt_t	cy_ota_storage_get_boot_pending_status (uint16_t app_id, uint8_t *status)
	Get boot pending status of the image in inactive slot. More...
cy_rslt_t	cy_ota_storage_image_validate (uint16_t app_id)
	Application has validated the new OTA Image in active slot and committing it. More...
cy_rslt_t	cy_ota_storage_get_image_validate_status (uint16_t app_id, uint8_t *status)
	Get validate/commit status of the OTA Image in active slot. More...
cy_rslt_t	cy_ota_storage_get_app_info (uint16_t slot_id, uint16_t image_num, cy_ota_app_info_t *app_info)
	Get Application image information. More...
cy_rslt_t	cy_ota_storage_get_slot_state (uint16_t slot_id, uint16_t image_num, cy_ota_slot_state_t *state)
	Get Application slot state information. More...
cy_rslt_t	cy_ota_storage_set_slot_state (uint16_t slot_id, uint16_t image_num, cy_ota_slot_state_t state)
	Set Application slot state information. More...

Function Documentation

cy_rslt_t cy_ota_mem_init

(

void

)

Initializes flash, QSPI flash, or any other external memory type.

NOTE: This function must be implemented in the user's code.

Returns

CY_RSLT_SUCCESS on success CY_RSLT_TYPE_ERROR on failure

cy_rslt_t cy_ota_mem_read	(	cy_ota_mem_type_t	mem_type,
		uint32_t	addr,
		void *	data,
		size_t	len
	)

Read from flash, QSPI flash, or any other external memory type.

NOTE: This function must be implemented in the user's code.

Parameters

[in]	mem_type	Memory type cy_ota_mem_type_t
[in]	addr	Starting address to read from.
[out]	data	Pointer to the buffer to store the data read from the memory.
[in]	len	Number of data bytes to read.

Returns

CY_RSLT_SUCCESS on success CY_RSLT_TYPE_ERROR on failure

cy_rslt_t cy_ota_mem_write	(	cy_ota_mem_type_t	mem_type,
		uint32_t	addr,
		void *	data,
		size_t	len
	)

Write to flash, QSPI flash, or any other external memory type.

NOTE: This function must be implemented in the user's code.

Parameters

[in]	mem_type	Memory type cy_ota_mem_type_t
[in]	addr	Starting address to write to.
[in]	data	Pointer to the buffer containing the data to be written.
[in]	len	Number of bytes to write.

Returns

CY_RSLT_SUCCESS on success CY_RSLT_TYPE_ERROR on failure

cy_rslt_t cy_ota_mem_erase	(	cy_ota_mem_type_t	mem_type,
		uint32_t	addr,
		size_t	len
	)

Erase flash, QSPI flash, or any other external memory type.

NOTE: This function must be implemented in the user's code.

Parameters

[in]	mem_type	Memory type cy_ota_mem_type_t
[in]	addr	Starting address to begin erasing.
[in]	len	Number of bytes to erase.

Returns

CY_RSLT_SUCCESS CY_RSLT_TYPE_ERROR

size_t cy_ota_mem_get_prog_size	(	cy_ota_mem_type_t	mem_type,
		uint32_t	addr
	)

To get page size for programming flash, QSPI flash, or any other external memory type.

NOTE: This function must be implemented in the user's code.

Parameters

[in]	mem_type	Memory type cy_ota_mem_type_t
[in]	addr	Address that belongs to the sector for which programming page size needs to be returned.

Returns

Page size in bytes.

size_t cy_ota_mem_get_erase_size	(	cy_ota_mem_type_t	mem_type,
		uint32_t	addr
	)

To get sector size of flash, QSPI flash, or any other external memory type.

NOTE: This function must be implemented in the user's code.

Parameters

[in]	mem_type	Memory type cy_ota_mem_type_t
[in]	addr	Address that belongs to the sector for which sector erase size needs to be returned.

Returns

Sector size in bytes.

cy_rslt_t cy_ota_storage_init

(

void

)

Initialize Storage area.

NOTE: Typically, this initializes flash hardware and Application is expected to call this API once before any other flash operation.

Returns

CY_RSLT_SUCCESS CY_RSLT_TYPE_ERROR

cy_rslt_t cy_ota_storage_open

(

cy_ota_storage_context_t *

storage_ptr

)

Open storage area for storing OTA UPGRADE images.

NOTE: Typically, This erases UPGRADE Slots.

Parameters

[in]

storage_ptr

Pointer to the OTA Agent storage context 'cy_ota_storage_context_t'

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_OPEN_STORAGE

cy_rslt_t cy_ota_storage_read	(	cy_ota_storage_context_t *	storage_ptr,
		cy_ota_storage_read_info_t *	chunk_info
	)

Read data from storage area.

Parameters

[in]	storage_ptr	Pointer to the OTA Agent storage context 'cy_ota_storage_context_t'
[in]	chunk_info	Pointer to read chunk information, buffer pointer used for the read

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_READ_STORAGE

cy_rslt_t cy_ota_storage_write	(	cy_ota_storage_context_t *	storage_ptr,
		cy_ota_storage_write_info_t *	chunk_info
	)

Write data to configured storage area.

Parameters

[in]	storage_ptr	Pointer to the OTA Agent storage context 'cy_ota_storage_context_t'
[in]	chunk_info	Pointer to write data chunk information

Returns

CY_UNTAR_SUCCESS CY_UNTAR_ERROR

cy_rslt_t cy_ota_storage_close

(

cy_ota_storage_context_t *

storage_ptr

)

Close Storage area for download.

Parameters

[in]

storage_ptr

Pointer to the OTA Agent storage context 'cy_ota_storage_context_t'

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_CLOSE_STORAGE

cy_rslt_t cy_ota_storage_verify

(

cy_ota_storage_context_t *

storage_ptr

)

Verify downloaded UPGRADE OTA image.

Parameters

[in]

storage_ptr

Pointer to the OTA Agent storage context 'cy_ota_storage_context_t'

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_GENERAL

cy_rslt_t cy_ota_storage_set_boot_pending

(

cy_ota_storage_context_t *

storage_ptr

)

Set boot pending.

Marks the image in the inactive slot as pending. On the next reboot, the system will perform a one-time boot of the the inactive slot image.

Parameters

[in]

storage_ptr

Pointer to the OTA Agent storage context cy_ota_storage_context_t

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_GENERAL

cy_rslt_t cy_ota_storage_get_boot_pending_status	(	uint16_t	app_id,
		uint8_t *	status
	)

Get boot pending status of the image in inactive slot.

Parameters

[in]	app_id	Application ID.
[out]	status	Pointer to the status variable to store boot pending status. CY_MCUBOOT_SWAP_TYPE_NONE(1) CY_MCUBOOT_SWAP_TYPE_TEST(2) CY_MCUBOOT_SWAP_TYPE_PERM(3) CY_MCUBOOT_SWAP_TYPE_REVERT(4)

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_GENERAL

cy_rslt_t cy_ota_storage_image_validate

(

uint16_t

app_id

)

Application has validated the new OTA Image in active slot and committing it.

This call needs to be after reboot and Bootloader has started the upgrade version of Application.

Parameters

[in]

app_id

Application ID.

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_GENERAL

cy_rslt_t cy_ota_storage_get_image_validate_status	(	uint16_t	app_id,
		uint8_t *	status
	)

Get validate/commit status of the OTA Image in active slot.

This call needs to be after reboot and Bootloader has started the upgrade version of Application.

Parameters

[in]	app_id	Application ID.
[out]	status	Pointer to the status variable to store image validate status. CY_MCUBOOT_FLAG_SET(1) CY_MCUBOOT_FLAG_BAD(2) CY_MCUBOOT_FLAG_UNSET(3) CY_MCUBOOT_FLAG_ANY(4)

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_GENERAL

cy_rslt_t cy_ota_storage_get_app_info	(	uint16_t	slot_id,
		uint16_t	image_num,
		cy_ota_app_info_t *	app_info
	)

Get Application image information.

This call needs to be after reboot and Bootloader has started the upgrade version of Application.

Parameters

[in]	slot_id	Memory slot ID.
[in]	image_num	Image number.
[out]	app_info	Pointer to the OTA Application information structure.

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_GENERAL

cy_rslt_t cy_ota_storage_get_slot_state	(	uint16_t	slot_id,
		uint16_t	image_num,
		cy_ota_slot_state_t *	state
	)

Get Application slot state information.

Parameters

[in]	slot_id	Slot ID.
[in]	image_num	Image number.
[out]	state	Pointer to the OTA Application state variable.

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_GENERAL

cy_rslt_t cy_ota_storage_set_slot_state	(	uint16_t	slot_id,
		uint16_t	image_num,
		cy_ota_slot_state_t	state
	)

Set Application slot state information.

Parameters

[in]	slot_id	Slot ID.
[in]	image_num	Image number.
[out]	state	OTA Application state variable.

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_GENERAL