Mistake on this page?
Report an issue in GitHub or email us
MBRBlockDevice.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2017 ARM Limited
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to deal
6  * in the Software without restriction, including without limitation the rights
7  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8  * copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20  * SOFTWARE.
21  */
22 
23 /** \addtogroup storage */
24 /** @{*/
25 
26 #ifndef MBED_MBR_BLOCK_DEVICE_H
27 #define MBED_MBR_BLOCK_DEVICE_H
28 
29 #include "BlockDevice.h"
30 
31 namespace mbed {
32 
33 /** Additional error codes used for MBR records
34  */
35 enum {
36  BD_ERROR_INVALID_MBR = -3101,
37  BD_ERROR_INVALID_PARTITION = -3102,
38 };
39 
40 
41 /** Block device for managing a Master Boot Record
42  * https://en.wikipedia.org/wiki/Master_boot_record
43  *
44  * @note
45  * The MBR partition table is relatively limited:
46  * - At most 4 partitions are supported
47  * - Extended partitions are currently not supported and will error during init
48  */
49 class MBRBlockDevice : public BlockDevice {
50 public:
51  /** Format the MBR to contain the following partition
52  *
53  * @param bd Block device to partition
54  * @param part Partition to use, 1-4
55  * @param type 8-bit partition type to specify the filesystem to use in this partition.
56  * It can be found in the filesystem documentation or refer to
57  * https://en.wikipedia.org/wiki/Partition_type#List_of_partition_IDs
58  * @param start Start block address to map to block 0 of partition.
59  * Negative addresses are calculated from the end of the
60  * underlying block devices. Block 0 is implicitly ignored
61  * from the range to store the MBR.
62  * @return 0 on success or a negative error code on failure.
63  * @note This is the same as partition(bd, part, type, start, bd->size())
64  */
65  static int partition(BlockDevice *bd, int part, uint8_t type, bd_addr_t start);
66 
67  /** Format the MBR to contain the following partition
68  *
69  * @param bd Block device to partition
70  * @param part Partition to use, 1-4
71  * @param type 8-bit partition type to specify the filesystem to use in this partition.
72  * It can be found in the filesystem documentation or refer to
73  * https://en.wikipedia.org/wiki/Partition_type#List_of_partition_IDs
74  * @param start Start block address to map to block 0 of partition,
75  * negative addresses are calculated from the end of the
76  * underlying block devices. Block 0 is implicitly ignored
77  * from the range to store the MBR.
78  * @param stop End block address to mark the end of the partition.
79  * This block is not mapped: negative addresses are calculated
80  * from the end of the underlying block device.
81  * @return 0 on success or a negative error code on failure.
82  */
83  static int partition(BlockDevice *bd, int part, uint8_t type, bd_addr_t start, bd_addr_t stop);
84 
85  /** Lifetime of the block device
86  *
87  * @param bd Block device to back the MBRBlockDevice
88  * @param part Partition to use, 1-4
89  */
90  MBRBlockDevice(BlockDevice *bd, int part);
91 
92  /** Lifetime of the block device
93  */
94  virtual ~MBRBlockDevice() {};
95 
96  /** Initialize a block device
97  *
98  * @return 0 on success or a negative error code on failure
99  */
100  virtual int init();
101 
102  /** Deinitialize a block device
103  *
104  * @return 0 on success or a negative error code on failure
105  */
106  virtual int deinit();
107 
108  /** Ensure data on storage is in sync with the driver
109  *
110  * @return 0 on success or a negative error code on failure
111  */
112  virtual int sync();
113 
114  /** Read blocks from a block device
115  *
116  * @param buffer Buffer to read blocks into
117  * @param addr Address of block to begin reading from
118  * @param size Size to read in bytes, must be a multiple of read block size
119  * @return 0 on success or a negative error code on failure
120  */
121  virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);
122 
123  /** Program blocks to a block device
124  *
125  * The blocks must have been erased prior to being programmed
126  *
127  * @param buffer Buffer of data to write to blocks
128  * @param addr Address of block to begin writing to
129  * @param size Size to write in bytes, must be a multiple of program block size
130  * @return 0 on success or a negative error code on failure
131  */
132  virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);
133 
134  /** Erase blocks on a block device
135  *
136  * The state of an erased block is undefined until it has been programmed,
137  * unless get_erase_value returns a non-negative byte value
138  *
139  * @param addr Address of block to begin erasing
140  * @param size Size to erase in bytes, must be a multiple of erase block size
141  * @return 0 on success or a negative error code on failure
142  */
143  virtual int erase(bd_addr_t addr, bd_size_t size);
144 
145  /** Get the size of a readable block
146  *
147  * @return Size of a readable block in bytes
148  */
149  virtual bd_size_t get_read_size() const;
150 
151  /** Get the size of a programmable block
152  *
153  * @return Size of a programmable block in bytes
154  * @note Must be a multiple of the read size
155  */
156  virtual bd_size_t get_program_size() const;
157 
158  /** Get the size of an erasable block
159  *
160  * @return Size of an erasable block in bytes
161  * @note Must be a multiple of the program size
162  */
163  virtual bd_size_t get_erase_size() const;
164 
165  /** Get the size of an erasable block given address
166  *
167  * @param addr Address within the erasable block
168  * @return Size of an erasable block in bytes
169  * @note Must be a multiple of the program size
170  */
171  virtual bd_size_t get_erase_size(bd_addr_t addr) const;
172 
173  /** Get the value of storage when erased
174  *
175  * If get_erase_value returns a non-negative byte value, the underlying
176  * storage is set to that value when erased, and storage containing
177  * that value can be programmed without another erase.
178  *
179  * @return The value of storage when erased, or -1 if you can't
180  * rely on the value of erased storage
181  */
182  virtual int get_erase_value() const;
183 
184  /** Get the total size of the underlying device
185  *
186  * @return Size of the underlying device in bytes
187  */
188  virtual bd_size_t size() const;
189 
190  /** Get the offset of the partition on the underlying block device
191  * @return Offset of the partition on the underlying device
192  */
193  virtual bd_addr_t get_partition_start() const;
194 
195  /** Get size of partition on underlying block device
196  * @return Size of the partition on the underlying device
197  */
198  virtual bd_addr_t get_partition_stop() const;
199 
200  /** Get 8-bit type of the partition
201  * @return 8-bit type of partition assigned during format
202  */
203  virtual uint8_t get_partition_type() const;
204 
205  /** Get the partition number
206  * @return The partition number, 1-4
207  */
208  virtual int get_partition_number() const;
209 
210  /** Get the BlockDevice class type.
211  *
212  * @return A string represent the BlockDevice class type.
213  */
214  virtual const char *get_type() const;
215 
216 protected:
217  BlockDevice *_bd;
218  bd_size_t _offset;
219  bd_size_t _size;
220  uint8_t _type;
221  uint8_t _part;
222  uint32_t _init_ref_count;
223  bool _is_initialized;
224 };
225 
226 } // namespace mbed
227 
228 // Added "using" for backwards compatibility
229 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
231 #endif
232 
233 #endif
234 
235 /** @}*/
virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size)
Program blocks to a block device.
Block device for managing a Master Boot Record https://en.wikipedia.org/wiki/Master_boot_record.
virtual bd_size_t size() const
Get the total size of the underlying device.
virtual int init()
Initialize a block device.
virtual uint8_t get_partition_type() const
Get 8-bit type of the partition.
A hardware device capable of writing and reading blocks.
Definition: BlockDevice.h:47
virtual int get_erase_value() const
Get the value of storage when erased.
virtual bd_addr_t get_partition_start() const
Get the offset of the partition on the underlying block device.
virtual int deinit()
Deinitialize a block device.
virtual int get_partition_number() const
Get the partition number.
virtual int sync()
Ensure data on storage is in sync with the driver.
virtual bd_size_t get_program_size() const
Get the size of a programmable block.
virtual bd_size_t get_erase_size() const
Get the size of an erasable block.
virtual bd_addr_t get_partition_stop() const
Get size of partition on underlying block device.
virtual ~MBRBlockDevice()
Lifetime of the block device.
virtual int erase(bd_addr_t addr, bd_size_t size)
Erase blocks on a block device.
virtual bd_size_t get_read_size() const
Get the size of a readable block.
MBRBlockDevice(BlockDevice *bd, int part)
Lifetime of the block device.
virtual int read(void *buffer, bd_addr_t addr, bd_size_t size)
Read blocks from a block device.
Definition: ATHandler.h:46
static int partition(BlockDevice *bd, int part, uint8_t type, bd_addr_t start)
Format the MBR to contain the following partition.
virtual const char * get_type() const
Get the BlockDevice class type.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.