Compile-Link

Compile and Link
File Components
There are 6 catogories of files to compose a execution having file system(F.S.) function:
Catogories | notes | Example 1 | Example 2 | Example 3
1 | F.S.Library | All file system functions are in lib "ertfsl.lib" | ertfsl.lib | ertfsl.lib | ertfsl.lib
2 | CPU Libary | According to the module type, select the proper library. For example, "8000L.lib, 7188xal.lib, 7188xbl.lib or 7188xl.lib". | 8000L.lib | 7188xal.lib | 7188xbl.lib
3 | call back functions | All functions in this file are called by F.S.library. There are two groups available. "RAMDISK3.c" for X607, "MMCDISK.c" for I8073. | MMCDISK.c | RAMDISK3.c | RAMDISK3.c
4 | Memory driver | "8073L.lib" for MMC card. "X607.C" for X607,X608 | 8073L.lib | X607.c | x607.c
5 | User Programs | Prepare your user programs. | mmc01.c, rtfsdem7.c | del.c | pcfree.c
6 Header files There are 4 groups of header files needed:
group 1:F.S.
   comumode.h
   define.h
   pcconf.h
   pcdisk.h
   portio.h
   potkern.h
   portterm.h
   rtfsapi.h
group 2:CPU
   8000.h
   or 7188xa.h
   or 7188xb.h
   or 7188x.h
group 3: memory driver
   8073.h
   or x607.h
group 4:Others,e.g.
   string.h
   math.h
 comumode.h
define.h
pcconf.h
pcdisk.h
portio.h
potkern.h
portterm.h
rtfsapi.h

8000.h
8073.h 		comumode.h
define.h
pcconf.h
pcdisk.h
portio.h
potkern.h
portterm.h
rtfsapi.h

7188xa.h
x607.h 		comumode.h
define.h
pcconf.h
pcdisk.h
portio.h
potkern.h
portterm.h
rtfsapi.h

7188xb.h
x607.h

Files hierarchy
In the release CD, files and directory are placed as the following graph:
  1. xa means all files in this sub-directory are for 7188xa
  2. example sub-directories
  3. call back function
  4. memory driver
  5. header files
  6. file utility
  7. user program. They are source files for file utility: ifs5xa.exe
files hierarchy

In every example sub-directory, files are placed as the following graph:
  1. user program source
  2. header files
  3. user program executable file
example sub-directory

4 key components of file system are placed in the directory "lib":
  1. File system library
  2. CPU library
  3. Memory driver
  4. call back functions
lib

Compiler Option Settings
File system library now only support large memory model. User have to sellect correct model. For example(BC++), make sure the large model is sellected.
memory mode

Directory setting must be as follows:
directory setting

Compile link examples

Example 1

8411 		+
8073 		= a MMC reader on I-8000 series
Please see ..\\rtfsmmc\mmc010.prj, project window(BC++) may be as follows:

Example 2

7188XA 		+
X607 		= File system on a 128K SRAM with 7188XA
Please see .. \\FileSys\7188xa\del\del.prj, project window(BC++) may be as follows:

Example 3

7188XB 		+
X608 		= File system on a 512K SRAM with 7188XB
Please see ..\\FileSys\7188xb\pcfree\avl.prj, project window(BC++) may be as follows:

[File System Library for MiniOS7 systems( 7188x/I-8000 series)] Ver 1.0.0
Final update date:[10/30/2002], By: Chang, Shao-Heng
Any question please E-Mail to:ICPDAS_SERVICE


Demo Description

Demo programs description
Now we support 10 demo programs for 7188XA/B and 8000 series.
No.* | Name | Usage | Description | Location
1 | [test utility] | ** | *** | [path]
2 | attr.exe | attr t.bmp | show attributes of "t.bmp" | [path]\atribute
3 | copy.exe | copy | copy "t.bmo" to "b.bmp" | [path]\copy
4 | delfile.exe | delfile | delete file "t.bmp" | [path]\del
5 | avl.exe | avl | show free space in disk | [path]\pcfree
6 | md.exe | md | make a directory "test2" | [path]\pcmkdir
7 | state.exe | state | show status of "r.bmp" | [path]\pcstat
8 | rn.exe | rn | rename "r.bmp" to "q.bmp" | [path]\rename
9 | cd.exe | cd | change working directory to "test2" | [path]\workdir
10 | rm.exe | rm | remove directory "test2" | [path]\rmdir

Note
*
If One tests the file system library for the first time, this "No." can be a good step to go through all demo programs withought compiling-linking any source. To do this, one must format a disk, create a initial file "t.bmp":
--format a disk
  • Run test utility
  • Input "format"
  • Follow the instructions to complete work
--create "t.bmp"
  • Run test utility
  • Input command:> fillfile t.bmp "FATFileSystem" 111
    Then disk will have a file named t.bmp with 111 lines. Each line is the string "FATFileSystem"

**
For 7188xa , test utility is "ifs5xa.exe"
For 7188xb, test utility is "ifs5xb.exe"
For 8000, test utility is "mmc010.exe"

***
Execute the test utility, then press Enter to get the usage guide. Generally, it contains functions in demo program 2~10.


File System library

File system library reference
Features
  • DOS compatible file system library for embedded systems
  • For X607(added on 7188XA/B/C)and I8073(MMC expansion card on 8000 series)
  • Supporting DOS 16 bit File Allocation Tables.

Compile and Link ...

Demo Programs
Now suport demo programs for 7188xa, 7188xb and 8000series
The files are placed at:
for 7188xa, [path] is 8000CD:\Napdos\FileSys\7188xa
for 7188xa, [parh] is 8000CD:\Napdos\FileSys\7188xb
for 8000 series, [parh] is 8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc
Demo programs description

API Calls
1. Initialization
pc_ertfs_init Mount devices from device driver table.

2. File Operations
po_open | Open a file
po_read | Read bytes from a file
po_write | Write Bytes to a file
po_close | Close a file and flush the file allocation table
po_flush | Flush an open file
pc_mv | Rename a file
pc_unlink | Delete a file
pc_set_attributes | Set File Attributes
pc_get_attributes | Get File Attributes
pc_stat | Obtain statistics on a path

3. Directory Operations
pc_mkdir | Create a directory
pc_rmdir | Delete a directory
pc_deltree | Delete an entire directory tree

4. Miscelaneous Functions
pc_free | Calculate and return the free space on a disk
pc_set_cwd | Set the current working directory
pc_isdir | Determine if a path is a director
pc_isvol | Determine if a path is a volume
pc_pwd | Get string representation of current working directory


 PC_DELTREE
Delete a directory tree
BOOLEAN pc_deltree (
char *directory
);
Parameters
directory[in]
name of directory tree to be deleted
Description:
Delete the directory specified in name, all subdirectories of that directory, and all files contained therein. Fail if name is not a directory, is read only or is currently in use.
Returns:
Returns TRUE if the directory was successfully removed. If FALSE is returned, get_errno will return one of these values:

PENOENT - Directory not found or path to file not found
PEACCES - Not a directory, not empty or in use
PENOSPC - Write failed
Example:
pc_deltree("test");
/*
delete tree "test" from the current directory
see also
8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\deltree\dtree.c
*/


 PC_DISKFLUSH
Flush the FAT and all files to a disk
BOOLEAN pc_diskflush(
char *path
);
Parameters
path[in]
path is a valid drive specifier.
Description
Given a path containing a valid drive specifier, flush the file allocation table and all changed files to the disk. After this call returns, the disk image is synchronized with an ERTPS internal view of the volume.
Returns
Returns TRUE if the disk flush succeeded, otherwise FALSE
Example
#include < pcdisk.h >
if(!pc_diskflush(A:))
   printf("Flush operation failed \n");


 PC_ERTFS_INIT
Configure ERTFS drive letter/device mapping and initialize device drivers.
BOOLEAN pc_ertfs_init(
int (*pRint)(char *fmt,...),
int (*kBhit)(void),
int (*gEtch)(void),
int (*lIneInput)(char *buf,int maxlen),
void (*dElayMs)(unsigned t),
void (*gEtDate)(int *year,int *month,int *day),
void (*gEtTime)(int *hour,int *minute,int *sec)
);
Parameters
pRint[in]
function pointer to Print()
kBhit[in]
function pointer to Kbhit()
gEtch[in]
function pointer to Getch()
lIneInput[in]
function pointer to LineInput()
dElayMs[in]
function pointer to DelayMs()
gEtDate[in]
function pointer to GetDate()
gEtTime[in]
function pointer to GetTime()
Description:
For cross all MiniOS7 base modules, pc_ertfs_init need function pointer for internal use.
Returns:
Returns TRUE if it initialization is successful.
Note:
This routine must be called prior to calling any other ERTFS routines. lf RTIP is included, it must be called after xn_rtip_init() returns successfully.
Example
#include < pcdisk.h >
   if (!pc_ertfs_init(Print,
                      Kbhit,
                      Getch,
                      LineInput,
                      DelayMs,
                      GetDate,
                      GetTime)
      )
      Print("pc_ertfs_init failed");


 PC_FREE
Return disk free space statistics
long pc_free(
char *drive,
dword *total_blocks,
dword *free_blocks
);
Parameters
drive[in]
drive ID
total_blocks[out]
Total blocks in the drive.
free_blocks[out]
Free blocks in the drive.
Description
Given a drive ID, return the number of free bytes on the drive, the total number of blocks on the drive and the number of blocks free.
Returns
The number of bytes free on the disk.
MOTE
The first time this routine is called after pc_dskinit it must scan the whole file allocation table to calculate the number of free clusters which takes some time. Subsequent calls return immediately with a valid value.
Example
pc_free("", &blocks_total, &blocks_free);
Print("\n\r%-8ld KBytes free\n\r", blocks_free/2);
/*
1 block=512 bytes
see also
8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\pcfree\pcfree.c
*/


 PC_GET_ATTRIBUTES
Get File Attributes
BOOLEAN pc_get_attributes(
char *path,
byte *p_return
);
Parameters
path[in]
name of a file of directory
p_return[out]
returned attribute stored in this byte
Description
Given a file or directory name. return the directory entry attributes associated with the entry.
One or more of the following values will be or'ed together:
    BIT  Nemonic

     0   ARDONLY
     1   AHIDDEN
     2   ASYSTEM
     3   AVOLUME
     4   ADIRENT
     5   ARCHIVE
Returns
Returns TRUE if successful, otherwise it returns FALSE and get_errno returns one of these values:
  PENOENT
Example
pc_get_attributes("test", &attr);
/*
find attribute of directory "test"
see also
8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\atribute\atribu.c
*/


 PC_ISDIR
Test if a path is a directory.
BOOLEAN pc_isdir(
char *path
);
Parameters
path[in]
path to be tested
Description
This is a simple routine that opens a path and checks if it is a directory, then closes the path. The program cp2pc in the samples directory uses it to test if a destination is a directory. The same functionality can be gotten by calling pc_gfirst and testing the DSTAT structure.
Returns
Returns TRUE if path points to a valid existing directory, otherwise FALSE.
Example
if (!pc_isdir(rmpath))
/*
Test whether rmpath is a directory.
See Also
8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\del\del.c
*/


 PC_ISVOL
Tests to see if a path specification is a volume specifier.
BOOLEAN pc_isvol(
char *path
);
Parameters
path[in]
path name
Description
Tests to see if a path specification is a volume specifier.
Returns
Returns TRUE if it is a volume.
Example
if (!pc_isvol(rmpath))
/*
Test whether rmpath is a volume specifier.
See Also
8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\del\del.c
*/


 PC_MKDIR
Create a subdirectory.
BOOLEAN pc_mkdir(
char *path
);
Parameters
path[in]
subdirectory name to be created
Description
Create a subdirectory in the path specified by path. Fails if a file or directory of the same name already exists or if the directory component (if there is one) of path is not found.
Returns
Returns TRUE if the subdirectory was created, otherwise FALSE.
If FALSE is returned, get_errno will return one of these values:
   PENOENT - Directory not found
   PEEXIST - File or directory already exists
   PENOSPC - Write failed
Example
pc_mkdir("test");
/*
make a subdirectory named "test" from the current working directory
*/


 PC_MV
Rename a file or directory
BOOLEAN pc_mv(
char *oldpath,
char *newname
);
Parameters
oldpath[in]
old filepath
newname[in]
new name of file or directory
Description
Renames the file oldpath to newname. Fails if newname is invalid, already exists or oldpath is not found.
Returns
Returns TRUE if the file was renamed, otherwise FALSE.
If FALSE is returned, get_errno will return one of these values:
   PENOENT - Directory not found
   PEEXIST - File or directory already exists
   PENOSPC - Write failed
Example
pc_mv("r.bmp","q.bmp");
/*
rename the file. old name is "r.bmp". new name is "q.bmp"
see Also
8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\rename\rename.c
*/


 PC_PWD
Return the current working directory.
BOOLEAN pc_pwd(
char *drive,
char *return_buffer
);
Parameters
drive[in]
drive
return_buffer[out]
full current working directory filled by this function call
Description
Fill retum_buffer with the full path name of the current working directory for the drive specified in drive. If drive points to an empty string ("") or an invalid drive specifier, the current working directory for the default drive is returned.
Returns
Returns YES if a valid path was returned in return_buffer, otherwise no if the current working directory could not be found. The failure mode would be due to either the fact that the drive is not mounted or an I/O error occurred.
Note
Return buffer must contain enough space to hold the full path.
Example
char pwd[128];
if(pc_pwd("A:",pwd)
   Print("Working dir is %s\n\r",pwd);
else
   Print("Can't find working dir for A:\n\r  ");
/*
See Also
8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\workdir\cd.c
*/


 PC_RMDIR
Delete a directory.
BOOLEAN pc_rmdir(
TEXT *path
);
Parameters
path[in]
directory to be deleted
Description
Delete the directory specified in path. Fails if path is not a directory, is read only or is not empty.
Returns
TRUE if the directory was successfully removed, otherwise FALSE. If FALSE is returned, get_errno will return one of these values:
   PENOENT - Directory not found
   PEACCES - Not a directory, not empty or in use
   PENOSPC - Write failed
Example
if(!pc_rmdir("A:\\test")
   Print("Can't delete directory\n\r");
/*
directory "test" on disk "A:" is about to be deleted.
See also 8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\rmdir\rm.c
*/


 PC_SET_ATTRIBUTES
Set File Attributes
BOOLEAN pc_set_attributes(
char *path,
byte attributes
);
Parameters
path[in]
file or directory name
attributes[in]
setting value
Description
Given a file or directory name set the directory entry attributes associated with the entry. One or more of the following values may be or'ed together
   BIT    Nemonic
    0     ARDONLY
    1     AHIDDEN
    2     ASYSTEM
    5     ARCHIVE
Returns
Returns TRUE if successful, otherwise FALSE and get_errno will return one of these values:
   PENOENT - Couldn't find the entry
   PENOSPC - Write failed
Example
unsigned char attributes;
pc_set_attributes("A:\\t.bmp",attributes);
/*
See also
8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\atribute\atribu.c
*/


 PC_SET_CWD
Set current working directory.
BOOLEAN pc_set_cwd(
char *path
);
Parameters
path[in]
directory name to be set to the current working directory
Description
Make path the current working directory. If path contains a drive component, the current working directory is changed for that drive, otherwise the current working directory is changed for the default drive.
Returns
Returns TRUE if the current working directory was changed, otherwise FALSE. If FALSE is returned, get_errno returns one of these values PENOENT - Directory not found Example:
Example
if(!pc_set_cwd("A:\\test")
   Print("Can't change working directory");
/*
See also
8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\workdir\cd.c
*/


 PC_STAT
Obtain statistics on a path.
int pc_stat(
char *path,
STAT *pstat
);
Parameters
path[in]
path name
pstat[out]
a STAT structure store statics or infomation for given path
Description
This routine searches for the file or directory provided in the first argument.
If found, it fills in the stat structure as described here:
   st_dev  -   the entry's drive number
   st_mode;

     S_IFMT    - type of file mask
     S_IFCHR   - character special (unused)
     S_IFDIR    -  directory
     S_IFBLK   -  block special  (unused)
     S_IFREG   - regular (a 'file")
     S_IWRITE  - Write permitted
     S_IREAD   - Read permitted.

   st_rdev    - the entry's drive number
   st_size    - file size
   st_atime   - creation date in DATESTR format
   st_mtime  - creation date in DATESTR format
   st_ctime   - creation date in DATESTR format
   t_blksize   - optimal blocksize for I/O (cluster size)
   t_btocks   - blocks allocated for file
   fattributes  - the DOS attributes. This is non-standard but supplied if you want to look at them.
Returns
Returns 0 if successful, otherwise -1 and get_errno will return one of these values:
   PENOENT
Example
int dostat( char *agv)
{
struct stat st;
   if (pc_stat(agv, &st)==0)
   {
      Print("\n\rDRIVENO: %02d SIZE: %7ld\n\r", st.st_dev, st.st_size);
      Print(" DATE:%02d-%02d",(st.st_atime.date >> 5 ) & 0xf,/* Month */(st.st_atime.date & 0x1f)/* Day */);
      Print("-%02d",80 +(st.st_atime.date >> 9) & 0xff); /* Year */
      Print("  TIME:%02d:%02d\n\r",(st.st_atime.time >> 11) & 0x1f,/* Hour */(st.st_atime.time >> 5) & 0x3f); /* Minute */
      Print("OPTIMAL BLOCK SIZE: %7ld FILE size (BLOCKS): %7ld\n\r",st.st_blksize,st.st_blocks);
      Print("MODE BITS :");
      if (st.st_mode&S_IFDIR)
         Print("S_IFDIR|");
      if (st.st_mode&S_IFREG)
         Print("S_IFREG|");
      if (st.st_mode&S_IWRITE)
         Print("S_IWRITE|");
      if (st.st_mode&S_IREAD)
         Print("S_IREAD\n\r");
      Print("\n\r");

      return (1);
   }
   else
   {
      Print("FSTAT failed\n\r");
      return(0);
   }
}
/*
See also
8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\pcstat\pcstat.c
*/


 PC_UNLINK
delete a file.
BOOLEAN pc_unlink
char *path
);
Parameters
path[in]
file path
Description
Delete the file in name. Fail if not a simple file, if it is open, does not exist, or is read only.
Returns
Returns TRUE if it successfully deleted the file, otherwise FALSE If FALSE is returned, get_errn will return one of these values
   PENOENT - File not found
   PEACCES - Is a directory or an open file
   PENOSPC - Write failed
Example
if(!pc_unlink("A:\\t.bmp"))
   Print("Can't delete a file");
/*
See Also
See also 8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\del\del.c
*/


 PO_CLOSE
Close a file.
int po_close(
PCPD fd
);
Parameters
fd[in]
file descripter of file to be closed. This descripter is the function return value of po_open()
Description
Close the file and update the disk by flushing the directory entry and file allocation table, then free all core associated with fd.
Returns
Returns 0 if all went well, otherwise -1. If -1 is returned, get_errno will return one of these values
   PEBADF  - Invalid file descriptor
   PENOSPC - I/O error occurred
See Also
po_flush
Example
if(po_close(fd)<0)
   Print("Error closing file");
/*
See also
8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\copy\copy.c
*/


 PO_FLUSH
Flush a file to disk.
BOOLEAN po_flush(
PCFD fd
);
Parameters
fd[in]
file descripter of file to be flushed. This descripter is the function return value of po_open()
Description
Write the file's directory entry to disk and flush the FAT. After this call completes, the on disk view of the file is completely consistent with the in memory view. It is a good idea to call this function periodically if a file is being extended. If a file is not flushed or closed and a power down occurs, the file size will be wrong on disk and the FAT chains will be lost.
Returns
Returns TRUE if flush succeeded, otherwise FALSE is returned. If FALSE is returned, get_errno will return one of these values:
   PEBADF  - Invalid file descriptor
   PENOSPC - I/O error occurred
Example
if(po_flush(fd)<0)
   Print("Error flushing file");


 PO_OPEN
Open a file.
PCFD po_open(
char *path,
word flag,
word mode
);
Parameters
path[in]
file path
flag[in]
flag value
mode[in]
mode value
Description
Open the file for access as specified in flag. If creating use mode to set the access permission.
Flag values are:
   PO_APPEND - All writes will be appended to the file
   PO_BINARY  - Ignored
   PO_TEXT    - Ignored
   PO_RDONLY - Open for read only
   PO_RDWR   - Read/write access allowed.
   PO_WRONLY - Open for write only
   PO_CREAT   - Create the file if it does not exist.
   PO_EXCL    - lf flag has(PO_CREATIPO_EXCL) and the file already exists,
                fail and set fs_user->p_errno to EEXIST.
   PO_TRUNC  - Truncate the file if it already exists
   PO_NOSHAREANY - Fail if already open, fail if another open is tried.
   PO_NOSHAREWRITE - Fail if already open for write and fail if another open for write is tried.
Mode values are:
   PS_IWRITE  - Write permitted
   PS_IREAD   - Read permitted. (Always true anyway)
Returns
Returns a non-negative integer to be used as a file descriptor for calling po_read, po_write, po_lseek, po_flush, po_truncate, and po_close, otherwise it returns -1 and get_errno will return:
   PENOENT  - File not found or path to file not found
   PEMFILE  - No file descriptors available (too many
                files open)
   PEEXIST  - Exclusive access requested but file already exists.
   PEACCESS - Attempt to open a read only file or a special (directory)file.
   PENOSPC  - Create failed
   PESHARE  - Sharing error. Already open exclusive or attempting to open exclusive
                and the file is already open.
Example
if ((in_fd = po_open(*agv,(word) (PO_BINARY|PO_RDONLY),(word) (PS_IWRITE | PS_IREAD) ) ) < 0)
{
   Print("Cant open %s\n\r", *agv);
   return(0);
}
/*
See also
8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\copy\copy.c
*/


 PO_READ
Read from a file.
word po_read(
PCFD fd,
byte *buf,
word count
);
Parameters
fd[in]
file descripter of file to be read. This descripter is the function return value of po_open()
buf[out]
buf where the data is placed.
count[in]
a number that the function attempts to read from the file.
Description
Attempt to read count bytes from the file at fd and place the data in buf. The file pointer is updated.
Returns
Returns the actual number of bytes read or Oxffff on error. If the return value is Oxffff, get_errno will return one of the following:
   PEBADF  - File descriptor invalid or open read only
   PENOSPC - File  I/O error.
Example
   PCFD in_fd;
   int nread;
   byte shellbuf[1024];
   nread = (word)po_read(in_fd,(byte*)shell_buf, 1024);
/* See Also
8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\copy\copy.c
*/


 PO_WRITE
Write to a file.
word po_write(
PCFD fd,
byte * buf,
word count
);
Parameters
fd[in]
file descripter of file to be read. This descripter is the function return value of po_open()
buf[in]
buf where contains data to be written to the file
count[in]
a number that the function attempts to write to the file.
Description
Attempt to write count bytes from buf to the current file pointer of file at fd. The file pointer is updated.
Returns
Returns the number of bytes written or Oxffff on error. If the return value is Oxffff, get_errno will return one of the following:
   PEBADF  - File descriptor invalid or open read only
   PENOSPC - Write failed because of no space or an I/O error.
Example
   PCFD out_fd;
   int nread;
   byte shellbuf[1024];
   po_write(out_fd,(byte*)shell_buf,(word)nread);
/* See Also
8000CD:\Napdos\8000\Common\MiniOS7\demo\Bc\rtfsmmc\copy\copy.c
*/