*
* -->
*
- * \author Francesco Sacchi <batt@develer.com>
+ * \defgroup io_kblock KBlock interface
+ * \ingroup core
+ * \{
*
* \brief KBlock interface
+ *
+ * A block device is a device which can only be read/written
+ * with data blocks of constant size: flash memories,
+ * SD cards, hard disks, etc...
+ * This interface is designed to adapt to most block devices and
+ * use peculiar features in order to save CPU time and memory space.
+ *
+ * There is no init function because you do not have to use this
+ * structure directly, specific implementations will supply their own init
+ * functions.
+ *
+ * Error handling is done in a way similar to standard C library: whenever a
+ * function (eg. kblock_flush()) returns error, you need to check the error
+ * code, which is implementation specific.
+ *
+ * Example of code flow:
+ * \code
+ * // init a KBlock-derived class
+ * Flash fls;
+ * flash_init(&fls.blk, 0);
+ *
+ * // use kblock_* functions to access the derived class
+ * kblock_write(&fls.blk, ...);
+ * if (kblock_flush(&fls.blk) == EOF)
+ * {
+ * // oops, error occurred!
+ * int err = kblock_error(&fls.blk);
+ * // handle Flash specific error conditions
+ * // ...
+ * // clear error condition
+ * kblock_clearerr(&fls.blk);
+ * }
+ * \endcode
+ *
+ * \note The KBlock interface is optimized for block reads. If you need a
+ * file-like access, you can use \ref kfile_block.
+ *
+ * \author Francesco Sacchi <batt@develer.com>
+ *
+ * $WIZ$ module_name = "kblock"
*/
#ifndef IO_KBLOCK_H
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_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_read_t readBuf;
+ 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_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 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.
- block_idx_t blk_start; ///< Start block number when the device is trimmed. \sa kblock_trim()
- block_idx_t curr_blk;
- bool cache_dirty;
+ 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.
- struct KBlockVTable *vt; ///< Virtual table of interface functions.
+ const struct KBlockVTable *vt; // Virtual table of interface functions.
} KBlockPriv;
/**
* KBlock: interface for a generic block device.
*
- * A block device is a device which can only be read/written
- * with data blocks of constant size: flash memories,
- * SD cards, hard disks, etc...
- *
- * This interface is designed to adapt to most block devices and
- * use peculiar features in order to save CPU time and memory space.
- *
- * You do not have to use this structure directly, specific implementations
- * will be supplied in the peripheral drivers.
*/
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;
* \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
*
* \param start The index of the start block for the limiting window in logical addressing units.
* \param count The number of blocks to be used.
*
+ * \return 0 if all is OK, EOF on errors.
*/
-INLINE void kblock_trim(struct KBlock *b, block_idx_t start, block_idx_t count)
-{
- ASSERT(start + count <= b->blk_cnt);
- b->priv.blk_start += start;
- b->blk_cnt = count;
-}
+int kblock_trim(struct KBlock *b, block_idx_t start, block_idx_t count);
#define KB_ASSERT_METHOD(b, method) \
*
* \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 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)
+{
+ ASSERT(b);
+ return (b->priv.flags & KB_BUFFERED);
}
+
+/**
+ * \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(kblock_buffered(b));
+ return b->priv.curr_blk;
+}
+
+
+/**
+ * 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)
+{
+ ASSERT(kblock_buffered(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 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);
+/**
+ * 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);
+
+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);
+
+/** \} */ //defgroup io_kblock
+
#endif /* IO_KBLOCK_H */
projects / bertos.git / blobdiff