Mbed OS Reference
Loading...
Searching...
No Matches
BufferedBlockDevice.h
1/* mbed Microcontroller Library
2 * Copyright (c) 2018-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_BUFFERED_BLOCK_DEVICE_H
20#define MBED_BUFFERED_BLOCK_DEVICE_H
21
22#include "BlockDevice.h"
23
24namespace mbed {
25
26/** \addtogroup storage-blockdevice */
27/** @{*/
28
29/**
30 * Block device which allows minimal read and program sizes (of 1) for the underlying BD
31 * using a buffer on the heap. This essentially "simulates" a byte-programmable device
32 * like a NOR flash or an EEPROM, using a non-byte-programmable device like an SD card or
33 * NAND flash.
34 *
35 * @note While the read and write size of the buffered block device will always be 1,
36 * the erase size is the same as the underlying block device. In other words, you
37 * still must erase in the hardware erase sector size.
38 */
40public:
41 /** Lifetime of a memory-buffered block device wrapping an underlying block device
42 *
43 * @param bd Block device to back the BufferedBlockDevice
44 */
46
47 /** Lifetime of the memory-buffered block device
48 */
50
51 /** Initialize a buffered-memory block device and its underlying block device
52 *
53 * @return 0 on success or a negative error code on failure
54 */
55 virtual int init();
56
57 /** Deinitialize the buffered-memory block device and its underlying block device
58 *
59 * @return 0 on success or a negative error code on failure
60 */
61 virtual int deinit();
62
63 /** Ensure that data on the underlying storage block device is in sync with the
64 * memory-buffered block device
65 *
66 * @return 0 on success or a negative error code on failure
67 */
68 virtual int sync();
69
70 /** Read blocks from the memory-buffered block device
71 *
72 * @param buffer Buffer to read blocks into
73 * @param addr Address of block to begin reading from
74 * @param size Size to read in bytes, must be a multiple of read block size
75 * @return 0 on success, negative error code on failure
76 */
77 virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);
78
79 /** Program data to the memory-buffered block device
80 *
81 * The write address blocks must be erased prior to being programmed.
82 *
83 * @param buffer Buffer of data to write to blocks
84 * @param addr Address of block to begin writing to
85 * @param size Size to write in bytes, must be a multiple of program block size
86 * @return 0 on success, negative error code on failure
87 */
88 virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);
89
90 /** Erase blocks from the memory-buffered block device
91 *
92 * The state of an erased block is undefined until it has been programmed,
93 * unless get_erase_value returns a non-negative byte value.
94 *
95 * @param addr Address of block to begin erasing
96 * @param size Size to erase in bytes, must be a multiple of erase block size
97 * @return 0 on success, negative error code on failure
98 */
99 virtual int erase(bd_addr_t addr, bd_size_t size);
100
101 /** Mark blocks as no longer in use
102 *
103 * This function provides a hint to the underlying block device that a region of blocks
104 * is no longer in use and may be erased without side effects. Erase must still be called
105 * before programming, but trimming allows flash-translation-layers to schedule erases when
106 * the device is not busy.
107 *
108 * @param addr Address of block to mark as unused
109 * @param size Size to mark as unused in bytes, must be a multiple of erase block size
110 * @return 0 on success, negative error code on failure
111 */
112 virtual int trim(bd_addr_t addr, bd_size_t size);
113
114 /** Get the size of a readable block
115 *
116 * @return Size of a readable block in bytes
117 */
118 virtual bd_size_t get_read_size() const;
119
120 /** Get the size of a programmable block
121 *
122 * @return Size of a programmable block in bytes
123 * @note Must be a multiple of the read size
124 */
126
127 /** Get the size of an erasable block
128 *
129 * @return Size of an erasable block in bytes
130 * @note Must be a multiple of the program size
131 */
132 virtual bd_size_t get_erase_size() const;
133
134 /** Get the size of an erasable block of a given address
135 *
136 * @param addr Address within the erasable block
137 * @return Size of an erasable block in bytes
138 * @note Must be a multiple of the program size
139 */
140 virtual bd_size_t get_erase_size(bd_addr_t addr) const;
141
142 /** Get the value of storage data after being erased
143 *
144 * If get_erase_value returns a non-negative byte value, the underlying
145 * storage is set to that value when erased, and storage containing
146 * that value can be programmed without another erase.
147 *
148 * @return The value of storage when erased, or -1 if you can't
149 * rely on the value of erased storage
150 */
151 virtual int get_erase_value() const;
152
153 /** Get the total size of the underlying device
154 *
155 * @return Size of the underlying device in bytes
156 */
157 virtual bd_size_t size() const;
158
159 /** Get the underlying BlockDevice class type
160 *
161 * @return A string representing the underlying BlockDevice class type
162 */
163 virtual const char *get_type() const;
164
165protected:
166 BlockDevice *_bd;
167 bd_size_t _bd_program_size;
168 bd_size_t _bd_read_size;
169 bd_size_t _bd_size;
170 bd_size_t _write_cache_addr;
171 bool _write_cache_valid;
172 uint8_t *_write_cache;
173 uint8_t *_read_buf;
174 uint32_t _init_ref_count;
175 bool _is_initialized;
176
177#if !(DOXYGEN_ONLY)
178 /** Flush data in cache
179 *
180 * @return 0 on success or a negative error code on failure
181 */
182 int flush();
183
184 /** Invalidate write cache
185 *
186 * @return none
187 */
188 void invalidate_write_cache();
189#endif //#if !(DOXYGEN_ONLY)
190};
191
192/** @}*/
193
194} // namespace mbed
195
196// Added "using" for backwards compatibility
197#ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
199#endif
200
201#endif
A hardware device capable of writing and reading blocks.
Definition: BlockDevice.h:53
Block device which allows minimal read and program sizes (of 1) for the underlying BD using a buffer ...
virtual const char * get_type() const
Get the underlying BlockDevice class type.
virtual ~BufferedBlockDevice()
Lifetime of the memory-buffered block device.
virtual int erase(bd_addr_t addr, bd_size_t size)
Erase blocks from the memory-buffered block device.
virtual bd_size_t get_program_size() const
Get the size of a programmable block.
virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size)
Program data to the memory-buffered block device.
virtual int sync()
Ensure that data on the underlying storage block device is in sync with the memory-buffered block dev...
virtual bd_size_t get_erase_size() const
Get the size of an erasable block.
virtual int deinit()
Deinitialize the buffered-memory block device and its underlying block device.
virtual bd_size_t get_read_size() const
Get the size of a readable block.
BufferedBlockDevice(BlockDevice *bd)
Lifetime of a memory-buffered block device wrapping an underlying block device.
virtual bd_size_t size() const
Get the total size of the underlying device.
virtual int trim(bd_addr_t addr, bd_size_t size)
Mark blocks as no longer in use.
virtual int read(void *buffer, bd_addr_t addr, bd_size_t size)
Read blocks from the memory-buffered block device.
virtual int init()
Initialize a buffered-memory block device and its underlying block device.
virtual int get_erase_value() const
Get the value of storage data after being erased.
virtual bd_size_t get_erase_size(bd_addr_t addr) const
Get the size of an erasable block of a 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