Clib_fatfs: C Library to FAT File System Example Application


This application uses the C library file I/O functions to perform file 
I/O on either a USB flash drive, an SD/MMC flash card or a Compact Flash
storage card.  

The C library interfaces with HCC Embedded's FAT file system to access a
USB Flash drive.  The following C library functions are used in the 
application:

mkdir()
fopen()
fclose()
fread()
fwrite()
fseek()
remove()

Three #define constants are used to selectively enable access to the three
types of storage devices.  Only one of these three types of storage devices
can be accessed at a time.

If the USE_SPI_MMC_DEVICES constant is set to 1, access to SPI based SD/MMC storage
devices is enabled.  There are #define constants that are used to select
the board type.  These constants are NS9750_TEASER_BOARD, NS9360_DEVl_BOARD
and NS9360_CONNECTCORE9C_BOARD.  Set one constant to 1 to run the application
on the respective board.  Do not set multiple constants to 1.

Since the SPI SD/MMC protocol driver uses the "simple" SPI API, the user
must specify in a NASpiDeviceConfigType structure all the relevant SPI
configuration parameters including port number, SPI mode, bit-rate, CS 
select/deselect functions and the SPI device name.  For the CS select and
deselect functions, the user must specify the GPIO pins used to enable or
disable to SPI device's CS line.

For a NS9750 Teaser board, GPIO pins 42, 43 and 7 are used for the SPI
multiplexer.  Refer to the NS9750 Teaser board schematics for more info.
For a NS9360 development board, GPIO pins 2, 3 and 7 are used for the SPI
multiplexer.  Refer to the NS9360 Teaser board schematics for more info.
For a NS9360 ConnectCore9C board, GPIO pins 16, 18 and 7 are used for the SPI
multiplexer.  Refer to the NS9360 ConnectCore9C board schematics for more info.
For other boards that feature an SPI based SD/MMC interface, you must
refer to the board schematics for info on which GPIO pins are used to
enable or disable the SPI device's CS line.

To enable SPI, the following changes are required:

For other processors:
- BSP_SERIAL_PORT_2 must be defined as BSP_SERIAL_SPI_DRIVER in bsp_serial.h.
- BSP_GPIO_MUX_SERIAL_B must be defined as BSP_GPIO_MUX_SERIAL_SPI_APP 
  in gpio.h.

If the USE_CF_DEVICES constant is set to 1, access to Compact Flash 
storage devices is enabled.  The current compact flash driver supports 
memory mode to access storage devices.  The user must specify in a 
CF_CONFIG structure all the relevant compact flash configuration parameters
including transfer mode, chip select base address, attribute memory address,
common memory base address, I/O mode address and IDE mode address.  

For NS9360 development board, use the following in the CF_CONF structure.

- tranfer_mode is CF_MEMORY_MODE
- cs_base_address is 0x03100000
- attribute_base_address is 0x200
- common_base_address is 0x800

The following changes are required to enable CF on the NS9360 development boards:

- Use the following setup on JUMPER_2:

                A  B  C
            1   o  ====
            2   o  ====
            3   o  ====
            4   o  ====
            5   o  ====
            6   ====  o
            7   ====  o
            8   ====  o

If the USE_USB_DEVICES constant is set to 1, access to USB storage devices
is enabled.  When this constant is 1, the ENABLE_EVENT_NOTIFICATION
constant is used.

If the ENABLE_EVENT_NOTIFICATION constant is set to 1, the user thread
waits indefinitely on a tx_event_flags_get() until a USB flash drive is
connencted and the USB mass storage driver sets the relevent event
flag to indicate that a specific FAT32 volume has been created.  Once 
tx_event_flags_get() returns without error, the user threads performs
its write and read tests.

If the ENABLE_EVENT_NOTIFICATION constant is set to 0, the user thread
polls the FAT32 file system using two functions, f_get_volume_count()
and f_get_volume_list(), to check for the available FAT32 volumes.  Once
the relevant FAT32 volume is detected, each user thread performs its 
write and read tests.

If the USE_SDIO_SD_DEVICES constant is set to 1, access to SDIO bus based
SD cards is enabled.  This option can be selected only for platforms based
on the NS9215 and NS9210 processors.  You must set BSP_INCLUDE_SDIO_DRIVER
to TRUE in bsp_drivers.h and recompile the BSP to enable the low level
SDIO driver. 

Note:

1)  The mass storage device must be formatted for the FAT file system.
    Otherwise, the FAT volume cannot be initialized.
2)  The FAT file system library (libfat32.a) in NET+OS is HCC Embedded's
    version 2.62 release.
3)  The PDF version of the FAT file system manual is included in the FAT 
    file system example application in ../src/examples/nafatfs
4)  The C library file I/O functions are implemented in blocking mode
    only.
5)  In the function mkdir(dirname, mode), the mode argument is ignored
    when creating a directory in the FAT file system since no directory
    creation modes are supported by the FAT file system.
6)  In the function fopen(filename, mode), the opened file will be in 
    binary mode only.  fopen(filename, "r"), fopen(filename, "rb") and 
    fopen(filename, "rt") will open the file as a binary file.
7)  The following C library functions are supported: mkdir(), rename(),
    remove(), fopen(), fclose(), fread(), fwrite(), fseek().  For 
    additional functionality, use the FAT file system API functions.
8)  By default, C library support for the FAT file system is NOT enabled
    in the bsp.  You must do the following to enable the C library support 
    for the FAT file system:
      a) Update the file ..\src\bsp\platforms\ns9xxx_a\bsp_fs.h such that 
         BSP_INCLUDE_FAT_FILESYSTEM_FOR_CLIBRARY is set to TRUE
      b) Rebuild the bsp
      c) Rebuild and rerun this application, after insuring that the
         filesys library is linked in via the Makefile
9)  This application will only work on NS9750 and NS9360 boards, since it
    uses USB host hardware.
11) Compact Flash storage devices are supported on the NS9360 development board.
12) SPI based SD/MMC storage devices are supported on the NS9750 Teaser board and
    the NS9360 development board.

End note

As the application executes, it sends status and error messages out 
\com\0 to the console.


One GNU make file is provided.  Build the target 'image' to
generate an image that can be debugged with gdb, and the file 
image.bin which can be written to flash if the bootloader is used.
Build the target 'rom.bin' to create the file rom.bin which 
can be written to ROM if the bootloader is not used.

The following files are provided in this template.

appconf.h         sets application configuration settings
makefile          Make file for the GNU toolset.
readme            this file
root.c            contains the applicationStart() function that starts
                  the example application

In addition, the following files in the BSP directory are built
as part of this application.

reset.s         contains the reset code
appconf_api.c   contains code used to read settings in appconf.h


The application build file links in the following libraries.  Most of these
libraries are not actually used by the application.  They are included because
this application is meant to be used as a template for other applications that
may use these libraries.  The linker only includes the code in libraries that 
is actually used.  


libbsp.a               contains the BSP library
libaddp.a			   contains the ADDP Library
libtcpip.a             contains the TCP/IP stack library
libpppintf.a		   contains the PPP Interface Library
libtx.a                contains the ThreadX kernel
libfilesys.a           contains the Native File System library
libposix.a             contains the POSIX layer library
libflash.a             contains the Flash driver API library
libsdiosd.a            contains the SDIO/SD library
libssh.a			   contains the SSH Library
libtelnsvr.a           contains the Telnet Server library
libdnsclnt.a           contains the DNS Client library
libusbmassstorage.a    contains the USB Mass Storage library
libusbhost.a           contains the USB Host library
libusbhub.a			   contains the USB Hub Library
libfat32.a             contains the FAT32 library
libfatdrvmgr.a         contains the FAT Drive Manager library
libcf.a                contains the Compact Flash library
libspimmc.a            contains the SPI SD/MMC library


The application uses the following files located in the
netos\src\linkerScripts directory.  These files are generated
when the BSP is built.

bootldr.dat     bootloader configuration file used to generate the
                file image.bin.  It controls the information placed
                in the bootloader header of the image.

image.ldr       GNU linker script used to build an image that can
                be debugged and used with the bootloader.

customize.ldr   Customizable GNU linker script

