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