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