Mistake on this page?
Report an issue in GitHub or email us
BlockDevice.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2017 ARM Limited
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /** \addtogroup storage */
18 /** @{*/
19 
20 #ifndef MBED_BLOCK_DEVICE_H
21 #define MBED_BLOCK_DEVICE_H
22 
23 #include <stdint.h>
24 
25 namespace mbed {
26 
27 /** Enum of standard error codes
28  *
29  * @enum bd_error
30  */
31 enum bd_error {
32  BD_ERROR_OK = 0, /*!< no error */
33  BD_ERROR_DEVICE_ERROR = -4001, /*!< device specific error */
34 };
35 
36 /** Type representing the address of a specific block
37  */
38 typedef uint64_t bd_addr_t;
39 
40 /** Type representing a quantity of 8-bit bytes
41  */
42 typedef uint64_t bd_size_t;
43 
44 
45 /** A hardware device capable of writing and reading blocks
46  */
47 class BlockDevice {
48 public:
49 
50  /** Return the default block device
51  *
52  * Returns the default block device based on the configuration JSON.
53  * Use the components in target.json or application config to change
54  * the default block device.
55  *
56  * An application can override all target settings by implementing
57  * BlockDevice::get_default_instance() - the default
58  * definition is weak, and calls get_target_default_instance().
59  */
61 
62  /** Lifetime of a block device
63  */
64  virtual ~BlockDevice() {};
65 
66  /** Initialize a block device
67  *
68  * @return 0 on success or a negative error code on failure
69  */
70  virtual int init() = 0;
71 
72  /** Deinitialize a block device
73  *
74  * @return 0 on success or a negative error code on failure
75  */
76  virtual int deinit() = 0;
77 
78  /** Ensure data on storage is in sync with the driver
79  *
80  * @return 0 on success or a negative error code on failure
81  */
82  virtual int sync()
83  {
84  return 0;
85  }
86 
87  /** Read blocks from a block device
88  *
89  * If a failure occurs, it is not possible to determine how many bytes succeeded
90  *
91  * @param buffer Buffer to write blocks to
92  * @param addr Address of block to begin reading from
93  * @param size Size to read in bytes, must be a multiple of the read block size
94  * @return 0 on success or a negative error code on failure
95  */
96  virtual int read(void *buffer, bd_addr_t addr, bd_size_t size) = 0;
97 
98  /** Program blocks to a block device
99  *
100  * The blocks must have been erased prior to being programmed
101  *
102  * If a failure occurs, it is not possible to determine how many bytes succeeded
103  *
104  * @param buffer Buffer of data to write to blocks
105  * @param addr Address of block to begin writing to
106  * @param size Size to write in bytes, must be a multiple of the program block size
107  * @return 0 on success or a negative error code on failure
108  */
109  virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size) = 0;
110 
111  /** Erase blocks on a block device
112  *
113  * The state of an erased block is undefined until it has been programmed,
114  * unless get_erase_value returns a non-negative byte value
115  *
116  * @param addr Address of block to begin erasing
117  * @param size Size to erase in bytes, must be a multiple of the erase block size
118  * @return 0 on success or a negative error code on failure
119  */
120  virtual int erase(bd_addr_t addr, bd_size_t size)
121  {
122  return 0;
123  }
124 
125  /** Mark blocks as no longer in use
126  *
127  * This function provides a hint to the underlying block device that a region of blocks
128  * is no longer in use and may be erased without side effects. Erase must still be called
129  * before programming, but trimming allows flash-translation-layers to schedule erases when
130  * the device is not busy.
131  *
132  * @param addr Address of block to mark as unused
133  * @param size Size to mark as unused in bytes, must be a multiple of the erase block size
134  * @return 0 on success or a negative error code on failure
135  */
136  virtual int trim(bd_addr_t addr, bd_size_t size)
137  {
138  return 0;
139  }
140 
141  /** Get the size of a readable block
142  *
143  * @return Size of a readable block in bytes
144  */
145  virtual bd_size_t get_read_size() const = 0;
146 
147  /** Get the size of a programmable block
148  *
149  * @return Size of a programmable block in bytes
150  * @note Must be a multiple of the read size
151  */
152  virtual bd_size_t get_program_size() const = 0;
153 
154  /** Get the size of an erasable block
155  *
156  * @return Size of an erasable block in bytes
157  * @note Must be a multiple of the program size
158  */
159  virtual bd_size_t get_erase_size() const
160  {
161  return get_program_size();
162  }
163 
164  /** Get the size of an erasable block given address
165  *
166  * @param addr Address within the erasable block
167  * @return Size of an erasable block in bytes
168  * @note Must be a multiple of the program size
169  */
170  virtual bd_size_t get_erase_size(bd_addr_t addr) const
171  {
172  return get_erase_size();
173  }
174 
175  /** Get the value of storage when erased
176  *
177  * If get_erase_value returns a non-negative byte value, the underlying
178  * storage is set to that value when erased, and storage containing
179  * that value can be programmed without another erase.
180  *
181  * @return The value of storage when erased, or -1 if you can't
182  * rely on the value of the erased storage
183  */
184  virtual int get_erase_value() const
185  {
186  return -1;
187  }
188 
189  /** Get the total size of the underlying device
190  *
191  * @return Size of the underlying device in bytes
192  */
193  virtual bd_size_t size() const = 0;
194 
195  /** Convenience function for checking block read validity
196  *
197  * @param addr Address of block to begin reading from
198  * @param size Size to read in bytes
199  * @return True if read is valid for underlying block device
200  */
201  virtual bool is_valid_read(bd_addr_t addr, bd_size_t size) const
202  {
203  return (
204  addr % get_read_size() == 0 &&
205  size % get_read_size() == 0 &&
206  addr + size <= this->size());
207  }
208 
209  /** Convenience function for checking block program validity
210  *
211  * @param addr Address of block to begin writing to
212  * @param size Size to write in bytes
213  * @return True if program is valid for underlying block device
214  */
215  virtual bool is_valid_program(bd_addr_t addr, bd_size_t size) const
216  {
217  return (
218  addr % get_program_size() == 0 &&
219  size % get_program_size() == 0 &&
220  addr + size <= this->size());
221  }
222 
223  /** Convenience function for checking block erase validity
224  *
225  * @param addr Address of block to begin erasing
226  * @param size Size to erase in bytes
227  * @return True if erase is valid for underlying block device
228  */
229  virtual bool is_valid_erase(bd_addr_t addr, bd_size_t size) const
230  {
231  return (
232  addr % get_erase_size(addr) == 0 &&
233  (addr + size) % get_erase_size(addr + size - 1) == 0 &&
234  addr + size <= this->size());
235  }
236 
237  /** Get the BlockDevice class type.
238  *
239  * @return A string represent the BlockDevice class type.
240  */
241  virtual const char *get_type() const = 0;
242 };
243 
244 } // namespace mbed
245 
246 // Added "using" for backwards compatibility
247 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
248 using mbed::BlockDevice;
249 using mbed::bd_addr_t;
250 using mbed::bd_size_t;
251 using mbed::BD_ERROR_OK;
252 using mbed::BD_ERROR_DEVICE_ERROR;
253 #endif
254 
255 #endif
256 
257 /** @}*/
virtual const char * get_type() const =0
Get the BlockDevice class type.
virtual int deinit()=0
Deinitialize a block device.
virtual bool is_valid_read(bd_addr_t addr, bd_size_t size) const
Convenience function for checking block read validity.
Definition: BlockDevice.h:201
virtual bd_size_t get_read_size() const =0
Get the size of a readable block.
A hardware device capable of writing and reading blocks.
Definition: BlockDevice.h:47
virtual int init()=0
Initialize a block device.
virtual bd_size_t size() const =0
Get the total size of the underlying device.
virtual bd_size_t get_program_size() const =0
Get the size of a programmable block.
virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size)=0
Program blocks to a block device.
virtual bool is_valid_program(bd_addr_t addr, bd_size_t size) const
Convenience function for checking block program validity.
Definition: BlockDevice.h:215
virtual bd_size_t get_erase_size(bd_addr_t addr) const
Get the size of an erasable block given address.
Definition: BlockDevice.h:170
virtual int get_erase_value() const
Get the value of storage when erased.
Definition: BlockDevice.h:184
virtual int sync()
Ensure data on storage is in sync with the driver.
Definition: BlockDevice.h:82
virtual bool is_valid_erase(bd_addr_t addr, bd_size_t size) const
Convenience function for checking block erase validity.
Definition: BlockDevice.h:229
virtual int erase(bd_addr_t addr, bd_size_t size)
Erase blocks on a block device.
Definition: BlockDevice.h:120
static BlockDevice * get_default_instance()
Return the default block device.
virtual int trim(bd_addr_t addr, bd_size_t size)
Mark blocks as no longer in use.
Definition: BlockDevice.h:136
virtual int read(void *buffer, bd_addr_t addr, bd_size_t size)=0
Read blocks from a block device.
virtual ~BlockDevice()
Lifetime of a block device.
Definition: BlockDevice.h:64
virtual bd_size_t get_erase_size() const
Get the size of an erasable block.
Definition: BlockDevice.h:159
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.