Mistake on this page?
Report an issue in GitHub or email us
ExhaustibleBlockDevice.h
1 /*
2  * Copyright (c) 2018-2019, Arm Limited and affiliates.
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 /** \addtogroup storage */
19 /** @{*/
20 
21 #ifndef MBED_EXHAUSTIBLE_BLOCK_DEVICE_H
22 #define MBED_EXHAUSTIBLE_BLOCK_DEVICE_H
23 
24 #include "BlockDevice.h"
25 
26 namespace mbed {
27 
28 /** Heap backed block device which simulates failures
29  *
30  * Similar to heap block device but sectors wear out and are no longer programmable
31  * after a configurable number of cycles.
32  *
33  */
35 public:
36  /** Lifetime of the block device
37  *
38  * @param bd Block device to back the ExhaustibleBlockDevice
39  * @param erase_cycles Number of erase cycles before failure
40  */
41  ExhaustibleBlockDevice(BlockDevice *bd, uint32_t erase_cycles);
42  virtual ~ExhaustibleBlockDevice();
43 
44  /**
45  * Get the number of erase cycles remaining on a block
46  *
47  * @param addr Any address in the block being queried for erase cycles
48  * @return Number of erase cycles remaining
49  */
50  uint32_t get_erase_cycles(bd_addr_t addr) const;
51 
52  /**
53  * Set the number of erase cycles before failure
54  *
55  * @param addr Any address in the block being queried for erase cycles
56  * @param cycles Erase cycles before the block malfunctions
57  */
58  void set_erase_cycles(bd_addr_t addr, uint32_t cycles);
59 
60  /** Initialize a block device
61  *
62  * @return 0 on success or a negative error code on failure
63  */
64  virtual int init();
65 
66  /** Deinitialize a block device
67  *
68  * @return 0 on success or a negative error code on failure
69  */
70  virtual int deinit();
71 
72  /** Ensure data on storage is in sync with the driver
73  *
74  * @return 0 on success or a negative error code on failure
75  */
76  virtual int sync();
77 
78  /** Read blocks from a block device
79  *
80  * @param buffer Buffer to read blocks into
81  * @param addr Address of block to begin reading from
82  * @param size Size to read in bytes, must be a multiple of read block size
83  * @return 0 on success, negative error code on failure
84  */
85  virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);
86 
87  /** Program blocks to a block device
88  *
89  * The blocks must have been erased prior to being programmed
90  *
91  * @param buffer Buffer of data to write to blocks
92  * @param addr Address of block to begin writing to
93  * @param size Size to write in bytes, must be a multiple of program block size
94  * @return 0 on success, negative error code on failure
95  */
96  virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);
97 
98  /** Erase blocks on a block device
99  *
100  * The state of an erased block is undefined until it has been programmed,
101  * unless get_erase_value returns a non-negative byte value
102  *
103  * @param addr Address of block to begin erasing
104  * @param size Size to erase in bytes, must be a multiple of erase block size
105  * @return 0 on success, negative error code on failure
106  */
107  virtual int erase(bd_addr_t addr, bd_size_t size);
108 
109  /** Get the size of a readable block
110  *
111  * @return Size of a readable block in bytes
112  */
113  virtual bd_size_t get_read_size() const;
114 
115  /** Get the size of a programmable block
116  *
117  * @return Size of a programmable block in bytes
118  */
119  virtual bd_size_t get_program_size() const;
120 
121  /** Get the size of an erasable block
122  *
123  * @return Size of an erasable block in bytes
124  */
125  virtual bd_size_t get_erase_size() const;
126 
127  /** Get the size of an erasable block 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 when 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 BlockDevice class type.
153  *
154  * @return A string represent the BlockDevice class type.
155  */
156  virtual const char *get_type() const;
157 
158 private:
159  BlockDevice *_bd;
160  uint32_t *_erase_array;
161  uint32_t _erase_cycles;
162  uint32_t _init_ref_count;
163  bool _is_initialized;
164 };
165 
166 } // namespace mbed
167 
168 // Added "using" for backwards compatibility
169 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
171 #endif
172 
173 #endif
174 
175 /** @}*/
virtual int deinit()
Deinitialize a block device.
virtual bd_size_t size() const
Get the total size of the underlying device.
virtual int get_erase_value() const
Get the value of storage when erased.
virtual bd_size_t get_read_size() const
Get the size of a readable block.
virtual bd_size_t get_erase_size() const
Get the size of an erasable block.
A hardware device capable of writing and reading blocks.
Definition: BlockDevice.h:47
void set_erase_cycles(bd_addr_t addr, uint32_t cycles)
Set the number of erase cycles before failure.
virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size)
Program blocks to a block device.
Heap backed block device which simulates failures.
virtual int read(void *buffer, bd_addr_t addr, bd_size_t size)
Read blocks from a block device.
virtual int erase(bd_addr_t addr, bd_size_t size)
Erase blocks on a block device.
virtual int sync()
Ensure data on storage is in sync with the driver.
virtual bd_size_t get_program_size() const
Get the size of a programmable block.
virtual int init()
Initialize a block device.
virtual const char * get_type() const
Get the BlockDevice class type.
ExhaustibleBlockDevice(BlockDevice *bd, uint32_t erase_cycles)
Lifetime of the block device.
uint32_t get_erase_cycles(bd_addr_t addr) const
Get the number of erase cycles remaining on a block.
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.