X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=bertos%2Fio%2Fkblock.h;h=f2966bafea2fd4def8512452e760a98f6e03e6c1;hb=540b160dbedfdb12ce29f9b107be860ba22cd6cb;hp=99135ab24801de6da2849f191a58b4514733953a;hpb=5116d38f82d41b65b0be5e1013dbff50da229dd7;p=bertos.git diff --git a/bertos/io/kblock.h b/bertos/io/kblock.h index 99135ab2..f2966baf 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 @@ -57,8 +59,8 @@ struct KBlock; * * \{ */ -typedef size_t (* kblock_read_direct_t) (struct KBlock *b, block_idx_t index, void *buf, size_t offset, size_t size); -typedef int (* kblock_write_block_t) (struct KBlock *b, block_idx_t index, const void *buf); +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); @@ -66,47 +68,49 @@ 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_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); /* \} */ -/** +/* * Table of interface functions for a KBlock device. */ typedef struct KBlockVTable { kblock_read_direct_t readDirect; - kblock_write_block_t writeBlock; + kblock_write_direct_t writeDirect; kblock_read_t readBuf; kblock_write_t writeBuf; kblock_load_t load; kblock_store_t store; - kblock_error_t error; ///< \sa kblock_error() - kblock_clearerr_t clearerr; ///< \sa kblock_clearerr() + kblock_error_t error; // \sa kblock_error() + kblock_clearerr_t clearerr; // \sa kblock_clearerr() - kblock_close_t close; ///< \sa kblock_close() + kblock_close_t close; // \sa kblock_close() } KBlockVTable; -#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_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 -/** + +/* * KBlock private members. * 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; ///< 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. + DB(id_t type); // Used to keep track, at runtime, of the class type. + int flags; // Status and error flags. + 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. + const struct KBlockVTable *vt; // Virtual table of interface functions. } KBlockPriv; /** @@ -201,16 +205,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. * @@ -221,7 +236,7 @@ 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); } /** @@ -264,6 +279,18 @@ INLINE bool kblock_cacheDirty(struct KBlock *b) return kblock_buffered(b) && (b->priv.flags & KB_CACHE_DIRTY); } +/** + * \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_PARTIAL_WRITE); +} /** * Read data from the block device. @@ -297,9 +324,9 @@ size_t kblock_read(struct KBlock *b, block_idx_t idx, void *buf, size_t offset, * 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 if the device is opened in - * buffered mode. You can use kblock_buffered() to check if the device - * has an internal cache or not. + * \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. @@ -314,29 +341,17 @@ size_t kblock_read(struct KBlock *b, block_idx_t idx, void *buf, size_t offset, * * \return the number of bytes written. * - * \sa kblock_read(), kblock_flush(), kblock_buffered(). + * \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); - -/** - * 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); - - /** * 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 opened in buffered mode. + * \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. @@ -350,5 +365,6 @@ 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 */