BA / SerialCom

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.

Fork of OmniWheels by Gustav Atmel

mbed-os/features/filesystem/bd/BlockDevice.h@1:9c5af431a1f1, 2018-05-01 (annotated)

Committer:
gustavatmel
Date:
Tue May 01 15:47:08 2018 +0000
Revision:
1:9c5af431a1f1
sdf

Who changed what in which revision?

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