bertos/io/kfile.h

   1 /**
   2  * \file
   3  * <!--
   4  * This file is part of BeRTOS.
   5  *
   6  * Bertos is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  19  *
  20  * As a special exception, you may use this file as part of a free software
  21  * library without restriction.  Specifically, if other files instantiate
  22  * templates or use macros or inline functions from this file, or you compile
  23  * this file and link it with other files to produce an executable, this
  24  * file does not by itself cause the resulting executable to be covered by
  25  * the GNU General Public License.  This exception does not however
  26  * invalidate any other reasons why the executable file might be covered by
  27  * the GNU General Public License.
  28  *
  29  * Copyright 2004 Develer S.r.l. (http://www.develer.com/)
  30  * Copyright 1999, 2000, 2001, 2003 Bernie Innocenti <bernie@codewiz.org>
  31  *
  32  * -->
  33  *
  34  * \defgroup core BeRTOS core functionality
  35  * \{
  36  *
  37  * \defgroup io_kfile KFile interface
  38  * \ingroup core
  39  * \{
  40  *
  41  * \brief Virtual KFile I/O interface.
  42  *
  43  * KFile is a simple, generic interface for file I/O.  It uses an
  44  * object-oriented model to supply a device-neutral interface to
  45  * communicate with drivers.
  46  *
  47  * This module contains only definitions, the instance structure
  48  * and the common API.
  49  * Each KFile subclass can override one or more methods of the interface,
  50  * and can extend the base KFile structure with its own private data.
  51  * For instance, a serial driver might implement the KFile interface by
  52  * declaring a context structure like this:
  53  *
  54  * \code
  55  * typedef struct Serial
  56  * {
  57  *      // base class instance
  58  *      KFile fd;
  59  *
  60  *      // private instance data
  61  *      FIFOBuffer txfifo, rxfifo;
  62  * } Serial;
  63  * \endcode
  64  *
  65  * You should also supply a macro for casting KFile to Serial:
  66  *
  67  * \code
  68  * INLINE Serial * SERIAL_CAST(KFile *fd)
  69  * {
  70  *              ASSERT(fd->_type == KFT_SERIAL);
  71  *              return (Serial *)fd;
  72  * }
  73  * \endcode
  74  *
  75  * Then you can implement as many interface functions as needed
  76  * and leave the rest to NULL.
  77  *
  78  * Example implementation of the close KFile method for Serial:
  79  *
  80  * \code
  81  * static int ser_kfile_close(struct KFile *fd)
  82  * {
  83  *              Serial *fds = SERIAL_CAST(fd);
  84  *      // [driver specific code here]
  85  *              return 0;
  86  * }
  87  * \endcode
  88  *
  89  * The SERIAL_CAST() macro helps ensure that the passed object is
  90  * really of type Serial.
  91  *
  92  * The KFile interface does not supply an open function: this is deliberate,
  93  * because in embedded systems each device has its own init parameters.
  94  * For the same reason, specific device settings like, for example,
  95  * the baudrate, are not part of interface and should be handled by the
  96  * driver-specific API.
  97  *
  98  * \author Bernie Innocenti <bernie@codewiz.org>
  99  * \author Francesco Sacchi <batt@develer.com>
 100  * \author Daniele Basile <asterix@develer.com>
 101  *
 102  * $WIZ$ module_name = "kfile"
 103  * $WIZ$ module_configuration = "bertos/cfg/cfg_kfile.h"
 104  * $WIZ$ module_depends = "timer", "formatwr"
 105  */
 106
 107 #ifndef KERN_KFILE_H
 108 #define KERN_KFILE_H
 109
 110 #include <cfg/compiler.h>
 111 #include <cfg/debug.h>
 112 #include <cfg/macros.h>
 113
 114 /* fwd decl */
 115 struct KFile;
 116
 117 typedef int32_t kfile_off_t;     ///< KFile offset type, used by kfile_seek().
 118
 119 /**
 120  * Costants for repositioning read/write file offset.
 121  * These are needed because on some embedded platforms
 122  * ANSI I/O library may not be present.
 123  */
 124 typedef enum KSeekMode
 125 {
 126         KSM_SEEK_SET, ///< Seek from file beginning.
 127         KSM_SEEK_CUR, ///< Seek from file current position.
 128         KSM_SEEK_END, ///< Seek from file end.
 129 } KSeekMode;
 130
 131 /*
 132  * Prototypes for KFile access functions.
 133  * I/O file functions must be ANSI compliant.
 134  * \note A KFile user can choose which function subset to implement,
 135  *       but has to set to NULL unimplemented features.
 136  */
 137
 138 /*
 139  * Read from file.
 140  * \return the number of bytes read.
 141  */
 142 typedef size_t (*ReadFunc_t) (struct KFile *fd, void *buf, size_t size);
 143
 144 /*
 145  * Write to file.
 146  * \return the number of bytes written.
 147  */
 148 typedef size_t (*WriteFunc_t) (struct KFile *fd, const void *buf, size_t size);
 149
 150 /*
 151  * Seek into file (if seekable).
 152  * \return the new file offset or EOF on errors.
 153  */
 154 typedef kfile_off_t (*SeekFunc_t) (struct KFile *fd, kfile_off_t offset, KSeekMode whence);
 155
 156 /*
 157  * Close and reopen file \a fd.
 158  * The reopening is done with the former file parameters and access modes.
 159  */
 160 typedef struct KFile * (*ReOpenFunc_t) (struct KFile *fd);
 161
 162 /*
 163  * Close file.
 164  * \return 0 on success, EOF on errors.
 165  */
 166 typedef int (*CloseFunc_t) (struct KFile *fd);
 167
 168 /*
 169  * Flush file I/O.
 170  * \return 0 on success, EOF on errors.
 171  */
 172 typedef int (*FlushFunc_t) (struct KFile *fd);
 173
 174 /*
 175  * Get file error mask.
 176  * \return 0 on success or file error code, device specific.
 177  */
 178 typedef int (*ErrorFunc_t) (struct KFile *fd);
 179
 180 /*
 181  * Clear errors.
 182  */
 183 typedef void (*ClearErrFunc_t) (struct KFile *fd);
 184
 185 /**
 186  * Context data for callback functions which operate on
 187  * pseudo files.
 188  *
 189  * \note Remember to add the corresponding accessor functions
 190  *       when extending this interface.
 191  */
 192 typedef struct KFile
 193 {
 194         ReadFunc_t     read;
 195         WriteFunc_t    write;
 196         ReOpenFunc_t   reopen;
 197         CloseFunc_t    close;
 198         SeekFunc_t     seek;
 199         FlushFunc_t    flush;
 200         ErrorFunc_t    error;
 201         ClearErrFunc_t clearerr;
 202         DB(id_t _type); // Used to keep track, at runtime, of the class type.
 203
 204         /* NOTE: these must _NOT_ be size_t on 16bit CPUs! */
 205         kfile_off_t    seek_pos;
 206         kfile_off_t    size;
 207 } KFile;
 208
 209 /*
 210  * Generic implementation of kfile_seek.
 211  */
 212 kfile_off_t kfile_genericSeek(struct KFile *fd, kfile_off_t offset, KSeekMode whence);
 213
 214 /*
 215  * Generic implementation of kfile_reopen.
 216  */
 217 struct KFile * kfile_genericReopen(struct KFile *fd);
 218
 219 int kfile_genericClose(struct KFile *fd);
 220
 221 /** @name KFile access functions
 222  * Interface functions for KFile access.
 223  * @{
 224  */
 225
 226 /**
 227  * Read \a size bytes from file \a fd into \a buf.
 228  *
 229  * \note This function will block if there are less than \a size bytes
 230  *       to read.
 231  *
 232  * \param fd KFile context.
 233  * \param buf User provided buffer.
 234  * \param size Number of bytes to read.
 235  * \return Number of bytes read.
 236  */
 237 INLINE size_t kfile_read(struct KFile *fd, void *buf, size_t size)
 238 {
 239         ASSERT(fd->read);
 240         return fd->read(fd, buf, size);
 241 }
 242 int kfile_gets(struct KFile *fd, char *buf, int size);
 243 int kfile_gets_echo(struct KFile *fd, char *buf, int size, bool echo);
 244
 245 /**
 246  * Write \a size bytes from buffer \a buf into KFile \a fd.
 247  *
 248  * Return value may be less than \a size.
 249  *
 250  * \param fd KFile context.
 251  * \param buf User provided data.
 252  * \param size Number of bytes to write.
 253  * \return Number of bytes written.
 254  */
 255 INLINE size_t kfile_write(struct KFile *fd, const void *buf, size_t size)
 256 {
 257         ASSERT(fd->write);
 258         return fd->write(fd, buf, size);
 259 }
 260
 261 int kfile_printf(struct KFile *fd, const char *format, ...);
 262 int kfile_print(struct KFile *fd, const char *s);
 263
 264 /**
 265  * Seek into file (if seekable).
 266  *
 267  * Move \a fd file seek position of \a offset bytes from \a whence.
 268  *
 269  * \param fd KFile context.
 270  * \param offset Offset bytes to move from position \a whence.
 271  * \param whence Position where to start the seek.
 272  * \return Current postion in the file.
 273  */
 274 INLINE kfile_off_t kfile_seek(struct KFile *fd, kfile_off_t offset, KSeekMode whence)
 275 {
 276         ASSERT(fd->seek);
 277         return fd->seek(fd, offset, whence);
 278 }
 279
 280 /**
 281  * Close and reopen file \a fd.
 282  * The reopening is done with the former file parameters and access modes.
 283  */
 284 INLINE KFile * kfile_reopen(struct KFile *fd)
 285 {
 286         ASSERT(fd->reopen);
 287         return fd->reopen(fd);
 288 }
 289
 290 /**
 291  * Close file.
 292  * \return 0 on success, EOF on errors.
 293  */
 294 INLINE int kfile_close(struct KFile *fd)
 295 {
 296         ASSERT(fd->close);
 297         return fd->close(fd);
 298 }
 299
 300 /**
 301  * Flush file I/O.
 302  * \return 0 on success, EOF on errors.
 303  */
 304 INLINE int kfile_flush(struct KFile *fd)
 305 {
 306         ASSERT(fd->flush);
 307         return fd->flush(fd);
 308 }
 309
 310 /**
 311  * Get file error mask.
 312  * \return 0 on success or file error code, device specific.
 313  */
 314 INLINE int kfile_error(struct KFile *fd)
 315 {
 316         ASSERT(fd->error);
 317         return fd->error(fd);
 318 }
 319
 320 /**
 321  * Clear errors.
 322  */
 323 INLINE void kfile_clearerr(struct KFile *fd)
 324 {
 325         ASSERT(fd->clearerr);
 326         fd->clearerr(fd);
 327 }
 328
 329 int kfile_putc(int c, struct KFile *fd); ///< Generic putc implementation using kfile_write.
 330 int kfile_getc(struct KFile *fd);  ///< Generic getc implementation using kfile_read.
 331 void kfile_resync(KFile *fd, mtime_t delay);
 332 void kfile_init(struct KFile *fd);
 333 /* @} */
 334
 335 /** \} */ //Defgroup io_kfile
 336
 337 /*
 338  * Kfile test function.
 339  */
 340 int kfile_testSetup(void);
 341 int kfile_testRun(void);
 342 int kfile_testRunGeneric(KFile *fd, uint8_t *test_buf, uint8_t *save_buf, size_t size);
 343 int kfile_testTearDown(void);
 344 /** \} */ //defgroup core
 345
 346
 347 #endif /* KERN_KFILE_H */