X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=bertos%2Fio%2Fkblock.h;h=9ac358ce37e34e01122a924c55018fea8de2b2ca;hb=b5f1efac2381ba2a14397e0343b097e9f87c363d;hp=14a5b88eec87c47c2005d0ff44e8c58d025eb0c0;hpb=976a96d1824ea1a84bb3a12023033cf2fed81761;p=bertos.git diff --git a/bertos/io/kblock.h b/bertos/io/kblock.h index 14a5b88e..9ac358ce 100644 --- a/bertos/io/kblock.h +++ b/bertos/io/kblock.h @@ -33,6 +33,8 @@ * \author Francesco Sacchi * * \brief KBlock interface + * + * $WIZ$ module_name = "kblock" */ #ifndef IO_KBLOCK_H @@ -49,24 +51,24 @@ typedef uint32_t block_idx_t; struct KBlock; /** - * \name Prototypes for KBlock access functions. + * \name Prototypes for KBlock low level access functions. * - * A KBlock user can choose which function subset to implement, - * but has to set to NULL unimplemented features. + * When writing a driver implementing the KBlock interface you can choose which + * function subset to implement, but you have to set to NULL unimplemented + * features. * * \{ */ -typedef size_t (* kblock_read_direct_t) (struct KBlock *b, block_idx_t index, void *buf, size_t offset, size_t size); +typedef size_t (* kblock_read_direct_t) (struct KBlock *b, block_idx_t index, void *buf, size_t offset, size_t size); +typedef size_t (* kblock_write_direct_t) (struct KBlock *b, block_idx_t index, const void *buf, size_t offset, size_t size); + typedef size_t (* kblock_read_t) (struct KBlock *b, void *buf, size_t offset, size_t size); typedef size_t (* kblock_write_t) (struct KBlock *b, const void *buf, size_t offset, size_t size); typedef int (* kblock_load_t) (struct KBlock *b, block_idx_t index); typedef int (* kblock_store_t) (struct KBlock *b, block_idx_t index); -typedef int (* kblock_write_block_t) (struct KBlock *b, block_idx_t index, const void *buf); -typedef int (* kblock_read_block_t) (struct KBlock *b, block_idx_t index, void *buf); - typedef int (* kblock_error_t) (struct KBlock *b); -typedef int (* kblock_clearerr_t) (struct KBlock *b); +typedef void (* kblock_clearerr_t) (struct KBlock *b); typedef int (* kblock_close_t) (struct KBlock *b); /* \} */ @@ -76,15 +78,13 @@ typedef int (* kblock_close_t) (struct KBlock *b); typedef struct KBlockVTable { kblock_read_direct_t readDirect; + kblock_write_direct_t writeDirect; kblock_read_t readBuf; kblock_write_t writeBuf; kblock_load_t load; kblock_store_t store; - - kblock_read_block_t readBlock; - kblock_write_block_t writeBlock; - + kblock_error_t error; ///< \sa kblock_error() kblock_clearerr_t clearerr; ///< \sa kblock_clearerr() @@ -92,21 +92,26 @@ typedef struct KBlockVTable } KBlockVTable; -#define KB_BUFFERED BV(0) -#define KB_CACHE_DIRTY BV(1) +#define KB_BUFFERED BV(0) ///< Internal flag: true if the KBlock has a buffer +#define KB_CACHE_DIRTY BV(1) ///< Internal flag: true if the cache is dirty +#define KB_PARTIAL_WRITE BV(2) ///< Internal flag: true if the device allows partial block write + +#define KB_WRITE_ONCE BV(3) ///< Allow only the one write on select block. +#define KB_OPEN_BUFF BV(4) ///< Open flash memory using page caching, allowing the modification and partial write. +#define KB_OPEN_UNBUFF BV(5) ///< Open flash memory whitout memory caching. /** * KBlock private members. - * These are the private members of the KBlock class, please do not + * These are the private members of the KBlock interface, please do not * access these directly, use the KBlock API. */ typedef struct KBlockPriv { DB(id_t type); ///< Used to keep track, at runtime, of the class type. int flags; ///< Status and error flags. - void *buf; - block_idx_t blk_start; ///< Start block number when the device is trimmed. \sa kblock_trim() - block_idx_t curr_blk; + void *buf; ///< Pointer to the page buffer for RAM-cached KBlocks. + block_idx_t blk_start; ///< Start block number when the device is trimmed. \sa kblock_trim(). + block_idx_t curr_blk; ///< Current cached block number in cached KBlocks. const struct KBlockVTable *vt; ///< Virtual table of interface functions. } KBlockPriv; @@ -128,7 +133,7 @@ typedef struct KBlock { KBlockPriv priv; ///< Interface private data, do not use directly. - /* Public access members/methods */ + /* Public access members */ size_t blk_size; ///< Block size. block_idx_t blk_cnt; ///< Number of blocks available in the device. } KBlock; @@ -154,7 +159,7 @@ typedef struct KBlock * \code * //...init KBlock device dev * kblock_trim(dev, 200, 1500); // Restrict access to the 200-1700 physical block range. - * kblock_load(dev, 0); // Load the physical block #200. + * kblock_read(dev, 0, buf, 0, dev->blk_size); // Read from physical block #200. * kblock_trim(dev, 0, 300); // Restrict access to the 200-500 physical block range. * \endcode * @@ -203,16 +208,27 @@ INLINE int kblock_error(struct KBlock *b) * * \param b KBlock device. * - * \return 0 on success, EOF on errors. * * \sa kblock_error() */ -INLINE int kblock_clearerr(struct KBlock *b) +INLINE void kblock_clearerr(struct KBlock *b) { KB_ASSERT_METHOD(b, clearerr); - return b->priv.vt->clearerr(b); + b->priv.vt->clearerr(b); } + +/** + * Flush the cache (if any) to the device. + * + * This function will write any pending modifications to the device. + * If the device does not have a cache, this function will do nothing. + * + * \return 0 if all is OK, EOF on errors. + * \sa kblock_read(), kblock_write(), kblock_buffered(). + */ +int kblock_flush(struct KBlock *b); + /** * Close the device. * @@ -223,57 +239,135 @@ INLINE int kblock_clearerr(struct KBlock *b) INLINE int kblock_close(struct KBlock *b) { KB_ASSERT_METHOD(b, close); - return b->priv.vt->close(b); + return kblock_flush(b) | b->priv.vt->close(b); } -INLINE int kblock_writeBlock(struct KBlock *b, block_idx_t index, const void *buf) +/** + * \return true if the device \a b is buffered, false otherwise. + * \param b KBlock device. + * \sa kblock_cachedBlock(), kblock_cacheDirty(). + */ +INLINE bool kblock_buffered(struct KBlock *b) { - KB_ASSERT_METHOD(b, writeBlock); - ASSERT(index < b->blk_cnt); - return b->priv.vt->writeBlock(b, b->priv.blk_start + index, buf); + ASSERT(b); + return (b->priv.flags & KB_BUFFERED); } -INLINE int kblock_readBlock(struct KBlock *b, block_idx_t index, void *buf) -{ - KB_ASSERT_METHOD(b, readDirect); - ASSERT(index < b->blk_cnt); - return b->priv.vt->readBlock(b, b->priv.blk_start + index, buf); -} -INLINE bool kblock_cacheDirty(struct KBlock *b) +/** + * \return The current cached block number if the device is buffered. + * \param b KBlock device. + * \note This function will throw an ASSERT if called on a non buffered KBlock. + * \sa kblock_buffered(), kblock_cacheDirty(). + */ +INLINE block_idx_t kblock_cachedBlock(struct KBlock *b) { - ASSERT(b); - return (b->priv.flags & KB_CACHE_DIRTY); + ASSERT(kblock_buffered(b)); + return b->priv.curr_blk; } -INLINE block_idx_t kblock_cachedBlock(struct KBlock *b) + +/** + * Return the status of the internal cache. + * + * \param b KBlock device. + * \return If the device supports buffering, returns true if the cache is dirty, + * false if the cache is clean and coherent with device content. + * \note This function will throw an ASSERT if called on a non buffered KBlock. + * \sa kblock_cachedBlock(), kblock_buffered(). + */ +INLINE bool kblock_cacheDirty(struct KBlock *b) { - return b->priv.curr_blk; + ASSERT(kblock_buffered(b)); + return kblock_buffered(b) && (b->priv.flags & KB_CACHE_DIRTY); } -INLINE bool kblock_buffered(struct KBlock *b) +/** + * \return true if the device \a b supports partial block write. That is, you + * can call kblock_write() with a size which is lesser than the block + * size. + * \param b KBlock device. + * \sa kblock_write(). + */ +INLINE bool kblock_partialWrite(struct KBlock *b) { ASSERT(b); - return (b->priv.flags & KB_BUFFERED); + return (b->priv.flags & KB_PARTIAL_WRITE); } - +/** + * Read data from the block device. + * + * This function will read \a size bytes from block \a idx starting at + * address \a offset inside the block. + * + * Most block devices (almost all flash memories, for instance), + * can efficiently read even a part of the block. + * + * \note This function can be slow if you try to partial read a block from + * a device which does not support partial block reads and is opened + * in unbuffered mode. + * + * \param b KBlock device. + * \param idx the block number where you want to read. + * \param buf a buffer where the data will be read. + * \param offset the offset inside the block from which data reading will start. + * \param size the size of data to be read. + * + * \return the number of bytes read. + * + * \sa kblock_write(). + */ size_t kblock_read(struct KBlock *b, block_idx_t idx, void *buf, size_t offset, size_t size); -int kblock_flush(struct KBlock *b); +/** + * Write data to the block device. + * + * This function will write \a size bytes to block \a idx starting at + * address \a offset inside the block. + * + * \note Partial block writes are supported only on certain devices. + * You can use kblock_partialWrite() in order to check if the device + * has this feature or not. + * + * \note If the device is opened in buffered mode, this function will use + * efficiently and trasparently the cache provided. + * In order to be sure that all modifications are actually written + * to the device you have to call kblock_flush(). + * + * \param b KBlock device. + * \param idx the block number where you want to write. + * \param buf a pointer to the data to be written. + * \param offset the offset inside the block from which data writing will start. + * \param size the size of data to be written. + * + * \return the number of bytes written. + * + * \sa kblock_read(), kblock_flush(), kblock_buffered(), kblock_partialWrite(). + */ size_t kblock_write(struct KBlock *b, block_idx_t idx, const void *buf, size_t offset, size_t size); -int kblock_copy(struct KBlock *b, block_idx_t idx1, block_idx_t idx2); - - -int kblock_swWriteBlock(struct KBlock *b, block_idx_t index, const void *buf); -int kblock_swReadBlock(struct KBlock *b, block_idx_t index, void *buf); +/** + * Copy one block to another. + * + * This function will copy the content of block \a src to block \a dest. + * + * \note This function is available only on devices which support partial + * block write or are opened in buffered mode. + * + * \param b KBlock device. + * \param src source block number. + * \param dest destination block number. + * + * \return 0 if all is OK, EOF on errors. + */ +int kblock_copy(struct KBlock *b, block_idx_t src, block_idx_t dest); -size_t kblock_swReadDirect(struct KBlock *b, block_idx_t index, void *buf, size_t offset, size_t size); int kblock_swLoad(struct KBlock *b, block_idx_t index); int kblock_swStore(struct KBlock *b, block_idx_t index); size_t kblock_swReadBuf(struct KBlock *b, void *buf, size_t offset, size_t size); size_t kblock_swWriteBuf(struct KBlock *b, const void *buf, size_t offset, size_t size); +int kblock_swClose(struct KBlock *b); #endif /* IO_KBLOCK_H */