Loading...
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 | /*
* Copyright (c) 2017 Nordic Semiconductor ASA
* Copyright (c) 2016 Intel Corporation
*
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @file
* @brief Public API for FLASH drivers
*/
#ifndef ZEPHYR_INCLUDE_FLASH_H_
#define ZEPHYR_INCLUDE_FLASH_H_
/**
* @brief FLASH Interface
* @defgroup flash_interface FLASH Interface
* @ingroup io_interfaces
* @{
*/
#include <zephyr/types.h>
#include <stddef.h>
#include <sys/types.h>
#include <device.h>
#ifdef __cplusplus
extern "C" {
#endif
#if defined(CONFIG_FLASH_PAGE_LAYOUT)
struct flash_pages_layout {
size_t pages_count; /* count of pages sequence of the same size */
size_t pages_size;
};
#endif /* CONFIG_FLASH_PAGE_LAYOUT */
typedef int (*flash_api_read)(struct device *dev, off_t offset, void *data,
size_t len);
typedef int (*flash_api_write)(struct device *dev, off_t offset,
const void *data, size_t len);
typedef int (*flash_api_erase)(struct device *dev, off_t offset, size_t size);
typedef int (*flash_api_write_protection)(struct device *dev, bool enable);
#if defined(CONFIG_FLASH_PAGE_LAYOUT)
/**
* @brief Retrieve a flash device's layout.
*
* A flash device layout is a run-length encoded description of the
* pages on the device. (Here, "page" means the smallest erasable
* area on the flash device.)
*
* For flash memories which have uniform page sizes, this routine
* returns an array of length 1, which specifies the page size and
* number of pages in the memory.
*
* Layouts for flash memories with nonuniform page sizes will be
* returned as an array with multiple elements, each of which
* describes a group of pages that all have the same size. In this
* case, the sequence of array elements specifies the order in which
* these groups occur on the device.
*
* @param dev Flash device whose layout to retrieve.
* @param layout The flash layout will be returned in this argument.
* @param layout_size The number of elements in the returned layout.
*/
typedef void (*flash_api_pages_layout)(struct device *dev,
const struct flash_pages_layout **layout,
size_t *layout_size);
#endif /* CONFIG_FLASH_PAGE_LAYOUT */
struct flash_driver_api {
flash_api_read read;
flash_api_write write;
flash_api_erase erase;
flash_api_write_protection write_protection;
#if defined(CONFIG_FLASH_PAGE_LAYOUT)
flash_api_pages_layout page_layout;
#endif /* CONFIG_FLASH_PAGE_LAYOUT */
const size_t write_block_size;
};
/**
* @brief Read data from flash
*
* @param dev : flash dev
* @param offset : Offset (byte aligned) to read
* @param data : Buffer to store read data
* @param len : Number of bytes to read.
*
* @return 0 on success, negative errno code on fail.
*/
__syscall int flash_read(struct device *dev, off_t offset, void *data,
size_t len);
static inline int z_impl_flash_read(struct device *dev, off_t offset, void *data,
size_t len)
{
const struct flash_driver_api *api = dev->driver_api;
return api->read(dev, offset, data, len);
}
/**
* @brief Write buffer into flash memory.
*
* Prior to the invocation of this API, the flash_write_protection_set needs
* to be called first to disable the write protection.
*
* @param dev : flash device
* @param offset : starting offset for the write
* @param data : data to write
* @param len : Number of bytes to write
*
* @return 0 on success, negative errno code on fail.
*/
__syscall int flash_write(struct device *dev, off_t offset, const void *data,
size_t len);
static inline int z_impl_flash_write(struct device *dev, off_t offset,
const void *data, size_t len)
{
const struct flash_driver_api *api = dev->driver_api;
return api->write(dev, offset, data, len);
}
/**
* @brief Erase part or all of a flash memory
*
* Acceptable values of erase size and offset are subject to
* hardware-specific multiples of page size and offset. Please check
* the API implemented by the underlying sub driver, for example by
* using flash_get_page_info_by_offs() if that is supported by your
* flash driver.
*
* Prior to the invocation of this API, the flash_write_protection_set needs
* to be called first to disable the write protection.
*
* @param dev : flash device
* @param offset : erase area starting offset
* @param size : size of area to be erased
*
* @return 0 on success, negative errno code on fail.
*
* @see flash_get_page_info_by_offs()
* @see flash_get_page_info_by_idx()
*/
__syscall int flash_erase(struct device *dev, off_t offset, size_t size);
static inline int z_impl_flash_erase(struct device *dev, off_t offset,
size_t size)
{
const struct flash_driver_api *api = dev->driver_api;
return api->erase(dev, offset, size);
}
/**
* @brief Enable or disable write protection for a flash memory
*
* This API is required to be called before the invocation of write or erase
* API. Please note that on some flash components, the write protection is
* automatically turned on again by the device after the completion of each
* write or erase calls. Therefore, on those flash parts, write protection needs
* to be disabled before each invocation of the write or erase API. Please refer
* to the sub-driver API or the data sheet of the flash component to get details
* on the write protection behavior.
*
* @param dev : flash device
* @param enable : enable or disable flash write protection
*
* @return 0 on success, negative errno code on fail.
*/
__syscall int flash_write_protection_set(struct device *dev, bool enable);
static inline int z_impl_flash_write_protection_set(struct device *dev,
bool enable)
{
const struct flash_driver_api *api = dev->driver_api;
return api->write_protection(dev, enable);
}
struct flash_pages_info {
off_t start_offset; /* offset from the base of flash address */
size_t size;
u32_t index;
};
#if defined(CONFIG_FLASH_PAGE_LAYOUT)
/**
* @brief Get the size and start offset of flash page at certain flash offset.
*
* @param dev flash device
* @param offset Offset within the page
* @param info Page Info structure to be filled
*
* @return 0 on success, -EINVAL if page of the offset doesn't exist.
*/
__syscall int flash_get_page_info_by_offs(struct device *dev, off_t offset,
struct flash_pages_info *info);
/**
* @brief Get the size and start offset of flash page of certain index.
*
* @param dev flash device
* @param page_index Index of the page. Index are counted from 0.
* @param info Page Info structure to be filled
*
* @return 0 on success, -EINVAL if page of the index doesn't exist.
*/
__syscall int flash_get_page_info_by_idx(struct device *dev, u32_t page_index,
struct flash_pages_info *info);
/**
* @brief Get the total number of flash pages.
*
* @param dev flash device
*
* @return Number of flash pages.
*/
__syscall size_t flash_get_page_count(struct device *dev);
/**
* @brief Callback type for iterating over flash pages present on a device.
*
* The callback should return true to continue iterating, and false to halt.
*
* @param info Information for current page
* @param data Private data for callback
* @return True to continue iteration, false to halt iteration.
* @see flash_page_foreach()
*/
typedef bool (*flash_page_cb)(const struct flash_pages_info *info, void *data);
/**
* @brief Iterate over all flash pages on a device
*
* This routine iterates over all flash pages on the given device,
* ordered by increasing start offset. For each page, it invokes the
* given callback, passing it the page's information and a private
* data object.
*
* @param dev Device whose pages to iterate over
* @param cb Callback to invoke for each flash page
* @param data Private data for callback function
*/
void flash_page_foreach(struct device *dev, flash_page_cb cb, void *data);
#endif /* CONFIG_FLASH_PAGE_LAYOUT */
/**
* @brief Get the minimum write block size supported by the driver
*
* The write block size supported by the driver might differ from the write
* block size of memory used because the driver might implements write-modify
* algorithm.
*
* @param dev flash device
*
* @return write block size in bytes.
*/
__syscall size_t flash_get_write_block_size(struct device *dev);
static inline size_t z_impl_flash_get_write_block_size(struct device *dev)
{
const struct flash_driver_api *api = dev->driver_api;
return api->write_block_size;
}
#ifdef __cplusplus
}
#endif
/**
* @}
*/
#include <syscalls/flash.h>
#endif /* ZEPHYR_INCLUDE_FLASH_H_ */
|