Useful Information

1 Nomenclature
2 µC/FS Device and Volume Names
3 µC/FS File and Directory Names and Paths
4 µC/FS Name Lengths
5 Resource Usage

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:

sd	The name of the device driver
:	A single colon
0	The unit number
:	A final colon

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

`<vol_name>`	is the name of the volume, identical to the string specified in FSVol_Open().
`<... Path ...>`	is the file path, which must always begin and end with a ‘\’.
`<File>`	is the file (or leaf directory) name, including any extension.

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

`<... Relative Path ...>`	is the file path, which must not begin with a ‘\’ but must end with a ‘\’.
`<File>`	is the file (or leaf directory) name, including any extension.