Marco Zecchini / Mbed OS Example_RTOS

Rtos API example

mbed-os/features/filesystem/bd/BlockDevice.h@0:9fca2b23d0ba, 2019-02-23 (annotated)

Committer:
marcozecchini
Date:
Sat Feb 23 12:13:36 2019 +0000
Revision:
0:9fca2b23d0ba
final commit

Who changed what in which revision?

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