FatFS for SYS/BIOS

Overview

FatFS is an open source project which has recently been built locally to support SYS/BIOS. The public FatFS web site is http://elm-chan.org/fsw/ff/00index_e.html.

SYS/BIOS support is currently limited to just a RAM disk, although other media can be added in the future. The interface to plug in other media is a simple set of functions that can be bound at link time.

This wiki topic gives a brief overview of the FatFS examples, as well as the FatFs Linux utilities, which are used for creating, saving, and updating RAM disk file system images that can be built into a target executable.

SYS/BIOS Integration

FatFS has been integrated with the TI C compiler's RTS library (fopen(), fread(), fwrite(), etc.). A configurable prefix is used to distinguish the local filesystem from the default/CCS support. For example, to open file1.txt for read permission with the default "fat" prefix, use 'fopen("fat:file1.txt", "r");'.

• We recommend using the C <stdio.h> functions to open/close/read/write files. However, you can also use the lower-level FatFS APIS (e.g. f_mkdir()) directly for those functions not supported by the TI/C RTS library. We may wrap these f_ functions with standard POSIX APIs in a future release. This would allow apps to use standard POSIX APIs with the FatFS for easy portability from/to other environments.

Users add FatFS to their applications by adding "xdc.useModule('ti.sysbios.fatfs.FatFS')" to their configuration script. The FatFS module contains 4 configuration parameters:

• fatfsPrefix -- default "fat" -- this string prefix is used when using TI/RTS fopen() function to distinguish the FatFS filesystem from default CCS/RTS support. Use "fat:filename" to reference filename on FatFS. Use "filename" to reference file via CCS.
• ramdiskSymbolName -- default is "" -- name of C array that contains the serialized RAM disk (serialized as integers). This is an array of integers (not chars!). On 6x and Arm the length of this array is the ramDiskSize/4. This array is typically created using the utilities described below.
• ramdiskSize -- default 512 * 256 -- the size of the ram disk. Size should be multiple of 512. This size MUST match the size of the disk specified in the 'mkImage' FatFS utility below.
• ramdiskDriveId -- default -1 -- the drive ID of the RAM disk or -1 to disable the RAM disk.

FatFS Utilities

FatFS currently has several Windows and Linux utilities which can be used to create and manipulate a RAM disk. Once created and saved, this RAM disk image can be built into a target executable and then mounted on the target at runtime.

For example, this could be useful if you want to make some set of files that are originally built on a local Windows or Linux box available to the target during program execution.

The following utilities are currently available for FatFS for SYS/BIOS. All utilities are found under the directory:

ti/sysbios/fatfs/utils/bin

In addition to the following, each utility also has a usage statement, as well as a description comment in its corresponding .c file.

• mkimage.x86U [filename] [size]
• mkimage.exe [filename] [size]
  • Creates a RAM disk image of size [size] and saves it to the local disk as [filename].
  • 'size' is in decimal and should be a multiple of 512. This size MUST match the size of the 'FatFS.ramdiskSize' specified in the configuration.
  • This utility is the starting point, used to create the intitial image.
  • currently small sizes are not supported. It looks like a bug, but if you start with size = 131072 this will work.

• cptoimage.x86U [image name] [source] [destination]
• cptoimage.exe [image name] [source] [destination]
  • Copies a file from the local HDD and saves it into an existing RAM disk image (created with mkimage).
  • This is used to transfer local files into the RAM disk image, in order to make them available to the target once the RAM disk is mounted at runtime.

• imagetosrc.x86U [image name] [output file name] [symbol name]
• imagetosrc.exe [image name] [output file name] [symbol name]
  • converts an existing RAM disk image into a C source file. The source file will contain an array with name 'symbol name', containing the data of the RAM disk.
  • The C file that is created may then be built into a target application and mounted. The target application must use the ti.sysbios.fatfs.FatFS module in order to set this module's parameter "ramdiskSymbolName" to the same value as 'symbol name' that's passed to this utility. For more info on this, see the file ti/sysbios/fatfs/FatFS.xdc, as well as the FatFS example (in below section).

• lsimage.x86U [image name]
• lsimage.exe [image name]
  • lists the contents of a RAM disk image to stdout.
  • useful to see what's on the image.

• catimagefile.x86U [image name] [file]
• catimagefile.exe [image name] [file]
  • prints out the contents of the text file [file] to stdout.
  • useful to verify contents of a file copied via cptoimage command.

FatFS Utilities

The FatFS example contains 2 parts.

• target code -- CCSv4.2 project/zip file attached to this wiki page. The .cfg file and 2 .c files can be used separately or import the project.
• ti/sysbios/fatfs/utils -- utilities to build the ramimage[] C array.

Script to Create a RAM disk image

Under the utils/examples directory, an example script is found there that does the following:

• This script demonstrates how to use the FatFS Linux utilities to create a RAM disk image, copy 3 target executables into it and then save the image into a C array. The C array can be built into a BIOS application and loaded as a RAM disk, which will allow that app to access the 3 executables stored there.

• Please refer to that script to see how the utils are used to do this. If you are a Windows user, a DOS batch file could easily be created to run the same commands as found in the Linux shell script.

Target App with existing RAM disk image built into it and mounted

• The FatFS example (Media:Fatfs-example.zip) loads an existing RAM disk image that contains 2 text files.
• The example mounts the RAM disk, stored in the file twoFiles_ramdisk.c, then opens these files in Task context, and prints out the contents of each.
• See the configuration in fattest1.cfg, specifically the value of ramdiskSymbolName.
• Notice that the value of ramdiskSymbolName is "ramDiskArray" - the same as the array name in twoFiles_ramdisk.c
• This example could easily be modified to load a ramdisk that contains target executables, created from the script in the utils/tests directory.