--- /dev/null
+/*\r
+ * FreeRTOS+FAT build 191128 - Note: FreeRTOS+FAT is still in the lab!\r
+ * Copyright (C) 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.\r
+ * Authors include James Walmsley, Hein Tibosch and Richard Barry\r
+ *\r
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
+ * this software and associated documentation files (the "Software"), to deal in\r
+ * the Software without restriction, including without limitation the rights to\r
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
+ * the Software, and to permit persons to whom the Software is furnished to do so,\r
+ * subject to the following conditions:\r
+ *\r
+ * The above copyright notice and this permission notice shall be included in all\r
+ * copies or substantial portions of the Software.\r
+ *\r
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
+ *\r
+ * https://www.FreeRTOS.org\r
+ *\r
+ */\r
+\r
+/**\r
+ * @file ff_ioman.h\r
+ * @ingroup IOMAN\r
+ **/\r
+\r
+#ifndef _FF_IOMAN_H_\r
+#define _FF_IOMAN_H_\r
+\r
+#ifdef __cplusplus\r
+extern "C" {\r
+#endif\r
+\r
+#include <stdlib.h> /* Use of malloc() */\r
+\r
+#ifndef PLUS_FAT_H\r
+ #error this header will be included from "plusfat.h"\r
+#endif\r
+\r
+#define FF_T_FAT12 0x0A\r
+#define FF_T_FAT16 0x0B\r
+#define FF_T_FAT32 0x0C\r
+\r
+#define FF_MODE_READ 0x01 /* Buffer / FILE Mode for Read Access. */\r
+#define FF_MODE_WRITE 0x02 /* Buffer / FILE Mode for Write Access. */\r
+#define FF_MODE_APPEND 0x04 /* FILE Mode Append Access. */\r
+#define FF_MODE_CREATE 0x08 /* FILE Mode Create file if not existing. */\r
+#define FF_MODE_TRUNCATE 0x10 /* FILE Mode Truncate an Existing file. */\r
+#define FF_MODE_VIRGIN 0x40 /* Buffer mode: do not fetch content from disk. Used for write-only buffers. */\r
+#define FF_MODE_DIR 0x80 /* Special Mode to open a Dir. (Internal use ONLY!) */\r
+\r
+#define FF_MODE_RD_WR ( FF_MODE_READ | FF_MODE_WRITE ) /* Just for bit filtering. */\r
+\r
+/* The buffer write-only mode saves a fetch from disk.\r
+The write-only mode is used when a buffer is needed just\r
+for clearing sectors. */\r
+#define FF_MODE_WR_ONLY ( FF_MODE_VIRGIN | FF_MODE_WRITE ) /* Buffer for Write-only Access (Internal use ONLY!) */\r
+\r
+#define FF_BUF_MAX_HANDLES 0xFFFF /* Maximum number handles sharing a buffer. (16 bit integer, we don't want to overflow it!) */\r
+\r
+#define FF_MAX_ENTRIES_PER_DIRECTORY 0xFFFF\r
+#define FF_SIZEOF_SECTOR 512\r
+#define FF_SIZEOF_DIRECTORY_ENTRY 32\r
+\r
+#ifndef pdTRUE_SIGNED\r
+ /* Temporary solution: eventually the defines below will appear\r
+ in 'Source\include\projdefs.h' */\r
+ #define pdTRUE_SIGNED pdTRUE\r
+ #define pdFALSE_SIGNED pdFALSE\r
+ #define pdTRUE_UNSIGNED ( ( UBaseType_t ) 1u )\r
+ #define pdFALSE_UNSIGNED ( ( UBaseType_t ) 0u )\r
+#endif\r
+/**\r
+ * I/O Driver Definitions\r
+ * Provide access to any Block Device via the following interfaces.\r
+ * Returns the number of blocks actually read or written.\r
+ **/\r
+\r
+/**\r
+ * A special information structure for the FreeRTOS+FAT mass storage device\r
+ * driver model.\r
+ **/\r
+typedef struct\r
+{\r
+ uint16_t BlkSize;\r
+ uint32_t TotalBlocks;\r
+} FF_DeviceInfo_t;\r
+\r
+#if( ffconfigHASH_CACHE != 0 )\r
+ #define FF_HASH_TABLE_ENTRY_COUNT ( ( ffconfigHASH_TABLE_SIZE + 3 ) / 4 )\r
+\r
+ struct xHASH_TABLE\r
+ {\r
+ uint32_t ulDirCluster; /* The Starting Cluster of the dir that the hash represents. */\r
+ uint32_t ulNumHandles; /* Number of active Handles using this hash table. */\r
+ uint32_t ulMisses; /* Number of times this Hash Table was missed, (i.e. how redundant it is). */\r
+ uint32_t ulBitTable[ FF_HASH_TABLE_ENTRY_COUNT ];\r
+ };\r
+\r
+ typedef struct xHASH_TABLE FF_HashTable_t;\r
+\r
+ void FF_ClearHash( FF_HashTable_t *pxHash, uint32_t ulHash );\r
+ void FF_SetHash( FF_HashTable_t *pxHash, uint32_t ulHash );\r
+ BaseType_t FF_isHashSet( FF_HashTable_t *pxHash, uint32_t ulHash );\r
+#endif /* ffconfigHASH_CACHE */\r
+\r
+/* A forward declaration for the I/O manager, to be used in 'struct xFFDisk'. */\r
+struct _FF_IOMAN;\r
+struct xFFDisk;\r
+\r
+typedef void ( *FF_FlushApplicationHook )( struct xFFDisk *pxDisk );\r
+\r
+/*\r
+ * Some low-level drivers also need to flush data to a device.\r
+ * Use an Application hook that will be called every time when\r
+ * FF_FlushCache() is called. The semaphore will still be taken\r
+ * to avoid unwanted reentrancy.\r
+ * For example:\r
+ *\r
+ * void FTL_FlushData( struct xFFDisk *pxDisk )\r
+ * {\r
+ * // You may or may not inspect 'pxDisk'\r
+ * FTL_FlushTableCache();\r
+ * }\r
+ *\r
+ * Make sure you bind the function to the disc object, right after creation:\r
+ *\r
+ * pxDisk->fnFlushApplicationHook = FTL_FlushData;\r
+ */\r
+\r
+/* Structure that contains fields common to all media drivers, and can be\r
+extended to contain additional fields to tailor it for use with a specific media\r
+type. */\r
+struct xFFDisk\r
+{\r
+ struct\r
+ {\r
+ /* Flags that can optionally be used by the media driver to ensure the\r
+ disk has been initialised, registered and mounted before it is accessed. */\r
+ uint32_t bIsInitialised : 1;\r
+ uint32_t bIsMounted : 1;\r
+ uint32_t spare0 : 5;\r
+\r
+ /* The partition number on the media described by this structure. */\r
+ uint32_t bPartitionNumber : 8;\r
+ uint32_t spare1 : 16;\r
+ } xStatus;\r
+\r
+ /* Provided to allow this structure to be extended to include additional\r
+ attributes that are specific to a media type. */\r
+ void * pvTag;\r
+\r
+ /* Points to input and output manager used by the disk described by this\r
+ structure. */\r
+ struct _FF_IOMAN *pxIOManager;\r
+\r
+ /* The number of sectors on the disk. */\r
+ uint32_t ulNumberOfSectors;\r
+\r
+ /* See comments here above. */\r
+ FF_FlushApplicationHook fnFlushApplicationHook;\r
+\r
+ /* Field that can optionally be set to a signature that is unique to the\r
+ media. Read and write functions can check the ulSignature field to validate\r
+ the media type before they attempt to access the pvTag field, or perform any\r
+ read and write operations. */\r
+ uint32_t ulSignature;\r
+};\r
+\r
+typedef struct xFFDisk FF_Disk_t;\r
+\r
+typedef int32_t ( *FF_WriteBlocks_t ) ( uint8_t *pucBuffer, uint32_t ulSectorAddress, uint32_t ulCount, FF_Disk_t *pxDisk );\r
+typedef int32_t ( *FF_ReadBlocks_t ) ( uint8_t *pucBuffer, uint32_t ulSectorAddress, uint32_t ulCount, FF_Disk_t *pxDisk );\r
+\r
+/**\r
+ * @public\r
+ * @brief Describes the block device driver interface to FreeRTOS+FAT.\r
+ **/\r
+typedef struct\r
+{\r
+ FF_WriteBlocks_t fnpWriteBlocks; /* Function Pointer, to write a block(s) from a block device. */\r
+ FF_ReadBlocks_t fnpReadBlocks; /* Function Pointer, to read a block(s) from a block device. */\r
+ FF_Disk_t *pxDisk; /* Earlier called 'pParam': pointer to some parameters e.g. for a Low-Level Driver Handle. */\r
+} FF_BlockDevice_t;\r
+\r
+/**\r
+ * @private\r
+ * @brief FreeRTOS+FAT handles memory with buffers, described as below.\r
+ * @note This may change throughout development.\r
+ **/\r
+typedef struct\r
+{\r
+ uint32_t ulSector; /* The LBA of the Cached sector. */\r
+ uint32_t ulLRU; /* For the Least Recently Used algorithm. */\r
+ uint8_t *pucBuffer; /* Pointer to the cache block. */\r
+ uint32_t ucMode : 8, /* Read or Write mode. */\r
+ bModified : 1, /* If the sector was modified since read. */\r
+ bValid : 1; /* Initially FALSE. */\r
+ uint16_t usNumHandles; /* Number of objects using this buffer. */\r
+ uint16_t usPersistance; /* For the persistance algorithm. */\r
+} FF_Buffer_t;\r
+\r
+typedef struct\r
+{\r
+#if( ffconfigUNICODE_UTF16_SUPPORT != 0 )\r
+ FF_T_WCHAR pcPath[ ffconfigMAX_FILENAME ];\r
+#else\r
+ char pcPath[ ffconfigMAX_FILENAME ];\r
+#endif\r
+ uint32_t ulDirCluster;\r
+} FF_PathCache_t;\r
+\r
+/**\r
+ * @private\r
+ * @brief FreeRTOS+FAT identifies a partition with the following data.\r
+ * @note This may shrink as development and optimisation goes on.\r
+ **/\r
+typedef struct\r
+{\r
+ uint32_t ulBeginLBA; /* LBA start address of the partition. */\r
+ uint32_t ulFATBeginLBA; /* LBA of the FAT tables. */\r
+ uint32_t ulSectorsPerFAT; /* Number of sectors per Fat. */\r
+ uint32_t ulTotalSectors;\r
+ uint32_t ulDataSectors;\r
+#if( ffconfigWRITE_FREE_COUNT != 0 )\r
+ uint32_t ulFSInfoLBA; /* LBA of the FSINFO sector. */\r
+#endif\r
+ uint32_t ulRootDirSectors;\r
+ uint32_t ulFirstDataSector;\r
+ uint32_t ulClusterBeginLBA; /* LBA of first cluster. */\r
+ uint32_t ulNumClusters; /* Number of clusters. */\r
+ uint32_t ulRootDirCluster; /* Cluster number of the root directory entry. */\r
+ uint32_t ulLastFreeCluster;\r
+ uint32_t ulFreeClusterCount; /* Records free space on mount. */\r
+ uint32_t ulSectorsPerCluster;/* Number of sectors per Cluster. */\r
+\r
+ char pcVolumeLabel[ 12 ];/* Volume Label of the partition. */\r
+\r
+ uint16_t usBlkSize; /* Size of a Sector Block in bytes. */\r
+ uint16_t usReservedSectors;\r
+\r
+ uint8_t ucType; /* Partition Type Identifier. */\r
+ uint8_t ucBlkFactor; /* Scale Factor for block sizes above 512! */\r
+ uint8_t ucNumFATS; /* Number of FAT tables. */\r
+ uint8_t ucPartitionMounted; /* pdTRUE if the partition is mounted, otherwise pdFALSE. */\r
+\r
+#if( ffconfigPATH_CACHE != 0 )\r
+ FF_PathCache_t pxPathCache[ffconfigPATH_CACHE_DEPTH];\r
+ uint32_t ulPCIndex;\r
+#endif\r
+} FF_Partition_t;\r
+\r
+\r
+\r
+/**\r
+ * @public\r
+ * @brief FF_IOManager_t Object description.\r
+ *\r
+ * FreeRTOS+FAT functions around an object like this.\r
+ **/\r
+#define FF_FAT_LOCK 0x01 /* Lock bit mask for FAT table locking. */\r
+#define FF_DIR_LOCK 0x02 /* Lock bit mask for DIR modification locking. */\r
+#define FF_BUF_LOCK 0x04 /* Lock bit mask for buffers. */\r
+\r
+/**\r
+ * @public\r
+ * @brief FF_IOManager_t Object. A developer should not touch these values.\r
+ *\r
+ **/\r
+typedef struct _FF_IOMAN\r
+{\r
+ FF_BlockDevice_t xBlkDevice; /* Pointer to a Block device description. */\r
+ FF_Partition_t xPartition; /* A partition description. */\r
+ FF_Buffer_t *pxBuffers; /* Pointer to an array of buffer descriptors. */\r
+ void *pvSemaphore; /* Pointer to a Semaphore object. (For buffer description modifications only!). */\r
+ void *FirstFile; /* Pointer to the first File object. */\r
+ void *xEventGroup; /* An event group, used for locking FAT, DIR and Buffers. Replaces ucLocks. */\r
+ uint8_t *pucCacheMem; /* Pointer to a block of memory for the cache. */\r
+ uint16_t usSectorSize; /* The sector size that IOMAN is configured to. */\r
+ uint16_t usCacheSize; /* Size of the cache in number of Sectors. */\r
+ uint8_t ucPreventFlush; /* Flushing to disk only allowed when 0. */\r
+ uint8_t ucFlags; /* Bit-Mask: identifying allocated pointers and other flags */\r
+#if( ffconfigHASH_CACHE != 0 )\r
+ FF_HashTable_t xHashCache[ ffconfigHASH_CACHE_DEPTH ];\r
+#endif\r
+ void *pvFATLockHandle;\r
+} FF_IOManager_t;\r
+\r
+/* Bit values for 'FF_IOManager_t::ucFlags': */\r
+/* Memory Allocation testing and other flags. */\r
+#define FF_IOMAN_ALLOC_BUFDESCR 0x01 /* Flags the pxBuffers pointer is allocated. */\r
+#define FF_IOMAN_ALLOC_BUFFERS 0x02 /* Flags the pucCacheMem pointer is allocated. */\r
+#define FF_IOMAN_BLOCK_DEVICE_IS_REENTRANT 0x10 /* When true, ffRead/ffWrite are not protected by a semaphore. */\r
+#if( ffconfigREMOVABLE_MEDIA != 0 )\r
+ #define FF_IOMAN_DEVICE_IS_EXTRACTED 0x20\r
+#endif /* ffconfigREMOVABLE_MEDIA */\r
+\r
+typedef struct xFF_CREATION_PARAMETERS\r
+{\r
+ uint8_t *pucCacheMemory; /* User provided memory, or use NULL to malloc the cache memory. */\r
+ uint32_t ulMemorySize; /* Size of the cache memory, must be a multiple of 'ulSectorSize'. */\r
+ BaseType_t ulSectorSize; /* Sector size, unit for reading/writing to the disk, normally 512 bytes. */\r
+ FF_WriteBlocks_t fnWriteBlocks; /* A function to write sectors to the device. */\r
+ FF_ReadBlocks_t fnReadBlocks; /* A function to read sectors from the device. */\r
+ FF_Disk_t *pxDisk; /* Some properties of the disk driver. */\r
+ void *pvSemaphore; /* Pointer to a Semaphore object. */\r
+ BaseType_t xBlockDeviceIsReentrant; /* Make non-zero if ffRead/ffWrite are re-entrant. */\r
+} FF_CreationParameters_t;\r
+\r
+/*---------- PROTOTYPES (in order of appearance). */\r
+\r
+/* PUBLIC (Interfaces): */\r
+FF_IOManager_t *FF_CreateIOManger( FF_CreationParameters_t *pxParameters, FF_Error_t *pError );\r
+FF_Error_t FF_DeleteIOManager( FF_IOManager_t *pxIOManager);\r
+FF_Error_t FF_Mount( FF_Disk_t *pxDisk, BaseType_t xPartitionNumber );\r
+FF_Error_t FF_Unmount( FF_Disk_t *pxDisk );\r
+FF_Error_t FF_FlushCache( FF_IOManager_t *pxIOManager );\r
+static portINLINE BaseType_t FF_Mounted( FF_IOManager_t *pxIOManager )\r
+{\r
+ return pxIOManager && pxIOManager->xPartition.ucPartitionMounted;\r
+}\r
+\r
+int32_t FF_GetPartitionBlockSize(FF_IOManager_t *pxIOManager);\r
+\r
+#if( ffconfig64_NUM_SUPPORT != 0 )\r
+ uint64_t FF_GetVolumeSize( FF_IOManager_t *pxIOManager );\r
+#else\r
+ uint32_t FF_GetVolumeSize( FF_IOManager_t *pxIOManager );\r
+#endif\r
+\r
+/* PUBLIC (To FreeRTOS+FAT Only): */\r
+int32_t FF_BlockRead( FF_IOManager_t *pxIOManager, uint32_t ulSectorLBA, uint32_t ulNumSectors, void *pBuffer, BaseType_t aSemLocked );\r
+int32_t FF_BlockWrite( FF_IOManager_t *pxIOManager, uint32_t ulSectorLBA, uint32_t ulNumSectors, void *pBuffer, BaseType_t aSemLocked );\r
+FF_Error_t FF_IncreaseFreeClusters( FF_IOManager_t *pxIOManager, uint32_t Count );\r
+FF_Error_t FF_DecreaseFreeClusters( FF_IOManager_t *pxIOManager, uint32_t Count );\r
+FF_Buffer_t *FF_GetBuffer( FF_IOManager_t *pxIOManager, uint32_t ulSector, uint8_t Mode );\r
+FF_Error_t FF_ReleaseBuffer( FF_IOManager_t *pxIOManager, FF_Buffer_t *pBuffer );\r
+\r
+/* 'Internal' to FreeRTOS+FAT. */\r
+typedef struct _SPart\r
+{\r
+ uint32_t ulStartLBA; /* FF_FAT_PTBL_LBA */\r
+ uint32_t ulSectorCount; /* FF_FAT_PTBL_SECT_COUNT */\r
+ uint32_t\r
+ ucActive : 8, /* FF_FAT_PTBL_ACTIVE */\r
+ ucPartitionID : 8, /* FF_FAT_PTBL_ID */\r
+ bIsExtended : 1;\r
+} FF_Part_t;\r
+\r
+typedef struct _SPartFound\r
+{\r
+ int iCount;\r
+ FF_Part_t pxPartitions[ffconfigMAX_PARTITIONS];\r
+} FF_SPartFound_t;\r
+\r
+/* This function will parse the 4 entries in a partition table: */\r
+void FF_ReadParts( uint8_t *pucBuffer, FF_Part_t *pxParts );\r
+\r
+/* FF_PartitionCount() has now been replaced by FF_PartitionSearch()\r
+ * It will enumerate all valid partitions found\r
+ * If sector-0 happens to be a valid MBR, 1 partition will be returned\r
+ */\r
+FF_Error_t FF_PartitionSearch( FF_IOManager_t *pxIOManager, FF_SPartFound_t *pPartsFound );\r
+\r
+/* HT : for debugging only. */\r
+BaseType_t xIsFatSector( FF_IOManager_t *pxIOManager, uint32_t ulSectorNr );\r
+BaseType_t xNeedLogging( FF_IOManager_t *pxIOManager );\r
+BaseType_t xIsRootDirSector( FF_IOManager_t *pxIOManager, uint32_t ulSectorNr );\r
+const char *pcSectorType( FF_IOManager_t *pxIOManager, uint32_t ulSectorNr );\r
+\r
+/* Needed to make this public/private to be used in FF_Partition/FF_Format. */\r
+void FF_IOMAN_InitBufferDescriptors( FF_IOManager_t *pxIOManager );\r
+\r
+#ifdef __cplusplus\r
+} /* extern "C" */\r
+#endif\r
+\r
+#endif\r
projects / freertos / blobdiff