System Routines

System Routines initialize the File System or Drive. More...

Functions
fsStatus	finit (const char *drive)
	Initialize File System and drive related driver. More...
fsStatus	funinit (const char *drive)
	Uninitialize File System. More...
fsStatus	fmount (const char *drive)
	Mount drive. More...
fsStatus	funmount (const char *drive)
	Unmount drive. More...
uint32_t	fversion (void)
	Retrieve the File System component version. More...

Description

System Routines initialize the File System or Drive.

The following diagram shows the basic flow of how to call the system routines to get access to a drive and a drive's media:

1. Call finit to initialize the drive itself.
2. Call fmount to get access to the drive's media.
3. Work with the media.
4. Call funmount to give up access to the media.
5. Call funinit to uninitialize the drive.

Basic Flow Diagram for Calling System Routines

The routines are thread safe.

Code Example

void main (void) {
  FILE *f;
 
  // Initialize the M: drive.
  if (finit ("M:") != fsOK) {
    // error handling
  ...
  }
  // Mount the M: drive.
  if (fmount ("M:") != fsOK) {
    // error handling
  ...
  }
  // Update a log file on SD card.
  f = fopen ("M:\\Logs\\Test_file.log","a");
  if (f == NULL) {
    // error handling
  ...
  }
  else {
    // write data to file
    fclose (f);
  }
  // The drive is no more needed.
  funmount ("M:");
  funinit ("M:");
  ..
}

Function Documentation

finit()

fsStatus finit

(

const char *

drive

)

Initialize File System and drive related driver.

Parameters

[in]

drive

a string specifying the memory or storage device.

Returns

execution status fsStatus

• fsOK = Operation successful.
• fsInvalidParameter = Input parameter invalid.
• fsInvalidDrive = Nonexistent drive letter specified.
• fsDriverError = Failed to initialize the driver.
• fsError = System resource create failed.

The function finit initializes the software library resources required for a certain drive, including the File System and the related driver. It must be called before invoking any other function accessing the file system of the drive. Calling finit does not access the actual media on the specified drive. Before working with the drive's media, a call to fmount is required. fmount checks if the media is present and formatted. finit fails if the File System Component in general or the driver cannot be initialized.

Once the drive is successfully initialized, all subsequent calls of finit will return execution status fsOK, leaving internal drive state unchanged.

The argument drive specifies the Drives, Memory Devices and Drivers to be initialized. Every drive that is used in the system must be initialized separately using this function. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

Note

Function finit initializes operating system resources and should not be called from multiple threads.

fmount()

fsStatus fmount

(

const char *

drive

)

Mount drive.

Parameters

[in]

drive

a string specifying the memory or storage device.

Returns

execution status fsStatus

• fsOK = Operation successful.
• fsUninitializedDrive = Media driver not initialized.
• fsInvalidParameter = Input parameter invalid.
• fsInvalidDrive = Nonexistent drive letter specified.
• fsDriverError = Media driver operation failed.
• fsMediaError = Failed to initialize the media.
• fsNoMedia = Media device is not insterted.
• fsNoFileSystem = No filesystem on the volume.

The function fmount is used to mount the File System of the specified Drives, Memory Devices and Drivers. It initializes memory media, media management layer and the file system on top of it. Mounting means that it will be checked if the drive's media is attached and formatted. After a successful mount, drive is ready for file I/O operations (such as fread, fwrite, etc.).

The argument drive specifies the Drives, Memory Devices and Drivers to be mounted. Every drive that is used in the system must be mounted separately using this function. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

The drive that requires formatting also requires operational memory media and therefore fmount shall be called before attempting to format the drive. The memory media is operational when fmount successfully examines the drive and returns with execution status fsOK or fsNoFileSystem. Execution status fsNoFileSystem is returned when the file system on the memory media is not present or is unrecognized.

funinit()

fsStatus funinit

(

const char *

drive

)

Uninitialize File System.

Parameters

[in]

drive

a string specifying the memory or storage device.

Returns

execution status fsStatus

• fsOK = Operation successful.
• fsInvalidParameter = Input parameter invalid.
• fsInvalidDrive = Nonexistent drive letter specified.
• fsError = System resource delete failed.

The funinit function uninitializes the File System. This is necessary if during application run time the drive volume needs to be disabled (for example for lowering power consumption). To reinitialize the drive afterwards, finit needs to be called again.

The execution of funinit is unconditional and will always uninitialize available drive resources.

The argument drive specifies the Drives, Memory Devices and Drivers to be uninitialized. Every drive that is used in the system must be uninitialized separately using this function. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

Note

Function funinit uninitializes operating system resources and should not be called from multiple threads.

funmount()

fsStatus funmount

(

const char *

drive

)

Unmount drive.

Parameters

[in]

drive

a string specifying the memory or storage device.

Returns

execution status fsStatus

• fsOK = Operation successful.
• fsInvalidParameter = Input parameter invalid.
• fsInvalidDrive = Nonexistent drive letter specified.

The function funmount is used to unmount a File System volume. When called, it flushes the data from internal file system buffers, closes all opened file handlers associated with the specified drive and disconnects the memory media. In case when removable memory media is not present only file handlers associated with the specified drive are closed.

The argument drive specifies the Drives, Memory Devices and Drivers to be unmounted. Every drive that is used in the system must be unmounted separately using this function. The Current Drive is used if an empty string is provided. A NULL pointer is not allowed and will be rejected.

fversion()

uint32_t fversion

(

void

)

Retrieve the File System component version.

Returns

BCD encoded version: 0xMMmmbbbb (MM:major, mm:minor, bbbb:build)

The function fversion retrieves the version of the File System component. Returned version is encoded in BCD format 0xMMmmbbbb where MM represents major version, mm minor version and bbbb build version.

Code Example

void print_version (void) {
  uint32_t fs_ver;
 
  fs_ver = fversion();
 
  // Extract and printf FileSystem version
  printf ("Major: %d%d, Minor: %d%d, Build: %d%d%d%d\n", \
          (fs_ver >> 28) & 0xF, (fs_ver >> 24) & 0xF,    \
          (fs_ver >> 20) & 0xF, (fs_ver >> 16) & 0xF,    \
          (fs_ver >> 12) & 0xF, (fs_ver >> 8)  & 0xF,    \
          (fs_ver >>  4) & 0xF, (fs_ver & 0xF));
}