Documentation/yaffs_direct.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
   2 <HTML>
   3 <HEAD>
   4         <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
   5         <TITLE></TITLE>
   6         <META NAME="GENERATOR" CONTENT="StarOffice/5.2 (Linux)">
   7         <META NAME="AUTHOR" CONTENT=" ">
   8         <META NAME="CREATED" CONTENT="20021129;9042700">
   9         <META NAME="CHANGEDBY" CONTENT=" ">
  10         <META NAME="CHANGED" CONTENT="20030121;16011900">
  11 </HEAD>
  12 <BODY>
  13 <H1>YAFFS Direct Interface (YDI)</H1>
  14 <H2>Now hear this!</H2>
  15 <P>YAFFS code is GPL. The YAFFS Direct Interface(YDI) is really
  16 intended to provide a direct interface to YAFFS in an embedded/RTOS
  17 environment. Using YAFFS in this way might violate GPL. Aleph One are
  18 looking at ways to make YAFFS licensing more flexible to support both
  19 GPL and YDI users. For further info, please contact Aleph One.</P>
  20 <H3>Purpose</H3>
  21 <P>The purpose of the YAFFS Direct Interface is to provide YAFFS to
  22 embedded/RTOS environments where full file system support is not
  23 available. Typically, therefore, YDI is intended for smaller embedded
  24 systems.</P>
  25 <H3>Software Modules</H3>
  26 <P>The software is designed in a modular fashion to facilitate
  27 integration and configuration.</P>
  28 <P>The software comprises the following main sections:</P>
  29 <UL>
  30         <LI><P>yaffscfg.c Configuration. Set up various device features etc
  31         and some OS integration (eg. locking function). Allows tuning.</P>
  32         <LI><P>yaffsfs.c: File system interface functions (and associated
  33         header file for inclusion in application code).
  34         </P>
  35         <LI><P>yaffs_flashif.c NAND integration functions (to be completed
  36         by the integrator) This currently holds a second ramdisk for test
  37         purposes.</P>
  38         <LI><P>yaffs_guts.c: The file system algorithms for yaffs.</P>
  39         <LI><P>nand_ecc.c: The ECC algorithms.</P>
  40         <LI><P>yaffs_ramdisk.c: RAMdisk support code.</P>
  41         <LI><P>yaffs_fileem.c: Flash emulation on a host file. This is for
  42         testing purposes only.</P>
  43         <LI><P>dtest.c: Test harness functions.</P>
  44 </UL>
  45 <P><BR><BR>
  46 </P>
  47 <H2>General Notes</H2>
  48 <H3>Licensing</H3>
  49 <P>The YAFFS file system is GPL.</P>
  50 <P>The YAFFS bootloader and header files are LGPL to allow
  51 incorporation of these into proprietary code.</P>
  52 <P>nand_ecc.c, copyright SJ Hill, is LGPL.</P>
  53 <H3>File names</H3>
  54 <P>Multiple partitions are defined by setting up the partition table
  55 in yaffscfg.c.</P>
  56 <P>The system has no concept of current directory, therefore all
  57 names and paths must be fully specified. eg. &quot;/boot/xxx&quot;</P>
  58 <P>Names are case sensitive.
  59 </P>
  60 <P>The divider between path elements is '/'. eg &quot;/ram/dir/file&quot;.</P>
  61 <H3>Permissions and attributes</H3>
  62 <P>The following permissions are supported in mode: S_IREAD,
  63 S_IWRITE.</P>
  64 <P>The following opening modes are checked: O_RDONLY, O_WRONLY,
  65 O_RDWR, O_EXCL.</P>
  66 <P>Times are just flat 32-bit numbers. The meaning of these numbers
  67 is OS dependent and is defined by completing the funbctiuon
  68 yaffsfs_CurrentTime() in yaffscfg.c</P>
  69 <P>Attributes are stored as a 32-bit unsigned value. Some of these
  70 are reserved. Others are used transparently (and may be used for
  71 additional information by the application). Reserved are:</P>
  72 <UL>
  73         <LI><P>S_IREAD, S_IWRITE.</P>
  74         <LI><P>S_IFMT, the file type bit-field for S_IFREG, S_IFDIR and
  75         S_IFLNK.</P>
  76 </UL>
  77 <P><BR><BR>
  78 </P>
  79 <H3>Threading</H3>
  80 <P>All yaffs routines are thread safe when called through the
  81 specified interface.</P>
  82 <P>All yaffs routines are controlled by a single locking
  83 mutex/semaphore by defining yaffsfs_Lock() and yaffsfs_Unlock() in
  84 yaffscfg.c.
  85 </P>
  86 <P>Thus, only one thread is able to execute yaffs functions at a
  87 time. Most yaffs functions execute quickly, so this generally not a
  88 limitation.</P>
  89 <H3>Compilation Configuration</H3>
  90 <P>Configuration is done in four places:
  91 </P>
  92 <UL>
  93         <LI><P>yaffscfg.c: OS specific functions</P>
  94         <LI><P>yaffscfg.h: Preferably only change YAFFSFS_N_HANDLES, the
  95         number of files that can be simultaneously opened.</P>
  96         <LI><P>yportenv.h: Preferably do not change this.</P>
  97         <LI><P>Compile options. The valid compile options for the YAFFS
  98         direct interface are:</P>
  99         <LI><P>CONFIG_YAFFS_DIRECT must be enabled to use the direct
 100         interface.</P>
 101         <LI><P>CONFIG_YAFFS_SHORT_NAMES_IN_RAM define to enable short name
 102         caching. This is suggested in cases unless RAM is very limited.</P>
 103 </UL>
 104 <H3>Device Configuration</H3>
 105 <P>The device configuration table is set up in yaffscfg.c and
 106 specifies what devices are in the system. The order is important
 107 since this is the order that is used when searching for
 108 files/directories and provides the &quot;switch&quot; mechanism to
 109 support multiple &quot;mount points&quot;</P>
 110 <P>The device configuration has the form:</P>
 111 <P STYLE="margin-left: 2cm"><FONT FACE="Courier, monospace">struct {
 112 <BR>const char *prefix;<BR>yaffs_Device *dev;<BR>};</FONT></P>
 113 <P>eg.</P>
 114 <P STYLE="margin-left: 2cm"><FONT FACE="Courier, monospace">{<BR>{&quot;/ram&quot;,ramDevice},
 115 <BR>{&quot;/boot&quot;,bootDevice},<BR>{&quot;/flash&quot;,flashDevice},<BR>{NULL,NULL}<BR>}</FONT></P>
 116 <P>Note that multiple yaffs_Devices can share a single physical NAND
 117 device by &quot;partitioning&quot;. Thus, for instance, /boot and
 118 /data may be on the same physical device, just with non-overlapping
 119 regions.</P>
 120 <P>Different properties may be attached to the different yaffs_Device
 121 entries. For example note that the RAM disk is set up with different
 122 NANDECC flags.</P>
 123 <H4>API Notes</H4>
 124 <P>int yaffs_open(const char *path, int oflag, int mode) ;</P>
 125 <P>Supported flags O_CREAT, O_EXCL, O_TRUNC, O_APPEND, O_RDONLY,
 126 O_RDWR, O_WRONLY.</P>
 127 <P>int yaffs_read(int fd, void *buf, unsigned int nbyte) ;</P>
 128 <P>int yaffs_write(int fd, const void *buf, unsigned int nbyte) ;</P>
 129 <P>int yaffs_close(int fd) ;</P>
 130 <P>off_t yaffs_lseek(int fd, off_t offset, int whence) ;</P>
 131 <P>int yaffs_unlink(const char *path) ;</P>
 132 <P>int yaffs_rename(const char *old, const char *new) ;</P>
 133 <P>int yaffs_stat(const char *path, struct stat *buf) ;</P>
 134 <P>int yaffs_lstat(const char *path, struct stat *buf) ;</P>
 135 <P>int yaffs_fstat(int fd, struct, struct stat *buf) ;</P>
 136 <P>int yaffs_chmod(const char *path, mode_t mode) ;</P>
 137 <P>int yaffs_fchmod(int fd, struct, mode_t mode) ;</P>
 138 <P>int yaffs_mkdir(const char *path, mode_t mode) ;</P>
 139 <P>int yaffs_rmdir(const char *path) ;</P>
 140 <P>yaffs_DIR *yaffs_opendir(const char *dirname) ;</P>
 141 <P>struct yaffs_dirent *yaffs_readdir(yaffs_DIR *dirp) ;</P>
 142 <P>void yaffs_rewinddir(yaffs_DIR *dirp) ;</P>
 143 <P>int yaffs_closedir(yaffs_DIR *dirp) ;</P>
 144 <P>int yaffs_mount(const char *path) ;</P>
 145 <P>int yaffs_unmount(const char *path) ;</P>
 146 <P>int yaffs_symlink(const char *oldpath, const char *newpath);
 147 </P>
 148 <P>int yaffs_readlink(const char *path, char *buf, size_t bufsiz);
 149 </P>
 150 <P>int yaffs_link(const char *oldpath, const char *newpath);
 151 </P>
 152 <P>int yaffs_mknod(const char *pathname, mode_t mode, dev_t dev);</P>
 153 <P>off_t yaffs_freespace(const char *path);</P>
 154 <H3><BR><BR>
 155 </H3>
 156 <P>$Id: yaffs_direct.html,v 1.1 2003-01-21 03:34:12 charles Exp $</P>
 157 <P><BR><BR>
 158 </P>
 159 </BODY>
 160 </HTML>