Skip to end of metadata
Go to start of metadata

This section describes how to set up and open a block device instance. The procedure is the same no matter which underlying media type is used, so the provided examples can be used to set up a block device on a variety of media types, including SD card, SCSI logical unit, RAM disk or NOR/NAND flash memory. There are, however, advanced configurations and APIs that are media-specific. Refer to the NAND, NOR and SD-specific options in the subsection Storage Configuration for more details about media-specific advanced configurations. Refer also to Media-Specific Operations for more details about media-specific functions.

Initializing the Storage Sub-Module

Listing - Initializing the Block Device Sub-Module illustrates how to initialize the file system's storage sub-module. The function FSStorage_Init() allocates and initializes internal data structures, and should be called only once. The storage sub-module can be configured using the optional advanced configuration API covered in File System Run-time Configuration.

RTOS_ERR  err;

FSStorage_Init(&err);
if (err.Code != RTOS_ERR_NONE) {
    /* An error occurred. Error handling should be added here. */
}
Listing - Initializing the Block Device Sub-Module

Opening and Closing a Block Device

Once the storage sub-module is initialized, the block device is ready to be opened. A block device can be opened using FSBlkDev_Open() and closed using FSBlkDev_Close(), as shown in Listing - Opening a Block Device. Notice the call to FSMedia_Get() embedded in the FSBlkDev_Open() function call. Though it is not the only way of retrieving and providing a media handle to FSBlkDev_Open(), this is a compact and convenient way of doing so, based on the media name (see File System Basic Concepts for more details on media and media names).

FS_BLK_DEV_HANDLE  blk_dev_handle;
RTOS_ERR           err;

blk_dev_handle = FSBlkDev_Open(FSMedia_Get("sd0"), &err);
if (err.Code != RTOS_ERR_NONE) {
    /* An error occurred. Error handling should be added here. */
}

/* The block device handle can be used here to perform block device operations. */

FSBlkDev_Close(blk_dev_handle, &err); 
if (err.Code != RTOS_ERR_NONE) {
    /* An error occurred. Error handling should be added here. */
}
Listing - Opening a Block Device

Low-Level Formatting Storage Media

NOR and NAND flash memories need to be low-level formatted before a block device can be opened on top of them. This can be done using FSMedia_LowFmt() as shown in Listing - Low-Level Formatting a Media. The first example (version 1) shows the situation where you want to low-level format the media explicitly, regardless of any existing on-disk formatting information. Version 2 shows a generic way to low-level format only if the media has an invalid format. For media other than NOR and NAND flash memories, FSMedia_LowFmt() does nothing.

FS_MEDIA_HANDLE    media_handle;
FS_BLK_DEV_HANDLE  blk_dev_handle;
RTOS_ERR           err;
                                                                /* ---------------- VERSION 1 ---------------- */
media_handle = FSMedia_Get("nand0");                               (1)
FSMedia_LowFmt(media_handle, &err);                                (2)
if (err.Code != RTOS_ERR_NONE) {
    /* An error occurred. Error handling should be added here. */
}

blk_dev_handle = FSBlkDev_Open(media_handle, &err);                (3)
if (err.Code != RTOS_ERR_NONE) {
    /* An error occurred. Error handling should be added here. */
}
                                                                /* ---------------- VERSION 2 ---------------- */
media_handle   = FSMedia_Get("nand0");                             (4)
blk_dev_handle = FSBlkDev_Open(media_handle, &err);                (5)
if (err.Code != RTOS_ERR_NONE) {
    if (err.Code == RTOS_ERR_BLK_DEV_FMT_INVALID) {                (6)
        FSMedia_LowFmt(media_handle, &err);                        
        if (err.Code != RTOS_ERR_NONE) {
            /* An error occurred. Error handling should be added here. */
        }
    } else {
        /* An error occurred. Error handling should be added here. */
    }
    blk_dev_handle = FSBlkDev_Open(media_handle, &err);            (7)
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occurred. Error handling should be added here. */
    }
}
Listing - Low-Level Formatting a Media

(1) In Version 1, the media handle associated with the string ID nand0 is obtained.

(2) Low-level format is performed explicitly regardless of the media on-disk formatting information.

(3) A block device is open on the media. A block device handle is obtained and can be used to open a volume on the media.

(4) In Version 2, once again the media handle associated to the string ID nand0 is retrieved.

(5) This time an attempt to open a block device on the media is done. If the open operation succeeds, it means that the media has a valid format and you can continue by opening a volume for instance.

(6) If the block device open operation fails, the error type is checked. If it matches RTOS_ERR_BLK_DEV_FMT_INVALID meaning invalid format, a low-level format is performed by calling FSMedia_LowFmt().

The low-level format is required only for NAND and NOR devices. Other media types such as SD or RAM disk do not need a low-level format. If FSMedia_LowFmt() is called for SD or RAM disk, the function does nothing and returns successfully.

(7) Upon success of FSMedia_LowFmt(), a new attempt to open the block device on the media is done. This block device opening should be successful.

  • No labels