 yaffs direct interface yaffs direct interface admin 23 july 2012 1237am yaffsdirectpdf this document describes the yaffs direct interface ydi which allows yaffs to be simply integrated with embedded systems with or without an rtos 1 background the purpose of this document is to describe the interfacing of the yaffs direct interface ydi as well as to provide sufficient information to allow a preliminary evaluation of yaffs this document tries to focus on the issues important to the system integrator without getting too detailed about how yaffs works other documents provide an indepth discussion of how yaffs works 2 licensing yaffs was originally released for linux under the gnu public license gpl various embedded developers soon identified that yaffs would be ideal for their applications but were not able to use gpl based code in their systems aleph one has alternative licensing arrangements to support such applications 3 what are yaffs and yaffs direct interface  yaffs stands for yet another flash file system  yaffs was the first file system designed from the ground up for nand storage in 2002 aleph one set out to identify file system options for using nand flash as a file system various file systems available at the time were evaluated and all were found lacking in one way or another the need for a suitable nand storage file system was identified and yaffs was designed to fill that need although yaffs was originally designed for nand flash it has been used successfully with nor flash systems and even as a ram file system this allows high reliability file systems to be constructed using nor flash with a future migration path to nand flash for higher density and performance yaffs was originally designed for use with the linux operating system but was designed in a very modular way the operatingsystemspecific code was kept separate from the main yaffs file system code this allows yaffs to be ported quite cleanly to other operating systems through operating system personality modules one such personality module is the yaffs direct interface ydi which allows yaffs to be simply integrated with embedded systems with or without an rtos yaffs has been used for many products using various operating systems including windows ce and various rtoss including threadx vxworks psos to name just a few note that there is a native port of yaffs to ecos that does not use ydi this is supported and distributed by ecoccentric http wwwecoscentriccom yaffs2 a more recent release of yaffs supports a wider range of nand flash components including 2k page devices and devices with multilevel cells mlc and produces equivalent or better performance it include yaffs1 compatibility code so yaffs1 images still work and migration is quite simple yaffs1 or yaffs2 mode of operation are simply selected by a runtime parameter as well as providing a nand file system ydi also provides a ram emulation layer to allow yaffs to operate as a ram file system too while the ram emulation is perhaps not as efficient as a dedicated ram file system this does allow one well proven file system to use both ram and flash 4 why use yaffs  yaffs is the first and perhaps only file system designed specifically for nand flash this means that yaffs has been designed to work around the various limitations and quirks of nand flash as well as exploit the various features of nand to achieve an effective file system some features to consider yaffs has been well proven and has been used to ship in large volumes in several products using many different operating systems compilers and processors yaffs is written in portable c and is endian neutral yaffs provides bad block handling and ecc algorithms to handle deficiencies in nand flash yaffs is a logstructured file system which makes it very robust to corruptions caused by power failures etc yaffs has highly optimised and predictable garbage collection strategies this makes it high performance and very deterministic when compared with similar file systems yaffs has a lower memory footprint than most other logstructured flash file systems yaffs provides a wide range of posixstyle file system support including directories symbolic and hard links etc through standard file system interface calls yaffs is h ighly configurable to work with various flash geometries various ecc options caching options etc yaffs direct interface is simple to integrate in a system only a few interface functions are required yaffs can be used with a wide range of memory technologies 5 source code and yaffs resources please note the licensing terms that apply to using the yaffs code http wwwyaffsnet serves as the hub for all yaffs information this document refers to the yaffs source code extensively and is available via the download link on this site there are various other documents and a yaffs mailing list for yaffs discussions consulting services are also available 6 system requirements determining minimum system requirements is often quite difficult the following are presented as a guideline only contact aleph one for more detailed analysis if required yaffs is endianneutral and works fine with littleendian and bigendian processors yaffs code has been used successfully with many different 32bit and 64bit cpus including mips 68000 arm coldfire powerpc and x86 variants yaffs has even been used with various dsp architectures yaffs should work with 16bit cpus too but this is generally untested and might need some tuning depending on compiler options because yaffs is log structured ram is required to build up runtime data structures for acceptable performance as a rule of thumb budget approximately 2 bytes per chunk of nand flash where a chunk is typically one page of nand for nand with 512byte pages budget approximately 4kbytes of ram per 1mbyte of nand for 2kbyte page devices budget approximately 1kbyte per 1mbyte of nand 7 how to integrate yaffs with an rtos embedded system yaffs direct interface ydi wraps yaffs in a way that is simple to integrate you need to provide a few functions for yaffs to use to talk to your hardware and rtos yaffs provides a set of posixcompliant functions for applications to use to talk to it in addition to the yaffs core file system the ydi has three parts which are each explained in more detail in further sections  posix application interface  this is the posixlike interface that the application code uses to access the yaffs file system  open close read write  etc  rtos integration interface  these are the functions that must be provided for yaffs to access the rtos system resources  initialise lock unlock get time  memory allocation  set error  etc  note that although we use the term rtos the same can be done with other oss or even with no rtos at all in a baremetal system flash device interface  this interface support is where the flash device and appropriate device drivers are installed to provide an access path from yaffs to the flash device s multiple different devices and device types can be supported simultaneously 71 source files the following source files contain the core file system yaffsallocatorc allocates yaffs object and tnode structures yaffsbitmapc block and chunk bitmap handling code yaffscheckpointrwc streamer for writing checkpoint data yaffseccc 1bit hamming ecc code yaffsgutsc the major yaffs algorithms yaffsnamevalc name value code for handling extended attributes xattr yaffsnandc flash interfacing abstraction yaffspackedtags1c yaffspackedtags2c tags packing code yaffssummaryc code for handling block summaries yaffstagscompatc tags compatibility code to support yaffs1 mode yaffstagsmarshallc tags marshalling code yaffsverifyc test verification code yaffsyaffs1c yaffs1mode specific code yaffsyaffs2c yaffs2mode specific code the yaffs direct interface is in yaffsfsc with the interface functions and structures defined in yaffsfdh yaffsattribsc attribute handling yaffserrorc error reporting code yaffsfsc yaffs direct interface wrapper code yaffshweightc counts the number of hot bits in a byte word etc yaffsqsortc qsort used during yaffs2 scanning example flash drivers simulators and configurations used for testing are are in direct testframework directory these include nanddrvc a nand driver layer that performs the commands to access nand flash in a rudimentary manner this code should work on many styles of cpu with little modification yaffsnanddrvc a wrapper around the nand driver which plugs it into yaffs nandsimc a nand simulator layer that works with a nandstorexxx backing store this simulates a nand chip nandstorefilec a storage backend for a nand simulator that stores the data to file nandsimfilec a wrapper around nandsimc and nandstorefilec which makes a nand simulator that saves its data in a file yaffsnandsimfilec a wrapper which creates a nand simulator instance hooks up the yaffs nand driver and then adds it to yaffs for use yaffsnordrvc yaffsm18drvc a driver for intel m18style nor flash yaffsosgluec an os glue layer example used in the test harness example and testing build files dtestc a test harness also has sample code that can be used for better understanding of how some function calls work yaffscfg2kc a test configuration yaffsfileemc yaffsfileem2kc nand flash simulation using a file as backing store further testing files are in direct tests and direct python 72 integrating the posix application interface the application interface is defined in yaffsfsh these provide a posix file system interface for the most part this interface consists of the standard clib function names prefixed with yaffs for example yaffsopen yaffsclose etc there is a lot of flexibility in how these functions are used and the system integrator needs to determine the best strategy for the system these functions can be used directly with the code written using these names for example int main initialisation f yaffsopen yaffsread f yaffsclose f the yaffs functions can also be wrapped in some way to allow existing code to use yaffs without modification for example define open path oflag mode yaffsopen path oflag mode int main initialisation f open read f close f a more complex approach that can be used if more than one filesystem is used is to provide redirection functions for example int open const char path determine which file system is being used i f itisayaffspath path return yaffsopen else do something else some rtos s provide a flexible way to integrate file systems in which case ydi can typically use these interfaces to access yaffs file systems 8 rtos integration interface before yaffs can be used it needs to be integrated with the system and configured so that the correct actions are performed to do this you need to modify the configuration file an example configuration file is presented in yaffscfgc and yaffscfg2kc this is a relatively straight forward process and defines the rtos access functions the rtos access functions are void yaffsfsseterror int err called by yaffs to set the system error void yaffsfslock void called by yaffs to lock yaffs from multithreaded access void yaffsfsunlock void called by yaffs to unlock yaffs u32 yaffsfscurrenttime void get current time from rtos void yaffsfsmalloc sizet size   called to allocate memory void yaffsfsfree void ptr   called to free memory void yaffsfs os initialisation void called to initialise rtos context void yaffsbugfn const char filename int lineno   function to report a bug int yaffsfscheckmemregion const void addr sizet size int writ erequest  function to check if accesses to a memory region is valid this function must return zero if the test passes and negative if it fails if yaffs is being used in a multithreaded environment then typically yaffslocalinitialisation will initialise a suitable rtos semaphore and yaffslock and yaffsunlock will call the appropriate functions to lock and release the semaphore yaffscurrenttime can be any time increment of use to the system if this is not required then it is fine to just use a function that is hardwired to return zero before the application code uses yaffs the yaffs fs osinitialisation function must be called yaffsfscheckmemregion  is used to check addresses passed to the various yaffsxxx functions yaffsopen yaffsread etc if the function returns 1 then the yaffsxxx function will return efault rather than attempt to dereference the address and crash an implementation might do something like  int yaffsfscheckmemregion const void addr sizet size int write request  u32 uaddr b  u32 addr  u32 uaddrt uaddrb size 1  if uaddr b  stackbottom uaddr b  stacktop  uaddrt stackbottom uaddrt stacktop return   r w access is ok  if uaddr b   heap bottom uaddr b   heap top  uaddrt heapbottom uaddrt heaptop return   r w access is ok  if  writerequest  uaddr b   rom bottom uaddr b   rom top  uaddrt rombottom uaddrt romtop return   read access is ok  return 1 bad access    9 yaffs nand model before defining the flash integration interface it is important to understand the model and corresponding nomenclature used throughout yaffs and its documentation yaffs uses a fairly abstract model for nand flash this allows a lot of flexibility in the way it can be used yaffs is designed for nand flash and makes the following assumptions and definitions the flash is arranged in blocks  each block is the same size and comprises an integer number of chunks each block is treated as a single erasable item a block contains a number of chunks a chunk equates to the allocation units of flash for yaffs1 each chunk equates to a 512byte or larger nand page that is a 512byte or larger data portion and a 16byte spare area for yaffs2 a chunk will typically be larger eg on 2k page devices a chunk will typically be a single 2k page 2kbytes of data and 64 bytes of spare yaffs2 is capable of working with smaller chunk sizes by using inband tags all accesses reads and writes are page chunk aligned some reads might only read the spare area where the tags are kept when programming a nand flash only the zero bits in the pattern being programmed are relevant and one bits are don t care for example if a byte already contains the binary pattern b1010 then programming b1001 will result in the pattern which is the logical and of these two patterns ie b1000 this is different to nor flash which would typically abort the attempt to convert a  into a 1 yaffs ide ntifies blocks by their block number and chunks by the chunk id a chunk id is calculated as chunkid blockid chunksperblock chunkoffsetinblock yaffs treats a blank 0xff filled block as being free or erased thus the equivalent of formatting for a yaffs partition is to erase all the blocks that are not bad yaffs2 has a generalised tags interface to provide better flexibility to cater for a wider range of devices with larger pages and stricter programming limitations yaffs2 thus handles more abstract constructs than yaffs1 and in older versions of yaffs more effort was required to interface to the nand in newer versions of yaffs the tags management has been abstracted out of the driver this makes the driver interface far simpler 91 formatting yaffs treats erased blocks as empty that makes it really easy to format a device just erase it note that this should be done while the partition is not mounted unmounting will not normally work when the file system is busy eg files are open some extra nonstandard unmount options are provided to enable an unmount to be forced note that using these will break any current handles and you will no longer be able to use open files there is a yaffsformat  function that will take care of the details 92 nand model considerations for yaffs1 the historical yaffs1 tags structure was laid out in accordance with the smartmedia specification for use with 512byte pages there is now much more flexibility in the way things can be configured yaffs1 is capable of being used with a variety of memory layouts so long as the flash supports the ability to overwrite the tags area to set the deletion marker to zero if the yaffsdev s usenandecc field is not set then yaffs will perform the ecc calculations if this is set then yaffs will expect the nand driver to do any required ecc checks on devices that are not using ecc for example nor set usenandecc 1 and then don t do any ecc anyway the yaffs1 flash model expects an area of 16 spare bytes some of which are used for tags the mapping between the spare bytes and the usage of the bytes is specified in yaffspackedtags1c the yaffs1 model has been used in many norbased systems one particularly instructive example is in yaffsnordrvc which implements a driver for yaffs1 mode on cfistyle nor flash this does not use ecc but uses checksumming instead the yaffsdev structure has a yaffsdriver structure which holds the function pointers to the driver for yaffs1 mode of operations the following are required drvwritechunkfn write a data chunk drvreadchunkfn read a data chunk drverasefn erase a block drvinitialisefn initialisation drvdeinitialisefn deinitialise these functions are described later 93 nand model for yaffs2 the yaffs2 interface is far more flexible than yaffs1 but that means a bit more effort must be done in the driver in particular there is is no standard spare area ecc layout the driver must handle all the layout of the spare area and ecc handling there is not a standard implementation for bad block markers thus the driver must provide functions for checking and marking bad blocks the yaffsdriver structure for yaffs2 mode requires the following functions drvwritechunkfn write a data chunk drvreadchunkfn read a data chunk drverasefn erase a block drvmarkbadfn mark a block bad drvcheckbadfn check bad block status of a block drvinitialisefn initialisation drvdeinitialisefn deinitialise 94 overview of flash driver function the best way to understand how to write these functions is to look at the example drivers int drvwritechunkfn struct yaffsdev dev int nandchunk const u8 data int datalen const u8 oob int ooblen this function writes the specified chunk data and oob spare data to flash this function should return yaffsok on success or yaffsfail on failure if this is a yaffs2 device or yaffs1 with usenandecc set then this function must take care of any ecc that is required int drvreadchunkfn struct yaffsdev dev int nandchunk u8 data int datalen u8 oob int ooblen enum yaffseccresult eccresult this function reads the specified chunk data and oob spare data from flash this function should return yaffsok on success or yaffsfail on failure if this is a yaffs2 device or yaffs1 with usenandecc set then this function must take care of any ecc that is required and set the eccresult int drverasefn struct yaffsdev dev int blockno this function erases the specified block this function should return yaffsok on success or yaffsfail on failure int drvmarkbadfn struct yaffsdev dev int blockno int drvcheckbadfn struct yaffsdev dev int blockno these functions are only required for yaffs2 mode they mark a block bad or check if it is bad int drvinitialisefn struct yaffsdev dev int drvdeinitialisefn struct yaffsdev dev these functions provide hooks for initialising or deinitialising the flash driver 10 configuration and flash driver installation for an example of how to do the configuration refer to yaffscfg2kc and one of the drivers such as yaffsnanddrvc the old mechanism was static and required a table of devices that was installed at start up this mechanism had shortcomings in particular it broke modularity and did not allow devices to be added dynamically things are different now as any time a yaffsdev structure can be configured and then registered with yaffs by using the yaffsadddevice function a yaffsdev structure has two parts which must be configured before yaffsadddevice is called the paramers dev param and the driver dev drv the driver configuration plugging in the driver functions has already been described above so we will now look at the yaffs parameters the yaffsparam structure must be set before the yaffsdev is added with yaffsadddevice and should not be modified after that the params are defined in the yaffs tuning document 11 using the posix file system interface this section is directed to readers that might not be very familiar with accessing a file system via posix and posixlike interfaces 111 difference to windows posixlike interfaces msdos and windows provide a posixlke interface if you are familiar with this then that will help you there are are however some slight differences most importantly windows has no concept of links and has a 11 mapping between file names and filesposix supports files with zero one or many names refer to the sections on linking and unlinking files for instance posix allows you to unlink a file ie delete the name for a file while it is still in use you can continue to read write the file but it will be deleted as soon as the last file handle to the file is closed windows on the other hand does not allow you to unlink a file while it is in use windows names drives with a letter posix has no drive letters the whole posix file system is in a single directory tree directories and folders are the same thing 112 fundamental concepts file a file is an object that is stored in the file system yaffs supports the following file types a regular file is a sequence of bytes stored in the file system a directory holds links to other files a symbolic link holds a name to another file a special file holds device ids or similar information directory this is a structure that holds links and allows a file to be found by name note that a single file may have many links ie names and many be found in many places in the directory structure link this is a name that allows the file to be found there are two types of link real links sometimes called hard links and symbolic or soft links handle a file handle provides a context from which a file can be accessed and manipulated a handle has a current file position pointer which points to where the file is being read or written multiple handles can simultaneously access a single file file mode the mode is the set of flags that define the type of file as well as the current permissions associated with the file path this is a string that defines the directories and file name for example data direct1 file1 file metadata this is the information about the file excluding the file contents the metadata includes the name mode size and other details mount partition file system these terms all refer to a single mounted flash area each mount is hooked into a common directory structure the term file system can sometimes be confusing because it is used both for a single mounted partition as well as the the file system code in other words we might say that both boot is a file system and might also say that yaffs is a file system inode number the inode number is a unique number that identifies the object within the mount note that inodes are not unique between two or more mounts there is no way to reach a file by inode only via its links 113 error code most functions result in error codes if the function does not execute successfully in these cases yaffs calls a function called yaffsseterror with the error value this function can be configured to deliver the error into the system s error mechanism in the case of functions that return integers a returned value smaller than  indicates an error occurred functions returning pointers will return null if an error occurred 114 links the hard kind not symbolic links  at first we re just considering real links and not symbolic links sometimes real links are also called hard links to differentiate them from symbolic links which are sometimes called soft links the difference between links and files is subtle and can be confusing briefly a file is the stored object in the file system the link is how it is hooked into the directory structure the first link to a file is created by using the file creation calls yaffsopen yaffsmknod yaffssymlink and yaffsmkdir a link can be destroyed by using the yaffsunlink function directories are destroyed using the yaffsrmdir function oh and the directory must be empty once a file is both unused there are no handles open to it and there are no links to it it is then deleted a link can be renamed by using the yaffsrename function a file may have many links these may be created using the yaffslink function all the links access the same file and there is no one link that is considered the real link and others being the duplicate link all links to a file have the same priority if you look at the inode number for a and for b then they will be the same because they are refering to exactly the same file thus if we start with a file called a and then call yaffslink a b we now have two links to the same file we can t tell them apart if we now unlink a the file still exists under the link b if we now unlink b the file will no longer be linked if there is a handle open to the file then we can still access the file through the handle and continue to read or modify the file if there is no link to the file it is deleted if an unlinked file was kept alive because of a handle being open the file will not show up in the directory structure because it has no link and will be deleted as soon as the handle is closed or if the file system is unmounted there are some limitations in how links are used the existing file you are linking to must exist the file you are linking to must be in the same mount partition as the link you are creating you cannot create a link to a directory because this would allow the creation of recursive loops the new link name must not exist 115 symbolic links now that you understand how hard links work we ll introduce symbolic or soft links a symbolic link holds an alias for a different object when you use that symbolic link in a path the alias is used instead to that extent symbolic link and hard links are the same you can remove symbolic links with the yaffsunlink function just like hard links there are however some important differences a symbolic link only does its linking function when the path is being evaluated and thus the file you are creating an alias to does not have to exist the file you are creating an alias to does not have to be in the same mount you can create symbolic links to directories a symbolic link will not keep a file alive by itself only a hard link can do that thus if we start with a file called a and then call yaffssymlink a b we now have one link to the file called a and a symbolic link aliasising from b to a if we use yaffsopen a or yaffsopen b they will open the same file the path resolution mechanism substitutes in the alias and so will look up a the same applies to almost all functions that takes a path such as yaffstruncate yaffsstat etc the only exceptions are yaffslstat and yaffsreadlink which will treat the path as pointing to the symbolic link and not the file you can tell a and b apart by using yaffslstat yaffslstat a will show the information for file a yaffslstat b will show the information for the symbolic link itself note the difference with hard links with hard links yaffslstat a and yaffslstat b would show the same results since they are exactly the same thing being referenced if we now unlink a then the file is no longer linked and will no longer be accessible from b note the difference with hard links 116 handlebased file handling a handle is file accessor that allows us to access the contents of a regular file the handle identifies the file being accessed as well as a position pointer tracking where the next read or write operation will take place a handle is identified by an integer of value  or greater a handle is created by using the yaffsopen call and returns the handle value if the handle could not be created then a negative value is returned and the yaffs error code is set a handle remains valid until the handle is closed by yaffsclose the yaffsopen call takes three parameters name full path name of the file being opened access flags flags being used to open this handle creation mode mode flags used when creating a file the access flags are one or more of ocreat create file if it does not already exist oexcl only use with ocreat create file if it does not exist if the file already exists then fail otrunc if the file exists and opening with write access then truncate the file to zero bytes long oappend regardless of the handle position always write to the end of the file ordwr open for read write access owronly open for write access and no read access  zero  if neither ordwr or owronly is set then the file will be opened for readonly access where they are not mutually exclusive these flags are typically combined for example ocreat otrunc ordwr create a new file if it does not exist otherwise if the file already exists then truncate to zero length typically used to overwrite a file or create if it does not already exist ocreat oexcl owronly create a new file opening it for write only fails if file already exists there are three mode flags that can be controlled or set these flags may be set by the open that creates the file or later by the yaffschmod siread the file may be opened for read access siwrite the file may be opened for write access siexec the file may be opened for execution this is not enforced by yaffs once you have opened a handle you can then do various operations on the file yaffsclose handle close the handle it is no longer usable yaffsfsync handle flush out any cached writes to the file as well as the file metadata yaffsdatasync handle same as yaffsfsync but no file metadata yaffsflush handle same as yaffsfsync yaffsdup handle duplicates a handle yaffslseek handle offset whence set the handle read write position note that this does not modify the file you can seek past the end of the file this does not modify the file size yaffsftruncate handle size change the file size it can be made bigger or smaller this does not change the handle read write position yaffsfstat handle buf get file status yaffsfchmod handle mode change the file mode yaffsread handle buffer nbytes read data from file at file pointer and update pointer yaffspread handle buffer nbytes position read data from file at specified position does not modify file pointer yaffswrite handle buffer nbytes write data to file at file pointer and update pointer yaffspread handle buffer nbytes position write data to file at specified position does not modify file pointer 117 changing file size yaffstruncate path newsize yaffsftruncate handle newsize these change a file s size note that truncating does not just mean make the file smaller the file can also be made larger yaffs does not store bytes that it does not need to if you use truncate to make a file larger then this will not necessarily occupt more flash space see also yaffslseek too note that yaffslseek only changes the position of the write pointer and does not impact on the file size unless the file is written 118 getting setting information about files yaffschmod path mode yaffsfchmod handle mode yaffsaccess path amode yaffsstat path struct yaffsstat buf yaffsfstat handle struct yaffsstat buf yaffslstat path struct yaffsstat buf yaffsreadlink path buf bufsize the chmod calls allow you to set different mode flags for the file these can only be used to manipulate the permissions flags and not change the mode flags relating to the type of file yaffsaccess tests that the file can be accessed in the specified mode this call returns zero on success and 1 is returned amode is a bitmask of the following values rok check read is ok wok check write is ok xok check execute is ok  zero just checks the file exists these can be combined for example if yaffsaccess path rok wok  the file exists and can be read and written if yaffsaccess path   the file exists the stat calls retrieve a yaffsstat structure of data which is defined in yaffsfsh there are three versions yaffsfstat takes a handle yaffsstat takes a path name and follows symbolic links yaffslstat takes a path but does not follow symbolic links thus if path is a symbolic link yaffsfstat will give information on the file that the link points to while yaffslstat will give information about the link itself yaffsreadlink will read the read the link value into the buffer provided for example yaffssymlink target link create a link called link to target yaffsreadlink link buffer 10 now buffer contains target  119 changing the directory structure and names yaffsopen path flags mode yaffsmkdir path mode yaffssymlink targetpath linkpath yaffsmknod pathname mode dev yaffslink existingpath newath yaffsunlink path yaffsrmdir path yaffsrename oldpath newpath files of various types and their first link are created via the yaffsopen yaffsmkdir yaffssymlink and yaffsmknod functions yaffslink can be used to create subsequent links to files note that you cannot create a link to a directory yaffsrename allows you to rename a link note that renaming one link over another link is an atomic operation that means that even if the operation is interrupted by a power failure the result will either complete or not happen at all if the target link is for a directory then the rename will only work if the target directory is empty 1110 searching directories yaffsdir yaffsopendir const ychar dirname struct yaffsdirent yaffsreaddir yaffsdir dirp void yaffsrewinddir yaffsdir dirp int yaffsclosedir yaffsdir dirp searching is performed by the following sequence of operations open the directory for reading with yaffsopendir iterate through the entries in the directory using yaffsreaddir each read will advance the directory read position you can reset to the start of the directory with yaffsrewinddir close the directory when finished with yaffsclosedir  1111 searching directories fd interface  int yaffsopen const ychar dirname ordonly  struct yaffsdirent yaffsreaddir fd int fd void yaffsrewinddir fd int fd int yaffsclose int fd this is not a posix interface but provides an alternate interface for reading directories searching is performed by the following sequence of operations open the directory for reading with yaffsopen name ordonly  iterate through the entries in the directory using yaffsreaddir fd each read will advance the directory read position you can reset to the start of the directory with yaffsrewinddir fd close the directory when finished with yaffsclose  1112 mount control and similar yaffsmount path yaffsmount2 path readonly yaffsunmount path yaffsunmount2 path int force yaffsremount path force readonly yaffssync path yaffsformat const ychar path int unmountflag int forceunmountflag int remountflag a partition must be mounted to be accessed yaffsmount will mount the partition for read write access yaffsmount2 can be used to control whether the access is read write or read only a partition can be unmounted to remove it from use yaffsunmount will fail if any files are in use whereas yaffsunmount2 allows you to force the unmount even if files are open note that any file handles will then be broken and will no longer access the files yaffsremount can be used to change the access to a currently mounted partition and is equivalent to making an unmount2 call followed by a mount2 call yaffssync does not change the mount status but flushes out any pending data on a partition that is mounted with write access yaffsformat  provides a mechanism to format a device it has various parameters unmountflag  if set yaffsformat will unmount the device before formatting if this flag is not set and the device is mounted then the format will fail with ebusy forceunmount  if set then an unmount is allowed even if the device is busy eg files open if not set then yaffsformat will fail ebusy if files are open remountflag  if set then the device will be remounted after the format if it was mounted the forceunmount and remountflag options only have meaning if unmountflag is set 1113 extended attributes xattrt  extended attributes provide a mechanism to attach a limited amount of extra data to a file without actually modifying the file each xattribute is a named pair of name and some data each file can have as many xattribs as there is space for in yaffs this is around chunksize 512 bytes so on devices with 2kbyte chunks you can store up to 15kbytes of xattribute information although there are 12 xattr functions there are really only four basic functions each with 3 different flavours the basic functions are set an xattr get an xattr remove an xattribute and list the xattribute names int yaffssetxattr const char path const char name const void data int size int flags int yaffslsetxattr const char path const char name const void data int size int flags int yaffsfsetxattr int fd const char name const void data int size int flags these functions are called with name being the name of the xattr a pointer to the data and the size of the data and flags the flags are xattrcreate create a new xattr fail with eexist if the xattrib already exists xattrreplace replace an existing xattr fail with enoattr if it does not exist zero just create with no checks replace if it already exists setting can fail with enospc if there is not enough space to store the xattrib int yaffsgetxattr const char path const char name void data int size int yaffslgetxattr const char path const char name void data int size int yaffsfgetxattr int fd const char name void data int size these get fetch an xattrib if the call succeeds the length of the retrieved xattrib is returned this call can fail with enoattr if the requested xattr does not exist or erange if the buffer was too small int yaffsremovexattr const char path const char name int yaffslremovexattr const char path const char name int yaffsfremovexattr int fd const char name these functions delete an existing xattr if the xattr does not exist then enoattr is returned int yaffslistxattr const char path char list int size int yaffsllistxattr const char path char list int size int yaffsflistxattr int fd char list int size these functions fetch a list of the xattrib names into the list buffer the names are nul terminated eg attrib00attrib10 the function returns the length of the list otherwise if the list buffer is too short it returns erange note if you call these functions with a list buffer size of zero this acts as a query of the required buffer size no data is actually transferred into the list for example we might choose to add some xattribs to a media file set description yaffsfsetxattr fd usercomment i hate this song 18 yaffsfsetxattr fd priceincents cost sizeof cost get the comment yaffsfgetxattr fd usercomment buffer sizeof buffer list the attributes in a nul delimited list yaffsflistxattr fd listbuf sizeof listbuf now listbuf has usercomment 0priceincents  yaffsfremovexattr fd usercomment  1114 other yaffsfreespace path yaffstotalspace path yaffsinodecount path these functions provide information on the free and total space in bytes for the mount that the path addresses yaffsinodecount returns the number of files on the mount that the path addresses 12 example yaffsreaddir and yaffsstat  this code snippet illustrates using yaffsreaddir and associated functions to iterate through a directory it also shows how to use yaffslstat to get information on a file and interpret it void dumpdirectory const char dname yaffsdir d yaffsdirent de struct yaffsstat s char str 100 d yaffsopendir dname if d printf opendir failed n else while de yaffsreaddir d null sprintf str s s dname de dname yaffslstat str s printf s inode d length d mode x str sstino int sstsize sstmode switch sstmode sifmt case sifreg printf data file break case sifdir printf directory break case siflnk printf symlink if yaffsreadlink str str 100  printf no alias else printf s str break default printf unknown break printf n if sstmode sifmt sifdir dumpdirectorytreeworker str yaffsclosedir d  