X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=bertos%2Fio%2Fkfile_block.h;h=c5dc26c5591363db131a6d5d1260fbf086b068cc;hb=7166a2cb55a257889ffc8f0199d048409449f89a;hp=9694ea94c5c97cf4b1b527f66427acca65156068;hpb=0142058531b1f00b0dbe740b43900dfc361656e5;p=bertos.git

diff --git a/bertos/io/kfile_block.h b/bertos/io/kfile_block.h
index 9694ea94..c5dc26c5 100644
--- a/bertos/io/kfile_block.h
+++ b/bertos/io/kfile_block.h
@@ -30,8 +30,41 @@
  *
  * -->
  *
+ * \defgroup kfile_block KFile interface over KBlock
+ * \ingroup core
+ * \{
+ *
  * \brief KFile interface over a KBlock.
  *
+ * With this module, you can access a KBlock device
+ * with the handy KFile interface.
+ * In order to achieve this, the block device must support partial block write.
+ *
+ * Error codes returned by kfile_error() are specific of the underlying
+ * KBlock implementation.
+ *
+ * Make sure you have trimmed the KBlock to avoid overwriting something.
+ * Example:
+ * \code
+ * // init a derived instance of KBlock
+ * // any will do.
+ * Flash flash;
+ * flash_init(&flash, 0);
+ * kblock_trim(&flash.blk, trim_start, internal_flash.blk.blk_cnt - trim_start);
+ *
+ * // now create and initialize the kfile_block instance
+ * KFileBlock kfb;
+ * kfileblock_init(&kfb, &flash.blk);
+ *
+ * // now you can access the Flash in a file like fashion
+ * kfile_read(&kfb.fd, buf, 20);
+ * \endcode
+ *
+ * \author Francesco Sacchi <batt@develer.com>
+ * \author Daniele Basile <asterix@develer.com>
+ *
+ * $WIZ$ module_name = "kfile_block"
+ * $WIZ$ module_depends = "kfile", "kblock"
  */
 
 #ifndef IO_KFILE_BLOCK_H
@@ -41,12 +74,27 @@
 #include <io/kblock.h>
 #include <io/kfile.h>
 
+/**
+ * KFileBlock context.
+ */
 typedef struct KFileBlock
 {
-	KFile fd;
-	KBlock *b;
+	KFile fd;    ///< KFile context
+	KBlock *blk; ///< KBlock device
 } KFileBlock;
 
-void kfileblock_init(KFileBlock *fb, KBlock *b);
+/**
+ * Init a KFile over KBlock.
+ * After this you can access your KBlock device with a handy KFile interface.
+ *
+ * \note The block device must support partial block write in order to support
+ *       random write access.
+ *
+ * \param fb KFileBlock context.
+ * \param blk block device to be accessed with a KFile interface.
+ */
+void kfileblock_init(KFileBlock *fb, KBlock *blk);
+
+/** \} */ //defgroup kfile_block
 
 #endif /* IO_KFILE_KBLOCK_H */