Nicolas Borla / Mbed OS BBR_1Ebene

BBR 1 Ebene

mbed-os/features/filesystem/bd/BlockDevice.h@0:fbdae7e6d805, 2018-05-14 (annotated)

Committer:
borlanic
Date:
Mon May 14 11:29:06 2018 +0000
Revision:
0:fbdae7e6d805
BBR

Who changed what in which revision?

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