Mbed OS Reference
Loading...
Searching...
No Matches
ChainingBlockDevice.h
1/* mbed Microcontroller Library
2 * Copyright (c) 2017-2020 ARM Limited
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18
19#ifndef MBED_CHAINING_BLOCK_DEVICE_H
20#define MBED_CHAINING_BLOCK_DEVICE_H
21
22#include "BlockDevice.h"
23#include "platform/mbed_assert.h"
24#include <stdlib.h>
25
26namespace mbed {
27
28/** \addtogroup storage-blockdevice */
29/** @{*/
30
31/** Block device for chaining multiple block devices
32 * with the similar block sizes at sequential addresses
33 *
34 * @code
35 * #include "mbed.h"
36 * #include "HeapBlockDevice.h"
37 * #include "ChainingBlockDevice.h"
38 *
39 * // Create two smaller block devices with
40 * // 64 and 32 blocks of size 512 bytes
41 * HeapBlockDevice mem1(64*512, 512);
42 * HeapBlockDevice mem2(32*512, 512);
43 *
44 * // Create a block device backed by mem1 and mem2
45 * // contains 96 blocks of size 512 bytes
46 * BlockDevice *bds[] = {&mem1, &mem2};
47 * ChainingBlockDevice chainmem(bds);
48 * @endcode
49 */
51public:
52 /** Lifetime of the memory block device
53 *
54 * @param bds Array of block devices to chain with sequential block addresses
55 * @param bd_count Number of block devices to chain
56 * @note All block devices must have the same block size
57 */
58 ChainingBlockDevice(BlockDevice **bds, size_t bd_count);
59
60 /** Lifetime of the memory block device
61 *
62 * @param bds Array of block devices to chain with sequential block addresses
63 * @note All block devices must have the same block size
64 */
65 template <size_t Size>
67 : _bds(bds), _bd_count(sizeof(bds) / sizeof(bds[0]))
68 , _read_size(0), _program_size(0), _erase_size(0), _size(0), _init_ref_count(0)
69 {
70 }
71
72 /** Lifetime of the memory block device
73 *
74 */
76
77 /** Initialize a block device
78 *
79 * @return 0 on success or a negative error code on failure
80 */
81 virtual int init();
82
83 /** Deinitialize a block device
84 *
85 * @return 0 on success or a negative error code on failure
86 */
87 virtual int deinit();
88
89 /** Ensure data on storage is in sync with the driver
90 *
91 * @return 0 on success or a negative error code on failure
92 */
93 virtual int sync();
94
95 /** Read blocks from a block device
96 *
97 * @param buffer Buffer to write blocks to
98 * @param addr Address of block to begin reading from
99 * @param size Size to read in bytes, must be a multiple of read block size
100 * @return 0 on success, negative error code on failure
101 */
102 virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);
103
104 /** Program blocks to a block device
105 *
106 * The blocks must have been erased prior to being programmed
107 *
108 * @param buffer Buffer of data to write to blocks
109 * @param addr Address of block to begin writing to
110 * @param size Size to write in bytes, must be a multiple of program block size
111 * @return 0 on success, negative error code on failure
112 */
113 virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);
114
115 /** Erase blocks on a block device
116 *
117 * The state of an erased block is undefined until it has been programmed,
118 * unless get_erase_value returns a non-negative byte value
119 *
120 * @param addr Address of block to begin erasing
121 * @param size Size to erase in bytes, must be a multiple of erase block size
122 * @return 0 on success, negative error code on failure
123 */
124 virtual int erase(bd_addr_t addr, bd_size_t size);
125
126 /** Get the size of a readable block
127 *
128 * @return Size of a readable block in bytes
129 */
130 virtual bd_size_t get_read_size() const;
131
132 /** Get the size of a programmable block
133 *
134 * @return Size of a programmable block in bytes
135 * @note Must be a multiple of the read size
136 */
138
139 /** Get the size of an eraseable block
140 *
141 * @return Size of an erasable block in bytes
142 * @note Must be a multiple of the program size
143 */
144 virtual bd_size_t get_erase_size() const;
145
146 /** Get the size of an erasable block given address
147 *
148 * @param addr Address within the erasable block
149 * @return Size of an erasable block in bytes
150 * @note Must be a multiple of the program size
151 */
152 virtual bd_size_t get_erase_size(bd_addr_t addr) const;
153
154 /** Get the value of storage when erased
155 *
156 * If get_erase_value returns a non-negative byte value, the underlying
157 * storage is set to that value when erased, and storage containing
158 * that value can be programmed without another erase.
159 *
160 * @return The value of storage when erased, or -1 if you can't
161 * rely on the value of erased storage
162 */
163 virtual int get_erase_value() const;
164
165 /** Get the total size of the underlying device
166 *
167 * @return Size of the underlying device in bytes
168 */
169 virtual bd_size_t size() const;
170
171 /** Get the BlockDevice class type.
172 *
173 * @return A string represent the BlockDevice class type.
174 */
175 virtual const char *get_type() const;
176
177protected:
178 BlockDevice **_bds;
179 size_t _bd_count;
180 bd_size_t _read_size;
181 bd_size_t _program_size;
182 bd_size_t _erase_size;
183 bd_size_t _size;
184 int _erase_value;
185 uint32_t _init_ref_count;
186 bool _is_initialized;
187};
188
189/** @}*/
190
191} // namespace mbed
192
193// Added "using" for backwards compatibility
194#ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
196#endif
197
198#endif
A hardware device capable of writing and reading blocks.
Definition: BlockDevice.h:53
Block device for chaining multiple block devices with the similar block sizes at sequential addresses...
virtual const char * get_type() const
Get the BlockDevice class type.
ChainingBlockDevice(BlockDevice **bds, size_t bd_count)
Lifetime of the memory block device.
virtual int erase(bd_addr_t addr, bd_size_t size)
Erase blocks on a block device.
virtual bd_size_t get_program_size() const
Get the size of a programmable block.
virtual ~ChainingBlockDevice()
Lifetime of the memory block device.
virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size)
Program blocks to a block device.
virtual int sync()
Ensure data on storage is in sync with the driver.
virtual bd_size_t get_erase_size() const
Get the size of an eraseable block.
virtual int deinit()
Deinitialize a block device.
virtual bd_size_t get_read_size() const
Get the size of a readable block.
virtual bd_size_t size() const
Get the total size of the underlying device.
virtual int read(void *buffer, bd_addr_t addr, bd_size_t size)
Read blocks from a block device.
virtual int init()
Initialize a block device.
ChainingBlockDevice(BlockDevice *(&bds)[Size])
Lifetime of the memory block device.
virtual int get_erase_value() const
Get the value of storage when erased.
virtual bd_size_t get_erase_size(bd_addr_t addr) const
Get the size of an erasable block given address.
uint64_t bd_size_t
Type representing a quantity of 8-bit bytes.
Definition: BlockDevice.h:48
uint64_t bd_addr_t
Type representing the address of a specific block.
Definition: BlockDevice.h:44