ExhaustibleBlockDevice.h

00001 /*
00002  * Copyright (c) 2018-2019, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 /** \addtogroup storage */
00019 /** @{*/
00020 
00021 #ifndef MBED_EXHAUSTIBLE_BLOCK_DEVICE_H
00022 #define MBED_EXHAUSTIBLE_BLOCK_DEVICE_H
00023 
00024 #include "BlockDevice.h"
00025 
00026 namespace mbed {
00027 
00028 /** Heap backed block device which simulates failures
00029  *
00030  * Similar to heap block device but sectors wear out and are no longer programmable
00031  * after a configurable number of cycles.
00032  *
00033  */
00034 class ExhaustibleBlockDevice : public BlockDevice {
00035 public:
00036     /** Lifetime of the block device
00037      *
00038      * @param bd            Block device to back the ExhaustibleBlockDevice
00039      * @param erase_cycles  Number of erase cycles before failure
00040      */
00041     ExhaustibleBlockDevice(BlockDevice *bd, uint32_t erase_cycles);
00042     virtual ~ExhaustibleBlockDevice();
00043 
00044     /**
00045      * Get the number of erase cycles remaining on a block
00046      *
00047      * @param addr      Any address in the block being queried for erase cycles
00048      * @return          Number of erase cycles remaining
00049      */
00050     uint32_t get_erase_cycles(bd_addr_t addr) const;
00051 
00052     /**
00053      * Set the number of erase cycles before failure
00054      *
00055      * @param addr      Any address in the block being queried for erase cycles
00056      * @param cycles    Erase cycles before the block malfunctions
00057      */
00058     void set_erase_cycles(bd_addr_t addr, uint32_t cycles);
00059 
00060     /** Initialize a block device
00061      *
00062      *  @return         0 on success or a negative error code on failure
00063      */
00064     virtual int init();
00065 
00066     /** Deinitialize a block device
00067      *
00068      *  @return         0 on success or a negative error code on failure
00069      */
00070     virtual int deinit();
00071 
00072     /** Ensure data on storage is in sync with the driver
00073      *
00074      *  @return         0 on success or a negative error code on failure
00075      */
00076     virtual int sync();
00077 
00078     /** Read blocks from a block device
00079      *
00080      *  @param buffer   Buffer to read blocks into
00081      *  @param addr     Address of block to begin reading from
00082      *  @param size     Size to read in bytes, must be a multiple of read block size
00083      *  @return         0 on success, negative error code on failure
00084      */
00085     virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);
00086 
00087     /** Program blocks to a block device
00088      *
00089      *  The blocks must have been erased prior to being programmed
00090      *
00091      *  @param buffer   Buffer of data to write to blocks
00092      *  @param addr     Address of block to begin writing to
00093      *  @param size     Size to write in bytes, must be a multiple of program block size
00094      *  @return         0 on success, negative error code on failure
00095      */
00096     virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);
00097 
00098     /** Erase blocks on a block device
00099      *
00100      *  The state of an erased block is undefined until it has been programmed,
00101      *  unless get_erase_value returns a non-negative byte value
00102      *
00103      *  @param addr     Address of block to begin erasing
00104      *  @param size     Size to erase in bytes, must be a multiple of erase block size
00105      *  @return         0 on success, negative error code on failure
00106      */
00107     virtual int erase(bd_addr_t addr, bd_size_t size);
00108 
00109     /** Get the size of a readable block
00110      *
00111      *  @return         Size of a readable block in bytes
00112      */
00113     virtual bd_size_t get_read_size() const;
00114 
00115     /** Get the size of a programmable block
00116      *
00117      *  @return         Size of a programmable block in bytes
00118      */
00119     virtual bd_size_t get_program_size() const;
00120 
00121     /** Get the size of an erasable block
00122      *
00123      *  @return         Size of an erasable block in bytes
00124      */
00125     virtual bd_size_t get_erase_size() const;
00126 
00127     /** Get the size of an erasable block given address
00128      *
00129      *  @param addr     Address within the erasable block
00130      *  @return         Size of an erasable block in bytes
00131      *  @note Must be a multiple of the program size
00132      */
00133     virtual bd_size_t get_erase_size(bd_addr_t addr) const;
00134 
00135     /** Get the value of storage when erased
00136      *
00137      *  If get_erase_value returns a non-negative byte value, the underlying
00138      *  storage is set to that value when erased, and storage containing
00139      *  that value can be programmed without another erase.
00140      *
00141      *  @return         The value of storage when erased, or -1 if you can't
00142      *                  rely on the value of erased storage
00143      */
00144     virtual int get_erase_value() const;
00145 
00146     /** Get the total size of the underlying device
00147      *
00148      *  @return         Size of the underlying device in bytes
00149      */
00150     virtual bd_size_t size() const;
00151 
00152     /** Get the BlockDevice class type.
00153      *
00154      *  @return         A string represent the BlockDevice class type.
00155      */
00156     virtual const char *get_type() const;
00157 
00158 private:
00159     BlockDevice *_bd;
00160     uint32_t *_erase_array;
00161     uint32_t _erase_cycles;
00162     uint32_t _init_ref_count;
00163     bool _is_initialized;
00164 };
00165 
00166 } // namespace mbed
00167 
00168 // Added "using" for backwards compatibility
00169 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
00170 using mbed::ExhaustibleBlockDevice;
00171 #endif
00172 
00173 #endif
00174 
00175 /** @}*/