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 int    (* kblock_write_block_t) (struct KBlock *b, block_idx_t index, const void *buf);
  61
  62 typedef size_t (* kblock_read_t)        (struct KBlock *b, void *buf, size_t offset, size_t size);
  63 typedef size_t (* kblock_write_t)       (struct KBlock *b, const void *buf, size_t offset, size_t size);
  64 typedef int    (* kblock_load_t)        (struct KBlock *b, block_idx_t index);
  65 typedef int    (* kblock_store_t)       (struct KBlock *b, block_idx_t index);
  66
  67 typedef int    (* kblock_error_t)       (struct KBlock *b);
  68 typedef int    (* kblock_clearerr_t)    (struct KBlock *b);
  69 typedef int    (* kblock_close_t)       (struct KBlock *b);
  70 /* \} */
  71
  72 /**
  73  * Table of interface functions for a KBlock device.
  74  */
  75 typedef struct KBlockVTable
  76 {
  77         kblock_read_direct_t readDirect;
  78         kblock_write_block_t writeBlock;
  79
  80         kblock_read_t  readBuf;
  81         kblock_write_t writeBuf;
  82         kblock_load_t  load;
  83         kblock_store_t store;
  84
  85         kblock_error_t    error;    ///< \sa kblock_error()
  86         kblock_clearerr_t clearerr; ///< \sa kblock_clearerr()
  87
  88         kblock_close_t  close; ///< \sa kblock_close()
  89 } KBlockVTable;
  90
  91
  92 #define KB_BUFFERED    BV(0)
  93 #define KB_CACHE_DIRTY BV(1)
  94
  95 /**
  96  * KBlock private members.
  97  * These are the private members of the KBlock class, please do not
  98  * access these directly, use the KBlock API.
  99  */
 100 typedef struct KBlockPriv
 101 {
 102         DB(id_t type);         ///< Used to keep track, at runtime, of the class type.
 103         int flags;             ///< Status and error flags.
 104         void *buf;
 105         block_idx_t blk_start; ///< Start block number when the device is trimmed. \sa kblock_trim()
 106         block_idx_t curr_blk;
 107
 108         const struct KBlockVTable *vt; ///< Virtual table of interface functions.
 109 } KBlockPriv;
 110
 111 /**
 112  * KBlock: interface for a generic block device.
 113  *
 114  * A block device is a device which can only be read/written
 115  * with data blocks of constant size: flash memories,
 116  * SD cards, hard disks, etc...
 117  *
 118  * This interface is designed to adapt to most block devices and
 119  * use peculiar features in order to save CPU time and memory space.
 120  *
 121  * You do not have to use this structure directly, specific implementations
 122  * will be supplied in the peripheral drivers.
 123  */
 124 typedef struct KBlock
 125 {
 126         KBlockPriv priv;         ///< Interface private data, do not use directly.
 127
 128         /* Public access members */
 129         size_t blk_size;         ///< Block size.
 130         block_idx_t blk_cnt;     ///< Number of blocks available in the device.
 131 } KBlock;
 132
 133
 134 /**
 135  * Use a subset of the blocks on the device.
 136  *
 137  * This function is useful for partitioning a device and use it for
 138  * different purposes at the same time.
 139  *
 140  * This function will limit the number of blocks used on the device by setting
 141  * a start index and a number of blocks to be used counting from that index.
 142  *
 143  * The blocks outside this range are no more accessible.
 144  *
 145  * Logical block indexes will be mapped to physical indexes inside this new
 146  * range automatically. Even following calls to kblock_trim() will use logical
 147  * indexes, so, once trimmed, access can only be limited further and never
 148  * expanded back.
 149  *
 150  * Example:
 151  * \code
 152  * //...init KBlock device dev
 153  * kblock_trim(dev, 200, 1500); // Restrict access to the 200-1700 physical block range.
 154  * kblock_load(dev, 0);  // Load the physical block #200.
 155  * kblock_trim(dev, 0, 300); // Restrict access to the 200-500 physical block range.
 156  * \endcode
 157  *
 158  * \param b KBlock device.
 159  * \param start The index of the start block for the limiting window in logical addressing units.
 160  * \param count The number of blocks to be used.
 161  *
 162  */
 163 INLINE void kblock_trim(struct KBlock *b, block_idx_t start, block_idx_t count)
 164 {
 165         ASSERT(start + count <= b->blk_cnt);
 166         b->priv.blk_start += start;
 167         b->blk_cnt = count;
 168 }
 169
 170
 171 #define KB_ASSERT_METHOD(b, method) \
 172         do \
 173         { \
 174                 ASSERT(b); \
 175                 ASSERT((b)->priv.vt); \
 176                 ASSERT((b)->priv.vt->method); \
 177         } \
 178         while (0)
 179
 180
 181 /**
 182  * Get the current errors for the device.
 183  *
 184  * \note Calling this function will not clear the errors.
 185  *
 186  * \param b KBlock device.
 187  *
 188  * \return 0 if no error is present, a driver specific mask of errors otherwise.
 189  *
 190  * \sa kblock_clearerr()
 191  */
 192 INLINE int kblock_error(struct KBlock *b)
 193 {
 194         KB_ASSERT_METHOD(b, error);
 195         return b->priv.vt->error(b);
 196 }
 197
 198 /**
 199  * Clear the errors of the device.
 200  *
 201  * \param b KBlock device.
 202  *
 203  * \return 0 on success, EOF on errors.
 204  *
 205  * \sa kblock_error()
 206  */
 207 INLINE int kblock_clearerr(struct KBlock *b)
 208 {
 209         KB_ASSERT_METHOD(b, clearerr);
 210         return b->priv.vt->clearerr(b);
 211 }
 212
 213 /**
 214  * Close the device.
 215  *
 216  * \param b KBlock device.
 217  *
 218  * \return 0 on success, EOF on errors.
 219  */
 220 INLINE int kblock_close(struct KBlock *b)
 221 {
 222         KB_ASSERT_METHOD(b, close);
 223         return b->priv.vt->close(b);
 224 }
 225
 226 INLINE bool kblock_cacheDirty(struct KBlock *b)
 227 {
 228         ASSERT(b);
 229         return (b->priv.flags & KB_CACHE_DIRTY);
 230 }
 231
 232 INLINE block_idx_t kblock_cachedBlock(struct KBlock *b)
 233 {
 234         return b->priv.curr_blk;
 235 }
 236
 237 INLINE bool kblock_buffered(struct KBlock *b)
 238 {
 239         ASSERT(b);
 240         return (b->priv.flags & KB_BUFFERED);
 241 }
 242
 243 size_t kblock_read(struct KBlock *b, block_idx_t idx, void *buf, size_t offset, size_t size);
 244
 245 size_t kblock_write(struct KBlock *b, block_idx_t idx, const void *buf, size_t offset, size_t size);
 246
 247 int kblock_flush(struct KBlock *b);
 248
 249 int kblock_copy(struct KBlock *b, block_idx_t idx1, block_idx_t idx2);
 250
 251 int kblock_swLoad(struct KBlock *b, block_idx_t index);
 252 int kblock_swStore(struct KBlock *b, block_idx_t index);
 253 size_t kblock_swReadBuf(struct KBlock *b, void *buf, size_t offset, size_t size);
 254 size_t kblock_swWriteBuf(struct KBlock *b, const void *buf, size_t offset, size_t size);
 255
 256 #endif /* IO_KBLOCK_H */