0ef1717155
Some checks failed
Basic Checks / license-check (push) Has been cancelled
Basic Checks / include-check (push) Has been cancelled
Basic Checks / style-check (push) Has been cancelled
Basic Checks / docs-check (push) Has been cancelled
Basic Checks / python-tests (push) Has been cancelled
Basic Checks / pin-validation (push) Has been cancelled
Basic Checks / cmake-checks (push) Has been cancelled
Basic Checks / frozen-tools-check (push) Has been cancelled
Publish or Update docker image for head of branch / prepare-tags (push) Has been cancelled
Release or update docker image for a released mbed-os version / prepare-tags (push) Has been cancelled
Publish or Update docker image for head of branch / build-container (push) Has been cancelled
Publish or Update docker image for head of branch / test-container (linux/amd64) (push) Has been cancelled
Publish or Update docker image for head of branch / test-container (linux/arm64) (push) Has been cancelled
Publish or Update docker image for head of branch / deploy-container (push) Has been cancelled
Release or update docker image for a released mbed-os version / build-container (push) Has been cancelled
Release or update docker image for a released mbed-os version / test-container (linux/amd64) (push) Has been cancelled
Release or update docker image for a released mbed-os version / test-container (linux/arm64) (push) Has been cancelled
Release or update docker image for a released mbed-os version / deploy-container (push) Has been cancelled
Prune temporary docker images / prune-images (push) Has been cancelled
286 lines
12 KiB
C
286 lines
12 KiB
C
/***************************************************************************//**
|
|
* \file cyhal_flash.h
|
|
*
|
|
* \brief
|
|
* Provides a high level interface for interacting with the Cypress Flash memory.
|
|
* This interface abstracts out the chip specific details. If any chip specific
|
|
* functionality is necessary, or performance is critical the low level functions
|
|
* can be used directly.
|
|
*
|
|
********************************************************************************
|
|
* \copyright
|
|
* Copyright 2018-2021 Cypress Semiconductor Corporation
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*
|
|
* 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
|
|
*
|
|
* 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.
|
|
*******************************************************************************/
|
|
|
|
/**
|
|
* \addtogroup group_hal_flash Flash (Flash System Routine)
|
|
* \ingroup group_hal
|
|
* \{
|
|
* High level interface to the internal flash memory.
|
|
*
|
|
* Flash memory provides non-volatile storage for user firmware, user configuration
|
|
* data, and bulk data storage.
|
|
*
|
|
* This driver allows data to be read from and written to flash. It also provides the
|
|
* ability to obtain information about the address and characteristics of the flash
|
|
* block(s) contained on the device. During flash write time, the device should not be
|
|
* reset (including XRES pin, software reset, and watchdog) or unexpected changes may
|
|
* be made to portions of the flash. Also, the low-voltage detect circuits should be
|
|
* configured to generate an interrupt instead of a reset.
|
|
*
|
|
* \note A Read while Write violation may occur for some devices when a flash Read
|
|
* operation is initiated in the same or neighboring flash sector where the flash
|
|
* Write, Erase, or Program operation is working. Refer the the device datasheet
|
|
* for more information. This violation may cause a HardFault exception. To avoid
|
|
* the Read while Write violation, the user must carefully split the Read and Write
|
|
* operations on flash sectors which are not neighboring, considering all cores in
|
|
* a multi-processor device. You may edit the linker script to place the code into
|
|
* neighboring sectors. For example, use sectors number 0 and 1 for code and sectors
|
|
* 2 and 3 for data storage.
|
|
*
|
|
* \section features Features
|
|
* * Flash operations are performed on a per-sector basis
|
|
* * Supports blocking or partially blocking erase, program and write
|
|
* \section code_snippet Code Snippets
|
|
* \subsection subsection_flash_use_case_1 Snippet 1: Discovering flash characteristics
|
|
* Following code snippet demonstrates how to discover flash characteristics. Refer \ref
|
|
* cyhal_flash_info_t for more information.
|
|
* \snippet hal_flash.c snippet_cyhal_flash_get_flash_info
|
|
*
|
|
* \subsection subsection_flash_use_case_2 Snippet 2: Blocking Flash Write Operation
|
|
* Following code snippet demonstrates blocking flash write.
|
|
* It uses a constant array with a size equaling the size of one flash row. This
|
|
* array is placed at an address in flash such that it occupies one complete flash row.
|
|
* It uses blocking flash write operation which blocks the caller until the write is
|
|
* completed. It then verifies the flash data by comparing the flash data with the
|
|
* written data.
|
|
* \snippet hal_flash.c flag_snippet_cyhal_flash_blocking_mode_flashwrite
|
|
* \note It is recommended to declare the flash array as global variable.
|
|
*
|
|
* \subsection subsection_flash_use_case_3 Snippet 3: Non-blocking Flash Write Operation using polling
|
|
* Following code snippet implements the non-blocking flash write using polling to
|
|
* complete the flash write operation. It uses a constant array with a size equaling
|
|
* the size of one flash row. This array is placed at an address in flash such that it
|
|
* occupies one complete flash row. It uses a polling method to complete the flash
|
|
* write operation. It then verifies the flash data by comparing the flash data with
|
|
* the written data.
|
|
* \snippet hal_flash.c flag_snippet_cyhal_flash_partially_blocking_mode_polling_flashwrite
|
|
* \note It is recommended to declare the flash array as global variable.
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#include <stdint.h>
|
|
#include <stdbool.h>
|
|
#include "cy_result.h"
|
|
#include "cyhal_hw_types.h"
|
|
|
|
#if defined(__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
/*******************************************************************************
|
|
* Defines
|
|
*******************************************************************************/
|
|
|
|
/** \addtogroup group_hal_results_flash Flash HAL Results
|
|
* Flash specific return codes
|
|
* \ingroup group_hal_results
|
|
* \{ *//**
|
|
*/
|
|
|
|
/** Invalid argument */
|
|
#define CYHAL_FLASH_RSLT_ERR_ADDRESS \
|
|
(CYHAL_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CYHAL_RSLT_MODULE_FLASH, 0))
|
|
/** API is not supported */
|
|
#define CYHAL_FLASH_RSLT_ERR_NOT_SUPPORTED \
|
|
(CYHAL_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CYHAL_RSLT_MODULE_FLASH, 1))
|
|
/** Unable to support due to power state */
|
|
/**
|
|
* \}
|
|
*/
|
|
|
|
/** @brief Information about a single block of flash memory */
|
|
typedef struct
|
|
{
|
|
uint32_t start_address; //!< Start address of the memory
|
|
uint32_t size; //!< Size of the flash memory
|
|
uint32_t sector_size; //!< Sector size of the memory
|
|
uint32_t page_size; //!< Page size of the memory
|
|
uint8_t erase_value; //!< The flash erase value
|
|
} cyhal_flash_block_info_t;
|
|
|
|
/** @brief Information about all of the blocks of flash memory */
|
|
typedef struct
|
|
{
|
|
uint8_t block_count; //!< The number of distinct flash blocks
|
|
const cyhal_flash_block_info_t *blocks; //!< Array of the distinct flash blocks
|
|
} cyhal_flash_info_t;
|
|
|
|
|
|
/*******************************************************************************
|
|
* Functions
|
|
*******************************************************************************/
|
|
|
|
/** Initialize the \ref cyhal_flash_t object for accessing flash through the HAL
|
|
*
|
|
* @param[out] obj Pointer to a flash object. The caller must allocate the memory
|
|
* for this object but the init function will initialize its contents.
|
|
* @return The status of the init request. Returns \ref CY_RSLT_SUCCESS on successful operation.
|
|
*/
|
|
cy_rslt_t cyhal_flash_init(cyhal_flash_t *obj);
|
|
|
|
/** Free resources associated with flash object through the HAL.
|
|
*
|
|
* @param[out] obj The flash object.
|
|
*
|
|
*/
|
|
void cyhal_flash_free(cyhal_flash_t *obj);
|
|
|
|
/** Gets flash characteristics like the start address, size, erase values etc.
|
|
* Refer \ref cyhal_flash_info_t for more information.
|
|
*
|
|
* @param[in] obj The flash object.
|
|
* @param[out] info The flash characteristic info.
|
|
*
|
|
* Refer \ref subsection_flash_use_case_1 for more information.
|
|
*/
|
|
void cyhal_flash_get_info(const cyhal_flash_t *obj, cyhal_flash_info_t *info);
|
|
|
|
/** Read data starting at a defined address.
|
|
*
|
|
* @param[in] obj The flash object.
|
|
* @param[in] address Address to begin reading from.
|
|
* @param[out] data The buffer to read data into.
|
|
* @param[in] size The number of bytes to read.
|
|
* @return The status of the read request. Returns \ref CY_RSLT_SUCCESS on successful operation.
|
|
*
|
|
* Refer \ref subsection_flash_use_case_2 for more information.
|
|
*
|
|
*/
|
|
cy_rslt_t cyhal_flash_read(cyhal_flash_t *obj, uint32_t address, uint8_t *data, size_t size);
|
|
|
|
/** Erase one page starting at a defined address. The address must be at page boundary. This
|
|
* will block until the erase operation is complete.
|
|
*
|
|
* @see cyhal_flash_get_info() to get the flash characteristics for legal address values and
|
|
* the page erase size.
|
|
*
|
|
* @param[in] obj The flash object
|
|
* @param[in] address The page starting address
|
|
* @return The status of the erase request. Returns \ref CY_RSLT_SUCCESS on successful operation.
|
|
*
|
|
* Refer \ref subsection_flash_use_case_2 for more information.
|
|
*/
|
|
cy_rslt_t cyhal_flash_erase(cyhal_flash_t *obj, uint32_t address);
|
|
|
|
/** This function erases the page and writes the new data into the page starting at a defined address. The address must be at page boundary. This
|
|
* will block until the write operation is complete.
|
|
*
|
|
*
|
|
* @see cyhal_flash_get_info() to get the flash characteristics for legal address values and
|
|
* the page write size. The provided data buffer must be at least as large as the flash
|
|
* page_size.
|
|
*
|
|
* @param[in] obj The flash object
|
|
* @param[in] address The page starting address
|
|
* @param[in] data The data to write to the flash
|
|
* @return The status of the write request. Returns \ref CY_RSLT_SUCCESS on successful operation.
|
|
*
|
|
* Refer \ref subsection_flash_use_case_2 for more information.
|
|
*/
|
|
cy_rslt_t cyhal_flash_write(cyhal_flash_t *obj, uint32_t address, const uint32_t *data);
|
|
|
|
/** Program one page with given data starting at defined address. The address must be at page boundary. This
|
|
* will block until the write operation is complete.
|
|
* \note This function does not erase the page prior to writing. The page must be erased
|
|
* first via a separate call to erase.
|
|
*
|
|
* @see cyhal_flash_get_info() to get the flash characteristics for legal address values and
|
|
* the total page size. The provided data buffer must be at least as large as the flash
|
|
* page_size.
|
|
*
|
|
* @param[in] obj The flash object
|
|
* @param[in] address The sector starting address
|
|
* @param[in] data The data buffer to be programmed
|
|
* @return The status of the program request. Returns \ref CY_RSLT_SUCCESS on successful operation.
|
|
*/
|
|
cy_rslt_t cyhal_flash_program(cyhal_flash_t *obj, uint32_t address, const uint32_t *data);
|
|
|
|
/** Starts an asynchronous erase of a single page of flash. Returns immediately and reports
|
|
* a successful start or reason for failure. The address must be aligned on a page boundary.
|
|
*
|
|
* @see cyhal_flash_get_info() to get the flash characteristics for legal address values and
|
|
* the page erase size.
|
|
*
|
|
* @param[in] obj The Flash object being operated on
|
|
* @param[in] address The address to start erasing from
|
|
* @return The status of the start_erase request.
|
|
*
|
|
* Refer \ref subsection_flash_use_case_3 for more information.
|
|
*/
|
|
cy_rslt_t cyhal_flash_start_erase(cyhal_flash_t *obj, uint32_t address);
|
|
|
|
/** Starts an asynchronous write to a single page of flash. Returns immediately and reports
|
|
* a successful start or reason for failure. The address must be aligned on a page boundary.
|
|
*
|
|
* @see cyhal_flash_get_info() to get the flash characteristics for legal address values and
|
|
* the page write size. The provided data buffer must be at least as large as the flash
|
|
* page_size.
|
|
*
|
|
* @param[in] obj The Flash object being operated on
|
|
* @param[in] address The address to start writing to
|
|
* @param[in] data The data to write to flash
|
|
* @return The status of the start_write request.
|
|
*
|
|
* Refer \ref subsection_flash_use_case_3 for more information.
|
|
*/
|
|
cy_rslt_t cyhal_flash_start_write(cyhal_flash_t *obj, uint32_t address, const uint32_t* data);
|
|
|
|
/** Starts asynchronous programming of a single page of flash. Returns immediately and reports
|
|
* a successful start or reason for failure.
|
|
*
|
|
* \note Perform erase operation prior to calling this.
|
|
*
|
|
* @see cyhal_flash_get_info() to get the flash characteristics for legal address values and
|
|
* the total page size. The provided data buffer must be at least as large as the flash
|
|
* page_size.
|
|
*
|
|
* @param[in] obj The Flash object being operated on
|
|
* @param[in] address The address to start programming
|
|
* @param[in] data The data to write to flash
|
|
* @return The status of the start_program request. Returns \ref CY_RSLT_SUCCESS on successful operation.
|
|
*/
|
|
cy_rslt_t cyhal_flash_start_program(cyhal_flash_t *obj, uint32_t address, const uint32_t* data);
|
|
|
|
/** Reports status of the flash operation
|
|
*
|
|
* @param[in] obj The Flash object being operated on
|
|
* @return true if flash operation is complete. false otherwise.
|
|
*/
|
|
bool cyhal_flash_is_operation_complete(cyhal_flash_t *obj);
|
|
|
|
|
|
#if defined(__cplusplus)
|
|
}
|
|
#endif
|
|
|
|
#ifdef CYHAL_FLASH_IMPL_HEADER
|
|
#include CYHAL_FLASH_IMPL_HEADER
|
|
#endif /* CYHAL_FLASH_IMPL_HEADER */
|
|
|
|
/** \} group_hal_flash */
|