* -->
*
* \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)
* }
* \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>
+ *
+ * $WIZ$ module_name = "kfile"
+ * $WIZ$ module_configuration = "bertos/cfg/cfg_kfile.h"
+ * $WIZ$ module_depends = "timer", "formatwr"
*/
#ifndef KERN_KFILE_H
/* 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.
/**
* 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
{
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;
/**
*/
struct KFile * kfile_genericReopen(struct KFile *fd);
+int kfile_genericClose(struct KFile *fd);
+
int kfile_putc(int c, struct KFile *fd); ///< Generic putc implementation using kfile_write.
int kfile_getc(struct KFile *fd); ///< Generic getc implementation using kfile_read.
int kfile_printf(struct KFile *fd, const char *format, ...);
int kfile_print(struct KFile *fd, const char *s);
int kfile_gets(struct KFile *fd, char *buf, int size);
int kfile_gets_echo(struct KFile *fd, char *buf, int size, bool echo);
+void kfile_resync(KFile *fd, mtime_t delay);
/**
* Interface functions for KFile access.
/**
* Kfile test function.
*/
-int kfile_testSetUp(void);
-int kfile_testRun(KFile *fd, uint8_t *test_buf, uint8_t *save_buf, size_t size);
+int kfile_testSetup(void);
+int kfile_testRun(void);
+int kfile_testRunGeneric(KFile *fd, uint8_t *test_buf, uint8_t *save_buf, size_t size);
int kfile_testTearDown(void);
#endif /* KERN_KFILE_H */
projects / bertos.git / blobdiff