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 low level access functions.
  53  *
  54  * When writing a driver implementing the KBlock interface you can choose which
  55  * function subset to implement, but you have to set to NULL unimplemented
  56  * features.
  57  *
  58  *  \{
  59  */
  60 typedef size_t (* kblock_read_direct_t) (struct KBlock *b, block_idx_t index, void *buf, size_t offset, size_t size);
  61 typedef int    (* kblock_write_block_t) (struct KBlock *b, block_idx_t index, const void *buf);
  62
  63 typedef size_t (* kblock_read_t)        (struct KBlock *b, void *buf, size_t offset, size_t size);
  64 typedef size_t (* kblock_write_t)       (struct KBlock *b, const void *buf, size_t offset, size_t size);
  65 typedef int    (* kblock_load_t)        (struct KBlock *b, block_idx_t index);
  66 typedef int    (* kblock_store_t)       (struct KBlock *b, block_idx_t index);
  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         kblock_write_block_t writeBlock;
  80
  81         kblock_read_t  readBuf;
  82         kblock_write_t writeBuf;
  83         kblock_load_t  load;
  84         kblock_store_t store;
  85
  86         kblock_error_t    error;    ///< \sa kblock_error()
  87         kblock_clearerr_t clearerr; ///< \sa kblock_clearerr()
  88
  89         kblock_close_t  close; ///< \sa kblock_close()
  90 } KBlockVTable;
  91
  92
  93 #define KB_BUFFERED    BV(0) ///< Internal flag: true if the KBlock has a buffer
  94 #define KB_CACHE_DIRTY BV(1) ///< Internal flag: true if the cache is dirty
  95
  96 /**
  97  * KBlock private members.
  98  * These are the private members of the KBlock interface, please do not
  99  * access these directly, use the KBlock API.
 100  */
 101 typedef struct KBlockPriv
 102 {
 103         DB(id_t type);         ///< Used to keep track, at runtime, of the class type.
 104         int flags;             ///< Status and error flags.
 105         void *buf;             ///< Pointer to the page buffer for RAM-cached KBlocks.
 106         block_idx_t blk_start; ///< Start block number when the device is trimmed. \sa kblock_trim().
 107         block_idx_t curr_blk;  ///< Current cached block number in cached KBlocks.
 108
 109         const struct KBlockVTable *vt; ///< Virtual table of interface functions.
 110 } KBlockPriv;
 111
 112 /**
 113  * KBlock: interface for a generic block device.
 114  *
 115  * A block device is a device which can only be read/written
 116  * with data blocks of constant size: flash memories,
 117  * SD cards, hard disks, etc...
 118  *
 119  * This interface is designed to adapt to most block devices and
 120  * use peculiar features in order to save CPU time and memory space.
 121  *
 122  * You do not have to use this structure directly, specific implementations
 123  * will be supplied in the peripheral drivers.
 124  */
 125 typedef struct KBlock
 126 {
 127         KBlockPriv priv;         ///< Interface private data, do not use directly.
 128
 129         /* Public access members */
 130         size_t blk_size;         ///< Block size.
 131         block_idx_t blk_cnt;     ///< Number of blocks available in the device.
 132 } KBlock;
 133
 134
 135 /**
 136  * Use a subset of the blocks on the device.
 137  *
 138  * This function is useful for partitioning a device and use it for
 139  * different purposes at the same time.
 140  *
 141  * This function will limit the number of blocks used on the device by setting
 142  * a start index and a number of blocks to be used counting from that index.
 143  *
 144  * The blocks outside this range are no more accessible.
 145  *
 146  * Logical block indexes will be mapped to physical indexes inside this new
 147  * range automatically. Even following calls to kblock_trim() will use logical
 148  * indexes, so, once trimmed, access can only be limited further and never
 149  * expanded back.
 150  *
 151  * Example:
 152  * \code
 153  * //...init KBlock device dev
 154  * kblock_trim(dev, 200, 1500); // Restrict access to the 200-1700 physical block range.
 155  * kblock_read(dev, 0, buf, 0, dev->blk_size);  // Read from physical block #200.
 156  * kblock_trim(dev, 0, 300); // Restrict access to the 200-500 physical block range.
 157  * \endcode
 158  *
 159  * \param b KBlock device.
 160  * \param start The index of the start block for the limiting window in logical addressing units.
 161  * \param count The number of blocks to be used.
 162  *
 163  */
 164 INLINE void kblock_trim(struct KBlock *b, block_idx_t start, block_idx_t count)
 165 {
 166         ASSERT(start + count <= b->blk_cnt);
 167         b->priv.blk_start += start;
 168         b->blk_cnt = count;
 169 }
 170
 171
 172 #define KB_ASSERT_METHOD(b, method) \
 173         do \
 174         { \
 175                 ASSERT(b); \
 176                 ASSERT((b)->priv.vt); \
 177                 ASSERT((b)->priv.vt->method); \
 178         } \
 179         while (0)
 180
 181
 182 /**
 183  * Get the current errors for the device.
 184  *
 185  * \note Calling this function will not clear the errors.
 186  *
 187  * \param b KBlock device.
 188  *
 189  * \return 0 if no error is present, a driver specific mask of errors otherwise.
 190  *
 191  * \sa kblock_clearerr()
 192  */
 193 INLINE int kblock_error(struct KBlock *b)
 194 {
 195         KB_ASSERT_METHOD(b, error);
 196         return b->priv.vt->error(b);
 197 }
 198
 199 /**
 200  * Clear the errors of the device.
 201  *
 202  * \param b KBlock device.
 203  *
 204  * \return 0 on success, EOF on errors.
 205  *
 206  * \sa kblock_error()
 207  */
 208 INLINE int kblock_clearerr(struct KBlock *b)
 209 {
 210         KB_ASSERT_METHOD(b, clearerr);
 211         return b->priv.vt->clearerr(b);
 212 }
 213
 214 /**
 215  * Close the device.
 216  *
 217  * \param b KBlock device.
 218  *
 219  * \return 0 on success, EOF on errors.
 220  */
 221 INLINE int kblock_close(struct KBlock *b)
 222 {
 223         KB_ASSERT_METHOD(b, close);
 224         return b->priv.vt->close(b);
 225 }
 226
 227 /**
 228  * \return true if the device \a b is buffered, false otherwise.
 229  * \param b KBlock device.
 230  * \sa kblock_cachedBlock(), kblock_cacheDirty().
 231  */
 232 INLINE bool kblock_buffered(struct KBlock *b)
 233 {
 234         ASSERT(b);
 235         return (b->priv.flags & KB_BUFFERED);
 236 }
 237
 238
 239 /**
 240  * \return The current cached block number if the device is buffered.
 241  * \param b KBlock device.
 242  * \note   This function will throw an ASSERT if called on a non buffered KBlock.
 243  * \sa kblock_buffered(), kblock_cacheDirty().
 244  */
 245 INLINE block_idx_t kblock_cachedBlock(struct KBlock *b)
 246 {
 247         ASSERT(kblock_buffered(b));
 248         return b->priv.curr_blk;
 249 }
 250
 251
 252 /**
 253  * Return the status of the internal cache.
 254  *
 255  * \param b KBlock device.
 256  * \return If the device supports buffering, returns true if the cache is dirty,
 257  *         false if the cache is clean and coherent with device content.
 258  * \note   This function will throw an ASSERT if called on a non buffered KBlock.
 259  * \sa kblock_cachedBlock(), kblock_buffered().
 260  */
 261 INLINE bool kblock_cacheDirty(struct KBlock *b)
 262 {
 263         ASSERT(kblock_buffered(b));
 264         return kblock_buffered(b) && (b->priv.flags & KB_CACHE_DIRTY);
 265 }
 266
 267
 268 /**
 269  * Read data from the block device.
 270  *
 271  * This function will read \a size bytes from block \a idx starting at
 272  * address \a offset inside the block.
 273  *
 274  * Most block devices (almost all flash memories, for instance),
 275  * can efficiently read even a part of the block.
 276  *
 277  * \note This function can be slow if you try to partial read a block from
 278  *       a device which does not support partial block reads and is opened
 279  *       in unbuffered mode.
 280  *
 281  * \param b KBlock device.
 282  * \param idx the block number where you want to read.
 283  * \param buf a buffer where the data will be read.
 284  * \param offset the offset inside the block from which data reading will start.
 285  * \param size the size of data to be read.
 286  *
 287  * \return the number of bytes read.
 288  *
 289  * \sa kblock_write().
 290  */
 291 size_t kblock_read(struct KBlock *b, block_idx_t idx, void *buf, size_t offset, size_t size);
 292
 293
 294 /**
 295  * Write data to the block device.
 296  *
 297  * This function will write \a size bytes to block \a idx starting at
 298  * address \a offset inside the block.
 299  *
 300  * \note Partial block writes are supported only if the device is opened in
 301  *       buffered mode. You can use kblock_buffered() to check if the device
 302  *       has an internal cache or not.
 303  *
 304  * \note If the device is opened in buffered mode, this function will use
 305  *       efficiently and trasparently the cache provided.
 306  *       In order to be sure that all modifications are actually written
 307  *       to the device you have to call kblock_flush().
 308  *
 309  * \param b KBlock device.
 310  * \param idx the block number where you want to write.
 311  * \param buf a pointer to the data to be written.
 312  * \param offset the offset inside the block from which data writing will start.
 313  * \param size the size of data to be written.
 314  *
 315  * \return the number of bytes written.
 316  *
 317  * \sa kblock_read(), kblock_flush(), kblock_buffered().
 318  */
 319 size_t kblock_write(struct KBlock *b, block_idx_t idx, const void *buf, size_t offset, size_t size);
 320
 321
 322 /**
 323  * Flush the cache (if any) to the device.
 324  *
 325  * This function will write any pending modifications to the device.
 326  * If the device does not have a cache, this function will do nothing.
 327  *
 328  * \return 0 if all is OK, EOF on errors.
 329  * \sa kblock_read(), kblock_write(), kblock_buffered().
 330  */
 331 int kblock_flush(struct KBlock *b);
 332
 333
 334 /**
 335  * Copy one block to another.
 336  *
 337  * This function will copy the content of block \a src to block \a dest.
 338  *
 339  * \note This function is available only on devices opened in buffered mode.
 340  *
 341  * \param b KBlock device.
 342  * \param src source block number.
 343  * \param dest destination block number.
 344  *
 345  * \return 0 if all is OK, EOF on errors.
 346  */
 347 int kblock_copy(struct KBlock *b, block_idx_t src, block_idx_t dest);
 348
 349 int kblock_swLoad(struct KBlock *b, block_idx_t index);
 350 int kblock_swStore(struct KBlock *b, block_idx_t index);
 351 size_t kblock_swReadBuf(struct KBlock *b, void *buf, size_t offset, size_t size);
 352 size_t kblock_swWriteBuf(struct KBlock *b, const void *buf, size_t offset, size_t size);
 353
 354 #endif /* IO_KBLOCK_H */