File System Component  Version 6.14.1
MDK Middleware for Devices with Flash File System
 All Data Structures Files Functions Variables Enumerations Enumerator Macros Groups Pages
Utility Routines

Utility Routines provide analytical and utility operations on drives. More...

Functions

fsStatus fchdrive (const char *drive)
 Change current drive. More...
 
int64_t ffree (const char *drive)
 Find free space on drive. More...
 
fsStatus fformat (const char *drive, const char *options)
 Format drive. More...
 
int32_t fanalyse (const char *drive)
 Analyse volume and check for file fragmentation. More...
 
fsStatus fcheck (const char *drive)
 Analyse volume and check for allocation errors. More...
 
fsStatus fdefrag (const char *drive)
 Defragment Embedded Flash drive. More...
 
fsStatus fmedia (const char *drive)
 Check if media present on removable drive. More...
 
fsStatus finfo (const char *drive, fsDriveInfo *info)
 Read drive information. More...
 
fsStatus fvol (const char *drive, char *label, uint32_t *serial)
 Read volume label and serial number. More...
 

Description

Utility Routines provide analytical and utility operations on drives.

You can change current drive, print working directory, analyse, format, and defragment drives. Also, reading drive and volume information data is supported.

Function Documentation

int32_t fanalyse ( const char *  drive)

Analyse volume and check for file fragmentation.

Parameters
[in]drivea string specifying the memory or storage device.
Returns
fragmentation factor or execution status
  • value >= 0 or <= 255: fragmentation factor
  • value < 0: error occurred, -value is execution status as defined with fsStatus
Note
This function supports EFS drives only.

The function fanalyse examines the Embedded File System and checks for file fragmentation.

The argument drive specifies the Drives, Memory Devices and Drivers to be analysed. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

Code Example

void free_space (void) {
printf ("\nFree space before defrag: %d bytes.", ffree(""));
if (fanalyse("") > 50) {
fdefrag ("");
}
printf ("\nFree space after defrag: %d bytes.", ffree(""));
}
fsStatus fchdrive ( const char *  drive)

Change current drive.

Parameters
[in]drivea string specifying the memory or storage device.
Returns
execution status fsStatus

The function fchdrive changes the Current Drive.

The argument drive specifies the Drives, Memory Devices and Drivers to be selected as the Current Drive. A NULL pointer is not allowed and will be rejected.

fsStatus fcheck ( const char *  drive)

Analyse volume and check for allocation errors.

Parameters
[in]drivea string specifying the memory or storage device.
Returns
execution status fsStatus
  • fsOK = Operation successful, no allocation errors.
  • fsInvalidDrive = Nonexistent drive letter specified.
  • fsUnsupported = FAT drive was specified.
  • fsError = Check failed due to allocation errors.
Note
This function supports EFS drives only.

The function fcheck analyses the consistency of the Embedded File System and determines if it has been initialized.

The argument drive specifies the Drives, Memory Devices and Drivers to be checked. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

Code Example

void tst_files (void) {
if (fcheck ("F:") != fsOK) {
printf ("Embedded File System inconsistent, formatting...\n");
if (fformat ("F:") != fsOK) {
printf ("Formatting failed.\n");
}
else {
printf ("Format done.\n");
}
}
}
fsStatus fdefrag ( const char *  drive)

Defragment Embedded Flash drive.

Parameters
[in]drivea string specifying the memory or storage device.
Returns
execution status fsStatus
  • fsOK = Operation successful.
  • fsInvalidDrive = Nonexistent drive letter specified.
  • fsAccessDenied = Not all files are closed on specified drive or unsupported drive.
  • fsNoFreeSpace = Not enough space to complete the defragmentation.
Note
This function supports EFS drives only.

The function fdefrag de-fragments the Embedded File System. Drive is examined for used blocks which are without valid file allocation records. Such blocks are erased and marked as empty. Fragmented files are consolidated. The result of file consolidation is faster file access and increased overall performance.

The argument drive specifies the Drives, Memory Devices and Drivers to be de-fragmented. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

Code Example

void free_space (void) {
printf ("\nFree space before defrag: %d bytes.", ffree("F:"));
if (fanalyse("F:") > 50) {
fdefrag ("F:");
}
printf ("\nFree space after defrag: %d bytes.", ffree("F:"));
}
fsStatus fformat ( const char *  drive,
const char *  options 
)

Format drive.

Parameters
[in]drivea string specifying the memory or storage device.
[in]optionsstring specifying formatting options.
Returns
execution status fsStatus

The function fformat formats an EFS or FAT storage media for using a file system. The function closes all open files on the specified drive. Existing file handles become invalid.

The argument drive specifies the Drives, Memory Devices and Drivers. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

The argument options can be pointer to a string or NULL when formatting options are not used.

FAT drive formatting options:

Option Description
/L label Specifies volume label. If /L option is not specified or if label is not given, then volume label will not be written. Terminating character for label can be slash (/) or NUL character. Trailing spaces will be ignored.
/FAT32 Formats the media for using the FAT32 file system. FAT32 can be used on media devices with size >= 256MB.
/W Clears all data. Erases all available data sectors.
/LL Clears all data. Performs low-level formatting first (NAND drive only).
/LLEB Clears all data. Performs low-level formatting and erases bad blocks first (NAND drive only). /LLEB has higher priority than /LL in case if both options are specified.
/<other> Unknown options are ignored.

When formatting option /FAT32 is not used, the media device will be formatted using default, predefined settings. The file system type depends then on media device size and will be chosen as follows:

  • FAT12 for devices with < 128MB
  • FAT16 for devices with >= 128MB and <= 2GB
  • FAT32 for devices with > 2GB

EFS drive formatting options:

There are no special formatting options available for the Embedded File System. Argument options is ignored.

Note
Before formatting the drive, fmount must be called to initialize the memory media and media management layer.

Code Example

void format_drive (void) {
char *opt;
// Set formatting options
opt = "/L SD Card /FAT32";
if (fformat ("M:", opt) != fsOK) {
printf ("Formatting failed!\n");
}
else {
printf ("Drive formatted using FAT 32 with label SD Card.\n");
}
}
int64_t ffree ( const char *  drive)

Find free space on drive.

Parameters
[in]drivea string specifying the memory or storage device.
Returns
free space or execution status
  • value >= 0: free space on drive in bytes.
  • value < 0: error occurred, -value is execution status as defined with fsStatus

The function ffree calculates the free space on a device.

The argument drive specifies the Drives, Memory Devices and Drivers. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

Code Example

void free_space (void) {
printf ("Flash Drive free: %lld bytes.\n", ffree("F:"));
printf ("Ram Drive free: %lld bytes.\n", ffree("R:"));
printf ("SD Card Drive 1 free: %lld bytes.\n", ffree("M0:"));
printf ("SD Card Drive 2 free: %lld bytes.\n", ffree("M1:"));
}
fsStatus finfo ( const char *  drive,
fsDriveInfo info 
)

Read drive information.

Parameters
[in]drivea string specifying the memory or storage device.
[out]infodrive information structure.
Returns
execution status fsStatus
  • fsOK = Operation successful.
  • fsInvalidParameter = Input parameters invalid.
  • fsInvalidDrive = Nonexistent drive letter specified.
  • fsAccessDenied = Specified drive is not mounted.

The function finfo reads general drive informations from the volume and puts them into the info structure.

The argument drive specifies the Drives, Memory Devices and Drivers. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

fsStatus fmedia ( const char *  drive)

Check if media present on removable drive.

Parameters
[in]drivea string specifying the memory or storage device.
Returns
execution status fsStatus
  • fsOK = Operation successful, media is present.
  • fsNoMedia = Media not present.
  • fsUnsupported = Media presence cannot be determined.
  • fsAccessDenied = Tried to access non-removable drive.
Note
This function supports FAT drives only.

The function fmedia uses media device interface driver to detect the presence of a removable drive in the system (such as SD/MMC cards or USB Flash drives). In case of SD/MMC cards, it can be used even when card socket does not provide card detection pin, but only after a successful device initialization (i.e. after a successful call of fmount or fs_ioc_device_ctrl using fsDevCtrlCodeControlMedia). In such case, device presence is determined using internal register states.

The argument drive specifies the Drives, Memory Devices and Drivers. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

fsStatus fvol ( const char *  drive,
char *  label,
uint32_t *  serial 
)

Read volume label and serial number.

Parameters
[in]drivea string specifying the memory or storage device.
[out]labelbuffer for storing label as a null terminated string. When volume has no label an empty string is returned. This parameter can be NULL meaning label will not be read.
[out]serialpointer to variable where serial number will be stored. This parameter can be NULL meaning serial number will not be read.
Returns
execution status fsStatus
  • fsOK = Operation successful.
  • fsInvalidDrive = Nonexistent drive letter specified.
  • fsAccessDenied = Trying to read label and serial from EFS drive.
  • fsDriverError = Read/write error.
Note
This function supports FAT drives only.

The function fvol reads the volume label.

The argument drive specifies the Drives, Memory Devices and Drivers. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

The argument label specifies a buffer where the volume label will be stored as a null terminated string. Its size must be at least 12 bytes to prevent buffer overflow. If volume has no label an empty string is returned.

The argument serial specifies a pointer to a 32-bit variable where the volume serial number will be stored. The serial number is usually written when the volume is formatted and can be used to distinguish between volumes on removable devices.

Code Example

void tst_fvol (void) {
char label[12];
uint32_t ser_num;
if (fvol("U0:", label, &ser_num) == fsOK) {
if (label_buf[0]) {
printf ("Volume in drive U0 is %s\n", label);
}
else {
printf ("Volume in drive U0 has no label.\n");
}
printf ("Volume serial number is %x\n", ser_num);
}
else {
printf ("Volume access error!\n");
}
}