amt630hv160-sdk-release/amt630hv160-freertos-beta/FreeRTOS-Plus/FreeRTOS-FAT/include/ff_ioman.h

/*
 * FreeRTOS+FAT V2.3.3
 * Copyright (C) 2021 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 * https://www.FreeRTOS.org
 * https://github.com/FreeRTOS
 *
 */

/**
 *	@file		ff_ioman.h
 *	@ingroup	IOMAN
 **/

#ifndef _FF_IOMAN_H_
    #define _FF_IOMAN_H_

    #ifdef __cplusplus
        extern "C" {
    #endif

    #include <stdlib.h> /* Use of malloc() */

    #ifndef PLUS_FAT_H
        #error this header will be included from "ff_headers.h"
    #endif

    #define FF_T_FAT12                      0x0A
    #define FF_T_FAT16                      0x0B
    #define FF_T_FAT32                      0x0C

    #define FF_MODE_READ                    0x01                             /* Buffer / FILE Mode for Read Access. */
    #define FF_MODE_WRITE                   0x02                             /* Buffer / FILE Mode for Write Access. */
    #define FF_MODE_APPEND                  0x04                             /* FILE Mode Append Access. */
    #define FF_MODE_CREATE                  0x08                             /* FILE Mode Create file if not existing. */
    #define FF_MODE_TRUNCATE                0x10                             /* FILE Mode Truncate an Existing file. */
    #define FF_MODE_VIRGIN                  0x40                             /* Buffer mode: do not fetch content from disk. Used for write-only buffers. */
    #define FF_MODE_DIR                     0x80                             /* Special Mode to open a Dir. (Internal use ONLY!) */

    #define FF_MODE_RD_WR                   ( FF_MODE_READ | FF_MODE_WRITE ) /* Just for bit filtering. */

/* The buffer write-only mode saves a fetch from disk.
 * The write-only mode is used when a buffer is needed just
 * for clearing sectors. */
    #define FF_MODE_WR_ONLY                 ( FF_MODE_VIRGIN | FF_MODE_WRITE ) /* Buffer for Write-only Access (Internal use ONLY!) */

    #define FF_BUF_MAX_HANDLES              0xFFFF                             /* Maximum number handles sharing a buffer. (16 bit integer, we don't want to overflow it!) */

    #define FF_MAX_ENTRIES_PER_DIRECTORY    0xFFFF
    #define FF_SIZEOF_DIRECTORY_ENTRY       32

    #ifndef pdTRUE_SIGNED

/* Temporary solution: eventually the defines below will appear
 * in 'Source\include\projdefs.h' */
        #define pdTRUE_SIGNED       pdTRUE
        #define pdFALSE_SIGNED      pdFALSE
        #define pdTRUE_UNSIGNED     ( ( UBaseType_t ) 1u )
        #define pdFALSE_UNSIGNED    ( ( UBaseType_t ) 0u )
    #endif

/**
 *	I/O Driver Definitions
 *	Provide access to any Block Device via the following interfaces.
 *	Returns the number of blocks actually read or written.
 **/

/**
 *	A special information structure for the FreeRTOS+FAT mass storage device
 *	driver model.
 **/
    typedef struct
    {
        uint16_t BlkSize;
        uint32_t TotalBlocks;
    } FF_DeviceInfo_t;

    #if ( ffconfigHASH_CACHE != 0 )
        #define FF_HASH_TABLE_ENTRY_COUNT    ( ( ffconfigHASH_TABLE_SIZE + 3 ) / 4 )

        struct xHASH_TABLE
        {
            uint32_t ulDirCluster; /* The Starting Cluster of the dir that the hash represents. */
            uint32_t ulNumHandles; /* Number of active Handles using this hash table. */
            uint32_t ulMisses;     /* Number of times this Hash Table was missed, (i.e. how redundant it is). */
            uint32_t ulBitTable[ FF_HASH_TABLE_ENTRY_COUNT ];
        };

        typedef struct xHASH_TABLE FF_HashTable_t;

        void FF_ClearHash( FF_HashTable_t * pxHash,
                           uint32_t ulHash );
        void FF_SetHash( FF_HashTable_t * pxHash,
                         uint32_t ulHash );
        BaseType_t FF_isHashSet( FF_HashTable_t * pxHash,
                                 uint32_t ulHash );
    #endif /* ffconfigHASH_CACHE */

/* A forward declaration for the I/O manager, to be used in 'struct xFFDisk'. */
    struct _FF_IOMAN;
    struct xFFDisk;

    typedef void ( * FF_FlushApplicationHook )( struct xFFDisk * pxDisk );

/*
 * Some low-level drivers also need to flush data to a device.
 * Use an Application hook that will be called every time when
 * FF_FlushCache() is called. The semaphore will still be taken
 * to avoid unwanted reentrancy.
 * For example:
 *
 *     void FTL_FlushData( struct xFFDisk *pxDisk )
 *     {
 *         // You may or may not inspect 'pxDisk'
 *         FTL_FlushTableCache();
 *     }
 *
 * Make sure you bind the function to the disc object, right after creation:
 *
 *    pxDisk->fnFlushApplicationHook = FTL_FlushData;
 */

/* Structure that contains fields common to all media drivers, and can be
 * extended to contain additional fields to tailor it for use with a specific media
 * type. */
    struct xFFDisk
    {
        struct
        {
            /* Flags that can optionally be used by the media driver to ensure the
             * disk has been initialised, registered and mounted before it is accessed. */
            uint32_t bIsInitialised : 1;
            uint32_t bIsMounted : 1;
            uint32_t spare0 : 5;

            /* The partition number on the media described by this structure. */
            uint32_t bPartitionNumber : 8;
            uint32_t spare1 : 16;
        }
        xStatus;

        /* Provided to allow this structure to be extended to include additional
         * attributes that are specific to a media type. */
        void * pvTag;

        /* Points to input and output manager used by the disk described by this
         * structure. */
        struct _FF_IOMAN * pxIOManager;

        /* The number of sectors on the disk. */
        uint32_t ulNumberOfSectors;

        /* See comments here above. */
        FF_FlushApplicationHook fnFlushApplicationHook;

        /* Field that can optionally be set to a signature that is unique to the
         * media.  Read and write functions can check the ulSignature field to validate
         * the media type before they attempt to access the pvTag field, or perform any
         * read and write operations. */
        uint32_t ulSignature;
    };

    typedef struct xFFDisk FF_Disk_t;

    typedef int32_t ( * FF_WriteBlocks_t ) ( uint8_t * pucBuffer,
                                             uint32_t ulSectorAddress,
                                             uint32_t ulCount,
                                             FF_Disk_t * pxDisk );
    typedef int32_t ( * FF_ReadBlocks_t ) ( uint8_t * pucBuffer,
                                            uint32_t ulSectorAddress,
                                            uint32_t ulCount,
                                            FF_Disk_t * pxDisk );

/**
 *	@public
 *	@brief	Describes the block device driver interface to FreeRTOS+FAT.
 **/
    typedef struct
    {
        FF_WriteBlocks_t fnpWriteBlocks; /* Function Pointer, to write a block(s) from a block device. */
        FF_ReadBlocks_t fnpReadBlocks;   /* Function Pointer, to read a block(s) from a block device. */
        FF_Disk_t * pxDisk;              /* Earlier called 'pParam': pointer to some parameters e.g. for a Low-Level Driver Handle. */
    } FF_BlockDevice_t;

/**
 *	@private
 *	@brief	FreeRTOS+FAT handles memory with buffers, described as below.
 *	@note	This may change throughout development.
 **/
    typedef struct
    {
        uint32_t ulSector;      /* The LBA of the Cached sector. */
        uint32_t ulLRU;         /* For the Least Recently Used algorithm. */
        uint8_t * pucBuffer;    /* Pointer to the cache block. */
        uint32_t ucMode : 8,    /* Read or Write mode. */
                 bModified : 1, /* If the sector was modified since read. */
                 bValid : 1;    /* Initially FALSE. */
        uint16_t usNumHandles;  /* Number of objects using this buffer. */
        uint16_t usPersistance; /* For the persistance algorithm. */
    } FF_Buffer_t;

    typedef struct
    {
        #if ( ffconfigUNICODE_UTF16_SUPPORT != 0 )
            FF_T_WCHAR pcPath[ ffconfigMAX_FILENAME ];
        #else
            char pcPath[ ffconfigMAX_FILENAME ];
        #endif
        uint32_t ulDirCluster;
    } FF_PathCache_t;

/**
 *	@private
 *	@brief	FreeRTOS+FAT identifies a partition with the following data.
 *	@note	This may shrink as development and optimisation goes on.
 **/
    typedef struct
    {
        uint32_t ulBeginLBA;      /* LBA start address of the partition. */
        uint32_t ulFATBeginLBA;   /* LBA of the FAT tables. */
        uint32_t ulSectorsPerFAT; /* Number of sectors per Fat. */
        uint32_t ulTotalSectors;
        uint32_t ulDataSectors;
        #if ( ffconfigWRITE_FREE_COUNT != 0 )
            uint32_t ulFSInfoLBA; /* LBA of the FSINFO sector. */
        #endif
        uint32_t ulRootDirSectors;
        uint32_t ulFirstDataSector;
        uint32_t ulClusterBeginLBA;   /* LBA of first cluster. */
        uint32_t ulNumClusters;       /* Number of clusters. */
        uint32_t ulRootDirCluster;    /* Cluster number of the root directory entry. */
        uint32_t ulLastFreeCluster;
        uint32_t ulFreeClusterCount;  /* Records free space on mount. */
        uint32_t ulSectorsPerCluster; /* Number of sectors per Cluster. */

        char pcVolumeLabel[ 12 ];     /* Volume Label of the partition. */

        uint16_t usBlkSize;           /* Size of a Sector Block in bytes. */
        uint16_t usReservedSectors;

        uint8_t ucType;             /* Partition Type Identifier. */
        uint8_t ucBlkFactor;        /* Scale Factor for block sizes above 512! */
        uint8_t ucNumFATS;          /* Number of FAT tables. */
        uint8_t ucPartitionMounted; /* pdTRUE if the partition is mounted, otherwise pdFALSE. */

        #if ( ffconfigPATH_CACHE != 0 )
            FF_PathCache_t pxPathCache[ ffconfigPATH_CACHE_DEPTH ];
            uint32_t ulPCIndex;
        #endif
    } FF_Partition_t;



/**
 *	@public
 *	@brief	FF_IOManager_t Object description.
 *
 *	FreeRTOS+FAT functions around an object like this.
 **/
    #define FF_FAT_LOCK    0x01     /* Lock bit mask for FAT table locking. */
    #define FF_DIR_LOCK    0x02     /* Lock bit mask for DIR modification locking. */
    #define FF_BUF_LOCK    0x04     /* Lock bit mask for buffers. */

/**
 *	@public
 *	@brief	FF_IOManager_t Object. A developer should not touch these values.
 *
 **/
    typedef struct _FF_IOMAN
    {
        FF_BlockDevice_t xBlkDevice; /* Pointer to a Block device description. */
        FF_Partition_t xPartition;   /* A partition description. */
        FF_Buffer_t * pxBuffers;     /* Pointer to an array of buffer descriptors. */
        void * pvSemaphore;          /* Pointer to a Semaphore object. (For buffer description modifications only!). */
        void * FirstFile;            /* Pointer to the first File object. */
        void * xEventGroup;          /* An event group, used for locking FAT, DIR and Buffers. Replaces ucLocks. */
        uint8_t * pucCacheMem;       /* Pointer to a block of memory for the cache. */
        uint16_t usSectorSize;       /* The sector size that IOMAN is configured to. */
        uint16_t usCacheSize;        /* Size of the cache in number of Sectors. */
        uint8_t ucPreventFlush;      /* Flushing to disk only allowed when 0. */
        uint8_t ucFlags;             /* Bit-Mask: identifying allocated pointers and other flags */
        #if ( ffconfigHASH_CACHE != 0 )
            FF_HashTable_t xHashCache[ ffconfigHASH_CACHE_DEPTH ];
        #endif
        void * pvFATLockHandle;
    } FF_IOManager_t;

/* Bit values for 'FF_IOManager_t::ucFlags': */
/* Memory Allocation testing and other flags. */
    #define FF_IOMAN_ALLOC_BUFDESCR               0x01 /* Flags the pxBuffers pointer is allocated. */
    #define FF_IOMAN_ALLOC_BUFFERS                0x02 /* Flags the pucCacheMem pointer is allocated. */
    #define FF_IOMAN_BLOCK_DEVICE_IS_REENTRANT    0x10 /* When true, ffRead/ffWrite are not protected by a semaphore. */
    #if ( ffconfigREMOVABLE_MEDIA != 0 )
        #define FF_IOMAN_DEVICE_IS_EXTRACTED      0x20
    #endif /* ffconfigREMOVABLE_MEDIA */

    typedef struct xFF_CREATION_PARAMETERS
    {
        uint8_t * pucCacheMemory;           /* User provided memory, or use NULL to malloc the cache memory. */
        uint32_t ulMemorySize;              /* Size of the cache memory, must be a multiple of 'ulSectorSize'. */
        BaseType_t ulSectorSize;            /* Sector size, unit for reading/writing to the disk, normally 512 bytes. */
        FF_WriteBlocks_t fnWriteBlocks;     /* A function to write sectors to the device. */
        FF_ReadBlocks_t fnReadBlocks;       /* A function to read sectors from the device. */
        FF_Disk_t * pxDisk;                 /* Some properties of the disk driver. */
        void * pvSemaphore;                 /* Pointer to a Semaphore object. */
        BaseType_t xBlockDeviceIsReentrant; /* Make non-zero if ffRead/ffWrite are re-entrant. */
    } FF_CreationParameters_t;

/*---------- PROTOTYPES (in order of appearance). */

/* PUBLIC (Interfaces): */
    FF_IOManager_t * FF_CreateIOManger( FF_CreationParameters_t * pxParameters,
                                        FF_Error_t * pError );
    FF_Error_t FF_DeleteIOManager( FF_IOManager_t * pxIOManager );
    FF_Error_t FF_Mount( FF_Disk_t * pxDisk,
                         BaseType_t xPartitionNumber );
    FF_Error_t FF_Unmount( FF_Disk_t * pxDisk );
    FF_Error_t FF_FlushCache( FF_IOManager_t * pxIOManager );
    static portINLINE BaseType_t FF_Mounted( FF_IOManager_t * pxIOManager )
    {
        return pxIOManager && pxIOManager->xPartition.ucPartitionMounted;
    }

    int32_t FF_GetPartitionBlockSize( FF_IOManager_t * pxIOManager );

    #if ( ffconfig64_NUM_SUPPORT != 0 )
        uint64_t FF_GetVolumeSize( FF_IOManager_t * pxIOManager );
    #else
        uint32_t FF_GetVolumeSize( FF_IOManager_t * pxIOManager );
    #endif

/* PUBLIC  (To FreeRTOS+FAT Only): */
    int32_t FF_BlockRead( FF_IOManager_t * pxIOManager,
                          uint32_t ulSectorLBA,
                          uint32_t ulNumSectors,
                          void * pBuffer,
                          BaseType_t aSemLocked );
    int32_t FF_BlockWrite( FF_IOManager_t * pxIOManager,
                           uint32_t ulSectorLBA,
                           uint32_t ulNumSectors,
                           void * pBuffer,
                           BaseType_t aSemLocked );
    FF_Error_t FF_IncreaseFreeClusters( FF_IOManager_t * pxIOManager,
                                        uint32_t Count );
    FF_Error_t FF_DecreaseFreeClusters( FF_IOManager_t * pxIOManager,
                                        uint32_t Count );
    FF_Buffer_t * FF_GetBuffer( FF_IOManager_t * pxIOManager,
                                uint32_t ulSector,
                                uint8_t Mode );
    FF_Error_t FF_ReleaseBuffer( FF_IOManager_t * pxIOManager,
                                 FF_Buffer_t * pBuffer );

/* 'Internal' to FreeRTOS+FAT. */
    typedef struct _SPart
    {
        uint32_t ulStartLBA;    /* FF_FAT_PTBL_LBA */
        uint32_t ulSectorCount; /* FF_FAT_PTBL_SECT_COUNT */
        uint32_t
            ucActive : 8,       /* FF_FAT_PTBL_ACTIVE */
            ucPartitionID : 8,  /* FF_FAT_PTBL_ID */
            bIsExtended : 1;
    } FF_Part_t;

    typedef struct _SPartFound
    {
        int iCount;
        FF_Part_t pxPartitions[ ffconfigMAX_PARTITIONS ];
    } FF_SPartFound_t;

/* This function will parse the 4 entries in a partition table: */
    void FF_ReadParts( uint8_t * pucBuffer,
                       FF_Part_t * pxParts );

/* FF_PartitionCount() has now been replaced by FF_PartitionSearch()
 * It will enumerate all valid partitions found
 * If sector-0 happens to be a valid MBR, 1 partition will be returned
 */
    FF_Error_t FF_PartitionSearch( FF_IOManager_t * pxIOManager,
                                   FF_SPartFound_t * pPartsFound );

/* HT : for debugging only. */
    BaseType_t xIsFatSector( FF_IOManager_t * pxIOManager,
                             uint32_t ulSectorNr );
    BaseType_t xNeedLogging( FF_IOManager_t * pxIOManager );
    BaseType_t xIsRootDirSector( FF_IOManager_t * pxIOManager,
                                 uint32_t ulSectorNr );
    const char * pcSectorType( FF_IOManager_t * pxIOManager,
                               uint32_t ulSectorNr );

/* Needed to make this public/private to be used in FF_Partition/FF_Format. */
    void FF_IOMAN_InitBufferDescriptors( FF_IOManager_t * pxIOManager );

    #ifdef __cplusplus
        } /* extern "C" */
    #endif

#endif /* ifndef _FF_IOMAN_H_ */