* \author Francesco Sacchi <batt@develer.com>
*
* \brief KBlock interface
+ *
+ * $WIZ$ module_name = "kblock"
*/
#ifndef IO_KBLOCK_H
*
* \{
*/
-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);
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;
/**
*
* \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.
*
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);
}
/**
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.
* 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.
*
* \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.
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 */
projects / bertos.git / blobdiff