[s1mp3-dev] [Swan API] STDIO module

[Bluechip]

I would suggest that you call it something other than "stdio" 
otherwise C coders will "#include <stdio.h>" and expect to be able to 
use C stdio functions.

I would also highlight the fact that the Swan API is *not* C compliant.

BC

At 22:53 18/06/2006, you wrote:
>This section is online at
>http://www.s1mp3.org/wiki/index.php/S1SDK_API_design#STDIO and will be
>edited considering the results of the ongoing discussion
>
>Please comment this (awful) API spec!
>
>-------------------
>
>
>       STDIO
>
>Previous names assigned to this module: /FS/, /FILESYSTEM/
>
>Module  : STDIO
>Purpose : provides functions to handle standard I/O, i.e. files on 
>the main NAND or virtual files
>Modules
>used    : NAND, possibly other devices' modules mapped as streams/DMA
>
>A file descriptor will be a struct (with child unions) which defines
>custom data depending on the file type (filesystem file, DMA dump,
>directories etc). File descriptors are supposed to be hold on a fixed
>size array stored somewhere on the ZRAM. The execution of a new program
>flags each file descriptor slot as available, allowing all the slots to
>be reused. Basically, file descriptors do not need an explicit close()
>since there are no cache buffers and all data is always flushed, but
>closing a fd allows its re-use during the application execution.
>
>The first fd slots will be reserved and will contain descriptors for
>core virtual files (I2C, NAND, DMA, STDIN,STDOUT,STDERR,etc.). Those
>files will be like if always open but through open_dev() they will be
>reinitialized if needed.
>
>The mode parameter will be expressed in the C standard way through a
>small null terminated string like /"rb"/. An alternative /open()/ style
>function will be available too (with predefined constant that can be
>used with OR, like /O_READ|O_WRITE|O_APPEND|O_CREATE|O_BINARY/).
>
>A negative result is considered an error.
>
>//a file descriptor will be the index of the file in the global 
>fd_slot[] table
>#define file            i8
>//the real maximum would be 255, but we have to optimize...
>#define MAX_FD_SLOTS    64
>
>     * file *open_dev(i8 id, i8 mode)* - basic function used to open
>       special devices as streams, like NAND (in dump mode), i2c, lineIn
>       and so on...returns a file descriptor compatible with all the
>       below functions.
>
>     * void *close(file fd)* - closes a file stream and releases the
>       internal file descriptor
>
>void close(file fd) {
>     if (fd >= MAX_FD_SLOTS) {
>        //eventually set error code to: invalid file
>        return;
>     }
>     if (!fd_slot[fd].__available) {
>        //eventually set error code to: file was not open
>        return;
>     }
>     fd_slot[fd].__available = true; // there is no need to free anything
>}
>
>     * file *fopen(char *path, char *mode)* - basic function used to open
>       a file given the filename
>
>     * i8 *seek(file fd,i32 offset, ui8 whence)* - used to move the file
>       pointer. Not all streams maybe seekable. /whence/ will be
>       [SEEK_SET|SEEK_CUR|SEEK_END]
>
>     * i16 *read*(file fd, const void *buffer, ui16 nobytes) - used to
>       read data, returns actually read byte count
>
>  i16 read(file fd, const void *buffer, ui16 nobytes) {
>      ui16 retval;
>      // as always, check the validity of 'fd'
>      switch (fd_slot[fd].__type) {
>          case FT_I2C:
>            retval = i2c_read(...);
>            break;
>          case FT_FILE:
>            ...
>            break;
>          case ...
>          default:
>            return -1;
>      }
>      return retval;
>  }
>
>
>     * i16 *write(file fd, void *buffer, ui16 nobytes)* - used to write
>       data, returns actually written bytes count
>
>     * i32 *tell(file fd)* - used to get the file pointer position. Not
>       available in non-seekable files
>
>     * ui32 *size(file fd)* - returns the current file size, with error
>       checking
>
>  ui32 size(file fd) {
>     // check for 'fd' validity, as in open_dev()
>     return fd_slot[fd].__size;
>  }
>
>     * void *rewind(file fd)* - returns to the start of the file, defined as
>
>  #define rewind(fd)      seek(fd, 0, SEEK_SET)
>
>     * bool *unlink(char *path)* - deletes a physical file from the NAND,
>       accepts the filename as parameter
>
>// the 'type' identifier for the file descriptor
>// will allow directory type
>#define dir     file
>
>     * dir opendir(char *path)
>     * i8 readdir(dir handle, char *buff, u8 no)
>
>Reads the next file in the directory and stores it in buff, for a
>maximum of no characters. Returns stored characters or -1 on error
>
>     * i8 closedir(dir handle)
>
>-------------------
>
>--
>   Legolas
>
>
>_______________________________________________
>s1mp3-dev mailing list
>s1mp3-dev at s1mp3.org
>http://s1mp3.org/mailman/listinfo/s1mp3-dev_s1mp3.org