X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=bertos%2Fkern%2Fkfile.h;h=ade4895d4500979f98e04e2f285085c8e4b97768;hb=e62ca0b357f09804d7d894949df44224c9d74bb7;hp=bcc88e7218751bd2b4862eb3329b980915e767d4;hpb=7bc87271c5cf15a352dadef1c425b808aab5d35e;p=bertos.git

diff --git a/bertos/kern/kfile.h b/bertos/kern/kfile.h
index bcc88e72..ade4895d 100644
--- a/bertos/kern/kfile.h
+++ b/bertos/kern/kfile.h
@@ -32,25 +32,30 @@
  * -->
  *
  * \brief Virtual KFile I/O interface.
- * KFile is a generic interface for file I/O.
- * It uses an object-oriented model to supply
- * a generic interface for drivers to communicate.
+ *
+ * KFile is a simple, generic interface for file I/O.  It uses an
+ * object-oriented model to supply a device-neutral interface to
+ * communicate with drivers.
+ *
  * This module contains only definitions, the instance structure
- * and an API.
- * Each KFile user should implement at least some methods.
- * E.G.
- * If you have a serial driver and want to comply to KFile interface,
- * you have to declare your context structure:
+ * and the common API.
+ * Each KFile subclass can override one or more methods of the interface,
+ * and can extend the base KFile structure with its own private data.
+ * For instance, a serial driver might implement the KFile interface by
+ * declaring a context structure like this:
  *
  * \code
- * typedef struct SerialKFile
+ * typedef struct Serial
  * {
- *		KFile fd;
- *		Serial *ser;
+ *      // base class instance
+ *      KFile fd;
+ *
+ *      // private instance data
+ *      FIFOBuffer txfifo, rxfifo;
  * } Serial;
  * \endcode
  *
- * You should also supply a macro for casting KFile to SerialKFile:
+ * You should also supply a macro for casting KFile to Serial:
  *
  * \code
  * INLINE Serial * SERIAL_CAST(KFile *fd)
@@ -60,27 +65,30 @@
  * }
  * \endcode
  *
- * Then you can implement as much interface functions as you like
- * and leave the others to NULL.
- * ser_close implementation example:
+ * Then you can implement as many interface functions as needed
+ * and leave the rest to NULL.
+ *
+ * Example implementation of the close KFile method for Serial:
  *
  * \code
  * static int ser_kfile_close(struct KFile *fd)
  * {
- *		SerialKFile *fds = SerialKFile(fd);
- *		ser_close(fds->ser);
+ *		Serial *fds = SERIAL_CAST(fd);
+ *      // [driver specific code here]
  *		return 0;
  * }
  * \endcode
- * SerialKFile macro helps to ensure that obj passed is really a Serial.
  *
- * KFile interface do not supply the open function: this is deliberate,
+ * The SERIAL_CAST() macro helps ensure that the passed object is
+ * really of type Serial.
+ *
+ * The KFile interface does not supply an open function: this is deliberate,
  * because in embedded systems each device has its own init parameters.
- * For the same reason specific file settings (like baudrate for Serial, for example)
- * are demanded to specific driver implementation.
+ * For the same reason, specific device settings like, for example,
+ * the baudrate, are not part of interface and should be handled by the
+ * driver-specific API.
  *
  * \version $Id$
- *
  * \author Bernie Innocenti <bernie@codewiz.org>
  * \author Francesco Sacchi <batt@develer.com>
  * \author Daniele Basile <asterix@develer.com>
@@ -96,8 +104,7 @@
 /* fwd decl */
 struct KFile;
 
-typedef int32_t kfile_off_t;    ///< KFile offset type, used by kfile_seek function.
-typedef uint32_t kfile_size_t;   ///< KFile size type, used in kfile struct.
+typedef int32_t kfile_off_t;     ///< KFile offset type, used by kfile_seek().
 
 /**
  * Costants for repositioning read/write file offset.
@@ -170,7 +177,9 @@ typedef void (*ClearErrFunc_t) (struct KFile *fd);
 /**
  * Context data for callback functions which operate on
  * pseudo files.
- * \note If you change interface, remember to add corresponding access function.
+ *
+ * \note Remember to add the corresponding accessor functions
+ *       when extending this interface.
  */
 typedef struct KFile
 {
@@ -182,11 +191,11 @@ typedef struct KFile
 	FlushFunc_t    flush;
 	ErrorFunc_t    error;
 	ClearErrFunc_t clearerr;
-	DB(id_t _type); ///< Used to keep trace, at runtime, of obj type.
+	DB(id_t _type); ///< Used to keep track, at runtime, of the class type.
 
 	/* NOTE: these must _NOT_ be size_t on 16bit CPUs! */
-	kfile_off_t  seek_pos;
-	kfile_size_t size;
+	kfile_off_t    seek_pos;
+	kfile_off_t    size;
 } KFile;
 
 /**