Kev Mann / mbed-dev-OS5_10_4

features/storage/blockdevice/BlockDevice.h@0:38ceb79fef03, 2018-11-28 (annotated)

Committer:
kevman
Date:
Wed Nov 28 15:10:15 2018 +0000
Revision:
0:38ceb79fef03
RTC modified

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kevman 0:38ceb79fef03 1 /* mbed Microcontroller Library
kevman 0:38ceb79fef03 2 * Copyright (c) 2017 ARM Limited
kevman 0:38ceb79fef03 3 *
kevman 0:38ceb79fef03 4 * Licensed under the Apache License, Version 2.0 (the "License");
kevman 0:38ceb79fef03 5 * you may not use this file except in compliance with the License.
kevman 0:38ceb79fef03 6 * You may obtain a copy of the License at
kevman 0:38ceb79fef03 7 *
kevman 0:38ceb79fef03 8 * http://www.apache.org/licenses/LICENSE-2.0
kevman 0:38ceb79fef03 9 *
kevman 0:38ceb79fef03 10 * Unless required by applicable law or agreed to in writing, software
kevman 0:38ceb79fef03 11 * distributed under the License is distributed on an "AS IS" BASIS,
kevman 0:38ceb79fef03 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
kevman 0:38ceb79fef03 13 * See the License for the specific language governing permissions and
kevman 0:38ceb79fef03 14 * limitations under the License.
kevman 0:38ceb79fef03 15 */
kevman 0:38ceb79fef03 16
kevman 0:38ceb79fef03 17 #ifndef MBED_BLOCK_DEVICE_H
kevman 0:38ceb79fef03 18 #define MBED_BLOCK_DEVICE_H
kevman 0:38ceb79fef03 19
kevman 0:38ceb79fef03 20 #include <stdint.h>
kevman 0:38ceb79fef03 21
kevman 0:38ceb79fef03 22
kevman 0:38ceb79fef03 23 /** Enum of standard error codes
kevman 0:38ceb79fef03 24 *
kevman 0:38ceb79fef03 25 * @enum bd_error
kevman 0:38ceb79fef03 26 */
kevman 0:38ceb79fef03 27 enum bd_error {
kevman 0:38ceb79fef03 28 BD_ERROR_OK = 0, /*!< no error */
kevman 0:38ceb79fef03 29 BD_ERROR_DEVICE_ERROR = -4001, /*!< device specific error */
kevman 0:38ceb79fef03 30 };
kevman 0:38ceb79fef03 31
kevman 0:38ceb79fef03 32 /** Type representing the address of a specific block
kevman 0:38ceb79fef03 33 */
kevman 0:38ceb79fef03 34 typedef uint64_t bd_addr_t;
kevman 0:38ceb79fef03 35
kevman 0:38ceb79fef03 36 /** Type representing a quantity of 8-bit bytes
kevman 0:38ceb79fef03 37 */
kevman 0:38ceb79fef03 38 typedef uint64_t bd_size_t;
kevman 0:38ceb79fef03 39
kevman 0:38ceb79fef03 40
kevman 0:38ceb79fef03 41 /** A hardware device capable of writing and reading blocks
kevman 0:38ceb79fef03 42 */
kevman 0:38ceb79fef03 43 class BlockDevice
kevman 0:38ceb79fef03 44 {
kevman 0:38ceb79fef03 45 public:
kevman 0:38ceb79fef03 46
kevman 0:38ceb79fef03 47 /** Return the default block device
kevman 0:38ceb79fef03 48 *
kevman 0:38ceb79fef03 49 * Returns the default BlockDevice base on configuration json.
kevman 0:38ceb79fef03 50 * Use the components in target.json or application config to change
kevman 0:38ceb79fef03 51 * the default block device.
kevman 0:38ceb79fef03 52 *
kevman 0:38ceb79fef03 53 * An application can override all target settings by implementing
kevman 0:38ceb79fef03 54 * BlockDevice::get_default_instance() themselves - the default
kevman 0:38ceb79fef03 55 * definition is weak, and calls get_target_default_instance().
kevman 0:38ceb79fef03 56 */
kevman 0:38ceb79fef03 57 static BlockDevice *get_default_instance();
kevman 0:38ceb79fef03 58
kevman 0:38ceb79fef03 59 /** Lifetime of a block device
kevman 0:38ceb79fef03 60 */
kevman 0:38ceb79fef03 61 virtual ~BlockDevice() {};
kevman 0:38ceb79fef03 62
kevman 0:38ceb79fef03 63 /** Initialize a block device
kevman 0:38ceb79fef03 64 *
kevman 0:38ceb79fef03 65 * @return 0 on success or a negative error code on failure
kevman 0:38ceb79fef03 66 */
kevman 0:38ceb79fef03 67 virtual int init() = 0;
kevman 0:38ceb79fef03 68
kevman 0:38ceb79fef03 69 /** Deinitialize a block device
kevman 0:38ceb79fef03 70 *
kevman 0:38ceb79fef03 71 * @return 0 on success or a negative error code on failure
kevman 0:38ceb79fef03 72 */
kevman 0:38ceb79fef03 73 virtual int deinit() = 0;
kevman 0:38ceb79fef03 74
kevman 0:38ceb79fef03 75 /** Ensure data on storage is in sync with the driver
kevman 0:38ceb79fef03 76 *
kevman 0:38ceb79fef03 77 * @return 0 on success or a negative error code on failure
kevman 0:38ceb79fef03 78 */
kevman 0:38ceb79fef03 79 virtual int sync()
kevman 0:38ceb79fef03 80 {
kevman 0:38ceb79fef03 81 return 0;
kevman 0:38ceb79fef03 82 }
kevman 0:38ceb79fef03 83
kevman 0:38ceb79fef03 84 /** Read blocks from a block device
kevman 0:38ceb79fef03 85 *
kevman 0:38ceb79fef03 86 * If a failure occurs, it is not possible to determine how many bytes succeeded
kevman 0:38ceb79fef03 87 *
kevman 0:38ceb79fef03 88 * @param buffer Buffer to write blocks to
kevman 0:38ceb79fef03 89 * @param addr Address of block to begin reading from
kevman 0:38ceb79fef03 90 * @param size Size to read in bytes, must be a multiple of read block size
kevman 0:38ceb79fef03 91 * @return 0 on success, negative error code on failure
kevman 0:38ceb79fef03 92 */
kevman 0:38ceb79fef03 93 virtual int read(void *buffer, bd_addr_t addr, bd_size_t size) = 0;
kevman 0:38ceb79fef03 94
kevman 0:38ceb79fef03 95 /** Program blocks to a block device
kevman 0:38ceb79fef03 96 *
kevman 0:38ceb79fef03 97 * The blocks must have been erased prior to being programmed
kevman 0:38ceb79fef03 98 *
kevman 0:38ceb79fef03 99 * If a failure occurs, it is not possible to determine how many bytes succeeded
kevman 0:38ceb79fef03 100 *
kevman 0:38ceb79fef03 101 * @param buffer Buffer of data to write to blocks
kevman 0:38ceb79fef03 102 * @param addr Address of block to begin writing to
kevman 0:38ceb79fef03 103 * @param size Size to write in bytes, must be a multiple of program block size
kevman 0:38ceb79fef03 104 * @return 0 on success, negative error code on failure
kevman 0:38ceb79fef03 105 */
kevman 0:38ceb79fef03 106 virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size) = 0;
kevman 0:38ceb79fef03 107
kevman 0:38ceb79fef03 108 /** Erase blocks on a block device
kevman 0:38ceb79fef03 109 *
kevman 0:38ceb79fef03 110 * The state of an erased block is undefined until it has been programmed,
kevman 0:38ceb79fef03 111 * unless get_erase_value returns a non-negative byte value
kevman 0:38ceb79fef03 112 *
kevman 0:38ceb79fef03 113 * @param addr Address of block to begin erasing
kevman 0:38ceb79fef03 114 * @param size Size to erase in bytes, must be a multiple of erase block size
kevman 0:38ceb79fef03 115 * @return 0 on success, negative error code on failure
kevman 0:38ceb79fef03 116 */
kevman 0:38ceb79fef03 117 virtual int erase(bd_addr_t addr, bd_size_t size)
kevman 0:38ceb79fef03 118 {
kevman 0:38ceb79fef03 119 return 0;
kevman 0:38ceb79fef03 120 }
kevman 0:38ceb79fef03 121
kevman 0:38ceb79fef03 122 /** Mark blocks as no longer in use
kevman 0:38ceb79fef03 123 *
kevman 0:38ceb79fef03 124 * This function provides a hint to the underlying block device that a region of blocks
kevman 0:38ceb79fef03 125 * is no longer in use and may be erased without side effects. Erase must still be called
kevman 0:38ceb79fef03 126 * before programming, but trimming allows flash-translation-layers to schedule erases when
kevman 0:38ceb79fef03 127 * the device is not busy.
kevman 0:38ceb79fef03 128 *
kevman 0:38ceb79fef03 129 * @param addr Address of block to mark as unused
kevman 0:38ceb79fef03 130 * @param size Size to mark as unused in bytes, must be a multiple of erase block size
kevman 0:38ceb79fef03 131 * @return 0 on success, negative error code on failure
kevman 0:38ceb79fef03 132 */
kevman 0:38ceb79fef03 133 virtual int trim(bd_addr_t addr, bd_size_t size)
kevman 0:38ceb79fef03 134 {
kevman 0:38ceb79fef03 135 return 0;
kevman 0:38ceb79fef03 136 }
kevman 0:38ceb79fef03 137
kevman 0:38ceb79fef03 138 /** Get the size of a readable block
kevman 0:38ceb79fef03 139 *
kevman 0:38ceb79fef03 140 * @return Size of a readable block in bytes
kevman 0:38ceb79fef03 141 */
kevman 0:38ceb79fef03 142 virtual bd_size_t get_read_size() const = 0;
kevman 0:38ceb79fef03 143
kevman 0:38ceb79fef03 144 /** Get the size of a programmable block
kevman 0:38ceb79fef03 145 *
kevman 0:38ceb79fef03 146 * @return Size of a programmable block in bytes
kevman 0:38ceb79fef03 147 * @note Must be a multiple of the read size
kevman 0:38ceb79fef03 148 */
kevman 0:38ceb79fef03 149 virtual bd_size_t get_program_size() const = 0;
kevman 0:38ceb79fef03 150
kevman 0:38ceb79fef03 151 /** Get the size of an erasable block
kevman 0:38ceb79fef03 152 *
kevman 0:38ceb79fef03 153 * @return Size of an erasable block in bytes
kevman 0:38ceb79fef03 154 * @note Must be a multiple of the program size
kevman 0:38ceb79fef03 155 */
kevman 0:38ceb79fef03 156 virtual bd_size_t get_erase_size() const
kevman 0:38ceb79fef03 157 {
kevman 0:38ceb79fef03 158 return get_program_size();
kevman 0:38ceb79fef03 159 }
kevman 0:38ceb79fef03 160
kevman 0:38ceb79fef03 161 /** Get the size of an erasable block given address
kevman 0:38ceb79fef03 162 *
kevman 0:38ceb79fef03 163 * @param addr Address within the erasable block
kevman 0:38ceb79fef03 164 * @return Size of an erasable block in bytes
kevman 0:38ceb79fef03 165 * @note Must be a multiple of the program size
kevman 0:38ceb79fef03 166 */
kevman 0:38ceb79fef03 167 virtual bd_size_t get_erase_size(bd_addr_t addr) const
kevman 0:38ceb79fef03 168 {
kevman 0:38ceb79fef03 169 return get_erase_size();
kevman 0:38ceb79fef03 170 }
kevman 0:38ceb79fef03 171
kevman 0:38ceb79fef03 172 /** Get the value of storage when erased
kevman 0:38ceb79fef03 173 *
kevman 0:38ceb79fef03 174 * If get_erase_value returns a non-negative byte value, the underlying
kevman 0:38ceb79fef03 175 * storage is set to that value when erased, and storage containing
kevman 0:38ceb79fef03 176 * that value can be programmed without another erase.
kevman 0:38ceb79fef03 177 *
kevman 0:38ceb79fef03 178 * @return The value of storage when erased, or -1 if you can't
kevman 0:38ceb79fef03 179 * rely on the value of erased storage
kevman 0:38ceb79fef03 180 */
kevman 0:38ceb79fef03 181 virtual int get_erase_value() const
kevman 0:38ceb79fef03 182 {
kevman 0:38ceb79fef03 183 return -1;
kevman 0:38ceb79fef03 184 }
kevman 0:38ceb79fef03 185
kevman 0:38ceb79fef03 186 /** Get the total size of the underlying device
kevman 0:38ceb79fef03 187 *
kevman 0:38ceb79fef03 188 * @return Size of the underlying device in bytes
kevman 0:38ceb79fef03 189 */
kevman 0:38ceb79fef03 190 virtual bd_size_t size() const = 0;
kevman 0:38ceb79fef03 191
kevman 0:38ceb79fef03 192 /** Convenience function for checking block read validity
kevman 0:38ceb79fef03 193 *
kevman 0:38ceb79fef03 194 * @param addr Address of block to begin reading from
kevman 0:38ceb79fef03 195 * @param size Size to read in bytes
kevman 0:38ceb79fef03 196 * @return True if read is valid for underlying block device
kevman 0:38ceb79fef03 197 */
kevman 0:38ceb79fef03 198 bool is_valid_read(bd_addr_t addr, bd_size_t size) const
kevman 0:38ceb79fef03 199 {
kevman 0:38ceb79fef03 200 return (
kevman 0:38ceb79fef03 201 addr % get_read_size() == 0 &&
kevman 0:38ceb79fef03 202 size % get_read_size() == 0 &&
kevman 0:38ceb79fef03 203 addr + size <= this->size());
kevman 0:38ceb79fef03 204 }
kevman 0:38ceb79fef03 205
kevman 0:38ceb79fef03 206 /** Convenience function for checking block program validity
kevman 0:38ceb79fef03 207 *
kevman 0:38ceb79fef03 208 * @param addr Address of block to begin writing to
kevman 0:38ceb79fef03 209 * @param size Size to write in bytes
kevman 0:38ceb79fef03 210 * @return True if program is valid for underlying block device
kevman 0:38ceb79fef03 211 */
kevman 0:38ceb79fef03 212 bool is_valid_program(bd_addr_t addr, bd_size_t size) const
kevman 0:38ceb79fef03 213 {
kevman 0:38ceb79fef03 214 return (
kevman 0:38ceb79fef03 215 addr % get_program_size() == 0 &&
kevman 0:38ceb79fef03 216 size % get_program_size() == 0 &&
kevman 0:38ceb79fef03 217 addr + size <= this->size());
kevman 0:38ceb79fef03 218 }
kevman 0:38ceb79fef03 219
kevman 0:38ceb79fef03 220 /** Convenience function for checking block erase validity
kevman 0:38ceb79fef03 221 *
kevman 0:38ceb79fef03 222 * @param addr Address of block to begin erasing
kevman 0:38ceb79fef03 223 * @param size Size to erase in bytes
kevman 0:38ceb79fef03 224 * @return True if erase is valid for underlying block device
kevman 0:38ceb79fef03 225 */
kevman 0:38ceb79fef03 226 bool is_valid_erase(bd_addr_t addr, bd_size_t size) const
kevman 0:38ceb79fef03 227 {
kevman 0:38ceb79fef03 228 return (
kevman 0:38ceb79fef03 229 addr % get_erase_size(addr) == 0 &&
kevman 0:38ceb79fef03 230 (addr + size) % get_erase_size(addr + size - 1) == 0 &&
kevman 0:38ceb79fef03 231 addr + size <= this->size());
kevman 0:38ceb79fef03 232 }
kevman 0:38ceb79fef03 233 };
kevman 0:38ceb79fef03 234
kevman 0:38ceb79fef03 235
kevman 0:38ceb79fef03 236 #endif