AVR 8-bit Microcontrollers

AVR42776: Using the Petit FAT File System

Module with AVR

APPLICATION NOTE

Features
• SDC/MMC file system access with limited memory consumption
® ®
• Device independent, ideal for Atmel AVR applications requiring
optimized memory usage
• FAT12, FAT16, and FAT32 supported
• Single volume and single file only
• Streaming file read
• File write with some restrictions

Introduction
This application note describes the use of the Petit FAT file system library
with a limited-memory AVR device. Full SDC/MMC file system interfacing is
normally not possible on devices with such small memories, but this compact
library enables limited interfacing with a file system on such devices. The
unneeded functions in the library can be disabled to minimize memory usage
even further. The Petit FatFs module is a subset of the FatFs module, hence
its limited functionality. It is platform independent for any ANSI C compliant
compiler, separated completely from the disk I/O layer; this means device-
specific functions for disk interfacing need to be provided additionally.

Atmel-42776A-Using-the-Petit-FAT-File-System-Module-with-AVR_AVR42776_Application Note-10/2016
Table of Contents

Features.......................................................................................................................... 1

Introduction......................................................................................................................1

1. Petit FAT File System................................................................................................ 3

2. Petit FatFs Limitations............................................................................................... 4

2.1. Write Function.............................................................................................................................. 4
2.2. File Access Efficiency...................................................................................................................4

3. Functions................................................................................................................... 5

4. Module Memory Usage and Configuration................................................................ 9

5. References.............................................................................................................. 10

6. Get Source Code from Atmel START...................................................................... 11

7. Revision History.......................................................................................................12

Atmel AVR42776: Using the Petit FAT File System Module with AVR [APPLICATION NOTE] 2
Atmel-42776A-Using-the-Petit-FAT-File-System-Module-with-AVR_AVR42776_Application Note-10/2016
1. Petit FAT File System
An SD card is a very convenient way to store large amounts of non-volatile data. A file system is
generally used to allow the data to be portable and easily accessible from a PC. An industry standard,
widely used file system is FAT. Many AVR applications require optimized usage of flash memory and
SRAM; when only limited interfacing is needed or insufficient resources are available, a normal FAT file
system module may be unsuitable, hence the need for the subset Petit FAT file system module (Petit
FatFs), available from ELM-ChaN*. It is specifically designed for 8-bit microcontrollers such as AVR 8-bit
microcontrollers, and enable basic interfacing with an FAT file system formatted MMC or SD card while
requiring limited resources. It is platform independent and so requires a lower disk I/O layer to be
functional, but sample drivers are available.
The functionality provided by the Petit FatFs library includes:
• Mounting a volume with a FAT file system
• Opening a file
• Read a file
• Write to a file (with some restrictions)
• Move R/W pointer
• Open a directory
• Read a directory item
Configuration regarding inclusion or exclusion of any function is defined in the configuration header file
(pffconf.h), in order to minimize compile size.
Note: *http://elm-chan.org/fsw/ff/00index_p.html.

Atmel AVR42776: Using the Petit FAT File System Module with AVR [APPLICATION NOTE] 3
Atmel-42776A-Using-the-Petit-FAT-File-System-Module-with-AVR_AVR42776_Application Note-10/2016
2. Petit FatFs Limitations
Petitfs specifically uses as little flash and stack as possible. This, however, comes at the expense of
some functionality. Files are not able be created or increased in size, and only one file can be accessed
at a time. The mode of sector access is limited in terms of efficiency, and therefore there are significant
periods where the SDC/MMC is busy. This busy period occurs for every partial sector access operation,
so in applications where an entire sector cannot be read or written at once, the maximum access
frequency further decreases.

2.1. Write Function

The Petit FatFs module contains a write function with some restrictions, in order to minimize the required
memory. These restrictions include:
• Files cannot be created; only an existing file can be written to
• Files cannot be expanded in size
• The time stamp of a file cannot be updated
• A write operation will only start and stop on a sector boundary
• A read-only file attribute will not block a write operation
This means that in order to write to a file, it must already exist on the SDC/MMC, and have the required
size allocated.

2.2. File Access Efficiency

The efficiency of a read or write operation is increased with the number of sectors able to be accessed in
one operation. Due to the necessity to decrease required memory, Petit FatFs uses single sector access,
meaning the access performance is decreased when compared with multiple sector access. An example
can be seen in the figure below, which depicts a card's busy time associated with both a multiple sector
write and a single sector write. This means the maximum read and write frequencies are decreased
substantially.
Figure 2-1. Multiple vs Single Sector Write

It should also be noted that SDC/MMC storage devices are not byte addressable, so for every partial
sector access operation (one byte up to the sector size of 512 bytes), the entire sector needs to be
accessed. For example, reading a sector byte-by-byte, the sector will be read 512 times. The minimum
busy time achievable with Petitfs is by reading or writing 512 bytes at a time (the size of a sector), so that
the sector is only accessed once. Therefore data should be written or read in as long of a block as
possible.

Atmel AVR42776: Using the Petit FAT File System Module with AVR [APPLICATION NOTE] 4
Atmel-42776A-Using-the-Petit-FAT-File-System-Module-with-AVR_AVR42776_Application Note-10/2016
3. Functions
Mount a Volume
FRESULT pf_mount (
FATFS* fs/* [IN] Pointer to the work area */
);

The pf_mount() function should be used prior to attempting any interfacing. It mounts the storage volume
and gives a work area to the Petit FatFs module.
• Parameters:
– fs: Pointer to the file system object (work area) to be registered.
• Return Values:
– FR_OK (0): Function success.
– FR_NOT_READY: The volume could not be mounted, due to a hard error or no volume
present.
– FR_DISK_ERR: An error occurred in the disk read function.
– FR_NO_FILESYSTEM: No valid FAT partition on the drive.

Open a File
FRESULT pf_open (
const char* path /* [IN] Pointer to the file name */
);

The pf_open() function should be used prior to writing to or reading from a file. The open file is valid until
the open function is used again for another file. Files cannot be created.
• Parameters:
– path: Pointer to a null-terminated string specifying the file name of the file to open.
• Return Values:
– FR_OK (0): Function success.
– FR_NO_FILE: The file or path could not be found.
– FR_DISK_ERR: The function failed due to a hard error, wrong FAT structure or an internal
error.
– FR_NOT_ENABLED: The volume has not been mounted.

Read from a File

FRESULT pf_read (
void* buff, /* [OUT] Pointer to the read buffer */
UINT btr, /* [IN] Number of bytes to read */
UINT* br /* [OUT] Number of bytes read */
);

The pf_read() function is used to read data from an open file. It is available when _USE_READ is written
to 1 in the pffconf.h file. The file pointer (fptr) in the file system object increases by the number of bytes
read. Upon function success, *br should be checked to detect end of file; if *br is less than btr at the end
of the function, end of the file was reached during the read operation. If the argument buff is given as
NULL, the read data is forwarded to the outgoing stream rather than stored in a memory buffer. The
streaming function depends on each project and will typically be implemented in the disk_readp()
function.

Atmel AVR42776: Using the Petit FAT File System Module with AVR [APPLICATION NOTE] 5
Atmel-42776A-Using-the-Petit-FAT-File-System-Module-with-AVR_AVR42776_Application Note-10/2016
 • Parameters:
– buff: Pointer to the buffer where read data should be stored. A null pointer will result in the
read data being forwarded to the output stream.
– btr: Number of bytes to read.
– br: Pointer to a variable which will indicate number of bytes read upon return.
• Return Values:
– FR_OK (0): Function success.
– FR_DISK_ERR: The function failed due to a hard error, wrong FAT structure or an internal
error.
– FR_NOT_OPENED: The file has not been opened.
– FR_NOT_ENABLED: The volume has not been mounted.

Write to a File
FRESULT pf_write (
const void* buff, /* [IN] Pointer to the data to be written */
UINT btw, /* [IN] Number of bytes to write */
UINT* bw /* [OUT] Pointer to the variable to return number of bytes written */
);

The pf_write() function is used to write data to an open file. It is available when _USE_WRITE is written to
1 in the pffconf.h file. The file pointer (fptr) in the file system object increases by the number of bytes
written. Upon function success, *bw should be checked to detect end of file; if *bw is less than btw at the
end of the function, end of the file was reached during the write operation.
Restrictions:
• Cannot create files
• Cannot increase the size of existing files
• Cannot update timestamp of the file, i.e. "Last Modified" attribute
• A write operation can only start and stop on a sector boundary
• A write operation will not be blocked by a file having a read-only attribute
File write must be completed in the following sequence:
1. pf_lseek(ofs); The read/write pointer must be moved to a sector boundary prior to initiating a write
operation. If this is not done, the pointer will be rounded down to the closest sector boundary.
2. pf_write(buff, btw, &bw); Write data to the file. This function can be called repeatedly if necessary
i.e. data is being produced continually. However, no data will be fully committed until the write is
finalized in the next step.
3. pf_write(0, 0, &bw); Finalize the write operation. If the read/write pointer is not on the sector
boundary, the remaining bytes in the sector will be filled with zeros. This step must be completed to
commit all written data.
• Parameters:
– buff: Pointer to the buffer where the data to be written is stored. A null pointer will indicate a
write operation should be finalized.
– btw: Number of bytes to write.
– bw: Pointer to a variable which will indicate number of bytes written upon return.
• Return Values:
– FR_OK (0): Function success.
– FR_DISK_ERR: The function failed due to a hard error, wrong FAT structure or an internal
error.

Atmel AVR42776: Using the Petit FAT File System Module with AVR [APPLICATION NOTE] 6
Atmel-42776A-Using-the-Petit-FAT-File-System-Module-with-AVR_AVR42776_Application Note-10/2016
 – FR_NOT_OPENED: The file has not been opened.
– FR_NOT_ENABLED: The volume has not been mounted.

Move the File Pointer

FRESULT pf_lseek (
DWORD ofs /* [IN] File offset in unit of byte */
);

The pf_lseek() function is used to move the read/write pointer within an open file. It is available when
_USE_LSEEK is written to 1 in the pffconf.h file. The offset should be specified relative to the top of the
file. The file pointer (fptr) in the file system object will reflect the change.
• Parameters:
– ofs: Where the read/write pointer should be moved, specified in bytes from the start of the file.
• Return Values:
– FR_OK (0): Function success.
– FR_DISK_ERR: The function failed due to a hard error, wrong FAT structure, or an internal
error.
– FR_NOT_OPENED: The file has not been opened.

Open a Directory
FRESULT pf_opendir (
DIR* dp, /* [OUT] Pointer to the blank directory object structure */
const char* path /* [IN] Pointer to the directory name */
);

The pf_opendir() function is used to open an existing directory, and create a directory object for future
reference which can be discarded at any time without specific procedure. It is available when _USE_DIR
is written to 1 in the pffconf.h file.
• Parameters:
– dp: Pointer to the blank directory object to be created.
– path: Pointer to a null-terminated string specifying the directory name of the directory to open.
• Return Values:
– FR_OK (0): Function success.
– FR_NO_FILE: The path could not be found.
– FR_NOT_READY: No volume.
– FR_DISK_ERR: The function failed due to a hard error, wrong FAT structure or an internal
error.
– FR_NOT_ENABLED: The volume has not been mounted.

Read a Directory
FRESULT pf_readdir (
DIR* dp, /* [IN] Pointer to the open directory object */
FILINFO* fno /* [OUT] Pointer to the file information structure */
);

The pf_readdir() function reads directory entries in sequence. It is available when _USE_DIR is written to
1 in the pffconf.h file. All items in the directory can be read by calling this function repeatedly. When all
directory entries have been read, the function puts a null string into member f_name[] in the file
information structure without returning an error. When fno is given as a null pointer, the read index of the
directory object will be rewinded.

Atmel AVR42776: Using the Petit FAT File System Module with AVR [APPLICATION NOTE] 7
Atmel-42776A-Using-the-Petit-FAT-File-System-Module-with-AVR_AVR42776_Application Note-10/2016
• Parameters:
– dp: Pointer to the open directory object.
– fno: Pointer to the file information structure in which to store the read item.
• Return Values:
– FR_OK (0): Function success.
– FR_DISK_ERR: The function failed due to a hard error, wrong FAT structure or an internal
error.
– FR_NOT_OPENED: The directory object has not been opened.

Atmel AVR42776: Using the Petit FAT File System Module with AVR [APPLICATION NOTE] 8
Atmel-42776A-Using-the-Petit-FAT-File-System-Module-with-AVR_AVR42776_Application Note-10/2016
4. Module Memory Usage and Configuration
The size of the Petit FatFs module when compiled using AVR-GCC varies between 1kB-4kB depending
on configuration and optimization settings used. The table below shows example compile sizes with
different configuration options, using Atmel Studio 7.0 with optimization for size. Default configuration is
with _USE_READ and _FS_FAT16 enabled, and all other options disabled. These approximations are for
the Petit FatFs module only, and does not include the disk I/O layer.
Table 4-1. Example Memory Usage of the Petit FatFs Module

Size [bytes]
Flash (Default configuration) 2064
Flash (!_USE_READ) -416
Flash (_USE_DIR) +688
Flash (_USE_LSEEK) +556
Flash (_USE_WRITE) +486
SRAM (bss) 1
SRAM (data) 42

Configuration can be customized according to what functions are required by the application. The
following table shows which functions are removed for each configuration option, contained in the
configuration header file (pffconf.h).
Table 4-2. Functions Removed by Configuration Options

Function _USE_READ 0 _USE_DIR 0 _USE_LSEEK 0 _USE_WRITE 0

pf_mount
pf_open
pf_read x
pf_lseek x
pf_opendir x
pf_readdir x
pf_write x

Atmel AVR42776: Using the Petit FAT File System Module with AVR [APPLICATION NOTE] 9
Atmel-42776A-Using-the-Petit-FAT-File-System-Module-with-AVR_AVR42776_Application Note-10/2016
5. References
This module and information regarding it was sourced from ELM-ChaN at http://elm-chan.org/fsw/ff/
00index_p.html.

Atmel AVR42776: Using the Petit FAT File System Module with AVR [APPLICATION NOTE] 10
Atmel-42776A-Using-the-Petit-FAT-File-System-Module-with-AVR_AVR42776_Application Note-10/2016
6. Get Source Code from Atmel START
The example code is available through Atmel START, which is a web-based tool that enables
configuration of application code through a graphical user interface. The code can be downloaded for
™
both Atmel Studio 7.0 and IAR IDE via the Examples-link below, or the BROWSE EXAMPLES button
on the Atmel START front page.
Web page: http://start.atmel.com/
Documentation: http://start.atmel.com/static/help/index.html
Examples: http://start.atmel.com/#examples
In the Examples-browser, search for: AVR42776 Petit FatFs Example (press User Guide in Atmel START
for detailed requirements for the example project).
Double-click the downloaded .atzip file and the project will be imported to Atmel Studio 7.0.
For information on how to import the project in IAR, press the Documentation-link above, select ‘Atmel
®
Start Output in External Tools' and 'IAR Embedded Workbench '.

Atmel AVR42776: Using the Petit FAT File System Module with AVR [APPLICATION NOTE] 11
Atmel-42776A-Using-the-Petit-FAT-File-System-Module-with-AVR_AVR42776_Application Note-10/2016
7. Revision History
Doc. Rev. Date Comments
42776A 10/2016 Initial document release

Atmel AVR42776: Using the Petit FAT File System Module with AVR [APPLICATION NOTE] 12
Atmel-42776A-Using-the-Petit-FAT-File-System-Module-with-AVR_AVR42776_Application Note-10/2016
Atmel Corporation 1600 Technology Drive, San Jose, CA 95110 USA T: (+1)(408) 441.0311 F: (+1)(408) 436.4200 | www.atmel.com

© 2016 Atmel Corporation. / Rev.: Atmel-42776A-Using-the-Petit-FAT-File-System-Module-with-AVR_AVR42776_Application Note-10/2016

® ® ®
Atmel , Atmel logo and combinations thereof, Enabling Unlimited Possibilities , AVR , and others are registered trademarks or trademarks of Atmel Corporation in
U.S. and other countries. Other terms and product names may be trademarks of others.

DISCLAIMER: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any
intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND
CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED
OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS
INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED
OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this
document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to
update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive
applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.

SAFETY-CRITICAL, MILITARY, AND AUTOMOTIVE APPLICATIONS DISCLAIMER: Atmel products are not designed for and will not be used in connection with any
applications where the failure of such products would reasonably be expected to result in significant personal injury or death (“Safety-Critical Applications”) without
an Atmel officer's specific written consent. Safety-Critical Applications include, without limitation, life support devices and systems, equipment or systems for the
operation of nuclear facilities and weapons systems. Atmel products are not designed nor intended for use in military or aerospace applications or environments
unless specifically designated by Atmel as military-grade. Atmel products are not designed nor intended for use in automotive applications unless specifically
designated by Atmel as automotive-grade.