MdeModulePkg/Universal/Disk/RamDiskDxe/RamDiskImpl.h

   1 /** @file
   2   The header file of RamDiskDxe driver.
   3
   4   Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _RAM_DISK_IMPL_H_
  16 #define _RAM_DISK_IMPL_H_
  17
  18 #include <Uefi.h>
  19 #include <Library/BaseLib.h>
  20 #include <Library/BaseMemoryLib.h>
  21 #include <Library/DebugLib.h>
  22 #include <Library/UefiLib.h>
  23 #include <Library/UefiDriverEntryPoint.h>
  24 #include <Library/UefiBootServicesTableLib.h>
  25 #include <Library/UefiHiiServicesLib.h>
  26 #include <Library/MemoryAllocationLib.h>
  27 #include <Library/HiiLib.h>
  28 #include <Library/FileExplorerLib.h>
  29 #include <Library/DevicePathLib.h>
  30 #include <Library/PrintLib.h>
  31 #include <Protocol/RamDisk.h>
  32 #include <Protocol/BlockIo.h>
  33 #include <Protocol/HiiConfigAccess.h>
  34 #include <Protocol/SimpleFileSystem.h>
  35 #include <Guid/MdeModuleHii.h>
  36 #include <Guid/RamDiskHii.h>
  37 #include <Guid/FileInfo.h>
  38
  39 #include "RamDiskNVData.h"
  40
  41 ///
  42 /// RAM disk general definitions and declarations
  43 ///
  44
  45 //
  46 // Block size for RAM disk
  47 //
  48 #define RAM_DISK_BLOCK_SIZE 512
  49
  50 //
  51 // Iterate through the doule linked list. NOT delete safe
  52 //
  53 #define EFI_LIST_FOR_EACH(Entry, ListHead)    \
  54   for(Entry = (ListHead)->ForwardLink; Entry != (ListHead); Entry = Entry->ForwardLink)
  55
  56 //
  57 // Iterate through the doule linked list. This is delete-safe.
  58 // Do not touch NextEntry
  59 //
  60 #define EFI_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead)            \
  61   for(Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink;\
  62       Entry != (ListHead); Entry = NextEntry, NextEntry = Entry->ForwardLink)
  63
  64 //
  65 // RamDiskDxe driver maintains a list of registered RAM disks.
  66 //
  67 extern  LIST_ENTRY                RegisteredRamDisks;
  68 extern  UINTN                     ListEntryNum;
  69
  70 //
  71 // RAM Disk create method.
  72 //
  73 typedef enum _RAM_DISK_CREATE_METHOD {
  74   RamDiskCreateOthers             = 0,
  75   RamDiskCreateHii
  76 } RAM_DISK_CREATE_METHOD;
  77
  78 //
  79 // RamDiskDxe driver maintains a list of registered RAM disks.
  80 // The struct contains the list entry and the information of each RAM
  81 // disk
  82 //
  83 typedef struct {
  84   UINTN                           Signature;
  85
  86   EFI_HANDLE                      Handle;
  87
  88   EFI_BLOCK_IO_PROTOCOL           BlockIo;
  89   EFI_BLOCK_IO_MEDIA              Media;
  90   EFI_DEVICE_PATH_PROTOCOL        *DevicePath;
  91
  92   UINT64                          StartingAddr;
  93   UINT64                          Size;
  94   EFI_GUID                        TypeGuid;
  95   UINT16                          InstanceNumber;
  96   RAM_DISK_CREATE_METHOD          CreateMethod;
  97
  98   LIST_ENTRY                      ThisInstance;
  99 } RAM_DISK_PRIVATE_DATA;
 100
 101 #define RAM_DISK_PRIVATE_DATA_SIGNATURE     SIGNATURE_32 ('R', 'D', 'S', 'K')
 102 #define RAM_DISK_PRIVATE_FROM_BLKIO(a)      CR (a, RAM_DISK_PRIVATE_DATA, BlockIo, RAM_DISK_PRIVATE_DATA_SIGNATURE)
 103 #define RAM_DISK_PRIVATE_FROM_THIS(a)       CR (a, RAM_DISK_PRIVATE_DATA, ThisInstance, RAM_DISK_PRIVATE_DATA_SIGNATURE)
 104
 105 ///
 106 /// RAM disk HII-related definitions and declarations
 107 ///
 108
 109 //
 110 // Tool generated IFR binary data and String package data
 111 //
 112 extern  UINT8                     RamDiskHiiBin[];
 113 extern  UINT8                     RamDiskDxeStrings[];
 114
 115 typedef struct {
 116   VENDOR_DEVICE_PATH              VendorDevicePath;
 117   EFI_DEVICE_PATH_PROTOCOL        End;
 118 } HII_VENDOR_DEVICE_PATH;
 119
 120 typedef struct {
 121   UINTN                           Signature;
 122
 123   EFI_HII_CONFIG_ACCESS_PROTOCOL  ConfigAccess;
 124   EFI_HANDLE                      DriverHandle;
 125   EFI_HII_HANDLE                  HiiHandle;
 126 } RAM_DISK_CONFIG_PRIVATE_DATA;
 127
 128 extern RAM_DISK_CONFIG_PRIVATE_DATA    mRamDiskConfigPrivateDataTemplate;
 129
 130 #define RAM_DISK_CONFIG_PRIVATE_DATA_SIGNATURE   SIGNATURE_32 ('R', 'C', 'F', 'G')
 131 #define RAM_DISK_CONFIG_PRIVATE_FROM_THIS(a)     CR (a, RAM_DISK_CONFIG_PRIVATE_DATA, ConfigAccess, RAM_DISK_CONFIG_PRIVATE_DATA_SIGNATURE)
 132
 133 #define RAM_DISK_LIST_VAR_OFFSET                 ((UINT16) OFFSET_OF (RAM_DISK_CONFIGURATION, RamDiskList))
 134
 135 /**
 136   Register a RAM disk with specified address, size and type.
 137
 138   @param[in]  RamDiskBase    The base address of registered RAM disk.
 139   @param[in]  RamDiskSize    The size of registered RAM disk.
 140   @param[in]  RamDiskType    The type of registered RAM disk. The GUID can be
 141                              any of the values defined in section 9.3.6.9, or a
 142                              vendor defined GUID.
 143   @param[in]  ParentDevicePath
 144                              Pointer to the parent device path. If there is no
 145                              parent device path then ParentDevicePath is NULL.
 146   @param[out] DevicePath     On return, points to a pointer to the device path
 147                              of the RAM disk device.
 148                              If ParentDevicePath is not NULL, the returned
 149                              DevicePath is created by appending a RAM disk node
 150                              to the parent device path. If ParentDevicePath is
 151                              NULL, the returned DevicePath is a RAM disk device
 152                              path without appending. This function is
 153                              responsible for allocating the buffer DevicePath
 154                              with the boot service AllocatePool().
 155
 156   @retval EFI_SUCCESS             The RAM disk is registered successfully.
 157   @retval EFI_INVALID_PARAMETER   DevicePath or RamDiskType is NULL.
 158                                   RamDiskSize is 0.
 159   @retval EFI_ALREADY_STARTED     A Device Path Protocol instance to be created
 160                                   is already present in the handle database.
 161   @retval EFI_OUT_OF_RESOURCES    The RAM disk register operation fails due to
 162                                   resource limitation.
 163
 164 **/
 165 EFI_STATUS
 166 EFIAPI
 167 RamDiskRegister (
 168   IN UINT64                       RamDiskBase,
 169   IN UINT64                       RamDiskSize,
 170   IN EFI_GUID                     *RamDiskType,
 171   IN EFI_DEVICE_PATH              *ParentDevicePath     OPTIONAL,
 172   OUT EFI_DEVICE_PATH_PROTOCOL    **DevicePath
 173   );
 174
 175 /**
 176   Unregister a RAM disk specified by DevicePath.
 177
 178   @param[in] DevicePath      A pointer to the device path that describes a RAM
 179                              Disk device.
 180
 181   @retval EFI_SUCCESS             The RAM disk is unregistered successfully.
 182   @retval EFI_INVALID_PARAMETER   DevicePath is NULL.
 183   @retval EFI_UNSUPPORTED         The device specified by DevicePath is not a
 184                                   valid ramdisk device path and not supported
 185                                   by the driver.
 186   @retval EFI_NOT_FOUND           The RAM disk pointed by DevicePath doesn't
 187                                   exist.
 188
 189 **/
 190 EFI_STATUS
 191 EFIAPI
 192 RamDiskUnregister (
 193   IN  EFI_DEVICE_PATH_PROTOCOL    *DevicePath
 194   );
 195
 196 /**
 197   Initialize the BlockIO protocol of a RAM disk device.
 198
 199   @param[in] PrivateData     Points to RAM disk private data.
 200
 201 **/
 202 VOID
 203 RamDiskInitBlockIo (
 204   IN     RAM_DISK_PRIVATE_DATA    *PrivateData
 205   );
 206
 207 /**
 208   Reset the Block Device.
 209
 210   @param[in] This            Indicates a pointer to the calling context.
 211   @param[in] ExtendedVerification
 212                              Driver may perform diagnostics on reset.
 213
 214   @retval EFI_SUCCESS             The device was reset.
 215   @retval EFI_DEVICE_ERROR        The device is not functioning properly and
 216                                   could not be reset.
 217
 218 **/
 219 EFI_STATUS
 220 EFIAPI
 221 RamDiskBlkIoReset (
 222   IN EFI_BLOCK_IO_PROTOCOL        *This,
 223   IN BOOLEAN                      ExtendedVerification
 224   );
 225
 226 /**
 227   Read BufferSize bytes from Lba into Buffer.
 228
 229   @param[in]  This           Indicates a pointer to the calling context.
 230   @param[in]  MediaId        Id of the media, changes every time the media is
 231                              replaced.
 232   @param[in]  Lba            The starting Logical Block Address to read from.
 233   @param[in]  BufferSize     Size of Buffer, must be a multiple of device block
 234                              size.
 235   @param[out] Buffer         A pointer to the destination buffer for the data.
 236                              The caller is responsible for either having
 237                              implicit or explicit ownership of the buffer.
 238
 239   @retval EFI_SUCCESS             The data was read correctly from the device.
 240   @retval EFI_DEVICE_ERROR        The device reported an error while performing
 241                                   the read.
 242   @retval EFI_NO_MEDIA            There is no media in the device.
 243   @retval EFI_MEDIA_CHANGED       The MediaId does not matched the current
 244                                   device.
 245   @retval EFI_BAD_BUFFER_SIZE     The Buffer was not a multiple of the block
 246                                   size of the device.
 247   @retval EFI_INVALID_PARAMETER   The read request contains LBAs that are not
 248                                   valid, or the buffer is not on proper alignment.
 249
 250 **/
 251 EFI_STATUS
 252 EFIAPI
 253 RamDiskBlkIoReadBlocks (
 254   IN EFI_BLOCK_IO_PROTOCOL        *This,
 255   IN UINT32                       MediaId,
 256   IN EFI_LBA                      Lba,
 257   IN UINTN                        BufferSize,
 258   OUT VOID                        *Buffer
 259   );
 260
 261 /**
 262   Write BufferSize bytes from Lba into Buffer.
 263
 264   @param[in] This            Indicates a pointer to the calling context.
 265   @param[in] MediaId         The media ID that the write request is for.
 266   @param[in] Lba             The starting logical block address to be written.
 267                              The caller is responsible for writing to only
 268                              legitimate locations.
 269   @param[in] BufferSize      Size of Buffer, must be a multiple of device block
 270                              size.
 271   @param[in] Buffer          A pointer to the source buffer for the data.
 272
 273   @retval EFI_SUCCESS             The data was written correctly to the device.
 274   @retval EFI_WRITE_PROTECTED     The device can not be written to.
 275   @retval EFI_DEVICE_ERROR        The device reported an error while performing
 276                                   the write.
 277   @retval EFI_NO_MEDIA            There is no media in the device.
 278   @retval EFI_MEDIA_CHNAGED       The MediaId does not matched the current
 279                                   device.
 280   @retval EFI_BAD_BUFFER_SIZE     The Buffer was not a multiple of the block
 281                                   size of the device.
 282   @retval EFI_INVALID_PARAMETER   The write request contains LBAs that are not
 283                                   valid, or the buffer is not on proper alignment.
 284
 285 **/
 286 EFI_STATUS
 287 EFIAPI
 288 RamDiskBlkIoWriteBlocks (
 289   IN EFI_BLOCK_IO_PROTOCOL        *This,
 290   IN UINT32                       MediaId,
 291   IN EFI_LBA                      Lba,
 292   IN UINTN                        BufferSize,
 293   IN VOID                         *Buffer
 294   );
 295
 296 /**
 297   Flush the Block Device.
 298
 299   @param[in] This            Indicates a pointer to the calling context.
 300
 301   @retval EFI_SUCCESS             All outstanding data was written to the device.
 302   @retval EFI_DEVICE_ERROR        The device reported an error while writting
 303                                   back the data
 304   @retval EFI_NO_MEDIA            There is no media in the device.
 305
 306 **/
 307 EFI_STATUS
 308 EFIAPI
 309 RamDiskBlkIoFlushBlocks (
 310   IN EFI_BLOCK_IO_PROTOCOL        *This
 311   );
 312
 313 /**
 314   This function publish the RAM disk configuration Form.
 315
 316   @param[in, out]  ConfigPrivateData
 317                              Points to RAM disk configuration private data.
 318
 319   @retval EFI_SUCCESS             HII Form is installed successfully.
 320   @retval EFI_OUT_OF_RESOURCES    Not enough resource for HII Form installation.
 321   @retval Others                  Other errors as indicated.
 322
 323 **/
 324 EFI_STATUS
 325 InstallRamDiskConfigForm (
 326   IN OUT RAM_DISK_CONFIG_PRIVATE_DATA       *ConfigPrivateData
 327   );
 328
 329 /**
 330   This function removes RAM disk configuration Form.
 331
 332   @param[in, out]  ConfigPrivateData
 333                              Points to RAM disk configuration private data.
 334
 335 **/
 336 VOID
 337 UninstallRamDiskConfigForm (
 338   IN OUT RAM_DISK_CONFIG_PRIVATE_DATA       *ConfigPrivateData
 339   );
 340
 341 /**
 342   Unregister all registered RAM disks.
 343
 344 **/
 345 VOID
 346 UnregisterAllRamDisks (
 347   VOID
 348   );
 349
 350 /**
 351   This function allows a caller to extract the current configuration for one
 352   or more named elements from the target driver.
 353
 354   @param[in]  This           Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
 355   @param[in]  Request        A null-terminated Unicode string in
 356                              <ConfigRequest> format.
 357   @param[out] Progress       On return, points to a character in the Request
 358                              string. Points to the string's null terminator if
 359                              request was successful. Points to the most recent
 360                              '&' before the first failing name/value pair (or
 361                              the beginning of the string if the failure is in
 362                              the first name/value pair) if the request was not
 363                              successful.
 364   @param[out] Results        A null-terminated Unicode string in
 365                              <ConfigAltResp> format which has all values filled
 366                              in for the names in the Request string. String to
 367                              be allocated by the called function.
 368
 369   @retval EFI_SUCCESS             The Results is filled with the requested
 370                                   values.
 371   @retval EFI_OUT_OF_RESOURCES    Not enough memory to store the results.
 372   @retval EFI_INVALID_PARAMETER   Request is illegal syntax, or unknown name.
 373   @retval EFI_NOT_FOUND           Routing data doesn't match any storage in
 374                                   this driver.
 375
 376 **/
 377 EFI_STATUS
 378 EFIAPI
 379 RamDiskExtractConfig (
 380   IN CONST EFI_HII_CONFIG_ACCESS_PROTOCOL   *This,
 381   IN CONST EFI_STRING                       Request,
 382        OUT EFI_STRING                       *Progress,
 383        OUT EFI_STRING                       *Results
 384   );
 385
 386 /**
 387   This function processes the results of changes in configuration.
 388
 389   @param[in]  This           Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
 390   @param[in]  Configuration  A null-terminated Unicode string in <ConfigResp>
 391                              format.
 392   @param[out] Progress       A pointer to a string filled in with the offset of
 393                              the most recent '&' before the first failing
 394                              name/value pair (or the beginning of the string if
 395                              the failure is in the first name/value pair) or
 396                              the terminating NULL if all was successful.
 397
 398   @retval EFI_SUCCESS             The Results is processed successfully.
 399   @retval EFI_INVALID_PARAMETER   Configuration is NULL.
 400   @retval EFI_NOT_FOUND           Routing data doesn't match any storage in
 401                                   this driver.
 402
 403 **/
 404 EFI_STATUS
 405 EFIAPI
 406 RamDiskRouteConfig (
 407   IN CONST EFI_HII_CONFIG_ACCESS_PROTOCOL   *This,
 408   IN CONST EFI_STRING                       Configuration,
 409        OUT EFI_STRING                       *Progress
 410   );
 411
 412 /**
 413   This function processes the results of changes in configuration.
 414
 415   @param[in]  This           Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
 416   @param[in]  Action         Specifies the type of action taken by the browser.
 417   @param[in]  QuestionId     A unique value which is sent to the original
 418                              exporting driver so that it can identify the type
 419                              of data to expect.
 420   @param[in]  Type           The type of value for the question.
 421   @param[in]  Value          A pointer to the data being sent to the original
 422                              exporting driver.
 423   @param[out] ActionRequest  On return, points to the action requested by the
 424                              callback function.
 425
 426   @retval EFI_SUCCESS             The callback successfully handled the action.
 427   @retval EFI_OUT_OF_RESOURCES    Not enough storage is available to hold the
 428                                   variable and its data.
 429   @retval EFI_DEVICE_ERROR        The variable could not be saved.
 430   @retval EFI_UNSUPPORTED         The specified Action is not supported by the
 431                                   callback.
 432
 433 **/
 434 EFI_STATUS
 435 EFIAPI
 436 RamDiskCallback (
 437   IN CONST EFI_HII_CONFIG_ACCESS_PROTOCOL   *This,
 438   IN     EFI_BROWSER_ACTION                 Action,
 439   IN     EFI_QUESTION_ID                    QuestionId,
 440   IN     UINT8                              Type,
 441   IN     EFI_IFR_TYPE_VALUE                 *Value,
 442      OUT EFI_BROWSER_ACTION_REQUEST         *ActionRequest
 443   );
 444
 445
 446 /**
 447   This function gets the file information from an open file descriptor,
 448   and stores it in a buffer allocated from pool.
 449
 450   @param[in] FHand           File Handle.
 451
 452   @return    A pointer to a buffer with file information or NULL is returned.
 453
 454 **/
 455 EFI_FILE_INFO *
 456 FileInfo (
 457   IN EFI_FILE_HANDLE                        FHand
 458   );
 459
 460
 461 /**
 462   This function will open a file or directory referenced by DevicePath.
 463
 464   This function opens a file with the open mode according to the file path. The
 465   Attributes is valid only for EFI_FILE_MODE_CREATE.
 466
 467   @param[in, out] FilePath   On input, the device path to the file.
 468                              On output, the remaining device path.
 469   @param[out]     FileHandle Pointer to the file handle.
 470   @param[in]      OpenMode   The mode to open the file with.
 471   @param[in]      Attributes The file's file attributes.
 472
 473   @retval EFI_SUCCESS             The information was set.
 474   @retval EFI_INVALID_PARAMETER   One of the parameters has an invalid value.
 475   @retval EFI_UNSUPPORTED         Could not open the file path.
 476   @retval EFI_NOT_FOUND           The specified file could not be found on the
 477                                   device or the file system could not be found
 478                                   on the device.
 479   @retval EFI_NO_MEDIA            The device has no medium.
 480   @retval EFI_MEDIA_CHANGED       The device has a different medium in it or
 481                                   the medium is no longer supported.
 482   @retval EFI_DEVICE_ERROR        The device reported an error.
 483   @retval EFI_VOLUME_CORRUPTED    The file system structures are corrupted.
 484   @retval EFI_WRITE_PROTECTED     The file or medium is write protected.
 485   @retval EFI_ACCESS_DENIED       The file was opened read only.
 486   @retval EFI_OUT_OF_RESOURCES    Not enough resources were available to open
 487                                   the file.
 488   @retval EFI_VOLUME_FULL         The volume is full.
 489 **/
 490 EFI_STATUS
 491 EFIAPI
 492 OpenFileByDevicePath(
 493   IN OUT EFI_DEVICE_PATH_PROTOCOL           **FilePath,
 494   OUT EFI_FILE_HANDLE                       *FileHandle,
 495   IN UINT64                                 OpenMode,
 496   IN UINT64                                 Attributes
 497   );
 498
 499 #endif