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.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
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 /** \addtogroup storage */ 00018 /** @{*/ 00019 00020 #ifndef MBED_BLOCK_DEVICE_H 00021 #define MBED_BLOCK_DEVICE_H 00022 00023 #include <stdint.h> 00024 00025 namespace mbed { 00026 00027 /** Enum of standard error codes 00028 * 00029 * @enum bd_error 00030 */ 00031 enum bd_error { 00032 BD_ERROR_OK = 0, /*!< no error */ 00033 BD_ERROR_DEVICE_ERROR = -4001, /*!< device specific error */ 00034 }; 00035 00036 /** Type representing the address of a specific block 00037 */ 00038 typedef uint64_t bd_addr_t; 00039 00040 /** Type representing a quantity of 8-bit bytes 00041 */ 00042 typedef uint64_t bd_size_t; 00043 00044 00045 /** A hardware device capable of writing and reading blocks 00046 */ 00047 class BlockDevice { 00048 public: 00049 00050 /** Return the default block device 00051 * 00052 * Returns the default block device based on the configuration JSON. 00053 * Use the components in target.json or application config to change 00054 * the default block device. 00055 * 00056 * An application can override all target settings by implementing 00057 * BlockDevice::get_default_instance() - the default 00058 * definition is weak, and calls get_target_default_instance(). 00059 */ 00060 static BlockDevice *get_default_instance(); 00061 00062 /** Lifetime of a block device 00063 */ 00064 virtual ~BlockDevice() {}; 00065 00066 /** Initialize a block device 00067 * 00068 * @return 0 on success or a negative error code on failure 00069 */ 00070 virtual int init() = 0; 00071 00072 /** Deinitialize a block device 00073 * 00074 * @return 0 on success or a negative error code on failure 00075 */ 00076 virtual int deinit() = 0; 00077 00078 /** Ensure data on storage is in sync with the driver 00079 * 00080 * @return 0 on success or a negative error code on failure 00081 */ 00082 virtual int sync() 00083 { 00084 return 0; 00085 } 00086 00087 /** Read blocks from a block device 00088 * 00089 * If a failure occurs, it is not possible to determine how many bytes succeeded 00090 * 00091 * @param buffer Buffer to write blocks to 00092 * @param addr Address of block to begin reading from 00093 * @param size Size to read in bytes, must be a multiple of the read block size 00094 * @return 0 on success or a negative error code on failure 00095 */ 00096 virtual int read(void *buffer, bd_addr_t addr, bd_size_t size) = 0; 00097 00098 /** Program blocks to a block device 00099 * 00100 * The blocks must have been erased prior to being programmed 00101 * 00102 * If a failure occurs, it is not possible to determine how many bytes succeeded 00103 * 00104 * @param buffer Buffer of data to write to blocks 00105 * @param addr Address of block to begin writing to 00106 * @param size Size to write in bytes, must be a multiple of the program block size 00107 * @return 0 on success or a negative error code on failure 00108 */ 00109 virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size) = 0; 00110 00111 /** Erase blocks on a block device 00112 * 00113 * The state of an erased block is undefined until it has been programmed, 00114 * unless get_erase_value returns a non-negative byte value 00115 * 00116 * @param addr Address of block to begin erasing 00117 * @param size Size to erase in bytes, must be a multiple of the erase block size 00118 * @return 0 on success or a negative error code on failure 00119 */ 00120 virtual int erase(bd_addr_t addr, bd_size_t size) 00121 { 00122 return 0; 00123 } 00124 00125 /** Mark blocks as no longer in use 00126 * 00127 * This function provides a hint to the underlying block device that a region of blocks 00128 * is no longer in use and may be erased without side effects. Erase must still be called 00129 * before programming, but trimming allows flash-translation-layers to schedule erases when 00130 * the device is not busy. 00131 * 00132 * @param addr Address of block to mark as unused 00133 * @param size Size to mark as unused in bytes, must be a multiple of the erase block size 00134 * @return 0 on success or a negative error code on failure 00135 */ 00136 virtual int trim(bd_addr_t addr, bd_size_t size) 00137 { 00138 return 0; 00139 } 00140 00141 /** Get the size of a readable block 00142 * 00143 * @return Size of a readable block in bytes 00144 */ 00145 virtual bd_size_t get_read_size() const = 0; 00146 00147 /** Get the size of a programmable block 00148 * 00149 * @return Size of a programmable block in bytes 00150 * @note Must be a multiple of the read size 00151 */ 00152 virtual bd_size_t get_program_size() const = 0; 00153 00154 /** Get the size of an erasable block 00155 * 00156 * @return Size of an erasable block in bytes 00157 * @note Must be a multiple of the program size 00158 */ 00159 virtual bd_size_t get_erase_size() const 00160 { 00161 return get_program_size(); 00162 } 00163 00164 /** Get the size of an erasable block given address 00165 * 00166 * @param addr Address within the erasable block 00167 * @return Size of an erasable block in bytes 00168 * @note Must be a multiple of the program size 00169 */ 00170 virtual bd_size_t get_erase_size(bd_addr_t addr) const 00171 { 00172 return get_erase_size(); 00173 } 00174 00175 /** Get the value of storage when erased 00176 * 00177 * If get_erase_value returns a non-negative byte value, the underlying 00178 * storage is set to that value when erased, and storage containing 00179 * that value can be programmed without another erase. 00180 * 00181 * @return The value of storage when erased, or -1 if you can't 00182 * rely on the value of the erased storage 00183 */ 00184 virtual int get_erase_value() const 00185 { 00186 return -1; 00187 } 00188 00189 /** Get the total size of the underlying device 00190 * 00191 * @return Size of the underlying device in bytes 00192 */ 00193 virtual bd_size_t size() const = 0; 00194 00195 /** Convenience function for checking block read validity 00196 * 00197 * @param addr Address of block to begin reading from 00198 * @param size Size to read in bytes 00199 * @return True if read is valid for underlying block device 00200 */ 00201 virtual bool is_valid_read(bd_addr_t addr, bd_size_t size) const 00202 { 00203 return ( 00204 addr % get_read_size() == 0 && 00205 size % get_read_size() == 0 && 00206 addr + size <= this->size()); 00207 } 00208 00209 /** Convenience function for checking block program validity 00210 * 00211 * @param addr Address of block to begin writing to 00212 * @param size Size to write in bytes 00213 * @return True if program is valid for underlying block device 00214 */ 00215 virtual bool is_valid_program(bd_addr_t addr, bd_size_t size) const 00216 { 00217 return ( 00218 addr % get_program_size() == 0 && 00219 size % get_program_size() == 0 && 00220 addr + size <= this->size()); 00221 } 00222 00223 /** Convenience function for checking block erase validity 00224 * 00225 * @param addr Address of block to begin erasing 00226 * @param size Size to erase in bytes 00227 * @return True if erase is valid for underlying block device 00228 */ 00229 virtual bool is_valid_erase(bd_addr_t addr, bd_size_t size) const 00230 { 00231 return ( 00232 addr % get_erase_size(addr) == 0 && 00233 (addr + size) % get_erase_size(addr + size - 1) == 0 && 00234 addr + size <= this->size()); 00235 } 00236 00237 /** Get the BlockDevice class type. 00238 * 00239 * @return A string represent the BlockDevice class type. 00240 */ 00241 virtual const char *get_type() const = 0; 00242 }; 00243 00244 } // namespace mbed 00245 00246 // Added "using" for backwards compatibility 00247 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE 00248 using mbed::BlockDevice; 00249 using mbed::bd_addr_t; 00250 using mbed::bd_size_t; 00251 using mbed::BD_ERROR_OK; 00252 using mbed::BD_ERROR_DEVICE_ERROR; 00253 #endif 00254 00255 #endif 00256 00257 /** @}*/
Generated on Tue Jul 12 2022 13:54:03 by
