FatPkg/FatPei/FatLitePeim.h

   1 /** @file
   2   Data structures for FAT recovery PEIM
   3
   4 Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>
   5
   6 This program and the accompanying materials are licensed and made available
   7 under the terms and conditions of the BSD License which accompanies this
   8 distribution. The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _FAT_PEIM_H_
  17 #define _FAT_PEIM_H_
  18
  19 #include <PiPei.h>
  20
  21 #include <Guid/RecoveryDevice.h>
  22 #include <Ppi/BlockIo.h>
  23 #include <Ppi/BlockIo2.h>
  24 #include <Ppi/DeviceRecoveryModule.h>
  25
  26 #include <Library/DebugLib.h>
  27 #include <Library/BaseLib.h>
  28 #include <Library/PeimEntryPoint.h>
  29 #include <Library/BaseMemoryLib.h>
  30 #include <Library/MemoryAllocationLib.h>
  31 #include <Library/PcdLib.h>
  32 #include <Library/PeiServicesTablePointerLib.h>
  33 #include <Library/PeiServicesLib.h>
  34
  35 #include "FatLiteApi.h"
  36 #include "FatLiteFmt.h"
  37
  38 //
  39 // Definitions
  40 //
  41
  42 #define PEI_FAT_CACHE_SIZE                            4
  43 #define PEI_FAT_MAX_BLOCK_SIZE                        8192
  44 #define FAT_MAX_FILE_NAME_LENGTH                      128
  45 #define PEI_FAT_MAX_BLOCK_DEVICE                      64
  46 #define PEI_FAT_MAX_BLOCK_IO_PPI                      32
  47 #define PEI_FAT_MAX_VOLUME                            64
  48
  49 #define PEI_FAT_MEMMORY_PAGE_SIZE                     0x1000
  50
  51 //
  52 // Data Structures
  53 //
  54 //
  55 // The block device
  56 //
  57 typedef struct {
  58
  59   UINT32                        BlockSize;
  60   UINT64                        LastBlock;
  61   UINT32                        IoAlign;
  62   BOOLEAN                       Logical;
  63   BOOLEAN                       PartitionChecked;
  64
  65   //
  66   // Following fields only valid for logical device
  67   //
  68   CHAR8                         PartitionFlag[8];
  69   UINT64                        StartingPos;
  70   UINTN                         ParentDevNo;
  71
  72   //
  73   // Following fields only valid for physical device
  74   //
  75   EFI_PEI_BLOCK_DEVICE_TYPE     DevType;
  76   UINT8                         InterfaceType;
  77   //
  78   // EFI_PEI_READ_BLOCKS         ReadFunc;
  79   //
  80   EFI_PEI_RECOVERY_BLOCK_IO_PPI  *BlockIo;
  81   EFI_PEI_RECOVERY_BLOCK_IO2_PPI *BlockIo2;
  82   UINT8                          PhysicalDevNo;
  83 } PEI_FAT_BLOCK_DEVICE;
  84
  85 //
  86 // the Volume structure
  87 //
  88 typedef struct {
  89
  90   UINTN         BlockDeviceNo;
  91   UINTN         VolumeNo;
  92   UINT64        VolumeSize;
  93   UINTN         MaxCluster;
  94   CHAR16        VolumeLabel[FAT_MAX_FILE_NAME_LENGTH];
  95   PEI_FAT_TYPE  FatType;
  96   UINT64        FatPos;
  97   UINT32        SectorSize;
  98   UINT32        ClusterSize;
  99   UINT64        FirstClusterPos;
 100   UINT64        RootDirPos;
 101   UINT32        RootEntries;
 102   UINT32        RootDirCluster;
 103
 104 } PEI_FAT_VOLUME;
 105
 106 //
 107 // File instance
 108 //
 109 typedef struct {
 110
 111   PEI_FAT_VOLUME  *Volume;
 112   CHAR16          FileName[FAT_MAX_FILE_NAME_LENGTH];
 113
 114   BOOLEAN         IsFixedRootDir;
 115
 116   UINT32          StartingCluster;
 117   UINT32          CurrentPos;
 118   UINT32          StraightReadAmount;
 119   UINT32          CurrentCluster;
 120
 121   UINT8           Attributes;
 122   UINT32          FileSize;
 123
 124 } PEI_FAT_FILE;
 125
 126 //
 127 // Cache Buffer
 128 //
 129 typedef struct {
 130
 131   BOOLEAN Valid;
 132   UINTN   BlockDeviceNo;
 133   UINT64  Lba;
 134   UINT32  Lru;
 135   UINT64  Buffer[PEI_FAT_MAX_BLOCK_SIZE / 8];
 136   UINTN   Size;
 137
 138 } PEI_FAT_CACHE_BUFFER;
 139
 140 //
 141 // Private Data.
 142 // This structure abstracts the whole memory usage in FAT PEIM.
 143 // The entry point routine will get a chunk of memory (by whatever
 144 // means) whose size is sizeof(PEI_FAT_PRIVATE_DATA), which is clean
 145 // in both 32 and 64 bit environment. The boundary of the memory chunk
 146 // should be 64bit aligned.
 147 //
 148 #define PEI_FAT_PRIVATE_DATA_SIGNATURE  SIGNATURE_32 ('p', 'f', 'a', 't')
 149
 150 typedef struct {
 151
 152   UINTN                               Signature;
 153   EFI_PEI_DEVICE_RECOVERY_MODULE_PPI  DeviceRecoveryPpi;
 154   EFI_PEI_PPI_DESCRIPTOR              PpiDescriptor;
 155   EFI_PEI_NOTIFY_DESCRIPTOR           NotifyDescriptor[2];
 156
 157   UINT8                               UnicodeCaseMap[0x300];
 158   CHAR8                               *EngUpperMap;
 159   CHAR8                               *EngLowerMap;
 160   CHAR8                               *EngInfoMap;
 161
 162   UINT64                              BlockData[PEI_FAT_MAX_BLOCK_SIZE / 8];
 163   UINTN                               BlockDeviceCount;
 164   PEI_FAT_BLOCK_DEVICE                BlockDevice[PEI_FAT_MAX_BLOCK_DEVICE];
 165   UINTN                               VolumeCount;
 166   PEI_FAT_VOLUME                      Volume[PEI_FAT_MAX_VOLUME];
 167   PEI_FAT_FILE                        File;
 168   PEI_FAT_CACHE_BUFFER                CacheBuffer[PEI_FAT_CACHE_SIZE];
 169
 170 } PEI_FAT_PRIVATE_DATA;
 171
 172 #define PEI_FAT_PRIVATE_DATA_FROM_THIS(a) \
 173   CR (a,  PEI_FAT_PRIVATE_DATA, DeviceRecoveryPpi, PEI_FAT_PRIVATE_DATA_SIGNATURE)
 174
 175 //
 176 // Extract INT32 from char array
 177 //
 178 #define UNPACK_INT32(a) \
 179   (INT32) ((((UINT8 *) a)[0] << 0) | (((UINT8 *) a)[1] << 8) | (((UINT8 *) a)[2] << 16) | (((UINT8 *) a)[3] << 24))
 180
 181 //
 182 // Extract UINT32 from char array
 183 //
 184 #define UNPACK_UINT32(a) \
 185   (UINT32) ((((UINT8 *) a)[0] << 0) | (((UINT8 *) a)[1] << 8) | (((UINT8 *) a)[2] << 16) | (((UINT8 *) a)[3] << 24))
 186
 187
 188 //
 189 // API functions
 190 //
 191
 192 /**
 193   Finds the recovery file on a FAT volume.
 194   This function finds the the recovery file named FileName on a specified FAT volume and returns
 195   its FileHandle pointer.
 196
 197   @param  PrivateData             Global memory map for accessing global
 198                                   variables.
 199   @param  VolumeIndex             The index of the volume.
 200   @param  FileName                The recovery file name to find.
 201   @param  Handle                  The output file handle.
 202
 203   @retval EFI_DEVICE_ERROR        Some error occured when operating the FAT
 204                                   volume.
 205   @retval EFI_NOT_FOUND           The recovery file was not found.
 206   @retval EFI_SUCCESS             The recovery file was successfully found on the
 207                                   FAT volume.
 208
 209 **/
 210 EFI_STATUS
 211 FindRecoveryFile (
 212   IN  PEI_FAT_PRIVATE_DATA  *PrivateData,
 213   IN  UINTN                 VolumeIndex,
 214   IN  CHAR16                *FileName,
 215   OUT PEI_FILE_HANDLE       *Handle
 216   );
 217
 218
 219 /**
 220   Returns the number of DXE capsules residing on the device.
 221   This function, by whatever mechanism, searches for DXE capsules from the associated device and
 222   returns the number and maximum size in bytes of the capsules discovered.Entry 1 is assumed to be
 223   the highest load priority and entry N is assumed to be the lowest priority.
 224
 225   @param  PeiServices             General-purpose services that are available to
 226                                   every PEIM.
 227   @param  This                    Indicates the
 228                                   EFI_PEI_DEVICE_RECOVERY_MODULE_PPI instance.
 229   @param  NumberRecoveryCapsules  Pointer to a caller-allocated UINTN.On output,
 230                                   *NumberRecoveryCapsules contains the number of
 231                                   recovery capsule images available for retrieval
 232                                   from this PEIM instance.
 233
 234   @retval EFI_SUCCESS             The function completed successfully.
 235
 236 **/
 237 EFI_STATUS
 238 EFIAPI
 239 GetNumberRecoveryCapsules (
 240   IN EFI_PEI_SERVICES                               **PeiServices,
 241   IN EFI_PEI_DEVICE_RECOVERY_MODULE_PPI             *This,
 242   OUT UINTN                                         *NumberRecoveryCapsules
 243   );
 244
 245
 246 /**
 247   Returns the size and type of the requested recovery capsule.
 248   This function returns the size and type of the capsule specified by CapsuleInstance.
 249
 250   @param  PeiServices             General-purpose services that are available to
 251                                   every PEIM.
 252   @param  This                    Indicates the
 253                                   EFI_PEI_DEVICE_RECOVERY_MODULE_PPI instance.
 254   @param  CapsuleInstance         Specifies for which capsule instance to
 255                                   retrieve the information.T his parameter must
 256                                   be between one and the value returned by
 257                                   GetNumberRecoveryCapsules() in
 258                                   NumberRecoveryCapsules.
 259   @param  Size                    A pointer to a caller-allocated UINTN in which
 260                                   the size of the requested recovery module is
 261                                   returned.
 262   @param  CapsuleType             A pointer to a caller-allocated EFI_GUID in
 263                                   which the type of the requested recovery
 264                                   capsule is returned.T he semantic meaning of
 265                                   the value returned is defined by the
 266                                   implementation.
 267
 268   @retval EFI_SUCCESS             The capsule type and size were retrieved.
 269   @retval EFI_INVALID_PARAMETER   The input CapsuleInstance does not match any
 270                                   discovered recovery capsule.
 271
 272 **/
 273 EFI_STATUS
 274 EFIAPI
 275 GetRecoveryCapsuleInfo (
 276   IN  EFI_PEI_SERVICES                              **PeiServices,
 277   IN  EFI_PEI_DEVICE_RECOVERY_MODULE_PPI            *This,
 278   IN  UINTN                                         CapsuleInstance,
 279   OUT UINTN                                         *Size,
 280   OUT EFI_GUID                                      *CapsuleType
 281   );
 282
 283
 284 /**
 285   Loads a DXE capsule from some media into memory.
 286
 287   This function, by whatever mechanism, retrieves a DXE capsule from some device
 288   and loads it into memory. Note that the published interface is device neutral.
 289
 290   @param[in]     PeiServices       General-purpose services that are available
 291                                    to every PEIM
 292   @param[in]     This              Indicates the EFI_PEI_DEVICE_RECOVERY_MODULE_PPI
 293                                    instance.
 294   @param[in]     CapsuleInstance   Specifies which capsule instance to retrieve.
 295   @param[out]    Buffer            Specifies a caller-allocated buffer in which
 296                                    the requested recovery capsule will be returned.
 297
 298   @retval EFI_SUCCESS        The capsule was loaded correctly.
 299   @retval EFI_DEVICE_ERROR   A device error occurred.
 300   @retval EFI_NOT_FOUND      A requested recovery DXE capsule cannot be found.
 301
 302 **/
 303 EFI_STATUS
 304 EFIAPI
 305 LoadRecoveryCapsule (
 306   IN EFI_PEI_SERVICES                             **PeiServices,
 307   IN EFI_PEI_DEVICE_RECOVERY_MODULE_PPI           *This,
 308   IN UINTN                                        CapsuleInstance,
 309   OUT VOID                                        *Buffer
 310   );
 311
 312
 313 /**
 314   This version is different from the version in Unicode collation
 315   protocol in that this version strips off trailing blanks.
 316   Converts an 8.3 FAT file name using an OEM character set
 317   to a Null-terminated Unicode string.
 318   Here does not expand DBCS FAT chars.
 319
 320   @param  FatSize           The size of the string Fat in bytes.
 321   @param  Fat               A pointer to a Null-terminated string that contains
 322                             an 8.3 file name using an OEM character set.
 323   @param  Str               A pointer to a Null-terminated Unicode string. The
 324                             string must be allocated in advance to hold FatSize
 325                             Unicode characters
 326
 327 **/
 328 VOID
 329 EngFatToStr (
 330   IN UINTN                            FatSize,
 331   IN CHAR8                            *Fat,
 332   OUT CHAR16                          *Str
 333   );
 334
 335
 336 /**
 337   Performs a case-insensitive comparison of two Null-terminated Unicode strings.
 338
 339   @param  PrivateData       Global memory map for accessing global variables
 340   @param  Str1              First string to perform case insensitive comparison.
 341   @param  Str2              Second string to perform case insensitive comparison.
 342
 343 **/
 344 BOOLEAN
 345 EngStriColl (
 346   IN  PEI_FAT_PRIVATE_DATA  *PrivateData,
 347   IN CHAR16                 *Str1,
 348   IN CHAR16                 *Str2
 349   );
 350
 351
 352 /**
 353   Reads a block of data from the block device by calling
 354   underlying Block I/O service.
 355
 356   @param  PrivateData       Global memory map for accessing global variables
 357   @param  BlockDeviceNo     The index for the block device number.
 358   @param  Lba               The logic block address to read data from.
 359   @param  BufferSize        The size of data in byte to read.
 360   @param  Buffer            The buffer of the
 361
 362   @retval EFI_DEVICE_ERROR  The specified block device number exceeds the maximum
 363                             device number.
 364   @retval EFI_DEVICE_ERROR  The maximum address has exceeded the maximum address
 365                             of the block device.
 366
 367 **/
 368 EFI_STATUS
 369 FatReadBlock (
 370   IN  PEI_FAT_PRIVATE_DATA   *PrivateData,
 371   IN  UINTN                  BlockDeviceNo,
 372   IN  EFI_PEI_LBA            Lba,
 373   IN  UINTN                  BufferSize,
 374   OUT VOID                   *Buffer
 375   );
 376
 377
 378 /**
 379   Check if there is a valid FAT in the corresponding Block device
 380   of the volume and if yes, fill in the relevant fields for the
 381   volume structure. Note there should be a valid Block device number
 382   already set.
 383
 384   @param  PrivateData            Global memory map for accessing global
 385                                  variables.
 386   @param  Volume                 On input, the BlockDeviceNumber field of the
 387                                  Volume  should be a valid value. On successful
 388                                  output, all  fields except the VolumeNumber
 389                                  field is initialized.
 390
 391   @retval EFI_SUCCESS            A FAT is found and the volume structure is
 392                                  initialized.
 393   @retval EFI_NOT_FOUND          There is no FAT on the corresponding device.
 394   @retval EFI_DEVICE_ERROR       There is something error while accessing device.
 395
 396 **/
 397 EFI_STATUS
 398 FatGetBpbInfo (
 399   IN      PEI_FAT_PRIVATE_DATA  *PrivateData,
 400   IN OUT  PEI_FAT_VOLUME        *Volume
 401   );
 402
 403
 404 /**
 405   Gets the next cluster in the cluster chain.
 406
 407   @param  PrivateData            Global memory map for accessing global variables
 408   @param  Volume                 The volume
 409   @param  Cluster                The cluster
 410   @param  NextCluster            The cluster number of the next cluster
 411
 412   @retval EFI_SUCCESS            The address is got
 413   @retval EFI_INVALID_PARAMETER  ClusterNo exceeds the MaxCluster of the volume.
 414   @retval EFI_DEVICE_ERROR       Read disk error
 415
 416 **/
 417 EFI_STATUS
 418 FatGetNextCluster (
 419   IN  PEI_FAT_PRIVATE_DATA  *PrivateData,
 420   IN  PEI_FAT_VOLUME        *Volume,
 421   IN  UINT32                Cluster,
 422   OUT UINT32                *NextCluster
 423   );
 424
 425
 426 /**
 427   Disk reading.
 428
 429   @param  PrivateData       the global memory map;
 430   @param  BlockDeviceNo     the block device to read;
 431   @param  StartingAddress   the starting address.
 432   @param  Size              the amount of data to read.
 433   @param  Buffer            the buffer holding the data
 434
 435   @retval EFI_SUCCESS       The function completed successfully.
 436   @retval EFI_DEVICE_ERROR  Something error.
 437
 438 **/
 439 EFI_STATUS
 440 FatReadDisk (
 441   IN  PEI_FAT_PRIVATE_DATA  *PrivateData,
 442   IN  UINTN                 BlockDeviceNo,
 443   IN  UINT64                StartingAddress,
 444   IN  UINTN                 Size,
 445   OUT VOID                  *Buffer
 446   );
 447
 448
 449 /**
 450   Set a file's CurrentPos and CurrentCluster, then compute StraightReadAmount.
 451
 452   @param  PrivateData            the global memory map
 453   @param  File                   the file
 454   @param  Pos                    the Position which is offset from the file's
 455                                  CurrentPos
 456
 457   @retval EFI_SUCCESS            Success.
 458   @retval EFI_INVALID_PARAMETER  Pos is beyond file's size.
 459   @retval EFI_DEVICE_ERROR       Something error while accessing media.
 460
 461 **/
 462 EFI_STATUS
 463 FatSetFilePos (
 464   IN  PEI_FAT_PRIVATE_DATA  *PrivateData,
 465   IN  PEI_FAT_FILE          *File,
 466   IN  UINT32                Pos
 467   );
 468
 469
 470 /**
 471   Reads file data. Updates the file's CurrentPos.
 472
 473   @param  PrivateData            Global memory map for accessing global variables
 474   @param  File                   The file.
 475   @param  Size                   The amount of data to read.
 476   @param  Buffer                 The buffer storing the data.
 477
 478   @retval EFI_SUCCESS            The data is read.
 479   @retval EFI_INVALID_PARAMETER  File is invalid.
 480   @retval EFI_DEVICE_ERROR       Something error while accessing media.
 481
 482 **/
 483 EFI_STATUS
 484 FatReadFile (
 485   IN  PEI_FAT_PRIVATE_DATA  *PrivateData,
 486   IN  PEI_FAT_FILE          *File,
 487   IN  UINTN                 Size,
 488   OUT VOID                  *Buffer
 489   );
 490
 491
 492 /**
 493   This function reads the next item in the parent directory and
 494   initializes the output parameter SubFile (CurrentPos is initialized to 0).
 495   The function updates the CurrentPos of the parent dir to after the item read.
 496   If no more items were found, the function returns EFI_NOT_FOUND.
 497
 498   @param  PrivateData            Global memory map for accessing global variables
 499   @param  ParentDir              The parent directory.
 500   @param  SubFile                The File structure containing the sub file that
 501                                  is caught.
 502
 503   @retval EFI_SUCCESS            The next sub file is obtained.
 504   @retval EFI_INVALID_PARAMETER  The ParentDir is not a directory.
 505   @retval EFI_NOT_FOUND          No more sub file exists.
 506   @retval EFI_DEVICE_ERROR       Something error while accessing media.
 507
 508 **/
 509 EFI_STATUS
 510 FatReadNextDirectoryEntry (
 511   IN  PEI_FAT_PRIVATE_DATA  *PrivateData,
 512   IN  PEI_FAT_FILE          *ParentDir,
 513   OUT PEI_FAT_FILE          *SubFile
 514   );
 515
 516
 517 /**
 518   This function finds partitions (logical devices) in physical block devices.
 519
 520   @param  PrivateData       Global memory map for accessing global variables.
 521
 522 **/
 523 VOID
 524 FatFindPartitions (
 525   IN  PEI_FAT_PRIVATE_DATA  *PrivateData
 526   );
 527
 528 #endif // _FAT_PEIM_H_