FatPkg/FatPei/FatLitePeim.h

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