Jump to main content

##

# 1.2.7.4.3 SYS_FS_Mount Function

## C

    SYS_FS_RESULT SYS_FS_Mount
    (
        const char *devName,
        const char *mountName,
        SYS_FS_FILE_SYSTEM_TYPE filesystemtype,
        unsigned long mountflags,
        const void *data
    );

## Summary

Mounts the disk/volume with specified file system.

## Description

The mount command attaches the file system specified to a volume. The call to the mount should be non blocking in nature. The application code has to allow the SYS_FS_Tasks to run periodically while calling the SYS_FS_Mount function.

If the SYS_FS_Mount is called in a blocking mode, then the SYS_FS_Tasks() never gets a chance to run and therefore, the media will not be analyzed and finally, the SYS_FS_Mount will never succeed. This will result in a deadlock.

There is no mechanism available for the application to know if the specified volume (devName) is really attached or not. The only available possibility is to keep trying to mount the volume (with the devname), until success is achieved or use the Automount feature.

It is prudent that the application code implements a time-out mechanism while trying to mount a volume (by calling SYS_FS_Mount). The trial for mount should continue at least 10 times before assuming that the mount will never succeed. This has to be done for every new volume to be mounted.

Once the mount is successful the application needs to use SYS_FS_Error() API to know if the mount was successful with valid filesystem on media or not. If SYS_FS_ERROR_NO_FILESYSTEM is returned application needs to Format the media using the SYS_FS_DriveFormat() API before performing any operations.

The standard names for volumes (devName) used in the MPLAB Harmony file system is as follows:

- NVM - "nvm" "media number" "volume number"
- SD card - "mmcblk" "media number" "volume number"
- MSD - "sd" "media number" "volume number"
- Flash - "mtd" "media number" "volume number"

Where,

- "media number" a, b, c... depends on the number of the type of connected media
- "volume number" 1, 2, 3... depends on the number of partitions in that media.

The convention for assigning names to volumes is further described below with examples:

If a SD card (with four partitions) is attached to the system, and assuming all four partitions are recognized, there will be four devNames:

- mmcblka1
- mmcblka2
- mmcblka3 and
- mmcblka4

Subsequently, if NVM media is attached that has only one partition, the devname will be: nvma1.

Later, if another SD card is attached to the system that has one partition, the devname will be mmcblkb1.

Finally, there will be six volume names (or devNames), which are available for the application to be mounted and used for the file system.

## Precondition

The "devName" name for the volume has to be known. The file system type with which each of the volumes are formatted has to be known.

Trying to mount a volume with a file system which is different from what the volume is actually formatted, will cause mount failure.

## Parameters

Param | Description
--- | ---
devName | The device name (name of volume) which needs to be mounted. The devName has to be preceded by the string "/dev/".
mountName | Mount name for the device to be mounted. This is a name provided by the user. In future, while accessing the mounted volume (say, during SYS_FS_FileOpen operation), the mountName is used to refer the path for file. The mount name has to be preceded by the string "/mnt/"
filesystemtype | Native file system of SYS_FS_FILE_SYSTEM_TYPE type.
mountflags | Mounting control flags. This parameter is reserved for future enhancements. Therefore, always pass zero.
data | The data argument is interpreted by the different file systems. This parameter is reserved for future enhancements. Therefore, always pass NULL.

## Returns

SYS_FS_RES_SUCCESS - Mount was successful.

SYS_FS_RES_FAILURE - Mount was unsuccessful. The reason for the failure can be retrieved with SYS_FS_Error.

## Example

    switch(appState)
    {
        case TRY_MOUNT:
        {
            if(SYS_FS_Mount("/dev/mmcblka1", "/mnt/myDrive", FAT, 0, NULL) != SYS_FS_RES_SUCCESS)
            {
                // Failure, try mounting again
            }
            else
            {
                // Mount was successful. Check for File System

                if (SYS_FS_Error() == SYS_FS_ERROR_NO_FILESYSTEM)
                {
                    //Perform Driver Format operation as there is no filesystem on media
                    SYS_FS_DriveFormat(...);
                }

                appState = DO_FURTHER_STUFFS;
            }
        }
        break;
    }

## Remarks

None