Mbed OS Reference
Loading...
Searching...
No Matches
SlicingBlockDevice.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_SLICING_BLOCK_DEVICE_H
20#define MBED_SLICING_BLOCK_DEVICE_H
21
22#include "BlockDevice.h"
23#include "platform/mbed_assert.h"
24
25namespace mbed {
26
27/** \addtogroup storage-blockdevice */
28/** @{*/
29
30/** Block device for mapping to a slice of another block device
31 */
33public:
34 /** Lifetime of the memory block device
35 *
36 * @param bd Block device to back the SlicingBlockDevice
37 * @param start Start block address to map to block 0, negative addresses
38 * are calculated from the end of the underlying block device
39 * @param end End block address to mark the end of the block device,
40 * this block is not mapped, negative addresses are
41 * calculated from the end of the underlying block device.
42 * The default stops at end of the underlying block device.
43 */
45
46 /** Lifetime of a block device
47 */
48 virtual ~SlicingBlockDevice() {};
49
50 /** Initialize a block device
51 *
52 * @return 0 on success or a negative error code on failure
53 */
54 virtual int init();
55
56 /** Deinitialize a block device
57 *
58 * @return 0 on success or a negative error code on failure
59 */
60 virtual int deinit();
61
62 /** Ensure data on storage is in sync with the driver
63 *
64 * @return 0 on success or a negative error code on failure
65 */
66 virtual int sync();
67
68 /** Read blocks from a block device
69 *
70 * @param buffer Buffer to read blocks into
71 * @param addr Address of block to begin reading from
72 * @param size Size to read in bytes, must be a multiple of read block size
73 * @return 0 on success or a negative error code on failure
74 */
75 virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);
76
77 /** Program blocks to a block device
78 *
79 * The blocks must have been erased prior to being programmed
80 *
81 * @param buffer Buffer of data to write to blocks
82 * @param addr Address of block to begin writing to
83 * @param size Size to write in bytes, must be a multiple of program block size
84 * @return 0 on success or a negative error code on failure
85 */
86 virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);
87
88 /** Erase blocks on a block device
89 *
90 * The state of an erased block is undefined until it has been programmed,
91 * unless get_erase_value returns a non-negative byte value
92 *
93 * @param addr Address of block to begin erasing
94 * @param size Size to erase in bytes, must be a multiple of erase block size
95 * @return 0 on success or a negative error code on failure
96 */
97 virtual int erase(bd_addr_t addr, bd_size_t size);
98
99 /** Get the size of a readable block
100 *
101 * @return Size of a readable block in bytes
102 */
103 virtual bd_size_t get_read_size() const;
104
105 /** Get the size of a programmable block
106 *
107 * @return Size of a programmable block in bytes
108 * @note Must be a multiple of the read size
109 */
111
112 /** Get the size of an erasable block
113 *
114 * @return Size of an erasable block in bytes
115 * @note Must be a multiple of the program size
116 */
117 virtual bd_size_t get_erase_size() const;
118
119 /** Get the size of an erasable block given address
120 *
121 * @param addr Address within the erasable block
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(bd_addr_t addr) const;
126
127 /** Get the value of storage when erased
128 *
129 * If get_erase_value returns a non-negative byte value, the underlying
130 * storage is set to that value when erased, and storage containing
131 * that value can be programmed without another erase.
132 *
133 * @return The value of storage when erased, or -1 if you can't
134 * rely on the value of erased storage
135 */
136 virtual int get_erase_value() const;
137
138 /** Get the total size of the underlying device
139 *
140 * @return Size of the underlying device in bytes
141 */
142 virtual bd_size_t size() const;
143
144 /** Get the BlockDevice class type.
145 *
146 * @return A string represent the BlockDevice class type.
147 */
148 virtual const char *get_type() const;
149
150 /** Convenience function for checking block program validity
151 *
152 * @param addr Address of block to begin writing to
153 * @param size Size to write in bytes
154 * @return True if program is valid for underlying block device
155 */
156 virtual bool is_valid_program(bd_addr_t addr, bd_size_t size) const;
157
158 /** Convenience function for checking block read validity
159 *
160 * @param addr Address of block to begin reading from
161 * @param size Size to read in bytes
162 * @return True if read is valid for underlying block device
163 */
164 virtual bool is_valid_read(bd_addr_t addr, bd_size_t size) const;
165
166 /** Convenience function for checking block erase validity
167 *
168 * @param addr Address of block to begin erasing
169 * @param size Size to erase in bytes
170 * @return True if erase is valid for underlying block device
171 */
172 virtual bool is_valid_erase(bd_addr_t addr, bd_size_t size) const;
173
174
175protected:
176 BlockDevice *_bd;
177 bool _start_from_end;
178 bd_size_t _start;
179 bool _stop_from_end;
180 bd_size_t _stop;
181};
182
183/** @}*/
184
185} // namespace mbed
186
187// Added "using" for backwards compatibility
188#ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
190#endif
191
192#endif
193
A hardware device capable of writing and reading blocks.
Definition: BlockDevice.h:53
Block device for mapping to a slice of another block device.
virtual const char * get_type() const
Get the BlockDevice class type.
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.
SlicingBlockDevice(BlockDevice *bd, bd_addr_t start, bd_addr_t end=0)
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 bool is_valid_read(bd_addr_t addr, bd_size_t size) const
Convenience function for checking block read validity.
virtual ~SlicingBlockDevice()
Lifetime of 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 erasable block.
virtual bool is_valid_erase(bd_addr_t addr, bd_size_t size) const
Convenience function for checking block erase validity.
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 bool is_valid_program(bd_addr_t addr, bd_size_t size) const
Convenience function for checking block program validity.
virtual int init()
Initialize a 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