X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=bertos%2Fio%2Fkblock.h;h=f3542947c308c1453a4e44527a8a5ebcb93d3bde;hb=4a71fb58e067d3dc00fe1c29927f945bd34be49a;hp=ea3d14ebcc7e39a13c21adc793fd38d1150594e8;hpb=12c71395c80c3d5e6f9532a4a912322b503ce391;p=bertos.git

diff --git a/bertos/io/kblock.h b/bertos/io/kblock.h
index ea3d14eb..f3542947 100644
--- a/bertos/io/kblock.h
+++ b/bertos/io/kblock.h
@@ -30,10 +30,50 @@
  *
  * -->
  *
- * \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"
  */
 
@@ -72,7 +112,7 @@ 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
@@ -85,45 +125,37 @@ typedef struct KBlockVTable
 	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
+#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;
 
 /**
  * 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
 {
@@ -163,13 +195,9 @@ typedef struct KBlock
  * \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) \
@@ -364,5 +392,9 @@ 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 */