Journaling: The Basics

Although it has mostly been supplanted by NTFS in the PC world, the FAT file system remains a popular choice for embedded developers. In addition to offering an embedded application the ability to seamlessly interact with a PC (since Windows continues to support FAT) a FAT-based file system solution can be a surprising source of added reliability for developers of devices that must operate with inconsistent power sources. But to deliver protection from power failures, a FAT implementation must be equipped with a journaling module.

In this brief article, we’ll go over the basics of how a journaling module works, what it does and doesn’t protect against, and how to enable the journaling module provided with Micrium’s FAT implementation (µC/FS).

A journaling module keeps track of changes not yet committed to the file system by recording the intentions of such changes in a data structure known as a “journal.” With this history of operations, the journaling module can maintain the file system directory hierarchy in the case of a power failure and ensure that the underlying structure is not corrupted. It’s important to note that, although the journaling module does protect the system from corruption, it does not provide protection for the data (the file contents, in other words). So, following a power failure, it’s possible for a file (that was being modified at the time of the failure) to be in an “unknown” state, in which all, a portion, or none of its expected contents are missing.

Of course, the specific steps that must be followed to use journaling vary across file system implementations. With Micrium’s FAT-based implementation (µC/FS), the procedure is a simple one, allowing you to go from not having any power-failure protection to fully protected in just four steps:

  1. You should start by ensuring that the fs_fat_journal.c file can be found in your project.

    This file has the following location:

    $:\Micrium\Software\uC-FS\FAT

    ($:\ represents the location of your Micrium software folder.)

  2. You’ll need to enable the FS_FAT_CFG_JOURNAL_EN #define in fs_cfg.h. In a Micrium example project, this file is normally contained in the same folder as the application code.

    FS_FAT_CFG_JOURNAL_EN enables the functions necessary to perform recordings during file system operations.

  3. You should update your application code with calls, to the below µC/FS API functions, for opening and starting the journal on a specified volume. It’s important to note that the device and volume must be mounted prior to performing these calls.
    • FS_FAT_JournalOpen()

      This opens the journal file found within the file system. If a journal cannot be located, then the file system will create one.

    • FS_FAT_JournalStart()

      Following this call, any changes to the targeted volume will be recorded in the journal.

  4. Finally, you’ll need to repeat step 3 for every additional volume with which you would like to use journaling. This is necessary because the journaling module is enabled for one particular volume at a time.

If you’ve completed all of the above steps, your application is using µC/FS’s journaling module and is protected against corruption. You may have noticed that instructions to stop and close the journaling module were not mentioned above. Although these options are available (stop with FS_FAT_JournalStop(), and close with FS_FAT_JournalClose()), it is our recommendation that you do not stop or close the journaling module, as once updates to the journal have been discontinued, all file system processes beyond that point will not be recorded or protected.

For more information on the journaling module, how it works and known limitations, please check out the “Optional Journaling System” section of our µC/FS documentation.

For users interested in a file system solution that protects the system as well as the data (although without the same level of PC compatibility), we also provide a transactional (atomic) file system named Reliance Edge. Please check out the Reliance Edge page for more information on this module.

Questions or Comments?

Have a question or a suggestion for a future article?
Don't hesitate to contact us and let us know!
All comments and ideas are welcome.