Useful Information

Nomenclature

This manual uses a set of terms to consistently describe operation of µC/FS and its hardware and software environment. The following is a small list of these terms, with definitions.

A file system suite is software which can find and access files and directories. Using “file system suite” rather than “file system” eliminates any need for disambiguation among the second term’s several meanings, which include “a system for organizing directories and files”, “a collection of files and directories stored on a drive” and (commonly) the software which will be referred to as a file system suite. The term file system will always mean a collection of files and directories stored on a drive (or, in this document, volume).

A device driver (or just driver) is a code module which allows the general-purpose file system suite to access a specific type of device. A device driver is registered with the file system suite.

A device is an instance of a device type that is accessed using a device driver. An addressable area (typically of 512 bytes) on a device is a sector. A sector is the smallest area that (from the file system suite’s point of view) can be atomically read or written.

Several devices can use the same device driver. These are distinguished by each having a unique unit number. Consequently, <DEVICE NAME>:<UNIT NUMBER>: is a unique device identifier if all devices are required to have unique names. That requirement is enforced in this file system suite.

A logical device is the combination of two or more separate devices. To form a logical device, the sector address spaces of the constituent devices are concatenated to form a single continuous address space.

A device can be partitioned, or subdivided into one or more regions (called partitions) each consisting of a number of consecutive sectors. Typically, structures are written to the device instructing software as to the location and size of these partitions. This file system suite supports DOS partitions.

A volume is a device or device partition with a file system. A device or device partition must go through a process called mounting to become a volume, which includes finding the file system and making it ready for use. The name by which a volume is addressed may also be called the volume’s mount point.

A device or volume may be formatted to create a new file system on the device. For disambiguation purposes, this process is also referred to as high-level formatting. The volume or device will automatically be mounted once formatting completes.

For certain devices, it is either necessary or desirable to perform low-level formatting. This is the process of associating logical sector numbers with areas of the device.

A file system driver is a code module which allows the general-purpose file system suite to access a specific type of file system. For example, this file system suite includes a FAT file system driver.

FAT (File Allocation Table) is a common file system type, prevalent in removable media that must work with various OSs. It is named after its primary data structure, a large table that records what clusters of the disk are allocated. A cluster, or group of sectors, is the minimum data allocation unit of the FAT file system.

µC/FS Device and Volume Names

Devices are specified by name. For example, a device can be opened:

FSDev_Open("sd:0:", (void *)0, &err);

In this case, “sd:0:” is the device name. It is a concatenation of:

The unit number allows multiple devices of the same type; for example, there could be several SD/MMC devices connected to the CPU: “ sd:0: ”, “ sd:1 ”, “ sd:2 ”…

The maximum length of a device name is FS_CFG_MAX_DEV_NAME_LEN; this must be at least three characters larger than the maximum length of a device driver name, FS_CFG_MAX_DEV_DRV_NAME_LEN. A device name (or device driver name) must not contain the characters:

: \ /

Volumes are also specified by name. For example, a volume can be formatted

FSVol_Fmt("vol:", (void *)0, &err);

It is typical to name a volume the same as a device; for example, a volume may be opened:Here, “vol:” is the volume name. µC/FS imposes no restrictions on these names, except that they must end with a colon (‘:’), must be no more than FS_CFG_MAX_VOL_NAME_LEN characters long, and must not contain either of the characters ‘\’ or ‘/’:

FSVol_Open("sd:0:"          (a) 
           "sd:0:"          (b)
          (void *)0,
           &err);

In this case, the name of the volume (a) is the same as the name as the device (b). When multiple volumes exist in the same application, the volume name should be prefixed to the file or directory path name:

p_file = fs_fopen("sd:0:\\dir01\file01.txt", "w");  // File on SD card
p_file = fs_fopen("ram:0:\\dir01\file01.txt", "w"); // File on RAM disk

µC/FS File and Directory Names and Paths

Files and directories are identified by a path string; for example, a file can be opened:

p_file = fs_fopen("\\test\\file001.txt", "w");

An application specifies the path of a file or directory using either an absolute or a relative path. An absolute path is a character string which specifies a unique file, and follows the pattern:In this case, “\\test\\file001.txt” is the path string.

<vol_name>:<... Path ...><File>

where

For example:

p_file = fs_fopen("sd:0:\\file.txt", "w");          (a)
p_file = fs_fopen("\\file.txt", "w");               (b)
p_file = fs_fopen("sd:0:\\dir01\\file01.txt", "w"); (c)
p_file = fs_opendir("sd:0:\\")                      (d)
p_file = fs_opendir("\\")                           (e)
p_file = fs_opendir("sd:0:\\dir01\\")               (f)

Which demonstrate (a) opening a file in the root directory of a specified volume; (b) opening a file in the root directory on a default volume; (c) opening a file in a non-root directory; (d) opening the root directory of a specified volume; (e) opening the root directory of the default volume; (f) opening a non-root directory.

Relative paths can be used if working directories are enabled (FS_CFG_WORKING_DIR_EN is DEF_ENABLED — see Feature Inclusion Configuration). A relative path begins with neither a volume name nor a ‘\’:

<... Relative Path ...><File>

where

Two special path components can be used. “..” moves the path to the parent directory. “.” keeps the path in the same directory (basically, it does nothing).

A relative path is appended to the current working directory of the calling task to form the absolute path of the file or directory. The working directory functions, fs_chdir() and fs_getcwd(), can be used to set and get the working directory.

µC/FS Name Lengths

The configuration constants FS_CFG_MAX_PATH_NAME_LEN, FS_CFG_MAX_FILE_NAME_LEN and FS_CFG_MAX_VOL_NAME_LEN in fs_cfg.h set the maximum length of path names, file names and volume names. The constant FS_CFG_MAX_FULL_NAME_LEN is defined in fs_cfg_fs.h to describe the maximum full name length. The path name begins with a path separator character and includes the file name; the file name is just the portion of the path name after the last (non-final) path separator character. The full name is composed of an explicit volume name (optional) and a path name; the maximum full name length can be calculated:

FullNameLenmax = VolNameLenmax + PathNameLenmax

Figure - File, path and volume name lengths demonstrates these definitions.

Figure - File, path and volume name lengths

No maximum parent name length is defined, though one may be derived. The parent name must be short enough so that the path of a file in the directory would be valid. Strictly, the minimum file name length is 1 character, though some OSs may enforce larger values (eleven on some Windows systems), thereby decreasing the maximum parent name length.

ParentNameLenmax = PathNameLenmax - FileNameLenmin - 1

The constants FS_CFG_MAX_DEV_DRV_NAME_LEN and FS_CFG_MAX_DEV_NAME_LEN in fs_cfg.h set the maximum length of device driver names and device names, as shown in Figure - Device and device driver name lengths. The device name is between three and five characters longer than the device driver name, since the unit number (the integer between the colons of the device name) must be between 0 and 255.

Each of the maximum name length configurations specifies the maximum string length without the NULL character. Consequently, a buffer which holds one of these names must be one character longer than the define value.

Resource Usage

µC/FS resource usage, of both ROM and RAM, depends heavily on application usage. How many (and which) interface functions are referenced determines the code and constant data space requirements. The greater the quantity of file system objects (buffers, files, directories, devices and volumes), the more RAM needed.

Table - ROM Requirements gives the ROM usage for the file system core, plus additional components that can be included optionally, collected on IAR EWARM v6.40.1. The ‘core’ ROM size includes all file system components and functions (except those itemized in the table); this is significantly larger than most installations because most applications use a fraction of the API.

*Includes code and data for all file system components and functions except those itemized in the table.

RAM requirements are summarized in Table - RAM Requirements. The total depends on the number of each object allocated and the maximum sector size (set by values passed to FS_Init() in the file system configuration structure), and various name length configuration parameters (see Name Restriction Configuration, “FS_CFG_MAX_PATH_NAME_LEN”).

§ The number of tasks that use relative path names

See also Driver Characterization for ROM/RAM characteristics of file system suite drivers.