Clean up DEC files:

[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 - 2008, Intel Corporation. All rights reserved.<BR>\r
This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
which accompanies this distribution.  The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\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
} 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