Marco Zecchini / Mbed OS Example_RTOS

Rtos API example

mbed-os/features/filesystem/bd/MBRBlockDevice.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 * Permission is hereby granted, free of charge, to any person obtaining a copy
marcozecchini 0:9fca2b23d0ba 5 * of this software and associated documentation files (the "Software"), to deal
marcozecchini 0:9fca2b23d0ba 6 * in the Software without restriction, including without limitation the rights
marcozecchini 0:9fca2b23d0ba 7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
marcozecchini 0:9fca2b23d0ba 8 * copies of the Software, and to permit persons to whom the Software is
marcozecchini 0:9fca2b23d0ba 9 * furnished to do so, subject to the following conditions:
marcozecchini 0:9fca2b23d0ba 10 *
marcozecchini 0:9fca2b23d0ba 11 * The above copyright notice and this permission notice shall be included in
marcozecchini 0:9fca2b23d0ba 12 * all copies or substantial portions of the Software.
marcozecchini 0:9fca2b23d0ba 13 *
marcozecchini 0:9fca2b23d0ba 14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
marcozecchini 0:9fca2b23d0ba 15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
marcozecchini 0:9fca2b23d0ba 16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
marcozecchini 0:9fca2b23d0ba 17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
marcozecchini 0:9fca2b23d0ba 18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
marcozecchini 0:9fca2b23d0ba 19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
marcozecchini 0:9fca2b23d0ba 20 * SOFTWARE.
marcozecchini 0:9fca2b23d0ba 21 */
marcozecchini 0:9fca2b23d0ba 22 #ifndef MBED_MBR_BLOCK_DEVICE_H
marcozecchini 0:9fca2b23d0ba 23 #define MBED_MBR_BLOCK_DEVICE_H
marcozecchini 0:9fca2b23d0ba 24
marcozecchini 0:9fca2b23d0ba 25 #include "BlockDevice.h"
marcozecchini 0:9fca2b23d0ba 26 #include "mbed.h"
marcozecchini 0:9fca2b23d0ba 27
marcozecchini 0:9fca2b23d0ba 28
marcozecchini 0:9fca2b23d0ba 29 /** Additional error codes used for MBR records
marcozecchini 0:9fca2b23d0ba 30 */
marcozecchini 0:9fca2b23d0ba 31 enum {
marcozecchini 0:9fca2b23d0ba 32 BD_ERROR_INVALID_MBR = -3101,
marcozecchini 0:9fca2b23d0ba 33 BD_ERROR_INVALID_PARTITION = -3102,
marcozecchini 0:9fca2b23d0ba 34 };
marcozecchini 0:9fca2b23d0ba 35
marcozecchini 0:9fca2b23d0ba 36
marcozecchini 0:9fca2b23d0ba 37 /** Block device for managing a Master Boot Record
marcozecchini 0:9fca2b23d0ba 38 * https://en.wikipedia.org/wiki/Master_boot_record
marcozecchini 0:9fca2b23d0ba 39 *
marcozecchini 0:9fca2b23d0ba 40 * Here is an example of partitioning a heap backed block device
marcozecchini 0:9fca2b23d0ba 41 * @code
marcozecchini 0:9fca2b23d0ba 42 * #include "mbed.h"
marcozecchini 0:9fca2b23d0ba 43 * #include "HeapBlockDevice.h"
marcozecchini 0:9fca2b23d0ba 44 * #include "MBRBlockDevice.h"
marcozecchini 0:9fca2b23d0ba 45 *
marcozecchini 0:9fca2b23d0ba 46 * // Create a block device with 64 blocks of size 512
marcozecchini 0:9fca2b23d0ba 47 * HeapBlockDevice mem(64*512, 512);
marcozecchini 0:9fca2b23d0ba 48 *
marcozecchini 0:9fca2b23d0ba 49 * // Partition into two partitions with ~half the blocks
marcozecchini 0:9fca2b23d0ba 50 * MBRBlockDevice::partition(&mem, 1, 0x83, 0*512, 32*512);
marcozecchini 0:9fca2b23d0ba 51 * MBRBlockDevice::partition(&mem, 2, 0x83, 32*512);
marcozecchini 0:9fca2b23d0ba 52 *
marcozecchini 0:9fca2b23d0ba 53 * // Create a block device that maps to the first 32 blocks (excluding MBR block)
marcozecchini 0:9fca2b23d0ba 54 * MBRBlockDevice part1(&mem, 1);
marcozecchini 0:9fca2b23d0ba 55 *
marcozecchini 0:9fca2b23d0ba 56 * // Create a block device that maps to the last 32 blocks
marcozecchini 0:9fca2b23d0ba 57 * MBRBlockDevice part2(&mem, 2);
marcozecchini 0:9fca2b23d0ba 58 * @endcode
marcozecchini 0:9fca2b23d0ba 59 *
marcozecchini 0:9fca2b23d0ba 60 * Here is a more realistic example where the MBRBlockDevice is used
marcozecchini 0:9fca2b23d0ba 61 * to partition a region of space on an SD card. When plugged into a computer,
marcozecchini 0:9fca2b23d0ba 62 * the partitions will be recognized appropriately.
marcozecchini 0:9fca2b23d0ba 63 * @code
marcozecchini 0:9fca2b23d0ba 64 * #include "mbed.h"
marcozecchini 0:9fca2b23d0ba 65 * #include "SDBlockDevice.h"
marcozecchini 0:9fca2b23d0ba 66 * #include "MBRBlockDevice.h"
marcozecchini 0:9fca2b23d0ba 67 * #include "FATFileSystem.h"
marcozecchini 0:9fca2b23d0ba 68 *
marcozecchini 0:9fca2b23d0ba 69 * // Create an SD card
marcozecchini 0:9fca2b23d0ba 70 * SDBlockDevice sd(s0, s1, s2, s3);
marcozecchini 0:9fca2b23d0ba 71 *
marcozecchini 0:9fca2b23d0ba 72 * // Create a partition with 1 GB of space
marcozecchini 0:9fca2b23d0ba 73 * MBRBlockDevice::partition(&sd, 1, 0x83, 0, 1024*1024);
marcozecchini 0:9fca2b23d0ba 74 *
marcozecchini 0:9fca2b23d0ba 75 * // Create the block device that represents the partition
marcozecchini 0:9fca2b23d0ba 76 * MBRBlockDevice part1(&sd, 1);
marcozecchini 0:9fca2b23d0ba 77 *
marcozecchini 0:9fca2b23d0ba 78 * // Format the partition with a FAT filesystem
marcozecchini 0:9fca2b23d0ba 79 * FATFileSystem::format(&part1);
marcozecchini 0:9fca2b23d0ba 80 *
marcozecchini 0:9fca2b23d0ba 81 * // Create the FAT filesystem instance, files can now be written to
marcozecchini 0:9fca2b23d0ba 82 * // the FAT filesystem in partition 1
marcozecchini 0:9fca2b23d0ba 83 * FATFileSystem fat("fat", &part1);
marcozecchini 0:9fca2b23d0ba 84 * @endcode
marcozecchini 0:9fca2b23d0ba 85 */
marcozecchini 0:9fca2b23d0ba 86 class MBRBlockDevice : public BlockDevice
marcozecchini 0:9fca2b23d0ba 87 {
marcozecchini 0:9fca2b23d0ba 88 public:
marcozecchini 0:9fca2b23d0ba 89 /** Format the MBR to contain the following partition
marcozecchini 0:9fca2b23d0ba 90 *
marcozecchini 0:9fca2b23d0ba 91 * @param bd Block device to partition
marcozecchini 0:9fca2b23d0ba 92 * @param part Partition to use, 1-4
marcozecchini 0:9fca2b23d0ba 93 * @param type 8-bit partition type to identitfy partition's contents
marcozecchini 0:9fca2b23d0ba 94 * @param start Start block address to map to block 0 of partition,
marcozecchini 0:9fca2b23d0ba 95 * negative addresses are calculated from the end of the
marcozecchini 0:9fca2b23d0ba 96 * underlying block devices. Block 0 is implicitly ignored
marcozecchini 0:9fca2b23d0ba 97 * from the range to store the MBR.
marcozecchini 0:9fca2b23d0ba 98 * @return 0 on success or a negative error code on failure
marcozecchini 0:9fca2b23d0ba 99 * @note This is the same as partition(bd, part, type, start, bd->size())
marcozecchini 0:9fca2b23d0ba 100 */
marcozecchini 0:9fca2b23d0ba 101 static int partition(BlockDevice *bd, int part, uint8_t type, bd_addr_t start);
marcozecchini 0:9fca2b23d0ba 102
marcozecchini 0:9fca2b23d0ba 103 /** Format the MBR to contain the following partition
marcozecchini 0:9fca2b23d0ba 104 *
marcozecchini 0:9fca2b23d0ba 105 * @param bd Block device to partition
marcozecchini 0:9fca2b23d0ba 106 * @param part Partition to use, 1-4
marcozecchini 0:9fca2b23d0ba 107 * @param type 8-bit partition type to identitfy partition's contents
marcozecchini 0:9fca2b23d0ba 108 * @param start Start block address to map to block 0 of partition,
marcozecchini 0:9fca2b23d0ba 109 * negative addresses are calculated from the end of the
marcozecchini 0:9fca2b23d0ba 110 * underlying block devices. Block 0 is implicitly ignored
marcozecchini 0:9fca2b23d0ba 111 * from the range to store the MBR.
marcozecchini 0:9fca2b23d0ba 112 * @param stop End block address to mark the end of the partition,
marcozecchini 0:9fca2b23d0ba 113 * this block is not mapped, negative addresses are calculated
marcozecchini 0:9fca2b23d0ba 114 * from the end of the underlying block device.
marcozecchini 0:9fca2b23d0ba 115 * @return 0 on success or a negative error code on failure
marcozecchini 0:9fca2b23d0ba 116 */
marcozecchini 0:9fca2b23d0ba 117 static int partition(BlockDevice *bd, int part, uint8_t type, bd_addr_t start, bd_addr_t stop);
marcozecchini 0:9fca2b23d0ba 118
marcozecchini 0:9fca2b23d0ba 119 /** Lifetime of the block device
marcozecchini 0:9fca2b23d0ba 120 *
marcozecchini 0:9fca2b23d0ba 121 * @param bd Block device to back the MBRBlockDevice
marcozecchini 0:9fca2b23d0ba 122 * @param part Partition to use, 1-4
marcozecchini 0:9fca2b23d0ba 123 */
marcozecchini 0:9fca2b23d0ba 124 MBRBlockDevice(BlockDevice *bd, int part);
marcozecchini 0:9fca2b23d0ba 125
marcozecchini 0:9fca2b23d0ba 126 /** Lifetime of the block device
marcozecchini 0:9fca2b23d0ba 127 */
marcozecchini 0:9fca2b23d0ba 128 virtual ~MBRBlockDevice() {};
marcozecchini 0:9fca2b23d0ba 129
marcozecchini 0:9fca2b23d0ba 130 /** Initialize a block device
marcozecchini 0:9fca2b23d0ba 131 *
marcozecchini 0:9fca2b23d0ba 132 * @return 0 on success or a negative error code on failure
marcozecchini 0:9fca2b23d0ba 133 */
marcozecchini 0:9fca2b23d0ba 134 virtual int init();
marcozecchini 0:9fca2b23d0ba 135
marcozecchini 0:9fca2b23d0ba 136 /** Deinitialize a block device
marcozecchini 0:9fca2b23d0ba 137 *
marcozecchini 0:9fca2b23d0ba 138 * @return 0 on success or a negative error code on failure
marcozecchini 0:9fca2b23d0ba 139 */
marcozecchini 0:9fca2b23d0ba 140 virtual int deinit();
marcozecchini 0:9fca2b23d0ba 141
marcozecchini 0:9fca2b23d0ba 142 /** Read blocks from a block device
marcozecchini 0:9fca2b23d0ba 143 *
marcozecchini 0:9fca2b23d0ba 144 * @param buffer Buffer to read blocks into
marcozecchini 0:9fca2b23d0ba 145 * @param addr Address of block to begin reading from
marcozecchini 0:9fca2b23d0ba 146 * @param size Size to read in bytes, must be a multiple of read block size
marcozecchini 0:9fca2b23d0ba 147 * @return 0 on success, negative error code on failure
marcozecchini 0:9fca2b23d0ba 148 */
marcozecchini 0:9fca2b23d0ba 149 virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);
marcozecchini 0:9fca2b23d0ba 150
marcozecchini 0:9fca2b23d0ba 151 /** Program blocks to a block device
marcozecchini 0:9fca2b23d0ba 152 *
marcozecchini 0:9fca2b23d0ba 153 * The blocks must have been erased prior to being programmed
marcozecchini 0:9fca2b23d0ba 154 *
marcozecchini 0:9fca2b23d0ba 155 * @param buffer Buffer of data to write to blocks
marcozecchini 0:9fca2b23d0ba 156 * @param addr Address of block to begin writing to
marcozecchini 0:9fca2b23d0ba 157 * @param size Size to write in bytes, must be a multiple of program block size
marcozecchini 0:9fca2b23d0ba 158 * @return 0 on success, negative error code on failure
marcozecchini 0:9fca2b23d0ba 159 */
marcozecchini 0:9fca2b23d0ba 160 virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);
marcozecchini 0:9fca2b23d0ba 161
marcozecchini 0:9fca2b23d0ba 162 /** Erase blocks on a block device
marcozecchini 0:9fca2b23d0ba 163 *
marcozecchini 0:9fca2b23d0ba 164 * The state of an erased block is undefined until it has been programmed
marcozecchini 0:9fca2b23d0ba 165 *
marcozecchini 0:9fca2b23d0ba 166 * @param addr Address of block to begin erasing
marcozecchini 0:9fca2b23d0ba 167 * @param size Size to erase in bytes, must be a multiple of erase block size
marcozecchini 0:9fca2b23d0ba 168 * @return 0 on success, negative error code on failure
marcozecchini 0:9fca2b23d0ba 169 */
marcozecchini 0:9fca2b23d0ba 170 virtual int erase(bd_addr_t addr, bd_size_t size);
marcozecchini 0:9fca2b23d0ba 171
marcozecchini 0:9fca2b23d0ba 172 /** Get the size of a readable block
marcozecchini 0:9fca2b23d0ba 173 *
marcozecchini 0:9fca2b23d0ba 174 * @return Size of a readable block in bytes
marcozecchini 0:9fca2b23d0ba 175 */
marcozecchini 0:9fca2b23d0ba 176 virtual bd_size_t get_read_size() const;
marcozecchini 0:9fca2b23d0ba 177
marcozecchini 0:9fca2b23d0ba 178 /** Get the size of a programable block
marcozecchini 0:9fca2b23d0ba 179 *
marcozecchini 0:9fca2b23d0ba 180 * @return Size of a programable block in bytes
marcozecchini 0:9fca2b23d0ba 181 * @note Must be a multiple of the read size
marcozecchini 0:9fca2b23d0ba 182 */
marcozecchini 0:9fca2b23d0ba 183 virtual bd_size_t get_program_size() const;
marcozecchini 0:9fca2b23d0ba 184
marcozecchini 0:9fca2b23d0ba 185 /** Get the size of a eraseable block
marcozecchini 0:9fca2b23d0ba 186 *
marcozecchini 0:9fca2b23d0ba 187 * @return Size of a eraseable block in bytes
marcozecchini 0:9fca2b23d0ba 188 * @note Must be a multiple of the program size
marcozecchini 0:9fca2b23d0ba 189 */
marcozecchini 0:9fca2b23d0ba 190 virtual bd_size_t get_erase_size() const;
marcozecchini 0:9fca2b23d0ba 191
marcozecchini 0:9fca2b23d0ba 192 /** Get the total size of the underlying device
marcozecchini 0:9fca2b23d0ba 193 *
marcozecchini 0:9fca2b23d0ba 194 * @return Size of the underlying device in bytes
marcozecchini 0:9fca2b23d0ba 195 */
marcozecchini 0:9fca2b23d0ba 196 virtual bd_size_t size() const;
marcozecchini 0:9fca2b23d0ba 197
marcozecchini 0:9fca2b23d0ba 198 /** Get the offset of the partition on the underlying block device
marcozecchini 0:9fca2b23d0ba 199 * @return Offset of the partition on the underlying device
marcozecchini 0:9fca2b23d0ba 200 */
marcozecchini 0:9fca2b23d0ba 201 virtual bd_addr_t get_partition_start() const;
marcozecchini 0:9fca2b23d0ba 202
marcozecchini 0:9fca2b23d0ba 203 /** Get size of partition on underlying block device
marcozecchini 0:9fca2b23d0ba 204 * @return Size of the partition on the underlying device
marcozecchini 0:9fca2b23d0ba 205 */
marcozecchini 0:9fca2b23d0ba 206 virtual bd_addr_t get_partition_stop() const;
marcozecchini 0:9fca2b23d0ba 207
marcozecchini 0:9fca2b23d0ba 208 /** Get 8-bit type of the partition
marcozecchini 0:9fca2b23d0ba 209 * @return 8-bit type of partition assigned during format
marcozecchini 0:9fca2b23d0ba 210 */
marcozecchini 0:9fca2b23d0ba 211 virtual uint8_t get_partition_type() const;
marcozecchini 0:9fca2b23d0ba 212
marcozecchini 0:9fca2b23d0ba 213 /** Get the partition number
marcozecchini 0:9fca2b23d0ba 214 * @return The partition number, 1-4
marcozecchini 0:9fca2b23d0ba 215 */
marcozecchini 0:9fca2b23d0ba 216 virtual int get_partition_number() const;
marcozecchini 0:9fca2b23d0ba 217
marcozecchini 0:9fca2b23d0ba 218 protected:
marcozecchini 0:9fca2b23d0ba 219 BlockDevice *_bd;
marcozecchini 0:9fca2b23d0ba 220 bd_size_t _offset;
marcozecchini 0:9fca2b23d0ba 221 bd_size_t _size;
marcozecchini 0:9fca2b23d0ba 222 uint8_t _type;
marcozecchini 0:9fca2b23d0ba 223 uint8_t _part;
marcozecchini 0:9fca2b23d0ba 224 };
marcozecchini 0:9fca2b23d0ba 225
marcozecchini 0:9fca2b23d0ba 226
marcozecchini 0:9fca2b23d0ba 227 #endif