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 /** Lifetime of a block device 00047 */ 00048 virtual ~BlockDevice() {}; 00049 00050 /** Initialize a block device 00051 * 00052 * @return 0 on success or a negative error code on failure 00053 */ 00054 virtual int init() = 0; 00055 00056 /** Deinitialize a block device 00057 * 00058 * @return 0 on success or a negative error code on failure 00059 */ 00060 virtual int deinit() = 0; 00061 00062 /** Ensure data on storage is in sync with the driver 00063 * 00064 * @return 0 on success or a negative error code on failure 00065 */ 00066 virtual int sync() 00067 { 00068 return 0; 00069 } 00070 00071 /** Read blocks from a block device 00072 * 00073 * If a failure occurs, it is not possible to determine how many bytes succeeded 00074 * 00075 * @param buffer Buffer to write blocks to 00076 * @param addr Address of block to begin reading from 00077 * @param size Size to read in bytes, must be a multiple of read block size 00078 * @return 0 on success, negative error code on failure 00079 */ 00080 virtual int read(void *buffer, bd_addr_t addr, bd_size_t size) = 0; 00081 00082 /** Program blocks to a block device 00083 * 00084 * The blocks must have been erased prior to being programmed 00085 * 00086 * If a failure occurs, it is not possible to determine how many bytes succeeded 00087 * 00088 * @param buffer Buffer of data to write to blocks 00089 * @param addr Address of block to begin writing to 00090 * @param size Size to write in bytes, must be a multiple of program block size 00091 * @return 0 on success, negative error code on failure 00092 */ 00093 virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size) = 0; 00094 00095 /** Erase blocks on a block device 00096 * 00097 * The state of an erased block is undefined until it has been programmed, 00098 * unless get_erase_value returns a non-negative byte value 00099 * 00100 * @param addr Address of block to begin erasing 00101 * @param size Size to erase in bytes, must be a multiple of erase block size 00102 * @return 0 on success, negative error code on failure 00103 */ 00104 virtual int erase(bd_addr_t addr, bd_size_t size) 00105 { 00106 return 0; 00107 } 00108 00109 /** Mark blocks as no longer in use 00110 * 00111 * This function provides a hint to the underlying block device that a region of blocks 00112 * is no longer in use and may be erased without side effects. Erase must still be called 00113 * before programming, but trimming allows flash-translation-layers to schedule erases when 00114 * the device is not busy. 00115 * 00116 * @param addr Address of block to mark as unused 00117 * @param size Size to mark as unused in bytes, must be a multiple of erase block size 00118 * @return 0 on success, negative error code on failure 00119 */ 00120 virtual int trim(bd_addr_t addr, bd_size_t size) 00121 { 00122 return 0; 00123 } 00124 00125 /** Get the size of a readable block 00126 * 00127 * @return Size of a readable block in bytes 00128 */ 00129 virtual bd_size_t get_read_size() const = 0; 00130 00131 /** Get the size of a programmable block 00132 * 00133 * @return Size of a programmable block in bytes 00134 * @note Must be a multiple of the read size 00135 */ 00136 virtual bd_size_t get_program_size() const = 0; 00137 00138 /** Get the size of an erasable block 00139 * 00140 * @return Size of an erasable block in bytes 00141 * @note Must be a multiple of the program size 00142 */ 00143 virtual bd_size_t get_erase_size() const 00144 { 00145 return get_program_size(); 00146 } 00147 00148 /** Get the size of an erasable block given address 00149 * 00150 * @param addr Address within the erasable block 00151 * @return Size of an erasable block in bytes 00152 * @note Must be a multiple of the program size 00153 */ 00154 virtual bd_size_t get_erase_size(bd_addr_t addr) const 00155 { 00156 return get_erase_size(); 00157 } 00158 00159 /** Get the value of storage when erased 00160 * 00161 * If get_erase_value returns a non-negative byte value, the underlying 00162 * storage is set to that value when erased, and storage containing 00163 * that value can be programmed without another erase. 00164 * 00165 * @return The value of storage when erased, or -1 if you can't 00166 * rely on the value of erased storage 00167 */ 00168 virtual int get_erase_value() const 00169 { 00170 return -1; 00171 } 00172 00173 /** Get the total size of the underlying device 00174 * 00175 * @return Size of the underlying device in bytes 00176 */ 00177 virtual bd_size_t size() const = 0; 00178 00179 /** Convenience function for checking block read validity 00180 * 00181 * @param addr Address of block to begin reading from 00182 * @param size Size to read in bytes 00183 * @return True if read is valid for underlying block device 00184 */ 00185 bool is_valid_read(bd_addr_t addr, bd_size_t size) const 00186 { 00187 return ( 00188 addr % get_read_size() == 0 && 00189 size % get_read_size() == 0 && 00190 addr + size <= this->size()); 00191 } 00192 00193 /** Convenience function for checking block program validity 00194 * 00195 * @param addr Address of block to begin writing to 00196 * @param size Size to write in bytes 00197 * @return True if program is valid for underlying block device 00198 */ 00199 bool is_valid_program(bd_addr_t addr, bd_size_t size) const 00200 { 00201 return ( 00202 addr % get_program_size() == 0 && 00203 size % get_program_size() == 0 && 00204 addr + size <= this->size()); 00205 } 00206 00207 /** Convenience function for checking block erase validity 00208 * 00209 * @param addr Address of block to begin erasing 00210 * @param size Size to erase in bytes 00211 * @return True if erase is valid for underlying block device 00212 */ 00213 bool is_valid_erase(bd_addr_t addr, bd_size_t size) const 00214 { 00215 return ( 00216 addr % get_erase_size() == 0 && 00217 size % get_erase_size() == 0 && 00218 addr + size <= this->size()); 00219 } 00220 }; 00221 00222 00223 #endif
Generated on Tue Jul 12 2022 12:43:36 by
