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