[ ]
Real time embedded FreeRTOS mailing list 
Homepage FreeRTOS Labs FreeRTOS+TCP FreeRTOS+FAT FreeRTOS+POSIX Contact / Enquiries


FreeRTOS+FAT is still in the lab
FreeRTOS+FAT is already in use in commercial products and we encourage you to try it yourself. Be aware however that FreeRTOS+FAT was acquired by Real Time Engineers Ltd., and is still being documented and updated to ensure it meets our strict quality standards. Please use the forum for support, or contact us directly if you have a specific business interest.

Creating a Media Driver: The Driver's Initialisation Function
[Creating a FreeRTOS+FAT Media Driver]


Actions performed within a media driver's initialisation
function (* optional steps)
The media driver's initialisation function must allocate an FF_Disk_t structure for use with the media.

The FF_Disk_t structure contains a pointer to an FF_IOManager_t structure. The FF_IOManager_t structure is created by calling FF_CreateIOManager().

For convenience, the media driver can optionally also mount a partition on the media, and add the mounted partition to FreeRTOS+FAT's virtual file system. Performing these two optional steps within the initialisation function removes the need for the application writer to perform them explicitly. The image on the right shows the media driver's initialisation function performing these optional steps.


Worked Example

As an example, below is the outline of the media driver initialisation function used by the FreeRTOS+FAT RAM disk driver. The full version, which includes additional error checking, can be found in /FreeRTOS-Plus/Source/FreeRTOS-Plus-FAT/portable/common/ff_ramdisk.c.


/* The size of each sector on the disk. */
#define ramSECTOR_SIZE                512UL

/* Only a single partition is used.  Partition numbers start at 0. */
#define ramPARTITION_NUMBER            0

/*
In this example:
  - pcName is the name to give the disk within FreeRTOS+FAT's virtual file system.
  - pucDataBuffer is the start of the RAM buffer used as the disk.
  - ulSectorCount is effectively the size of the disk, each sector is 512 bytes.
  - xIOManagerCacheSize is the size of the IO manager's cache, which must be a
   multiple of the sector size, and at least twice as big as the sector size.
*/
FF_Disk_t *FF_RAMDiskInit( char *pcName,
                          uint8_t *pucDataBuffer,
                          uint32_t ulSectorCount,
                          size_t xIOManagerCacheSize )
{
FF_Error_t xError;
FF_Disk_t *pxDisk = NULL;
FF_CreationParameters_t xParameters;

    /* Check the validity of the xIOManagerCacheSize parameter. */
    configASSERT( ( xIOManagerCacheSize % ramSECTOR_SIZE ) == 0 );
    configASSERT( ( xIOManagerCacheSize >= ( 2 * ramSECTOR_SIZE ) ) );

    /* Attempt to allocated the FF_Disk_t structure. */
    pxDisk = ( FF_Disk_t * ) pvPortMalloc( sizeof( FF_Disk_t ) );

    if( pxDisk != NULL )
    {
        /* It is advisable to clear the entire structure to zero after it has been
        allocated - that way the media driver will be compatible with future
        FreeRTOS+FAT versions, in which the FF_Disk_t structure may include
        additional members. */
        memset( pxDisk, '\0', sizeof( FF_Disk_t ) );

        /* The pvTag member of the FF_Disk_t structure allows the structure to be
        extended to also include media specific parameters.  The only media
        specific data that needs to be stored in the FF_Disk_t structure for a
        RAM disk is the location of the RAM buffer itself - so this is stored
        directly in the FF_Disk_t's pvTag member. */
        pxDisk->pvTag = ( void * ) pucDataBuffer;

        /* The signature is used by the disk read and disk write functions to
        ensure the disk being accessed is a RAM disk. */
        pxDisk->ulSignature = ramSIGNATURE;

        /* The number of sectors is recorded for bounds checking in the read and
        write functions. */
        pxDisk->ulNumberOfSectors = ulSectorCount;

        /* Create the IO manager that will be used to control the RAM disk -
        the FF_CreationParameters_t structure completed with the required
        parameters, then passed into the FF_CreateIOManager() function. */
        memset (&xParameters, '\0', sizeof xParameters);
        xParameters.pucCacheMemory = NULL;
        xParameters.ulMemorySize = xIOManagerCacheSize;
        xParameters.ulSectorSize = ramSECTOR_SIZE;
        xParameters.fnWriteBlocks = prvWriteRAM;
        xParameters.fnReadBlocks = prvReadRAM;
        xParameters.pxDisk = pxDisk;

        /* The driver is re-entrant as it just accesses RAM using memcpy(), so
        xBlockDeviceIsReentrant can be set to pdTRUE.  In this case the
        semaphore is only used to protect FAT data structures, and not the read
        and write function. */
        xParameters.pvSemaphore = ( void * ) xSemaphoreCreateRecursiveMutex();
        xParameters.xBlockDeviceIsReentrant = pdTRUE;


        pxDisk->pxIOManager = FF_CreateIOManger( &xParameters, &xError );

        if( ( pxDisk->pxIOManager != NULL ) && ( FF_isERR( xError ) == pdFALSE ) )
        {
            /* Record that the RAM disk has been initialised. */
            pxDisk->xStatus.bIsInitialised = pdTRUE;

            /* Create a partition on the RAM disk.  NOTE!  The disk is only
            being partitioned here because it is a new RAM disk.  It is
            known that the disk has not been used before, and cannot already
            contain any partitions.  Most media drivers will not perform
            this step because the media will already been partitioned and
            formatted. */
            xError = prvPartitionAndFormatDisk( pxDisk );

            if( FF_isERR( xError ) == pdFALSE )
            {
                /* Record the partition number the FF_Disk_t structure is, then
                mount the partition. */
                pxDisk->xStatus.bPartitionNumber = ramPARTITION_NUMBER;

                /* Mount the partition. */
                xError = FF_Mount( pxDisk, ramPARTITION_NUMBER );
            }

            if( FF_isERR( xError ) == pdFALSE )
            {
                /* The partition mounted successfully, add it to the virtual
                file system - where it will appear as a directory off the file
                system's root directory. */
                FF_FS_Add( pcName, pxDisk->pxIOManager );
            }
        }
        else
        {
            /* The disk structure was allocated, but the disk's IO manager could
            not be allocated, so free the disk again. */
            FF_RAMDiskDelete( pxDisk );
            pxDisk = NULL;
        }
    }

    return pxDisk;
}
						
The outline of a media driver's initialisation function











[ Back to the top ]    [ About FreeRTOS ]    [ Privacy ]    [ FreeRTOS Labs Sitemap ]    [ Main FreeRTOS Sitemap ]    [ ]




Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.