Mistake on this page?
Report an issue in GitHub or email us
ChainingBlockDevice.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_CHAINING_BLOCK_DEVICE_H
27 #define MBED_CHAINING_BLOCK_DEVICE_H
28 
29 #include "BlockDevice.h"
30 #include "platform/mbed_assert.h"
31 #include <stdlib.h>
32 
33 namespace mbed {
34 
35 /** Block device for chaining multiple block devices
36  * with the similar block sizes at sequential addresses
37  *
38  * @code
39  * #include "mbed.h"
40  * #include "HeapBlockDevice.h"
41  * #include "ChainingBlockDevice.h"
42  *
43  * // Create two smaller block devices with
44  * // 64 and 32 blocks of size 512 bytes
45  * HeapBlockDevice mem1(64*512, 512);
46  * HeapBlockDevice mem2(32*512, 512);
47  *
48  * // Create a block device backed by mem1 and mem2
49  * // contains 96 blocks of size 512 bytes
50  * BlockDevice *bds[] = {&mem1, &mem2};
51  * ChainingBlockDevice chainmem(bds);
52  * @endcode
53  */
55 public:
56  /** Lifetime of the memory block device
57  *
58  * @param bds Array of block devices to chain with sequential block addresses
59  * @param bd_count Number of block devices to chain
60  * @note All block devices must have the same block size
61  */
62  ChainingBlockDevice(BlockDevice **bds, size_t bd_count);
63 
64  /** Lifetime of the memory block device
65  *
66  * @param bds Array of block devices to chain with sequential block addresses
67  * @note All block devices must have the same block size
68  */
69  template <size_t Size>
71  : _bds(bds), _bd_count(sizeof(bds) / sizeof(bds[0]))
72  , _read_size(0), _program_size(0), _erase_size(0), _size(0), _init_ref_count(0)
73  {
74  }
75 
76  /** Lifetime of the memory block device
77  *
78  */
79  virtual ~ChainingBlockDevice() {}
80 
81  /** Initialize a block device
82  *
83  * @return 0 on success or a negative error code on failure
84  */
85  virtual int init();
86 
87  /** Deinitialize a block device
88  *
89  * @return 0 on success or a negative error code on failure
90  */
91  virtual int deinit();
92 
93  /** Ensure data on storage is in sync with the driver
94  *
95  * @return 0 on success or a negative error code on failure
96  */
97  virtual int sync();
98 
99  /** Read blocks from a block device
100  *
101  * @param buffer Buffer to write blocks to
102  * @param addr Address of block to begin reading from
103  * @param size Size to read in bytes, must be a multiple of read block size
104  * @return 0 on success, negative error code on failure
105  */
106  virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);
107 
108  /** Program blocks to a block device
109  *
110  * The blocks must have been erased prior to being programmed
111  *
112  * @param buffer Buffer of data to write to blocks
113  * @param addr Address of block to begin writing to
114  * @param size Size to write in bytes, must be a multiple of program block size
115  * @return 0 on success, negative error code on failure
116  */
117  virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);
118 
119  /** Erase blocks on a block device
120  *
121  * The state of an erased block is undefined until it has been programmed,
122  * unless get_erase_value returns a non-negative byte value
123  *
124  * @param addr Address of block to begin erasing
125  * @param size Size to erase in bytes, must be a multiple of erase block size
126  * @return 0 on success, negative error code on failure
127  */
128  virtual int erase(bd_addr_t addr, bd_size_t size);
129 
130  /** Get the size of a readable block
131  *
132  * @return Size of a readable block in bytes
133  */
134  virtual bd_size_t get_read_size() const;
135 
136  /** Get the size of a programmable block
137  *
138  * @return Size of a programmable block in bytes
139  * @note Must be a multiple of the read size
140  */
141  virtual bd_size_t get_program_size() const;
142 
143  /** Get the size of an eraseable block
144  *
145  * @return Size of an erasable block in bytes
146  * @note Must be a multiple of the program size
147  */
148  virtual bd_size_t get_erase_size() const;
149 
150  /** Get the size of an erasable block given address
151  *
152  * @param addr Address within the erasable block
153  * @return Size of an erasable block in bytes
154  * @note Must be a multiple of the program size
155  */
156  virtual bd_size_t get_erase_size(bd_addr_t addr) const;
157 
158  /** Get the value of storage when erased
159  *
160  * If get_erase_value returns a non-negative byte value, the underlying
161  * storage is set to that value when erased, and storage containing
162  * that value can be programmed without another erase.
163  *
164  * @return The value of storage when erased, or -1 if you can't
165  * rely on the value of erased storage
166  */
167  virtual int get_erase_value() const;
168 
169  /** Get the total size of the underlying device
170  *
171  * @return Size of the underlying device in bytes
172  */
173  virtual bd_size_t size() const;
174 
175  /** Get the BlockDevice class type.
176  *
177  * @return A string represent the BlockDevice class type.
178  */
179  virtual const char *get_type() const;
180 
181 protected:
182  BlockDevice **_bds;
183  size_t _bd_count;
184  bd_size_t _read_size;
185  bd_size_t _program_size;
186  bd_size_t _erase_size;
187  bd_size_t _size;
188  int _erase_value;
189  uint32_t _init_ref_count;
190  bool _is_initialized;
191 };
192 
193 } // namespace mbed
194 
195 // Added "using" for backwards compatibility
196 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
198 #endif
199 
200 #endif
201 
202 /** @}*/
virtual int read(void *buffer, bd_addr_t addr, bd_size_t size)
Read blocks from a block device.
virtual bd_size_t get_program_size() const
Get the size of a programmable block.
ChainingBlockDevice(BlockDevice *(&bds)[Size])
Lifetime of the memory block device.
virtual ~ChainingBlockDevice()
Lifetime of the memory block device.
A hardware device capable of writing and reading blocks.
Definition: BlockDevice.h:47
virtual const char * get_type() const
Get the BlockDevice class type.
virtual int get_erase_value() const
Get the value of storage when erased.
virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size)
Program blocks to a block device.
virtual bd_size_t size() const
Get the total size of the underlying device.
virtual int init()
Initialize a block device.
virtual bd_size_t get_read_size() const
Get the size of a readable block.
virtual int erase(bd_addr_t addr, bd_size_t size)
Erase blocks on a block device.
virtual int deinit()
Deinitialize a block device.
Block device for chaining multiple block devices with the similar block sizes at sequential addresses...
virtual int sync()
Ensure data on storage is in sync with the driver.
ChainingBlockDevice(BlockDevice **bds, size_t bd_count)
Lifetime of the memory block device.
virtual bd_size_t get_erase_size() const
Get the size of an eraseable block.
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.