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