Skip to end of metadata
Go to start of metadata

This section explains the possible methods to handle removable media, and optionally fixed media.

Handling Synchronous Connection and Disconnection

The synchronous approach to media connection and disconnection handling is simple: presume that the media exists, is connected, and relies on returned errors (most likely an IO error) to detect disconnections. This approach is more naturally fitted for fixed media, but can be used for removable media as well. Consider an application where a USB key is guaranteed to remain physically connected, for instance. In this context, it would make sense to use the synchronous approach even though the USB device is fundamentally a removable media.

Handling Asynchronous Connection and Disconnection

The asynchronous notification is available when FS_STORAGE_CFG_MEDIA_POLL_TASK_EN is set to DEF_ENABLED in fs_storage_cfg.h.

In order to receive the notifications, all you need to do is register two callbacks, one for connection and one for disconnection, using the FSStorage_ConfigureMediaConnCallback() API. Upon media connection or disconnection, the Media Poll task will call the corresponding application callback and pass the media handle as an argument.  Listing - Media Connection / Disconnection Motification Mechanism Usage shows a minimal example of the notification mechanism where the user-provided callbacks merely print a message on the standard output each time a connection or disconnection event occurs. In a real-world context, the callback would typically post another task responsible for the actual event handling.

#define  APP_FS_CFG_MAX_MEDIA_NAME_LEN  20u
 
void  MyConnCb (FS_MEDIA_HANDLE  media_handle)
{
    RTOS_ERR  err;
    CPU_CHAR  name[APP_FS_CFG_MAX_MEDIA_NAME_LEN + 1u];      /* +1 for null character terminating string. */
    
    FSMedia_NameGet(media_handle, name, sizeof(name), &err);
    if (err.Code == RTOS_ERR_NONE) {
        printf("Media '%s' connected!\r\n", name);
    }
}

void  MyDisconnCb (FS_MEDIA_HANDLE  media_handle)				(1)
{
    RTOS_ERR  err;
    CPU_CHAR  name[APP_FS_CFG_MAX_MEDIA_NAME_LEN + 1u];      /* +1 for null character terminating string. */
    
    FSMedia_NameGet(media_handle, name, sizeof(name), &err);
    if (err.Code == RTOS_ERR_NONE) {
        printf("Media '%s' disconnected!\r\n", name);
    }
}

/* ... */

RTOS_ERR  err;

FSStorage_ConfigureMediaConnCallback(MyConnCb, MyDisconnCb);

FSStorage_Init(&err)
if (err.Code != RTOS_ERR_NONE) {
    /* An error occurred. Error handling should be added here. */
}

/* From this point on, if a removable media is inserted or removed,
   a corresponding message will be printed on the standard output. */
Listing - Media Connection / Disconnection Motification Mechanism Usage

(1) In the disconnection callback, you could signal a task of your application that a removable media has been disconnected. If this task closes an opened volume with FSVol_Close(), you could get an error returned indicating an I/O error (RTOS_ERR_IO). In that case, the error should be considered as a normal situation. Indeed if the FAT journaling module is enabled via the configuration FS_FAT_CFG_JOURNAL_EN, when you close the volume, the File System stack deletes the journal file. Since the removable media (SCSI or SD) has been disconnected, the delete access on the physical media fails and an I/O error is returned.

Figure - Media Poll Task summarizes the usage of the Media Poll task for the asynchronous media detection.

Micrium OS FS Media Poll Task
Figure - Media Poll Task

(1) The Media Poll task interrogates periodically each opened block device to know if a connection or disconnection has occurred.

(2) If a connection or disconnection has been detected, the Media Poll task will call the appropriate application callback. In general, the connection callback will notify a user task about the media connection. For fixed media, the user application is notified only once about the connection. The fixed media disconnection cannot happen of course.

(3) The SCSI media driver has the ability to notify the application about a device presence without using the Media Poll task's help. Refer to the section Detection Regarless of Media Poll Task Presence for more details.

SCSI Removable Media

Detection Regarless of Media Poll Task Presence

As explained in the section Media, which describes the media's physical nature, SD card and SCSI media types are considered to be removable media. Yet there is a difference between an SD card and a SCSI device: their persistence. From the File System perspective, an SD card is said to be persistent, as opposed to a SCSI device, which is non-persistent. This difference makes it possible for the SCSI storage driver to be independent from the Media Poll task presence. That is, regardless of the Media Poll task configuration (#define FS_STORAGE_CFG_MEDIA_POLL_TASK_EN in fs_storage_cfg.h), the user callbacks will always be called upon SCSI device connection or disconnection. If you want to perform file accesses on a SCSI device, you must rely on the application connection callbacks called by File System. On the other hand, if the Media Poll task is disabled, an SD card will not be detected asynchronously. You can still detect an SD card synchronously if the SD card is always inserted in the SD slot.

Automatic Media Naming

As described in the section Media, a media name is assigned by you to NAND, NOR, RAM disk and SD so that they are registered in the Platform Manager and known from Micrium OS File System for properly configuring them. SCSI devices are a bit different because the media name is internally assigned by the SCSI media driver upon the device's connection. While you have full control on the media name for NAND, NOR, RAM disk and SD, the SCSI media name follows this format:

"scsiXXYY" where XX is a unique ID assigned to the connected SCSI device and YY is the logical unit number (a SCSI device is composed of one to N logical units). 

When your application connection callback is called upon the SCSI device connection's detection, you have access to the SCSI media handle as shown in Listing - Media Connection / Disconnection Motification Mechanism Usage. If this media handle is passed to the function FSMedia_NameGet(), you will get for example the SCSI device with the name "scsi0001".

Micrium OS USB Host's Hub Task

The SCSI media driver works with Micrium OS USB Host to transport the SCSI commands over USB to memory sticks and memory card readers. Micrium OS USB Host has an internal task called the hub task responsible for all the hub-related events such as device connection, disconnection, etc. When a SCSI device connects to an embedded USB host, the USB Host hub task calls a connection callback provided by the SCSI media driver. Then this SCSI media driver's callback calls your application connection callback. This situation occurs only if the Media Poll task is disabled (#define FS_STORAGE_CFG_MEDIA_POLL_TASK_EN set to DEF_DISABLED in fs_storage_cfg.h). Within your application callback, you could call any functions that perform a file operation such as FSFile_Open(), FSFile_Rd(), etc. When calling these type of functions, several media read/write accesses can be done by the SCSI media driver passing through the different layers of Micrium OS USB Host stack. At this point, all the functions call stack is done within the USB Host hub task's context. For that specific case, the hub task must have a stack size large enough to accommodate worst case scenario of call stack. The default hub task's stack size is 768 elements as indicated in Table - Micrium OS Internal tasks. This stack size value should be sufficient for most typical cases. In general, your application connection callback would typically post another task responsible for the actual connection event handling. This other task would perform any file operations and would avoid any hub task's overflow issue. 

  • No labels