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