flash_api.h

00001 /** \addtogroup hal */
00002 /** @{*/
00003 
00004 /* mbed Microcontroller Library
00005  * Copyright (c) 2017 ARM Limited
00006  * SPDX-License-Identifier: Apache-2.0
00007  *
00008  * Licensed under the Apache License, Version 2.0 (the "License");
00009  * you may not use this file except in compliance with the License.
00010  * You may obtain a copy of the License at
00011  *
00012  *     http://www.apache.org/licenses/LICENSE-2.0
00013  *
00014  * Unless required by applicable law or agreed to in writing, software
00015  * distributed under the License is distributed on an "AS IS" BASIS,
00016  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00017  * See the License for the specific language governing permissions and
00018  * limitations under the License.
00019  */
00020 #ifndef MBED_FLASH_API_H
00021 #define MBED_FLASH_API_H
00022 
00023 #include "device.h"
00024 #include <stdint.h>
00025 
00026 #if DEVICE_FLASH
00027 
00028 #define MBED_FLASH_INVALID_SIZE     0xFFFFFFFF
00029 
00030 typedef struct flash_s flash_t;
00031 
00032 #if TARGET_FLASH_CMSIS_ALGO
00033 #include "flash_data.h"
00034 #endif
00035 
00036 #ifdef __cplusplus
00037 extern "C" {
00038 #endif
00039 
00040 /**
00041  * \defgroup flash_hal Flash HAL API
00042  * @{
00043  */
00044 
00045 /** Initialize the flash peripheral and the flash_t object
00046  *
00047  * @param obj The flash object
00048  * @return 0 for success, -1 for error
00049  */
00050 int32_t flash_init(flash_t *obj);
00051 
00052 /** Uninitialize the flash peripheral and the flash_t object
00053  *
00054  * @param obj The flash object
00055  * @return 0 for success, -1 for error
00056  */
00057 int32_t flash_free(flash_t *obj);
00058 
00059 /** Erase one sector starting at defined address
00060  *
00061  * The address should be at sector boundary. This function does not do any check for address alignments
00062  * @param obj The flash object
00063  * @param address The sector starting address
00064  * @return 0 for success, -1 for error
00065  */
00066 int32_t flash_erase_sector(flash_t *obj, uint32_t address);
00067 
00068 /** Read data starting at defined address
00069  *
00070  * This function has a WEAK implementation using memcpy for backwards compatibility.
00071  * @param obj The flash object
00072  * @param address Address to begin reading from
00073  * @param data The buffer to read data into
00074  * @param size The number of bytes to read
00075  * @return 0 for success, -1 for error
00076  */
00077 int32_t flash_read(flash_t *obj, uint32_t address, uint8_t *data, uint32_t size);
00078 
00079 /** Program pages starting at defined address
00080  *
00081  * The pages should not cross multiple sectors.
00082  * This function does not do any check for address alignments or if size is aligned to a page size.
00083  * @param obj The flash object
00084  * @param address The sector starting address
00085  * @param data The data buffer to be programmed
00086  * @param size The number of bytes to program
00087  * @return 0 for success, -1 for error
00088  */
00089 int32_t flash_program_page(flash_t *obj, uint32_t address, const uint8_t *data, uint32_t size);
00090 
00091 /** Get sector size
00092  *
00093  * @param obj The flash object
00094  * @param address The sector starting address
00095  * @return The size of a sector
00096  */
00097 uint32_t flash_get_sector_size(const flash_t *obj, uint32_t address);
00098 
00099 /** Get page size
00100  *
00101  * The page size defines the writable page size
00102  * @param obj The flash object
00103  * @return The size of a page
00104  */
00105 uint32_t flash_get_page_size(const flash_t *obj);
00106 
00107 /** Get start address for the flash region
00108  *
00109  * @param obj The flash object
00110  * @return The start address for the flash region
00111  */
00112 uint32_t flash_get_start_address(const flash_t *obj);
00113 
00114 /** Get the flash region size
00115  *
00116  * @param obj The flash object
00117  * @return The flash region size
00118  */
00119 uint32_t flash_get_size(const flash_t *obj);
00120 
00121 /** Get the flash erase value
00122  *
00123  * @param obj The flash object
00124  * @return The flash erase value
00125  */
00126 uint8_t flash_get_erase_value(const flash_t *obj);
00127 
00128 /**@}*/
00129 
00130 #ifdef __cplusplus
00131 }
00132 #endif
00133 
00134 #endif
00135 
00136 #endif
00137 
00138 /** @}*/