bertos/io/kblock.h

   1 /**
   2  * \file
   3  * <!--
   4  * This file is part of BeRTOS.
   5  *
   6  * Bertos is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  19  *
  20  * As a special exception, you may use this file as part of a free software
  21  * library without restriction.  Specifically, if other files instantiate
  22  * templates or use macros or inline functions from this file, or you compile
  23  * this file and link it with other files to produce an executable, this
  24  * file does not by itself cause the resulting executable to be covered by
  25  * the GNU General Public License.  This exception does not however
  26  * invalidate any other reasons why the executable file might be covered by
  27  * the GNU General Public License.
  28  *
  29  * Copyright 2009 Develer S.r.l. (http://www.develer.com/)
  30  *
  31  * -->
  32  *
  33  * \author Francesco Sacchi <batt@develer.com>
  34  *
  35  * \brief KBlock interface
  36  */
  37
  38 #ifndef IO_KBLOCK_H
  39 #define IO_KBLOCK_H
  40
  41 #include <cfg/compiler.h>
  42 #include <cfg/debug.h>
  43 #include <cfg/macros.h>
  44
  45 /** Type for addressing blocks in the device. */
  46 typedef uint32_t block_idx_t;
  47
  48 // Fwd Declaration
  49 struct KBlock;
  50
  51 /**
  52  * \name Prototypes for KBlock access functions.
  53  *
  54  * A KBlock user can choose which function subset to implement,
  55  * but has to set to NULL unimplemented features.
  56  *
  57  *  \{
  58  */
  59 typedef size_t (* kblock_read_direct_t) (struct KBlock *b, block_idx_t index, void *buf, size_t offset, size_t size);
  60 typedef size_t (* kblock_read_t)        (struct KBlock *b, void *buf, size_t offset, size_t size);
  61 typedef size_t (* kblock_write_t)       (struct KBlock *b, const void *buf, size_t offset, size_t size);
  62 typedef int    (* kblock_load_t)        (struct KBlock *b, block_idx_t index);
  63 typedef int    (* kblock_store_t)       (struct KBlock *b, block_idx_t index);
  64 typedef int    (* kblock_error_t)       (struct KBlock *b);
  65 typedef int    (* kblock_clearerr_t)    (struct KBlock *b);
  66 typedef int    (* kblock_close_t)       (struct KBlock *b);
  67 /* \} */
  68
  69 /**
  70  * Table of interface functions for a KBlock device.
  71  */
  72 typedef struct KBlockVTable
  73 {
  74         kblock_read_direct_t readDirect;
  75     kblock_read_t  readBuf;
  76         kblock_write_t writeBuf;
  77         kblock_load_t  load;
  78         kblock_store_t store;
  79
  80         kblock_error_t    error;    ///< \sa kblock_error()
  81         kblock_clearerr_t clearerr; ///< \sa kblock_clearerr()
  82
  83         kblock_close_t  close; ///< \sa kblock_close()
  84 } KBlockVTable;
  85
  86
  87 /**
  88  * KBlock private members.
  89  * These are the private members of the KBlock class, please do not
  90  * access these directly, use the KBlock API.
  91  */
  92 typedef struct KBlockPriv
  93 {
  94         DB(id_t type);         ///< Used to keep track, at runtime, of the class type.
  95         int flags;             ///< Status and error flags.
  96         block_idx_t blk_start; ///< Start block number when the device is trimmed. \sa kblock_trim()
  97         block_idx_t curr_blk;
  98         bool cache_dirty;
  99
 100         struct KBlockVTable *vt; ///< Virtual table of interface functions.
 101 } KBlockPriv;
 102
 103 /**
 104  * KBlock: interface for a generic block device.
 105  *
 106  * A block device is a device which can only be read/written
 107  * with data blocks of constant size: flash memories,
 108  * SD cards, hard disks, etc...
 109  *
 110  * This interface is designed to adapt to most block devices and
 111  * use peculiar features in order to save CPU time and memory space.
 112  *
 113  * You do not have to use this structure directly, specific implementations
 114  * will be supplied in the peripheral drivers.
 115  */
 116 typedef struct KBlock
 117 {
 118         KBlockPriv priv;         ///< Interface private data, do not use directly.
 119
 120         /* Public access members/methods */
 121         size_t blk_size;         ///< Block size.
 122         block_idx_t blk_cnt;     ///< Number of blocks available in the device.
 123 } KBlock;
 124
 125
 126 /**
 127  * Use a subset of the blocks on the device.
 128  *
 129  * This function is useful for partitioning a device and use it for
 130  * different purposes at the same time.
 131  *
 132  * This function will limit the number of blocks used on the device by setting
 133  * a start index and a number of blocks to be used counting from that index.
 134  *
 135  * The blocks outside this range are no more accessible.
 136  *
 137  * Logical block indexes will be mapped to physical indexes inside this new
 138  * range automatically. Even following calls to kblock_trim() will use logical
 139  * indexes, so, once trimmed, access can only be limited further and never
 140  * expanded back.
 141  *
 142  * Example:
 143  * \code
 144  * //...init KBlock device dev
 145  * kblock_trim(dev, 200, 1500); // Restrict access to the 200-1700 physical block range.
 146  * kblock_load(dev, 0);  // Load the physical block #200.
 147  * kblock_trim(dev, 0, 300); // Restrict access to the 200-500 physical block range.
 148  * \endcode
 149  *
 150  * \param b KBlock device.
 151  * \param start The index of the start block for the limiting window in logical addressing units.
 152  * \param count The number of blocks to be used.
 153  *
 154  */
 155 INLINE void kblock_trim(struct KBlock *b, block_idx_t start, block_idx_t count)
 156 {
 157         ASSERT(start + count <= b->blk_cnt);
 158         b->priv.blk_start += start;
 159         b->blk_cnt = count;
 160 }
 161
 162
 163 #define KB_ASSERT_METHOD(b, method) \
 164         do \
 165         { \
 166                 ASSERT(b); \
 167                 ASSERT((b)->priv.vt); \
 168                 ASSERT((b)->priv.vt->method); \
 169         } \
 170         while (0)
 171
 172
 173 /**
 174  * Get the current errors for the device.
 175  *
 176  * \note Calling this function will not clear the errors.
 177  *
 178  * \param b KBlock device.
 179  *
 180  * \return 0 if no error is present, a driver specific mask of errors otherwise.
 181  *
 182  * \sa kblock_clearerr()
 183  */
 184 INLINE int kblock_error(struct KBlock *b)
 185 {
 186         KB_ASSERT_METHOD(b, error);
 187         return b->priv.vt->error(b);
 188 }
 189
 190 /**
 191  * Clear the errors of the device.
 192  *
 193  * \param b KBlock device.
 194  *
 195  * \return 0 on success, EOF on errors.
 196  *
 197  * \sa kblock_error()
 198  */
 199 INLINE int kblock_clearerr(struct KBlock *b)
 200 {
 201         KB_ASSERT_METHOD(b, clearerr);
 202         return b->priv.vt->clearerr(b);
 203 }
 204
 205 /**
 206  * Close the device.
 207  *
 208  * \param b KBlock device.
 209  *
 210  * \return 0 on success, EOF on errors.
 211  */
 212 INLINE int kblock_close(struct KBlock *b)
 213 {
 214         KB_ASSERT_METHOD(b, close);
 215         return b->priv.vt->close(b);
 216 }
 217
 218 size_t kblock_read(struct KBlock *b, block_idx_t idx, void *buf, size_t offset, size_t size);
 219
 220 int kblock_flush(struct KBlock *b);
 221
 222 size_t kblock_write(struct KBlock *b, block_idx_t idx, const void *buf, size_t offset, size_t size);
 223
 224 int kblock_copy(struct KBlock *b, block_idx_t idx1, block_idx_t idx2);
 225
 226 #endif /* IO_KBLOCK_H */