MdeModulePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / MdeModulePkg / Core / Dxe / FwVolBlock / FwVolBlock.h

/** @file\r
  Firmware Volume Block protocol functions.\r
  Consumes FV hobs and creates appropriate block protocols.\r
\r
Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef _FWVOL_BLOCK_H_\r
#define _FWVOL_BLOCK_H_\r
\r
\r
#define FVB_DEVICE_SIGNATURE       SIGNATURE_32('_','F','V','B')\r
\r
\r
typedef struct {\r
  UINTN                       Base;\r
  UINTN                       Length;\r
} LBA_CACHE;\r
\r
typedef struct {\r
  MEMMAP_DEVICE_PATH          MemMapDevPath;\r
  EFI_DEVICE_PATH_PROTOCOL    EndDevPath;\r
} FV_MEMMAP_DEVICE_PATH;\r
\r
//\r
// UEFI Specification define FV device path format if FV provide name guid in extension header\r
//\r
typedef struct {\r
  MEDIA_FW_VOL_DEVICE_PATH    FvDevPath;\r
  EFI_DEVICE_PATH_PROTOCOL    EndDevPath;\r
} FV_PIWG_DEVICE_PATH;\r
\r
typedef struct {\r
  UINTN                                 Signature;\r
  EFI_HANDLE                            Handle;\r
  EFI_DEVICE_PATH_PROTOCOL              *DevicePath;\r
  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL    FwVolBlockInstance;\r
  UINTN                                 NumBlocks;\r
  LBA_CACHE                             *LbaCache;\r
  UINT32                                FvbAttributes;\r
  EFI_PHYSICAL_ADDRESS                  BaseAddress;\r
  UINT32                                AuthenticationStatus;\r
} EFI_FW_VOL_BLOCK_DEVICE;\r
\r
\r
#define FVB_DEVICE_FROM_THIS(a) \\r
  CR(a, EFI_FW_VOL_BLOCK_DEVICE, FwVolBlockInstance, FVB_DEVICE_SIGNATURE)\r
\r
\r
/**\r
  Retrieves Volume attributes.  No polarity translations are done.\r
\r
  @param  This                   Calling context\r
  @param  Attributes             output buffer which contains attributes\r
\r
  @retval EFI_SUCCESS            The firmware volume attributes were returned.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FwVolBlockGetAttributes (\r
  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,\r
  OUT       EFI_FVB_ATTRIBUTES_2                *Attributes\r
  );\r
\r
\r
\r
/**\r
  Modifies the current settings of the firmware volume according to the input parameter.\r
\r
  @param  This                   Calling context\r
  @param  Attributes             input buffer which contains attributes\r
\r
  @retval EFI_SUCCESS            The firmware volume attributes were returned.\r
  @retval EFI_INVALID_PARAMETER  The attributes requested are in conflict with\r
                                 the capabilities as declared in the firmware\r
                                 volume header.\r
  @retval EFI_UNSUPPORTED        Not supported.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FwVolBlockSetAttributes (\r
  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,\r
  IN CONST  EFI_FVB_ATTRIBUTES_2                *Attributes\r
  );\r
\r
\r
\r
/**\r
  The EraseBlock() function erases one or more blocks as denoted by the\r
  variable argument list. The entire parameter list of blocks must be verified\r
  prior to erasing any blocks.  If a block is requested that does not exist\r
  within the associated firmware volume (it has a larger index than the last\r
  block of the firmware volume), the EraseBlock() function must return\r
  EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.\r
\r
  @param  This                   Calling context\r
  @param  ...                    Starting LBA followed by Number of Lba to erase.\r
                                 a -1 to terminate the list.\r
\r
  @retval EFI_SUCCESS            The erase request was successfully completed.\r
  @retval EFI_ACCESS_DENIED      The firmware volume is in the WriteDisabled\r
                                 state.\r
  @retval EFI_DEVICE_ERROR       The block device is not functioning correctly\r
                                 and could not be written. The firmware device\r
                                 may have been partially erased.\r
  @retval EFI_INVALID_PARAMETER  One or more of the LBAs listed in the variable\r
                                 argument list do\r
  @retval EFI_UNSUPPORTED        Not supported.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FwVolBlockEraseBlock (\r
  IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL    *This,\r
  ...\r
  );\r
\r
\r
\r
/**\r
  Read the specified number of bytes from the block to the input buffer.\r
\r
  @param  This                   Indicates the calling context.\r
  @param  Lba                    The starting logical block index to read.\r
  @param  Offset                 Offset into the block at which to begin reading.\r
  @param  NumBytes               Pointer to a UINT32. At entry, *NumBytes\r
                                 contains the total size of the buffer. At exit,\r
                                 *NumBytes contains the total number of bytes\r
                                 actually read.\r
  @param  Buffer                 Pinter to a caller-allocated buffer that\r
                                 contains the destine for the read.\r
\r
  @retval EFI_SUCCESS            The firmware volume was read successfully.\r
  @retval EFI_BAD_BUFFER_SIZE    The read was attempted across an LBA boundary.\r
  @retval EFI_ACCESS_DENIED      Access denied.\r
  @retval EFI_DEVICE_ERROR       The block device is malfunctioning and could not\r
                                 be read.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FwVolBlockReadBlock (\r
  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL   *This,\r
  IN CONST  EFI_LBA                              Lba,\r
  IN CONST  UINTN                                Offset,\r
  IN OUT    UINTN                                *NumBytes,\r
  IN OUT    UINT8                                *Buffer\r
  );\r
\r
\r
\r
/**\r
  Writes the specified number of bytes from the input buffer to the block.\r
\r
  @param  This                   Indicates the calling context.\r
  @param  Lba                    The starting logical block index to write to.\r
  @param  Offset                 Offset into the block at which to begin writing.\r
  @param  NumBytes               Pointer to a UINT32. At entry, *NumBytes\r
                                 contains the total size of the buffer. At exit,\r
                                 *NumBytes contains the total number of bytes\r
                                 actually written.\r
  @param  Buffer                 Pinter to a caller-allocated buffer that\r
                                 contains the source for the write.\r
\r
  @retval EFI_SUCCESS            The firmware volume was written successfully.\r
  @retval EFI_BAD_BUFFER_SIZE    The write was attempted across an LBA boundary.\r
                                 On output, NumBytes contains the total number of\r
                                 bytes actually written.\r
  @retval EFI_ACCESS_DENIED      The firmware volume is in the WriteDisabled\r
                                 state.\r
  @retval EFI_DEVICE_ERROR       The block device is malfunctioning and could not\r
                                 be written.\r
  @retval EFI_UNSUPPORTED        Not supported.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FwVolBlockWriteBlock (\r
  IN     EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL   *This,\r
  IN     EFI_LBA                              Lba,\r
  IN     UINTN                                Offset,\r
  IN OUT UINTN                                *NumBytes,\r
  IN     UINT8                                *Buffer\r
  );\r
\r
\r
\r
/**\r
  Get Fvb's base address.\r
\r
  @param  This                   Indicates the calling context.\r
  @param  Address                Fvb device base address.\r
\r
  @retval EFI_SUCCESS            Successfully got Fvb's base address.\r
  @retval EFI_UNSUPPORTED        Not supported.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FwVolBlockGetPhysicalAddress (\r
  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,\r
  OUT       EFI_PHYSICAL_ADDRESS                *Address\r
  );\r
\r
\r
\r
/**\r
  Retrieves the size in bytes of a specific block within a firmware volume.\r
\r
  @param  This                   Indicates the calling context.\r
  @param  Lba                    Indicates the block for which to return the\r
                                 size.\r
  @param  BlockSize              Pointer to a caller-allocated UINTN in which the\r
                                 size of the block is returned.\r
  @param  NumberOfBlocks         Pointer to a caller-allocated UINTN in which the\r
                                 number of consecutive blocks starting with Lba\r
                                 is returned. All blocks in this range have a\r
                                 size of BlockSize.\r
\r
  @retval EFI_SUCCESS            The firmware volume base address is returned.\r
  @retval EFI_INVALID_PARAMETER  The requested LBA is out of range.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FwVolBlockGetBlockSize (\r
  IN CONST  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  *This,\r
  IN CONST  EFI_LBA                             Lba,\r
  IN OUT    UINTN                               *BlockSize,\r
  IN OUT    UINTN                               *NumberOfBlocks\r
  );\r
\r
\r
#endif\r