File Systems

VFS

Basic Concepts

The Virtual File System (VFS) is not a real file system. It is an abstract layer on top of a heterogeneous file system and provides you with a unified Unix-like interface for file operations. Different types of file systems use different file operation interfaces. If there are multiple types of file systems in a system, different and non-standard interfaces are required for accessing these file systems. The VFS is introduced as an abstract layer to shield the differences between these heterogeneous file systems. With the VFS, you do not need to care about the underlying storage medium and file system type.

The OpenHarmony LiteOS-M kernel supports the File Allocation Table (FAT) and LittleFS file systems. It provides the Portable Operating System Interface (POSIX) over the VFS to ensure interface consistency. However, the VFS of the LiteOS-M kernel is light and does not provide advanced functions (such as pagecache) due to insufficient resources. Therefore, the VFS of the LiteOS-M kernel implements only API standardization and adaptation. The file systems handle specific transactions. The following tables describe the APIs supported by the file systems of the LiteOS-M kernel.

Available APIs

Table 1 APIs for file operations

Table 2 APIs for directory operations

Table 3 APIs for partition operations

Interfaces, such as ioctl and fcntl, are supported by different libraries and are irrelevant to the underlying file system.

FAT

Basic Concepts

As a file system designed for personal computers, the FAT file system consists of the DOS Boot Record (DBR) region, FAT region, and Data region. Each entry in the FAT region records information about the corresponding cluster in the storage device. The cluster information includes whether the cluster is used, number of the next cluster of the file, whether the file ends with the cluster.

The FAT file system supports a variety of formats, including FAT12, FAT16, and FAT32. The numbers 12, 16, and 32 indicate the number of bits per cluster within the FAT, respectively. The FAT file system also supports diversified storage media, especially removable media (such as USB flash drives, SD cards, and removable hard drives). It features good compatibility between embedded devices and desktop systems (such as Windows and Linux) and facilitates file management.

The OpenHarmony kernel supports FAT12, FAT16, and FAT32 file systems. These file systems require a tiny amount of code to implement, use less resources, support a variety of physical media, and are tailorable and compatible with Windows and Linux systems. They also support identification of multiple devices and partitions. The kernel supports multiple partitions on hard drives and allows creation of the FAT file system on the primary and logical partitions.

Development Guidelines

Driver Adaptation

The use of a FAT file system requires support from the underlying MultiMediaCard (MMC) driver. Before using a FAT file system on a board with an MMC, you must perform the following operations:

1. Implement the disk_status, disk_initialize, disk_read, disk_write, and disk_ioctl APIs to adapt to the embedded MMC (eMMC) driver on the board.

2. Add the fs_config.h file with information such as FS_MAX_SS (maximum sector size of the storage device) and FF_VOLUME_STRS (partition names) configured.

   The following is an example:

#define FF_VOLUME_STRS     "system", "inner", "update", "user"
#define FS_MAX_SS          512
#define FAT_MAX_OPEN_FILES 50

Mounting Partitions

Before using a FAT file system on a device, you need to initialize the flash drive and partition the device storage.

API for partitioning the storage:

int LOS_DiskPartition(const char *dev, const char *fsType, int *lengthArray, int *addrArray, int partNum);

• dev: pointer to the device name, for example, spinorblk0.
• fsType: pointer to the file system type, which is vfat for the FAT file system.
• lengthArray: pointer to a list of partition lengths (in percentage for a FAT file system) of the device.
• addrArray: pointer to a list of partition start addresses of the device.
• partNum: number of partitions.

API for formatting a partition:

int LOS_PartitionFormat(const char *partName, char *fsType, void *data);

• partName: pointer to the partition name, in the Device_name+p+Partition_ number format. For example, spinorblk0p0.
• fsType: pointer to the file system type, which is vfat for the FAT file system.
• data: pointer to the private data that passes in (VOID *) formatType, for example, FMT_FAT or FMT_FAT32.

API for mounting a partition:

int mount(const char *source, const char *target, const char *filesystemtype, unsigned long mountflags, const void *data);

• source: pointer to the partition name, in the Device_name+p+Partition_ number format. For example, spinorblk0p0.
• target: pointer to the target path to mount.
• filesystemtype: pointer to the file system type, which is vfat for the FAT file system.
• mountflags: parameters used for the mount operation.
• data: pointer to the private data that passes in (VOID *) formatType, for example, FMT_FAT or FMT_FAT32.

The sample code is implemented in ./device/qemu/arm_mps2_an386/liteos_m/board/fs/fs_init.c and can be directly used on the Quick EMUlator (QEMU) that uses the LiteOS-M kernel. You can modify the code based on the hardware you use.

#include "fatfs_conf.h"
#include "fs_config.h"
#include "los_config.h"
#include "ram_virt_flash.h"
#include "los_fs.h"

struct fs_cfg {
    CHAR *mount_point;
    struct PartitionCfg partCfg;
};

INT32 FatfsLowLevelInit()
{
    INT32 ret;
    INT32 i;
    UINT32 addr;
    int data = FMT_FAT32;

    const char * const pathName[FF_VOLUMES] = {FF_VOLUME_STRS};
    HalLogicPartition *halPartitionsInfo = getPartitionInfo(); /* Function for obtaining the partition lengths and start addresses. Modify it as required. */
    INT32 lengthArray[FF_VOLUMES] = {25, 25, 25, 25};
    INT32 addrArray[FF_VOLUMES];

    /* Set the address and length for each partition. */
    for (i = 0; i < FF_VOLUMES; i++) {
        addr = halPartitionsInfo[FLASH_PARTITION_DATA1].partitionStartAddr + i * 0x10000;
        addrArray[i] = addr;
        FlashInfoInit(i, addr);
    }

    /* Set partition information. */
    SetupDefaultVolToPartTable();

    ret = LOS_DiskPartition("spinorblk0", "vfat", lengthArray, addrArray, FF_VOLUMES);
    printf("%s: DiskPartition %s\n", __func__, (ret == 0) ? "succeed" : "failed");
    if (ret != 0) {
        return -1;
    }

    ret = LOS_PartitionFormat("spinorblk0p0", "vfat", &data);
    printf("%s: PartitionFormat %s\n", __func__, (ret == 0) ? "succeed" : "failed");
    if (ret != 0) {
        return -1;
    }

    ret = mount("spinorblk0p0", "/system", "vfat", 0, &data);
    printf("%s: mount fs on '%s' %s\n", __func__, pathName[0], (ret == 0) ? "succeed" : "failed");
    if (ret != 0) {
        return -1;
    }
    return 0;
}

How to Develop

Observe the following when managing files and directories in a FAT file system:

• A file cannot exceed 4 GB.
• FAT_MAX_OPEN_FILES specifies the maximum number files you can open at a time, and FAT_MAX_OPEN_DIRS specifies the maximum number of folders you can open at a time.
• Root directory management is not supported. File and directory names start with the partition name. For example, user/testfile indicates the testfile file or directory in the user partition.
• To open a file multiple times at the same time, use O_RDONLY (read-only mode). O_RDWR or O_WRONLY (writable mode) can open a file only once at a time.
• The read and write pointers are not separated. If a file is open in O_APPEND mode, the read pointer is also at the end of the file. If you want to read the file from the beginning, you must manually set the position of the read pointer.
• File and directory permission management is not supported.
• The stat and fstat APIs do not support query of the modification time, creation time, and last access time. The Microsoft FAT protocol does not support time before A.D. 1980.

Observe the following when managing files and directories in a FAT file system:

• Partitions can be mounted with the read-only attribute. If the input parameter of mount() is MS_RDONLY, all APIs with the write attribute, such as write(), mkdir(), unlink(), and open() with non-O_RDONLY attributes, will be rejected.
• You can use the MS_REMOUNT flag in mount() to modify the permissions for a mounted partition.
• Before unmounting a partition, ensure that all directories and files in the partition are closed.
• You can use umount2 with the MNT_FORCE parameter to forcibly close all files and folders and unmount the partition. However, this may cause data loss. Therefore, exercise caution when using umount2.

You can use fatfs_fdisk() and fatfs_format() to re-partition the device storage and format the partitions. Observe the following:

• Before using fatfs_format(), ensure that the target partition is unmounted and all directories and files in the partition are closed.
• Before using fatfs_fdisk, ensure that all partitions in the device are unmounted.
• Using fatfs_fdisk and fatfs_format may cause data loss. Exercise caution when using them.

Development Example

Example Description

This example implements the following:

1. Create a system/test directory.

2. Create a file.txt file in the system/test directory.

3. Write Hello OpenHarmony! at the beginning of the file.

4. Save the file to a device.

5. Set the offset to the start position of the file.

6. Reads the file content.

7. Close the file.

8. Delete the file.

9. Delete the directory.

Sample Code

Prerequisites

• The system partition is mounted to the QEMU.
• FAT is enabled.
  1. In the kernel/liteos_m directory, run the make menuconfig command and choose FileSystem->Enable FS VFS to enable VFS.
  2. Select Enable FAT to enable the FAT file system.

Implementation

The sample code can be compiled and verified in ./kernel/liteos_m/testsuites/src/osTest.c. The ExampleFatfs function is called in TestTaskEntry.

#include <stdio.h>
#include <string.h>
#include "sys/stat.h"
#include "fcntl.h"
#include "unistd.h"

#define BUF_SIZE 20
#define TEST_ROOT "system" /* Set the test root directory. */
VOID ExampleFatfs(VOID)
{
  int ret;
  int fd;
  ssize_t len;
  off_t off;
  char dirName[BUF_SIZE] = TEST_ROOT"/test";
  char fileName[BUF_SIZE] = TEST_ROOT"/test/file.txt";
  char writeBuf[BUF_SIZE] = "Hello OpenHarmony!";
  char readBuf[BUF_SIZE] = {0};

  /* Create a test directory. */
  ret = mkdir(dirName, 0777);
  if (ret != LOS_OK) {
      printf("mkdir failed.\n");
      return;
  }

  /* Create a file that is readable and writable. */
  fd = open(fileName, O_RDWR | O_CREAT, 0777);
  if (fd < 0) {
      printf("open file failed.\n");
      return;
  }

  /* Write the content from writeBuf to the file. */
  len = write(fd, writeBuf, strlen(writeBuf));
  if (len != strlen(writeBuf)) {
      printf("write file failed.\n");
      return;
  }

  /* Save the file to a storage device. */
  ret = fsync(fd);
  if (ret != LOS_OK) {
      printf("fsync failed.\n");
      return;
  }

  /* Move the read/write pointer to the beginning of the file. */
  off = lseek(fd, 0, SEEK_SET);
  if (off != 0) {
      printf("lseek failed.\n");
      return;
  }

  /* Read the file content with the length of readBuf to readBuf. */
  len = read(fd, readBuf, sizeof(readBuf));
  if (len != strlen(writeBuf)) {
      printf("read file failed.\n");
      return;
  }
  printf("%s\n", readBuf);

  /* Close the test file. */
  ret = close(fd);
  if (ret != LOS_OK) {
      printf("close failed.\n");
      return;
  }

  /* Delete the test file. */
  ret = unlink(fileName);
  if (ret != LOS_OK) {
      printf("unlink failed.\n");
      return;
  }

  /* Delete the test directory. */
  ret = rmdir(dirName);
  if (ret != LOS_OK) {
      printf("rmdir failed.\n");
      return;
  }

  return;
}

Verification

The development is successful if the return result is as follows:

Hello OpenHarmony!

LittleFS

Basic Concepts

LittleFS is a small file system designed for the flash drive. It stores metadata in log structure and data in the copy-on-write (COW) structure. This feature empowers LittleFS high power-loss resilience. LittleFS uses the statistical wear leveling algorithm when allocating COW data blocks, effectively prolonging the service life of flash devices. LittleFS is designed for small-sized devices with limited resources, such as ROM and RAM. All RAM resources are allocated through a buffer with the fixed size (configurable). That is, the RAM usage does not grow with the file system.

LittleFS is a good choice when you look for a flash file system that is power-cut resilient and has wear leveling support on a small device with limited resources.

Development Guidelines

Before using a LittleFS to a device, you need to initialize the flash drive and partition the device storage

API for partitioning the storage:

int LOS_DiskPartition(const char *dev, const char *fsType, int *lengthArray, int *addrArray, int partNum);

• dev: pointer to the device name.
• fsType: pointer to the file system type, which is littlefs for LittleFS.
• lengthArray: pointer to a list of partition lengths of the device.
• addrArray: pointer to a list of partition start addresses of the device.
• partNum: number of partitions.

API for formatting a partition:

int LOS_PartitionFormat(const char *partName, char *fsType, void *data);

• partName: pointer to the partition name.
• fsType: pointer to the file system type, which is littlefs for LittleFS.
• data: pointer to the private data that passes in void pass (VOID *) struct fs_cfg.

API for mounting a partition:

int mount(const char *source, const char *target, const char *filesystemtype, unsigned long mountflags, const void *data);

• source: pointer to the partition name.
• target: pointer to the target path to mount.
• filesystemtype: pointer to the file system type, which is littlefs for LittleFS.
• mountflags: parameters used for the mount operation.
• data: pointer to the private data that passes in void pass (VOID *) struct fs_cfg.

The sample code is implemented in ./device/qemu/arm_mps2_an386/liteos_m/board/fs/fs_init.c and can be directly used on the QEMU that uses the LiteOS-M kernel. You can modify the code based on the hardware you use.

#include "los_config.h"
#include "ram_virt_flash.h"
#include "los_fs.h"

struct fs_cfg {
    CHAR *mount_point;
    struct PartitionCfg partCfg;
};

INT32 LfsLowLevelInit()
{
    INT32 ret;
    struct fs_cfg fs[LOSCFG_LFS_MAX_MOUNT_SIZE] = {0};
    HalLogicPartition *halPartitionsInfo = getPartitionInfo();  /* Function for obtaining the partition lengths and start addresses. You can modify the function to match your development. */

    INT32 lengthArray[2];
    lengthArray[0]= halPartitionsInfo[FLASH_PARTITION_DATA0].partitionLength;

    INT32 addrArray[2];
    addrArray[0] = halPartitionsInfo[FLASH_PARTITION_DATA0].partitionStartAddr;

    ret = LOS_DiskPartition("flash0", "littlefs", lengthArray, addrArray, 2);
    printf("%s: DiskPartition %s\n", __func__, (ret == 0) ? "succeed" : "failed");
    if (ret != 0) {
        return -1;
    }
    fs[0].mount_point = "/littlefs";
    fs[0].partCfg.partNo = 0;
    fs[0].partCfg.blockSize = 4096; /* 4096, lfs block size */
    fs[0].partCfg.blockCount = 1024; /* 2048, lfs block count */
    fs[0].partCfg.readFunc = virt_flash_read;		/* Function for reading data from the flash drive. You can modify it to match your development. */
    fs[0].partCfg.writeFunc = virt_flash_write;		/* Function for writing data to the flash drive. You can modify it to match your development. */
    fs[0].partCfg.eraseFunc = virt_flash_erase;		/* Function for erasing the flash driver. You can modify it to match your development. */

    fs[0].partCfg.readSize = 256; /* 256, lfs read size */
    fs[0].partCfg.writeSize = 256; /* 256, lfs prog size */
    fs[0].partCfg.cacheSize = 256; /* 256, lfs cache size */
    fs[0].partCfg.lookaheadSize = 16; /* 16, lfs lookahead size */
    fs[0].partCfg.blockCycles = 1000; /* 1000, lfs block cycles */

    ret = LOS_PartitionFormat("flash0", "littlefs", &fs[0].partCfg);
    printf("%s: PartitionFormat %s\n", __func__, (ret == 0) ? "succeed" : "failed");
    if (ret != 0) {
        return -1;
    }
    ret = mount(NULL, fs[0].mount_point, "littlefs", 0, &fs[0].partCfg);
    printf("%s: mount fs on '%s' %s\n", __func__, fs[0].mount_point, (ret == 0) ? "succeed" : "failed");
    if (ret != 0) {
        return -1;
    }
    return 0;
}

The .readFunc, .writeFunc, and .eraseFunc functions correspond to read(), write(), and erase() of the underlying hardware platform.

readSize indicates the number of bytes read each time. You can set it to a value greater than the physical read unit to improve performance. This value determines the size of the read cache. However, if the value is too large, more memory is consumed.

writeSize indicates the number of bytes written each time. You can set it to a value greater than the physical write unit to improve performance. This value determines the size of the write cache and must be an integral multiple of readSize. However, if the value is too large, more memory is consumed.

blockSize indicates the number of bytes in each erase block. The value can be greater than that of the physical erase unit. However, a smaller value is recommended because each file occupies at least one block. The value must be an integral multiple of writeSize.

blockCount indicates the number of blocks that can be erased, which depends on the capacity of the block device and the size of the block to be erased (blockSize).

Sample Code

Prerequisites

• /littlefs is mounted to the QEMU.
• LittleFS is enabled.
  1. In the kernel/liteos_m directory, run the make menuconfig command and choose FileSystem->Enable FS VFS to enable VFS.
  2. Select Enable Little FS to enable the LittleFS.

The sample code is as follows:

The sample code can be compiled and verified in ./kernel/liteos_m/testsuites/src/osTest.c. The ExampleLittlefs function is called in TestTaskEntry.

#include <stdio.h>
#include <string.h>
#include "sys/stat.h"
#include "fcntl.h"
#include "unistd.h"

#define BUF_SIZE 20
#define TEST_ROOT "/littlefs" /* Set the test root directory. */
VOID ExampleLittlefs(VOID)
{
    int ret;
    int fd;
    ssize_t len;
    off_t off;
    char dirName[BUF_SIZE] = TEST_ROOT"/test";
    char fileName[BUF_SIZE] = TEST_ROOT"/test/file.txt";
    char writeBuf[BUF_SIZE] = "Hello OpenHarmony!";
    char readBuf[BUF_SIZE] = {0};

    /* Create a test directory. */
    ret = mkdir(dirName, 0777);
    if (ret != LOS_OK) {
        printf("mkdir failed.\n");
        return;
    }

    /* Create a file that is readable and writable. */
    fd = open(fileName, O_RDWR | O_CREAT, 0777);
    if (fd < 0) {
        printf("open file failed.\n");
        return;
    }

    /* Write the content from writeBuf to the file. */
    len = write(fd, writeBuf, strlen(writeBuf));
    if (len != strlen(writeBuf)) {
        printf("write file failed.\n");
        return;
    }

    /* Save the file to a storage device. */
    ret = fsync(fd);
    if (ret != LOS_OK) {
        printf("fsync failed.\n");
        return;
    }

    /* Move the read/write pointer to the beginning of the file. */
    off = lseek(fd, 0, SEEK_SET);
    if (off != 0) {
        printf("lseek failed.\n");
        return;
    }

    /* Read the file content with the length of readBuf to readBuf. */
    len = read(fd, readBuf, sizeof(readBuf));
    if (len != strlen(writeBuf)) {
        printf("read file failed.\n");
        return;
    }
    printf("%s\n", readBuf);

    /* Close the test file. */
    ret = close(fd);
    if (ret != LOS_OK) {
        printf("close failed.\n");
        return;
    }

    /* Delete the test file. */
    ret = unlink(fileName);
    if (ret != LOS_OK) {
        printf("unlink failed.\n");
        return;
    }

    /* Delete the directory. */
    ret = rmdir(dirName);
    if (ret != LOS_OK) {
        printf("rmdir failed.\n");
        return;
    }

    return LOS_OK;
}

Verification

The development is successful if the return result is as follows:

Hello OpenHarmony!