Use LittleFS as SD card file system

Showing results for 
Show  only  | Search instead for 
Did you mean: 

Use LittleFS as SD card file system

No ratings

Use LittleFS as SD card file system

LittleFS is a file system used for microcontroller internal flash and external NOR flash. Since it is more suitable for small embedded systems than traditional FAT file systems, more and more people are using it in their projects. So in addition to NOR/NAND flash type storage devices, can LittleFS be used in SD cards? It seems that it is okay too. This article will use the littlefs_shell and sdcard_fatfs demo project in the i.mxRT1050 SDK to make a new littefs_shell project for reading and writing SD cards.

This experiment uses MCUXpresso IDE v11.7, and the SDK uses version 2.13. The littleFS file system has only 4 files, of which the current version shown in lfs.h is littleFS 2.5.

The first step, of course, is to add SD-related code to the littlefs_shell project. The easiest way is to import another sdcard_fatfs project and copy all of the sdmmc directories into our project. Then copy sdmmc_config.c and sdmmc_config.h in the /board directory, and fsl_usdhc.c and fsl_usdhc.h in the /drivers directory.

The second step is to modify the program to include SD card detection and initialization, adding a bridge from LittleFS to SD drivers. Add the following code to littlefs_shell.c.

extern sd_card_t m_sdCard;  
status_t sdcardWaitCardInsert(void)  
    /* SD host init function */  
    if (SD_HostInit(&m_sdCard) != kStatus_Success)  
        PRINTF("\r\nSD host init fail\r\n");  
        return kStatus_Fail;  
    /* wait card insert */  
    if (SD_PollingCardInsert(&m_sdCard, kSD_Inserted) == kStatus_Success)  
        PRINTF("\r\nCard inserted.\r\n");  
        /* power off card */  
        SD_SetCardPower(&m_sdCard, false);  
        /* power on the card */  
        SD_SetCardPower(&m_sdCard, true);  
//        SdMmc_Init();  
        PRINTF("\r\nCard detect fail.\r\n");  
        return kStatus_Fail;  
    return kStatus_Success;  
status_t sd_disk_initialize()  
    static bool isCardInitialized = false;  
    /* demostrate the normal flow of card re-initialization. If re-initialization is not neccessary, return RES_OK directly will be fine */  
    if (kStatus_Success != SD_Init(&m_sdCard))  
        memset(&m_sdCard, 0U, sizeof(m_sdCard));  
        return kStatus_Fail;  
    isCardInitialized = true;  
    return kStatus_Success;  

In main(), add these code

 if (sdcardWaitCardInsert() != kStatus_Success)
 return -1;
 status = sd_disk_initialize();

Next, create two new c files, lfs_sdmmc.c and lfs_sdmmc_bridge.c. The call order is littlefs->lfs_sdmmc.c->lfs_sdmmc_bridge.c->fsl_sd.c. lfs_sdmmc.c and lfs_sdmmc_bridge.c acting as intermediate layers that can connect the LITTLEFS and SD upper layer drivers. One of the things that must be noted is the mapping of addresses. The address given by littleFS is the block address + offset address. See figure below. This is a read command issued by the ‘mount’ command. The block address refers to the address of the erased sector address in SD. The read and write operation uses the smallest read-write block address (BLOCK) of SD, as described below. Therefore, in lfs_sdmmc.c, the address given by littleFS is first converted to the byte address. Then change the SD card read-write address to the BLOCK address in lfs_sdmmc_bridge.c. Since most SD cards today exceed 4GB, the byte address requires a 64-bit variable.


Finally, the most important step is littleFS parameter configuration. There is a structure LittlsFS_config in peripherals.c, which contains not only the operation functions of the SD card, but also the read and write sectors and cache size. The setup of this structure is critical. If the setting is not good, it will not only affect the performance, but also cause errors in operation. Before setting it up, let's introduce some of the general ideal of SD card and littleFS.

The storage unit of the SD card is BLOCK, and both reading and writing can be carried out according to BLOCK. The size of each block can be different for different cards. For standard SD cards, the length of the block command can be set with CMD16, and the block command length is fixed at 512 bytes for SDHC cards. The SD card is erased sector by sector. The size of each sector needs to be checked in the CSD register of the SD card. If the CSD register ERASE_BLK_EN = 0, Sector is the smallest erase unit, and its unit is "block". The value of sector size is equal to the value of the SECTOR_SIZE field in the CSD register plus 1. For example, if SECTOR_SIZE is 127, then the minimum erase unit is 512*(127+1)=65536 bytes. In addition, sometimes there are doubts, many of the current SD cards actually have wear functions to reduce the loss caused by frequent erasing and writing, and extend the service life. So in fact, delete operations or read and write operations are not necessarily real physical addresses. Instead, it is mapped by the SD controller. But for the user, this mapping is transparent. So don't worry about this affecting normal operation.

LittleFS is a lightweight file system that has power loss recovery and dynamic wear leveling compared to FAT systems. Once mounted, littleFS provides a complete set of POSIX-like file and directory functions, so it can be operated like a common file system. LittleFS has only 4 files in total, and it basically does not need to be modified when used. Since the NOR/NAND flash to be operated by LittleFS is essentially a block device, in order to facilitate use, LittleFS is read and written in blocks, and the underlying NOR/NAND Flash interface drivers are carried out in blocks.

Let's take a look at the specific content of LittleFS configuration parameters.

const struct lfs_config LittleFS_config = {  
  .context = (void*)0,  
  .read = lfs_sdmmc_read,  
  .prog = lfs_sdmmc_prog,  
  .erase = lfs_sdmmc_erase,  
  .sync = lfs_sdmmc_sync,  
  .read_size = 512,  
  .prog_size = 512,  
  .block_size = 65536,  
  .block_count = 128,  
  .block_cycles = 100,  
  .cache_size = 512,  
  .lookahead_size = LITTLEFS_LOOKAHEAD_SIZE  

Among them, the first item (.context) is not used in this project, and is used in the original project to save the offset of the file system stored in Flash.

Items two (.read) through five (.sync) point to the handlers for each operation.

The sixth item (.read_size) is the smallest unit of read operation. This value is roughly equal to the BLOCK size of the SD card. In the SD card driver, this size has been fixed to 512. So for convenience, it is also set to 512.

The seventh item (.prog_size) is the number of bytes written each time, which is 512 bytes like .read_size.

The eighth item is .block_size. This can be considered to be the smallest erase block supported by the SD card when performing an erase operation. Here the default value is not important, you need to set it in the program according to the actual value after the SD card is initialized. The card used in this experiment is 64k bytes as an erase block, so 65536 is used directly here.

Item 9 (.block_count) is used to indicate how many erasable blocks there are. Multiply the .block_size to get the size of the card. If the card is replaceable, it needs to be determined according to the parameters after the SD card is initialized.

The tenth item (.block_cycles) is the number of erase cycles per block.

Item 11 (.cache_size) is about the cache buffer. It feels like bigger is better, but actually modifies this value won't work. So still 512.

Item 12 (lookahead_size), littleFS uses a lookahead buffer to manage and allocate blocks. A lookahead buffer is a fixed-size bitmap that records information about block allocations within an area. The lookahead buffer only records the information of block allocations in one area, and when you need to know the allocation of other regions, you need to scan the file system to find allocated blocks. If there are no free blocks in the lookahead buffer, you need to move the lookahead buffer to find other free blocks in the file system. The lookahead buffer position shifts one lookahead_size at a time. Use the original value here.

 That’s all for the porting work. We can test the project now.


You can see it works fine. The littleFS-SD project can read/write/create folder and erase. And it also support append to an exist file.

But after more testing, a problem was found, if you repeatedly add->-close->-add-> close a file, the file will open more and more slowly, even taking a few seconds. This is what should be added and is not written directly in the last block of the file, but will apply for a new block, regardless of whether the previous block is full or not. See figure below.


The figure above prints out all the read, write, and erase operations used in each write command. You can see that each time in the lfs_file_open there is one more read than the last write operation. In this way, after dozens or hundreds of cycles, a file will involve many blocks. It is very time-consuming to read these blocks in turn. Tests found that more than 100 read took longer than seconds. To speed things up, it is recommended to copy the contents of one file to another file after adding it dozens of times. In this way, the scattered content will be consolidated to write a small number of blocks. This can greatly speed up reading and writing.

Version history
Last update:
‎11-01-2023 03:17 AM
Updated by: