[s1mp3-dev] [Swan API] STDIO module

[Legolas]

Bluechip ha scritto:

>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.
>  
>
FILESYSTEM? We can change whatever we want before v1.0 in my opinion, so 
FILESYSTEM should be good enough (add proposals here)

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

I expect the below API - simple if compared to the other modules - to be 
re-designed with the help of the experienced members of this mailing 
list. I can spot enough inconsistencies in it to feel the need of a 
rewrital and I would like to keep the wiki pages "fresh" as potential 
new members do read them before joining. We are also working on the 
mailing list to properly update the Dev:Swan API wiki page with the LCD 
API discussion thread.

>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
>>    
>>
>
>
>_______________________________________________
>s1mp3-dev mailing list
>s1mp3-dev at s1mp3.org
>http://s1mp3.org/mailman/listinfo/s1mp3-dev_s1mp3.org
>
>  
>