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 programable block 00132 * 00133 * @return Size of a programable 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 a eraseable block 00139 * 00140 * @return Size of a eraseable 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 value of storage when erased 00149 * 00150 * If get_erase_value returns a non-negative byte value, the underlying 00151 * storage is set to that value when erased, and storage containing 00152 * that value can be programmed without another erase. 00153 * 00154 * @return The value of storage when erased, or -1 if you can't 00155 * rely on the value of erased storage 00156 */ 00157 virtual int get_erase_value() const 00158 { 00159 return -1; 00160 } 00161 00162 /** Get the total size of the underlying device 00163 * 00164 * @return Size of the underlying device in bytes 00165 */ 00166 virtual bd_size_t size() const = 0; 00167 00168 /** Convenience function for checking block read validity 00169 * 00170 * @param addr Address of block to begin reading from 00171 * @param size Size to read in bytes 00172 * @return True if read is valid for underlying block device 00173 */ 00174 bool is_valid_read(bd_addr_t addr, bd_size_t size) const 00175 { 00176 return ( 00177 addr % get_read_size() == 0 && 00178 size % get_read_size() == 0 && 00179 addr + size <= this->size()); 00180 } 00181 00182 /** Convenience function for checking block program validity 00183 * 00184 * @param addr Address of block to begin writing to 00185 * @param size Size to write in bytes 00186 * @return True if program is valid for underlying block device 00187 */ 00188 bool is_valid_program(bd_addr_t addr, bd_size_t size) const 00189 { 00190 return ( 00191 addr % get_program_size() == 0 && 00192 size % get_program_size() == 0 && 00193 addr + size <= this->size()); 00194 } 00195 00196 /** Convenience function for checking block erase validity 00197 * 00198 * @param addr Address of block to begin erasing 00199 * @param size Size to erase in bytes 00200 * @return True if erase is valid for underlying block device 00201 */ 00202 bool is_valid_erase(bd_addr_t addr, bd_size_t size) const 00203 { 00204 return ( 00205 addr % get_erase_size() == 0 && 00206 size % get_erase_size() == 0 && 00207 addr + size <= this->size()); 00208 } 00209 }; 00210 00211 00212 #endif
Generated on Tue Jul 12 2022 13:29:30 by
