{"id":53,"date":"2025-07-04T23:18:56","date_gmt":"2025-07-04T23:18:56","guid":{"rendered":"https:\/\/blog.ganji.dev\/?p=53"},"modified":"2025-07-04T23:23:11","modified_gmt":"2025-07-04T23:23:11","slug":"lessons-from-building-fatfs-mount-handler","status":"publish","type":"post","link":"https:\/\/blog.ganji.dev\/?p=53","title":{"rendered":"Lessons from Building FatFS Mount Handler"},"content":{"rendered":"\n

 Integrating a third-party filesystem like FatFS into RTEMS requires understanding both the RTEMS filesystem architecture and the nuances of bridging two different APIs. Here’s what I learned while implementing the FatFS mount functionality for RTEMS.

 The Challenge: Two Different Worlds<\/strong>

 RTEMS uses a POSIX-like filesystem abstraction with operations like open(), read(), and write(), while FatFS provides its own API with
 functions like f_open(), f_read(), and f_write(). The integration layer must translate between these two worlds seamlessly.

 Understanding RTEMS Filesystem Architecture<\/strong>

 RTEMS filesystems are built around several key structures:

 – rtems_filesystem_operations_table<\/strong>: Contains filesystem-level operations (mount, unmount, path evaluation, etc.)
 – rtems_filesystem_file_handlers_r<\/strong>: Contains file-level operations (open, close, read, write, etc.)
 – rtems_filesystem_mount_table_entry_t<\/strong>: Describes a mounted filesystem instance

 The mount handler is the entry point where everything begins. It’s responsible for:
 1. Initializing the filesystem
 2. Setting up the root directory
 3. Configuring the mount table entry
 4. Handling errors gracefully

 Key Components of the FatFS Integration<\/strong>

 1. The Filesystem Info Structure<\/p>\n\n\n\n

 typedef struct {
     FATFS fatfs;                    \/\/ FatFS filesystem object
     rtems_recursive_mutex vol_mutex; \/\/ Thread safety
     const rtems_filesystem_file_handlers_r *file_handlers;
     const rtems_filesystem_file_handlers_r *dir_handlers;
     BYTE drive_number;              \/\/ Drive number for FatFS
     char mount_path[256];           \/\/ FatFS drive path (“0:”, “1:”, etc.)
 } rtems_fatfs_fs_info_t;

 This structure bridges RTEMS and FatFS, containing both the FatFS volume object and RTEMS-specific data.

 2. The Disk I\/O Bridge

 One of the most critical pieces is the disk I\/O layer (rtems-diskio.c<\/code>). FatFS expects certain disk I\/O functions (disk_read, disk_write,
 disk_ioctl, disk_status), while RTEMS provides block device access through its rtems_bdbuf interface.

 The bridge maintains a mapping between FatFS drive numbers and RTEMS block devices:

 typedef struct {
     int fd;                         \/\/ RTEMS file descriptor
     rtems_disk_device *dd;          \/\/ RTEMS disk device
     bool initialized;               \/\/ Registration state
 } fatfs_volume_t;

 static fatfs_volume_t volumes[FF_VOLUMES];

 3. Error Code Translation

 FatFS and RTEMS use different error codes. A translation layer converts FatFS FRESULT codes to POSIX errno values:

 static inline int rtems_fatfs_fresult_to_errno(FRESULT fr) {
     switch (fr) {
         case FR_OK: return 0;
         case FR_NO_FILE: return ENOENT;
         case FR_DENIED: return EACCES;
         case FR_EXIST: return EEXIST;
         \/\/ … more mappings
     }
 }

 The Mount Process: Step by Step<\/strong>

 1. Memory Allocation and Setup<\/p>\n\n\n\n

fs_info = calloc(1, sizeof(*fs_info));\nroot_node = calloc(1, sizeof(*root_node));\nrtems_recursive_mutex_init(&fs_info->vol_mutex, RTEMS_FILESYSTEM_TYPE_FATFS);<\/code><\/pre>\n\n\n\n

 2. Drive Number Management<\/p>\n\n\n\n
 FatFS uses numeric drive identifiers (0-9). The mount handler assigns unique drive numbers with wraparound:<\/p>\n\n\n\n
 fs_info->drive_number = next_drive_number++;\n if (next_drive_number >= FF_VOLUMES) {\n     next_drive_number = 0;\n }<\/code><\/pre>\n\n\n\n
 3. Device Registration

 The RTEMS block device must be registered with the FatFS disk I\/O layer:

 rc = fatfs_diskio_register_device(fs_info->drive_number, mt_entry->dev);<\/code>

 4. FatFS Mount

 Create the drive path and mount the FatFS volume:

 snprintf(drive_path, sizeof(drive_path), \"%u:\", fs_info->drive_number);
 fr = f_mount(&fs_info->fatfs, drive_path, 1);  \/\/ 1 = immediate mount<\/code>

 5. Root Directory Setup

 This was trickier than expected. Initially, I tried to use f_stat() to get root directory information, but FatFS has limitations with root directory paths. The solution is to manually set up the root directory:<\/p>\n\n\n\n
 root_node->is_directory = true;\n root_node->is_open = false;\n strcpy(root_node->path, \"\/\");\n memset(&root_node->info, 0, sizeof(root_node->info));\n root_node->info.fattrib = AM_DIR;  \/\/ Mark as directory<\/code><\/pre>\n\n\n\n

6. Mount Table Configuration

 Finally, configure the RTEMS mount table entry:<\/p>\n\n\n\n
 mt_entry->fs_info = fs_info;\n mt_entry->ops = &rtems_fatfs_ops;\n mt_entry->mt_fs_root->location.node_access = root_node;\n mt_entry->mt_fs_root->location.handlers = fs_info->dir_handlers;<\/code><\/pre>\n\n\n\n

\u00a0Lessons Learned<\/strong>

\u00a01. Path Handling Complexity

\u00a0FatFS uses drive-prefixed paths (“0:\/file.txt”) while RTEMS uses Unix-style paths (“\/mnt\/fat\/file.txt”). The integration layer must handle this translation carefully.

\u00a02. Error Handling is Critical

\u00a0Both allocation failures and FatFS errors must be handled with proper cleanup. The mount handler needs comprehensive error paths:

\u00a0if (fr != FR_OK) {
\u00a0\u00a0\u00a0\u00a0\u00a0fatfs_diskio_unregister_device(fs_info->drive_number);
\u00a0\u00a0\u00a0\u00a0\u00a0rtems_recursive_mutex_destroy(&fs_info->vol_mutex);
\u00a0\u00a0\u00a0\u00a0\u00a0free(root_node);
\u00a0\u00a0\u00a0\u00a0\u00a0free(fs_info);
\u00a0\u00a0\u00a0\u00a0\u00a0errno = rtems_fatfs_fresult_to_errno(fr);
\u00a0\u00a0\u00a0\u00a0\u00a0return -1;
\u00a0}

\u00a03. Thread Safety from Day One

\u00a0RTEMS is multithreaded, so the filesystem must be thread-safe. Using recursive mutexes allows proper locking without deadlocks when filesystem operations call each other.<\/p>\n\n\n\n
Debugging<\/h2>\n\n\n\n
Debugging was a crucial part of making this whole thing work. It is as simple as running the app with -s<\/code> flag, then:<\/p>\n\n\n\n
gdb \/path\/to\/exe<\/code><\/pre>\n\n\n\n
And inside gdb (assuming you’ve ran your code with QEMU):<\/p>\n\n\n\n
target remote localhost:1234<\/code><\/pre>\n\n\n\n
I saw a really good cheatsheet<\/a> for GDB. Manually running GDB is both powerful and dangerous. A wise man once said: “Programs walk before they can run”.<\/p>\n","protected":false},"excerpt":{"rendered":"
 Integrating a third-party filesystem like FatFS into RTEMS requires understanding both the RTEMS filesystem architecture and the nuances of bridging two different APIs. Here’s what I learned while implementing the FatFS mount functionality for RTEMS.  The Challenge: Two Different Worlds  RTEMS uses a POSIX-like filesystem abstraction with operations like open(), read(), and write(), while FatFS […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[5],"tags":[],"class_list":["post-53","post","type-post","status-publish","format-standard","hentry","category-gsoc"],"_links":{"self":[{"href":"https:\/\/blog.ganji.dev\/index.php?rest_route=\/wp\/v2\/posts\/53","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.ganji.dev\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.ganji.dev\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.ganji.dev\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.ganji.dev\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=53"}],"version-history":[{"count":4,"href":"https:\/\/blog.ganji.dev\/index.php?rest_route=\/wp\/v2\/posts\/53\/revisions"}],"predecessor-version":[{"id":57,"href":"https:\/\/blog.ganji.dev\/index.php?rest_route=\/wp\/v2\/posts\/53\/revisions\/57"}],"wp:attachment":[{"href":"https:\/\/blog.ganji.dev\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=53"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.ganji.dev\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=53"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.ganji.dev\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=53"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}