git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/FreeRTOS-Plus-FAT/include/ff_ioman.h

   1 /*\r
   2  * FreeRTOS+FAT build 191128 - Note:  FreeRTOS+FAT is still in the lab!\r
   3  * Copyright (C) 2018 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  * Authors include James Walmsley, Hein Tibosch and Richard Barry\r
   5  *\r
   6  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   7  * this software and associated documentation files (the "Software"), to deal in\r
   8  * the Software without restriction, including without limitation the rights to\r
   9  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
  10  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  11  * subject to the following conditions:\r
  12  *\r
  13  * The above copyright notice and this permission notice shall be included in all\r
  14  * copies or substantial portions of the Software.\r
  15  *\r
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  18  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  19  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  20  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  22  *\r
  23  * https://www.FreeRTOS.org\r
  24  *\r
  25  */\r
  26 \r
  27 /**\r
  28  *      @file           ff_ioman.h\r
  29  *      @ingroup        IOMAN\r
  30  **/\r
  31 \r
  32 #ifndef _FF_IOMAN_H_\r
  33 #define _FF_IOMAN_H_\r
  34 \r
  35 #ifdef __cplusplus\r
  36 extern "C" {\r
  37 #endif\r
  38 \r
  39 #include <stdlib.h>                                                     /* Use of malloc() */\r
  40 \r
  41 #ifndef PLUS_FAT_H\r
  42         #error this header will be included from "ff_headers.h"\r
  43 #endif\r
  44 \r
  45 #define FF_T_FAT12                              0x0A\r
  46 #define FF_T_FAT16                              0x0B\r
  47 #define FF_T_FAT32                              0x0C\r
  48 \r
  49 #define FF_MODE_READ                    0x01            /* Buffer / FILE Mode for Read Access. */\r
  50 #define FF_MODE_WRITE                   0x02            /* Buffer / FILE Mode for Write Access. */\r
  51 #define FF_MODE_APPEND                  0x04            /* FILE Mode Append Access. */\r
  52 #define FF_MODE_CREATE                  0x08            /* FILE Mode Create file if not existing. */\r
  53 #define FF_MODE_TRUNCATE                0x10            /* FILE Mode Truncate an Existing file. */\r
  54 #define FF_MODE_VIRGIN                  0x40            /* Buffer mode: do not fetch content from disk. Used for write-only buffers. */\r
  55 #define FF_MODE_DIR                             0x80            /* Special Mode to open a Dir. (Internal use ONLY!) */\r
  56 \r
  57 #define FF_MODE_RD_WR                   ( FF_MODE_READ | FF_MODE_WRITE ) /* Just for bit filtering. */\r
  58 \r
  59 /* The buffer write-only mode saves a fetch from disk.\r
  60 The write-only mode is used when a buffer is needed just\r
  61 for clearing sectors. */\r
  62 #define FF_MODE_WR_ONLY                 ( FF_MODE_VIRGIN | FF_MODE_WRITE )              /* Buffer for Write-only Access (Internal use ONLY!) */\r
  63 \r
  64 #define FF_BUF_MAX_HANDLES              0xFFFF          /* Maximum number handles sharing a buffer. (16 bit integer, we don't want to overflow it!) */\r
  65 \r
  66 #define FF_MAX_ENTRIES_PER_DIRECTORY    0xFFFF\r
  67 #define FF_SIZEOF_SECTOR                                512\r
  68 #define FF_SIZEOF_DIRECTORY_ENTRY               32\r
  69 \r
  70 #ifndef pdTRUE_SIGNED\r
  71         /* Temporary solution: eventually the defines below will appear\r
  72         in 'Source\include\projdefs.h' */\r
  73         #define pdTRUE_SIGNED           pdTRUE\r
  74         #define pdFALSE_SIGNED          pdFALSE\r
  75         #define pdTRUE_UNSIGNED         ( ( UBaseType_t ) 1u )\r
  76         #define pdFALSE_UNSIGNED        ( ( UBaseType_t ) 0u )\r
  77 #endif\r
  78 /**\r
  79  *      I/O Driver Definitions\r
  80  *      Provide access to any Block Device via the following interfaces.\r
  81  *      Returns the number of blocks actually read or written.\r
  82  **/\r
  83 \r
  84 /**\r
  85  *      A special information structure for the FreeRTOS+FAT mass storage device\r
  86  *      driver model.\r
  87  **/\r
  88 typedef struct\r
  89 {\r
  90         uint16_t BlkSize;\r
  91         uint32_t TotalBlocks;\r
  92 } FF_DeviceInfo_t;\r
  93 \r
  94 #if( ffconfigHASH_CACHE != 0 )\r
  95         #define FF_HASH_TABLE_ENTRY_COUNT               ( ( ffconfigHASH_TABLE_SIZE + 3 ) / 4 )\r
  96 \r
  97         struct xHASH_TABLE\r
  98         {\r
  99                 uint32_t ulDirCluster;  /* The Starting Cluster of the dir that the hash represents. */\r
 100                 uint32_t ulNumHandles;  /* Number of active Handles using this hash table. */\r
 101                 uint32_t ulMisses;              /* Number of times this Hash Table was missed, (i.e. how redundant it is). */\r
 102                 uint32_t ulBitTable[ FF_HASH_TABLE_ENTRY_COUNT ];\r
 103         };\r
 104 \r
 105         typedef struct xHASH_TABLE FF_HashTable_t;\r
 106 \r
 107         void FF_ClearHash( FF_HashTable_t *pxHash, uint32_t ulHash );\r
 108         void FF_SetHash( FF_HashTable_t *pxHash, uint32_t ulHash );\r
 109         BaseType_t FF_isHashSet( FF_HashTable_t *pxHash, uint32_t ulHash );\r
 110 #endif /* ffconfigHASH_CACHE */\r
 111 \r
 112 /* A forward declaration for the I/O manager, to be used in 'struct xFFDisk'. */\r
 113 struct _FF_IOMAN;\r
 114 struct xFFDisk;\r
 115 \r
 116 typedef void ( *FF_FlushApplicationHook )( struct xFFDisk *pxDisk );\r
 117 \r
 118 /*\r
 119  * Some low-level drivers also need to flush data to a device.\r
 120  * Use an Application hook that will be called every time when\r
 121  * FF_FlushCache() is called. The semaphore will still be taken\r
 122  * to avoid unwanted reentrancy.\r
 123  * For example:\r
 124  *\r
 125  *     void FTL_FlushData( struct xFFDisk *pxDisk )\r
 126  *     {\r
 127  *         // You may or may not inspect 'pxDisk'\r
 128  *         FTL_FlushTableCache();\r
 129  *     }\r
 130  *\r
 131  * Make sure you bind the function to the disc object, right after creation:\r
 132  *\r
 133  *    pxDisk->fnFlushApplicationHook = FTL_FlushData;\r
 134  */\r
 135 \r
 136 /* Structure that contains fields common to all media drivers, and can be\r
 137 extended to contain additional fields to tailor it for use with a specific media\r
 138 type. */\r
 139 struct xFFDisk\r
 140 {\r
 141         struct\r
 142         {\r
 143                 /* Flags that can optionally be used by the media driver to ensure the\r
 144                 disk has been initialised, registered and mounted before it is accessed. */\r
 145                 uint32_t bIsInitialised : 1;\r
 146                 uint32_t bIsMounted : 1;\r
 147                 uint32_t spare0 : 5;\r
 148 \r
 149                 /* The partition number on the media described by this structure. */\r
 150                 uint32_t bPartitionNumber : 8;\r
 151                 uint32_t spare1 : 16;\r
 152         } xStatus;\r
 153 \r
 154         /* Provided to allow this structure to be extended to include additional\r
 155         attributes that are specific to a media type. */\r
 156         void * pvTag;\r
 157 \r
 158         /* Points to input and output manager used by the disk described by this\r
 159         structure. */\r
 160         struct _FF_IOMAN *pxIOManager;\r
 161 \r
 162         /* The number of sectors on the disk. */\r
 163         uint32_t ulNumberOfSectors;\r
 164 \r
 165         /* See comments here above. */\r
 166         FF_FlushApplicationHook fnFlushApplicationHook;\r
 167 \r
 168         /* Field that can optionally be set to a signature that is unique to the\r
 169         media.  Read and write functions can check the ulSignature field to validate\r
 170         the media type before they attempt to access the pvTag field, or perform any\r
 171         read and write operations. */\r
 172         uint32_t ulSignature;\r
 173 };\r
 174 \r
 175 typedef struct xFFDisk FF_Disk_t;\r
 176 \r
 177 typedef int32_t ( *FF_WriteBlocks_t ) ( uint8_t *pucBuffer, uint32_t ulSectorAddress, uint32_t ulCount, FF_Disk_t *pxDisk );\r
 178 typedef int32_t ( *FF_ReadBlocks_t ) ( uint8_t *pucBuffer, uint32_t ulSectorAddress, uint32_t ulCount, FF_Disk_t *pxDisk );\r
 179 \r
 180 /**\r
 181  *      @public\r
 182  *      @brief  Describes the block device driver interface to FreeRTOS+FAT.\r
 183  **/\r
 184 typedef struct\r
 185 {\r
 186         FF_WriteBlocks_t        fnpWriteBlocks; /* Function Pointer, to write a block(s) from a block device. */\r
 187         FF_ReadBlocks_t fnpReadBlocks;  /* Function Pointer, to read a block(s) from a block device. */\r
 188         FF_Disk_t *pxDisk;                              /* Earlier called 'pParam': pointer to some parameters e.g. for a Low-Level Driver Handle. */\r
 189 } FF_BlockDevice_t;\r
 190 \r
 191 /**\r
 192  *      @private\r
 193  *      @brief  FreeRTOS+FAT handles memory with buffers, described as below.\r
 194  *      @note   This may change throughout development.\r
 195  **/\r
 196 typedef struct\r
 197 {\r
 198         uint32_t                ulSector;               /* The LBA of the Cached sector. */\r
 199         uint32_t                ulLRU;                  /* For the Least Recently Used algorithm. */\r
 200         uint8_t                 *pucBuffer;             /* Pointer to the cache block. */\r
 201         uint32_t                ucMode : 8,             /* Read or Write mode. */\r
 202                                         bModified : 1,  /* If the sector was modified since read. */\r
 203                                         bValid : 1;             /* Initially FALSE. */\r
 204         uint16_t                usNumHandles;   /* Number of objects using this buffer. */\r
 205         uint16_t                usPersistance;  /* For the persistance algorithm. */\r
 206 } FF_Buffer_t;\r
 207 \r
 208 typedef struct\r
 209 {\r
 210 #if( ffconfigUNICODE_UTF16_SUPPORT != 0 )\r
 211         FF_T_WCHAR pcPath[ ffconfigMAX_FILENAME ];\r
 212 #else\r
 213         char pcPath[ ffconfigMAX_FILENAME ];\r
 214 #endif\r
 215         uint32_t ulDirCluster;\r
 216 } FF_PathCache_t;\r
 217 \r
 218 /**\r
 219  *      @private\r
 220  *      @brief  FreeRTOS+FAT identifies a partition with the following data.\r
 221  *      @note   This may shrink as development and optimisation goes on.\r
 222  **/\r
 223 typedef struct\r
 224 {\r
 225          uint32_t               ulBeginLBA;                     /* LBA start address of the partition. */\r
 226          uint32_t               ulFATBeginLBA;          /* LBA of the FAT tables. */\r
 227          uint32_t               ulSectorsPerFAT;        /* Number of sectors per Fat. */\r
 228          uint32_t               ulTotalSectors;\r
 229          uint32_t               ulDataSectors;\r
 230 #if( ffconfigWRITE_FREE_COUNT != 0 )\r
 231          uint32_t       ulFSInfoLBA;            /* LBA of the FSINFO sector. */\r
 232 #endif\r
 233          uint32_t               ulRootDirSectors;\r
 234          uint32_t               ulFirstDataSector;\r
 235          uint32_t               ulClusterBeginLBA;      /* LBA of first cluster. */\r
 236          uint32_t               ulNumClusters;          /* Number of clusters. */\r
 237          uint32_t               ulRootDirCluster;       /* Cluster number of the root directory entry. */\r
 238          uint32_t               ulLastFreeCluster;\r
 239          uint32_t               ulFreeClusterCount;     /* Records free space on mount. */\r
 240          uint32_t               ulSectorsPerCluster;/* Number of sectors per Cluster. */\r
 241 \r
 242          char                   pcVolumeLabel[ 12 ];/* Volume Label of the partition. */\r
 243 \r
 244          uint16_t               usBlkSize;                      /* Size of a Sector Block in bytes. */\r
 245          uint16_t               usReservedSectors;\r
 246 \r
 247          uint8_t                ucType;                         /* Partition Type Identifier. */\r
 248          uint8_t        ucBlkFactor;            /* Scale Factor for block sizes above 512! */\r
 249          uint8_t                ucNumFATS;                      /* Number of FAT tables. */\r
 250          uint8_t                ucPartitionMounted;     /* pdTRUE if the partition is mounted, otherwise pdFALSE. */\r
 251 \r
 252 #if( ffconfigPATH_CACHE != 0 )\r
 253          FF_PathCache_t pxPathCache[ffconfigPATH_CACHE_DEPTH];\r
 254          uint32_t               ulPCIndex;\r
 255 #endif\r
 256 } FF_Partition_t;\r
 257 \r
 258 \r
 259 \r
 260 /**\r
 261  *      @public\r
 262  *      @brief  FF_IOManager_t Object description.\r
 263  *\r
 264  *      FreeRTOS+FAT functions around an object like this.\r
 265  **/\r
 266 #define FF_FAT_LOCK                     0x01    /* Lock bit mask for FAT table locking. */\r
 267 #define FF_DIR_LOCK                     0x02    /* Lock bit mask for DIR modification locking. */\r
 268 #define FF_BUF_LOCK                     0x04    /* Lock bit mask for buffers. */\r
 269 \r
 270 /**\r
 271  *      @public\r
 272  *      @brief  FF_IOManager_t Object. A developer should not touch these values.\r
 273  *\r
 274  **/\r
 275 typedef struct _FF_IOMAN\r
 276 {\r
 277         FF_BlockDevice_t        xBlkDevice;                     /* Pointer to a Block device description. */\r
 278         FF_Partition_t  xPartition;                     /* A partition description. */\r
 279         FF_Buffer_t             *pxBuffers;                     /* Pointer to an array of buffer descriptors. */\r
 280         void                    *pvSemaphore;           /* Pointer to a Semaphore object. (For buffer description modifications only!). */\r
 281         void                    *FirstFile;                     /* Pointer to the first File object. */\r
 282         void                    *xEventGroup;           /* An event group, used for locking FAT, DIR and Buffers. Replaces ucLocks. */\r
 283         uint8_t                 *pucCacheMem;           /* Pointer to a block of memory for the cache. */\r
 284         uint16_t                usSectorSize;           /* The sector size that IOMAN is configured to. */\r
 285         uint16_t                usCacheSize;            /* Size of the cache in number of Sectors. */\r
 286         uint8_t                 ucPreventFlush;         /* Flushing to disk only allowed when 0. */\r
 287         uint8_t                 ucFlags;                        /* Bit-Mask: identifying allocated pointers and other flags */\r
 288 #if( ffconfigHASH_CACHE != 0 )\r
 289         FF_HashTable_t  xHashCache[ ffconfigHASH_CACHE_DEPTH ];\r
 290 #endif\r
 291         void                    *pvFATLockHandle;\r
 292 } FF_IOManager_t;\r
 293 \r
 294 /* Bit values for 'FF_IOManager_t::ucFlags': */\r
 295 /* Memory Allocation testing and other flags. */\r
 296 #define FF_IOMAN_ALLOC_BUFDESCR 0x01    /* Flags the pxBuffers pointer is allocated. */\r
 297 #define FF_IOMAN_ALLOC_BUFFERS  0x02    /* Flags the pucCacheMem pointer is allocated. */\r
 298 #define FF_IOMAN_BLOCK_DEVICE_IS_REENTRANT              0x10    /* When true, ffRead/ffWrite are not protected by a semaphore. */\r
 299 #if( ffconfigREMOVABLE_MEDIA != 0 )\r
 300         #define FF_IOMAN_DEVICE_IS_EXTRACTED            0x20\r
 301 #endif /* ffconfigREMOVABLE_MEDIA */\r
 302 \r
 303 typedef struct xFF_CREATION_PARAMETERS\r
 304 {\r
 305         uint8_t *pucCacheMemory;                /* User provided memory, or use NULL to malloc the cache memory. */\r
 306         uint32_t ulMemorySize;                  /* Size of the cache memory, must be a multiple of 'ulSectorSize'. */\r
 307         BaseType_t ulSectorSize;                /* Sector size, unit for reading/writing to the disk, normally 512 bytes. */\r
 308         FF_WriteBlocks_t fnWriteBlocks; /* A function to write sectors to the device. */\r
 309         FF_ReadBlocks_t fnReadBlocks;   /* A function to read sectors from the device. */\r
 310         FF_Disk_t *pxDisk;                              /* Some properties of the disk driver. */\r
 311         void *pvSemaphore;                              /* Pointer to a Semaphore object. */\r
 312         BaseType_t xBlockDeviceIsReentrant;     /* Make non-zero if ffRead/ffWrite are re-entrant. */\r
 313 } FF_CreationParameters_t;\r
 314 \r
 315 /*---------- PROTOTYPES (in order of appearance). */\r
 316 \r
 317 /* PUBLIC (Interfaces): */\r
 318 FF_IOManager_t *FF_CreateIOManger( FF_CreationParameters_t *pxParameters, FF_Error_t *pError );\r
 319 FF_Error_t FF_DeleteIOManager( FF_IOManager_t *pxIOManager);\r
 320 FF_Error_t FF_Mount( FF_Disk_t *pxDisk, BaseType_t xPartitionNumber );\r
 321 FF_Error_t FF_Unmount( FF_Disk_t *pxDisk );\r
 322 FF_Error_t FF_FlushCache( FF_IOManager_t *pxIOManager );\r
 323 static portINLINE BaseType_t FF_Mounted( FF_IOManager_t *pxIOManager )\r
 324 {\r
 325         return pxIOManager && pxIOManager->xPartition.ucPartitionMounted;\r
 326 }\r
 327 \r
 328 int32_t FF_GetPartitionBlockSize(FF_IOManager_t *pxIOManager);\r
 329 \r
 330 #if( ffconfig64_NUM_SUPPORT != 0 )\r
 331         uint64_t FF_GetVolumeSize( FF_IOManager_t *pxIOManager );\r
 332 #else\r
 333         uint32_t FF_GetVolumeSize( FF_IOManager_t *pxIOManager );\r
 334 #endif\r
 335 \r
 336 /* PUBLIC  (To FreeRTOS+FAT Only): */\r
 337 int32_t FF_BlockRead( FF_IOManager_t *pxIOManager, uint32_t ulSectorLBA, uint32_t ulNumSectors, void *pBuffer, BaseType_t aSemLocked );\r
 338 int32_t FF_BlockWrite( FF_IOManager_t *pxIOManager, uint32_t ulSectorLBA, uint32_t ulNumSectors, void *pBuffer, BaseType_t aSemLocked );\r
 339 FF_Error_t FF_IncreaseFreeClusters( FF_IOManager_t *pxIOManager, uint32_t Count );\r
 340 FF_Error_t FF_DecreaseFreeClusters( FF_IOManager_t *pxIOManager, uint32_t Count );\r
 341 FF_Buffer_t *FF_GetBuffer( FF_IOManager_t *pxIOManager, uint32_t ulSector, uint8_t Mode );\r
 342 FF_Error_t FF_ReleaseBuffer( FF_IOManager_t *pxIOManager, FF_Buffer_t *pBuffer );\r
 343 \r
 344 /* 'Internal' to FreeRTOS+FAT. */\r
 345 typedef struct _SPart\r
 346 {\r
 347         uint32_t ulStartLBA;            /* FF_FAT_PTBL_LBA */\r
 348         uint32_t ulSectorCount;         /* FF_FAT_PTBL_SECT_COUNT */\r
 349         uint32_t\r
 350                         ucActive : 8,           /* FF_FAT_PTBL_ACTIVE */\r
 351                         ucPartitionID : 8,      /* FF_FAT_PTBL_ID */\r
 352                         bIsExtended : 1;\r
 353 } FF_Part_t;\r
 354 \r
 355 typedef struct _SPartFound\r
 356 {\r
 357         int iCount;\r
 358         FF_Part_t pxPartitions[ffconfigMAX_PARTITIONS];\r
 359 } FF_SPartFound_t;\r
 360 \r
 361 /* This function will parse the 4 entries in a partition table: */\r
 362 void FF_ReadParts( uint8_t *pucBuffer, FF_Part_t *pxParts );\r
 363 \r
 364 /* FF_PartitionCount() has now been replaced by FF_PartitionSearch()\r
 365  * It will enumerate all valid partitions found\r
 366  * If sector-0 happens to be a valid MBR, 1 partition will be returned\r
 367  */\r
 368 FF_Error_t FF_PartitionSearch( FF_IOManager_t *pxIOManager, FF_SPartFound_t *pPartsFound );\r
 369 \r
 370 /* HT : for debugging only. */\r
 371 BaseType_t xIsFatSector( FF_IOManager_t *pxIOManager, uint32_t ulSectorNr );\r
 372 BaseType_t xNeedLogging( FF_IOManager_t *pxIOManager );\r
 373 BaseType_t xIsRootDirSector( FF_IOManager_t *pxIOManager, uint32_t ulSectorNr );\r
 374 const char *pcSectorType( FF_IOManager_t *pxIOManager, uint32_t ulSectorNr );\r
 375 \r
 376 /* Needed to make this public/private to be used in FF_Partition/FF_Format. */\r
 377 void FF_IOMAN_InitBufferDescriptors( FF_IOManager_t *pxIOManager );\r
 378 \r
 379 #ifdef __cplusplus\r
 380 } /* extern "C" */\r
 381 #endif\r
 382 \r
 383 #endif\r