Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
BlockDevice.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2017 ARM Limited 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef MBED_BLOCK_DEVICE_H 00018 #define MBED_BLOCK_DEVICE_H 00019 00020 #include <stdint.h> 00021 00022 00023 /** Enum of standard error codes 00024 * 00025 * @enum bd_error 00026 */ 00027 enum bd_error { 00028 BD_ERROR_OK = 0, /*!< no error */ 00029 BD_ERROR_DEVICE_ERROR = -4001, /*!< device specific error */ 00030 }; 00031 00032 /** Type representing the address of a specific block 00033 */ 00034 typedef uint64_t bd_addr_t; 00035 00036 /** Type representing a quantity of 8-bit bytes 00037 */ 00038 typedef uint64_t bd_size_t; 00039 00040 00041 /** A hardware device capable of writing and reading blocks 00042 */ 00043 class BlockDevice 00044 { 00045 public: 00046 00047 /** Return the default block device 00048 * 00049 * Returns the default BlockDevice base on configuration json. 00050 * Use the components in target.json or application config to change 00051 * the default block device. 00052 * 00053 * An application can override all target settings by implementing 00054 * BlockDevice::get_default_instance() themselves - the default 00055 * definition is weak, and calls get_target_default_instance(). 00056 */ 00057 static BlockDevice *get_default_instance(); 00058 00059 /** Lifetime of a block device 00060 */ 00061 virtual ~BlockDevice() {}; 00062 00063 /** Initialize a block device 00064 * 00065 * @return 0 on success or a negative error code on failure 00066 */ 00067 virtual int init() = 0; 00068 00069 /** Deinitialize a block device 00070 * 00071 * @return 0 on success or a negative error code on failure 00072 */ 00073 virtual int deinit() = 0; 00074 00075 /** Ensure data on storage is in sync with the driver 00076 * 00077 * @return 0 on success or a negative error code on failure 00078 */ 00079 virtual int sync() 00080 { 00081 return 0; 00082 } 00083 00084 /** Read blocks from a block device 00085 * 00086 * If a failure occurs, it is not possible to determine how many bytes succeeded 00087 * 00088 * @param buffer Buffer to write blocks to 00089 * @param addr Address of block to begin reading from 00090 * @param size Size to read in bytes, must be a multiple of read block size 00091 * @return 0 on success, negative error code on failure 00092 */ 00093 virtual int read(void *buffer, bd_addr_t addr, bd_size_t size) = 0; 00094 00095 /** Program blocks to a block device 00096 * 00097 * The blocks must have been erased prior to being programmed 00098 * 00099 * If a failure occurs, it is not possible to determine how many bytes succeeded 00100 * 00101 * @param buffer Buffer of data to write to blocks 00102 * @param addr Address of block to begin writing to 00103 * @param size Size to write in bytes, must be a multiple of program block size 00104 * @return 0 on success, negative error code on failure 00105 */ 00106 virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size) = 0; 00107 00108 /** Erase blocks on a block device 00109 * 00110 * The state of an erased block is undefined until it has been programmed, 00111 * unless get_erase_value returns a non-negative byte value 00112 * 00113 * @param addr Address of block to begin erasing 00114 * @param size Size to erase in bytes, must be a multiple of erase block size 00115 * @return 0 on success, negative error code on failure 00116 */ 00117 virtual int erase(bd_addr_t addr, bd_size_t size) 00118 { 00119 return 0; 00120 } 00121 00122 /** Mark blocks as no longer in use 00123 * 00124 * This function provides a hint to the underlying block device that a region of blocks 00125 * is no longer in use and may be erased without side effects. Erase must still be called 00126 * before programming, but trimming allows flash-translation-layers to schedule erases when 00127 * the device is not busy. 00128 * 00129 * @param addr Address of block to mark as unused 00130 * @param size Size to mark as unused in bytes, must be a multiple of erase block size 00131 * @return 0 on success, negative error code on failure 00132 */ 00133 virtual int trim(bd_addr_t addr, bd_size_t size) 00134 { 00135 return 0; 00136 } 00137 00138 /** Get the size of a readable block 00139 * 00140 * @return Size of a readable block in bytes 00141 */ 00142 virtual bd_size_t get_read_size() const = 0; 00143 00144 /** Get the size of a programmable block 00145 * 00146 * @return Size of a programmable block in bytes 00147 * @note Must be a multiple of the read size 00148 */ 00149 virtual bd_size_t get_program_size() const = 0; 00150 00151 /** Get the size of an erasable block 00152 * 00153 * @return Size of an erasable block in bytes 00154 * @note Must be a multiple of the program size 00155 */ 00156 virtual bd_size_t get_erase_size() const 00157 { 00158 return get_program_size(); 00159 } 00160 00161 /** Get the size of an erasable block given address 00162 * 00163 * @param addr Address within the erasable block 00164 * @return Size of an erasable block in bytes 00165 * @note Must be a multiple of the program size 00166 */ 00167 virtual bd_size_t get_erase_size(bd_addr_t addr) const 00168 { 00169 return get_erase_size(); 00170 } 00171 00172 /** Get the value of storage when erased 00173 * 00174 * If get_erase_value returns a non-negative byte value, the underlying 00175 * storage is set to that value when erased, and storage containing 00176 * that value can be programmed without another erase. 00177 * 00178 * @return The value of storage when erased, or -1 if you can't 00179 * rely on the value of erased storage 00180 */ 00181 virtual int get_erase_value() const 00182 { 00183 return -1; 00184 } 00185 00186 /** Get the total size of the underlying device 00187 * 00188 * @return Size of the underlying device in bytes 00189 */ 00190 virtual bd_size_t size() const = 0; 00191 00192 /** Convenience function for checking block read validity 00193 * 00194 * @param addr Address of block to begin reading from 00195 * @param size Size to read in bytes 00196 * @return True if read is valid for underlying block device 00197 */ 00198 bool is_valid_read(bd_addr_t addr, bd_size_t size) const 00199 { 00200 return ( 00201 addr % get_read_size() == 0 && 00202 size % get_read_size() == 0 && 00203 addr + size <= this->size()); 00204 } 00205 00206 /** Convenience function for checking block program validity 00207 * 00208 * @param addr Address of block to begin writing to 00209 * @param size Size to write in bytes 00210 * @return True if program is valid for underlying block device 00211 */ 00212 bool is_valid_program(bd_addr_t addr, bd_size_t size) const 00213 { 00214 return ( 00215 addr % get_program_size() == 0 && 00216 size % get_program_size() == 0 && 00217 addr + size <= this->size()); 00218 } 00219 00220 /** Convenience function for checking block erase validity 00221 * 00222 * @param addr Address of block to begin erasing 00223 * @param size Size to erase in bytes 00224 * @return True if erase is valid for underlying block device 00225 */ 00226 bool is_valid_erase(bd_addr_t addr, bd_size_t size) const 00227 { 00228 return ( 00229 addr % get_erase_size(addr) == 0 && 00230 (addr + size) % get_erase_size(addr + size - 1) == 0 && 00231 addr + size <= this->size()); 00232 } 00233 }; 00234 00235 00236 #endif
Generated on Tue Aug 9 2022 00:37:03 by
