X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=bertos%2Fkern%2Fkfile.h;h=5d3ebc677a52cc2ada60d446d72d12f603fb4d4a;hb=71743c2a5a8bf9dbf66a945fd9656baed0d16329;hp=52f7991c88b75bf5112c65a0c26cdf2499ef70e2;hpb=3f32a55a47be10c12c127ab5c46ff483ba2e371e;p=bertos.git diff --git a/bertos/kern/kfile.h b/bertos/kern/kfile.h index 52f7991c..5d3ebc67 100644 --- a/bertos/kern/kfile.h +++ b/bertos/kern/kfile.h @@ -27,62 +27,74 @@ * the GNU General Public License. * * Copyright 2004 Develer S.r.l. (http://www.develer.com/) - * Copyright 1999, 2000, 2001, 2003 Bernardo Innocenti + * Copyright 1999, 2000, 2001, 2003 Bernie Innocenti * * --> * * \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 KFileSerial + * typedef struct Serial * { - * KFile fd; - * Serial *ser; - * } KFileSerial; + * // base class instance + * KFile fd; + * + * // private instance data + * FIFOBuffer txfifo, rxfifo; + * } Serial; * \endcode * - * You should also supply a macro for casting KFile to KFileSerial: + * You should also supply a macro for casting KFile to Serial: * * \code - * INLINE KFileSerial * KFILESERIAL(KFile *fd) + * INLINE Serial * SERIAL_CAST(KFile *fd) * { - * ASSERT(fd->_type == KFT_SERIAL); - * return (KFileSerial *)fd; + * ASSERT(fd->_type == KFT_SERIAL); + * return (Serial *)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) * { - * KFileSerial *fds = KFILESERIAL(fd); - * ser_close(fds->ser); - * return 0; + * Serial *fds = SERIAL_CAST(fd); + * // [driver specific code here] + * return 0; * } * \endcode - * KFILESERIAL 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 Bernardo Innocenti + * \author Bernie Innocenti * \author Francesco Sacchi * \author Daniele Basile + * + * $WIZ$ module_name = "kfile" + * $WIZ$ module_configuration = "bertos/cfg/cfg_kfile.h" */ #ifndef KERN_KFILE_H @@ -95,8 +107,7 @@ /* fwd decl */ struct KFile; -typedef int32_t kfile_off_t; ///< KFile offset type, used by kfile_seek function. -typedef int32_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. @@ -169,7 +180,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 { @@ -181,11 +194,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; /** @@ -198,12 +211,15 @@ kfile_off_t kfile_genericSeek(struct KFile *fd, kfile_off_t offset, KSeekMode wh */ 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. @@ -262,6 +278,8 @@ INLINE void kfile_clearerr(struct KFile *fd) /** * Kfile test function. */ -bool kfile_test(KFile *fd, uint8_t *test_buf, uint8_t *save_buf, size_t size); +int kfile_testSetup(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 */