BlockDevice.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2017 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef MBED_BLOCK_DEVICE_H
00018 #define MBED_BLOCK_DEVICE_H
00019 
00020 #include <stdint.h>
00021 
00022 
00023 /** Enum of standard error codes
00024  *
00025  *  @enum bd_error
00026  */
00027 enum bd_error {
00028     BD_ERROR_OK                 = 0,     /*!< no error */
00029     BD_ERROR_DEVICE_ERROR       = -4001, /*!< device specific error */
00030 };
00031 
00032 /** Type representing the address of a specific block
00033  */
00034 typedef uint64_t bd_addr_t;
00035 
00036 /** Type representing a quantity of 8-bit bytes
00037  */
00038 typedef uint64_t bd_size_t;
00039 
00040 
00041 /** A hardware device capable of writing and reading blocks
00042  */
00043 class BlockDevice
00044 {
00045 public:
00046 
00047     /** Return the default block device
00048      *
00049      * Returns the default BlockDevice base on configuration json.
00050      * Use the components in target.json or application config to change
00051      * the default block device.
00052      *
00053      * An application can override all target settings by implementing
00054      * BlockDevice::get_default_instance() themselves - the default
00055      * definition is weak, and calls get_target_default_instance().
00056     */
00057     static BlockDevice *get_default_instance();
00058 
00059     /** Lifetime of a block device
00060      */
00061     virtual ~BlockDevice() {};
00062 
00063     /** Initialize a block device
00064      *
00065      *  @return         0 on success or a negative error code on failure
00066      */
00067     virtual int init() = 0;
00068 
00069     /** Deinitialize a block device
00070      *
00071      *  @return         0 on success or a negative error code on failure
00072      */
00073     virtual int deinit() = 0;
00074 
00075     /** Ensure data on storage is in sync with the driver
00076      *
00077      *  @return         0 on success or a negative error code on failure
00078      */
00079     virtual int sync()
00080     {
00081         return 0;
00082     }
00083 
00084     /** Read blocks from a block device
00085      *
00086      *  If a failure occurs, it is not possible to determine how many bytes succeeded
00087      *
00088      *  @param buffer   Buffer to write blocks to
00089      *  @param addr     Address of block to begin reading from
00090      *  @param size     Size to read in bytes, must be a multiple of read block size
00091      *  @return         0 on success, negative error code on failure
00092      */
00093     virtual int read(void *buffer, bd_addr_t addr, bd_size_t size) = 0;
00094 
00095     /** Program blocks to a block device
00096      *
00097      *  The blocks must have been erased prior to being programmed
00098      *
00099      *  If a failure occurs, it is not possible to determine how many bytes succeeded
00100      *
00101      *  @param buffer   Buffer of data to write to blocks
00102      *  @param addr     Address of block to begin writing to
00103      *  @param size     Size to write in bytes, must be a multiple of program block size
00104      *  @return         0 on success, negative error code on failure
00105      */
00106     virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size) = 0;
00107 
00108     /** Erase blocks on a block device
00109      *
00110      *  The state of an erased block is undefined until it has been programmed,
00111      *  unless get_erase_value returns a non-negative byte value
00112      *
00113      *  @param addr     Address of block to begin erasing
00114      *  @param size     Size to erase in bytes, must be a multiple of erase block size
00115      *  @return         0 on success, negative error code on failure
00116      */
00117     virtual int erase(bd_addr_t addr, bd_size_t size)
00118     {
00119         return 0;
00120     }
00121 
00122     /** Mark blocks as no longer in use
00123      *
00124      *  This function provides a hint to the underlying block device that a region of blocks
00125      *  is no longer in use and may be erased without side effects. Erase must still be called
00126      *  before programming, but trimming allows flash-translation-layers to schedule erases when
00127      *  the device is not busy.
00128      *
00129      *  @param addr     Address of block to mark as unused
00130      *  @param size     Size to mark as unused in bytes, must be a multiple of erase block size
00131      *  @return         0 on success, negative error code on failure
00132      */
00133     virtual int trim(bd_addr_t addr, bd_size_t size)
00134     {
00135         return 0;
00136     }
00137 
00138     /** Get the size of a readable block
00139      *
00140      *  @return         Size of a readable block in bytes
00141      */
00142     virtual bd_size_t get_read_size() const = 0;
00143 
00144     /** Get the size of a programmable block
00145      *
00146      *  @return         Size of a programmable block in bytes
00147      *  @note Must be a multiple of the read size
00148      */
00149     virtual bd_size_t get_program_size() const = 0;
00150 
00151     /** Get the size of an erasable block
00152      *
00153      *  @return         Size of an erasable block in bytes
00154      *  @note Must be a multiple of the program size
00155      */
00156     virtual bd_size_t get_erase_size() const
00157     {
00158         return get_program_size();
00159     }
00160 
00161     /** Get the size of an erasable block given address
00162      *
00163      *  @param addr     Address within the erasable block
00164      *  @return         Size of an erasable block in bytes
00165      *  @note Must be a multiple of the program size
00166      */
00167     virtual bd_size_t get_erase_size(bd_addr_t addr) const
00168     {
00169         return get_erase_size();
00170     }
00171 
00172     /** Get the value of storage when erased
00173      *
00174      *  If get_erase_value returns a non-negative byte value, the underlying
00175      *  storage is set to that value when erased, and storage containing
00176      *  that value can be programmed without another erase.
00177      *
00178      *  @return         The value of storage when erased, or -1 if you can't
00179      *                  rely on the value of erased storage
00180      */
00181     virtual int get_erase_value() const
00182     {
00183         return -1;
00184     }
00185 
00186     /** Get the total size of the underlying device
00187      *
00188      *  @return         Size of the underlying device in bytes
00189      */
00190     virtual bd_size_t size() const = 0;
00191 
00192     /** Convenience function for checking block read validity
00193      *
00194      *  @param addr     Address of block to begin reading from
00195      *  @param size     Size to read in bytes
00196      *  @return         True if read is valid for underlying block device
00197      */
00198     bool is_valid_read(bd_addr_t addr, bd_size_t size) const
00199     {
00200         return (
00201             addr % get_read_size() == 0 &&
00202             size % get_read_size() == 0 &&
00203             addr + size <= this->size());
00204     }
00205 
00206     /** Convenience function for checking block program validity
00207      *
00208      *  @param addr     Address of block to begin writing to
00209      *  @param size     Size to write in bytes
00210      *  @return         True if program is valid for underlying block device
00211      */
00212     bool is_valid_program(bd_addr_t addr, bd_size_t size) const
00213     {
00214         return (
00215             addr % get_program_size() == 0 &&
00216             size % get_program_size() == 0 &&
00217             addr + size <= this->size());
00218     }
00219 
00220     /** Convenience function for checking block erase validity
00221      *
00222      *  @param addr     Address of block to begin erasing
00223      *  @param size     Size to erase in bytes
00224      *  @return         True if erase is valid for underlying block device
00225      */
00226     bool is_valid_erase(bd_addr_t addr, bd_size_t size) const
00227     {
00228         return (
00229             addr % get_erase_size(addr) == 0 &&
00230             (addr + size) % get_erase_size(addr + size - 1) == 0 &&
00231             addr + size <= this->size());
00232     }
00233 };
00234 
00235 
00236 #endif