Committing changes to the comments, after review with engineers.

[mirror_edk2.git] / IntelFrameworkPkg / Include / Guid / Capsule.h

/** @file\r
  Framework Capule related Definition.\r
\r
  Copyright (c) 2007 - 2009, Intel Corporation\r
  All rights reserved. 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
  @par Revision Reference:\r
  Capsule Spec Version 0.9\r
**/\r
\r
#ifndef _CAPSULE_GUID_H__\r
#define _CAPSULE_GUID_H__\r
\r
//\r
// This is the GUID of the capsule header of the image on disk.\r
//\r
#define EFI_CAPSULE_GUID \\r
  { \\r
    0x3B6686BD, 0x0D76, 0x4030, {0xB7, 0x0E, 0xB5, 0x51, 0x9E, 0x2F, 0xC5, 0xA0 } \\r
  }\r
\r
//\r
// This is the GUID of the configuration results file created by the capsule\r
// application.\r
//\r
#define EFI_CONFIG_FILE_NAME_GUID \\r
  { \\r
    0x98B8D59B, 0xE8BA, 0x48EE, {0x98, 0xDD, 0xC2, 0x95, 0x39, 0x2F, 0x1E, 0xDB } \\r
  }\r
\r
///\r
/// Bits in the flags field of the capsule header\r
/// This flag is set if the capsule can support setup changes, and cleared if it cannot.\r
///\r
#define EFI_CAPSULE_HEADER_FLAG_SETUP 0x00000001\r
\r
#define CAPSULE_BLOCK_DESCRIPTOR_SIGNATURE  SIGNATURE_32 ('C', 'B', 'D', 'S')\r
\r
//\r
// An array of these structs describe the blocks that make up a capsule for\r
// a capsule update.\r
//\r
typedef struct {\r
  UINT64                Length;     ///< length of the data block\r
  EFI_PHYSICAL_ADDRESS  Data;       ///< physical address of the data block\r
  UINT32                Signature;  ///< CBDS\r
  UINT32                CheckSum;   ///< to sum this structure to 0\r
} FRAMEWORK_EFI_CAPSULE_BLOCK_DESCRIPTOR;\r
\r
typedef struct {\r
  EFI_GUID  OemGuid;\r
  UINT32    HeaderSize;\r
  //\r
  // UINT8                       OemHdrData[];\r
  //\r
} EFI_CAPSULE_OEM_HEADER;\r
\r
typedef struct {\r
  ///\r
  /// A defined GUID that indicates the start of a capsule.\r
  ///\r
  EFI_GUID  CapsuleGuid;\r
  ///\r
  /// The size of the EFI_CAPSULE_HEADER structure.\r
  ///\r
  UINT32    HeaderSize;\r
  ///\r
  /// A bit-mapped list describing the capsule's attributes. \r
  /// All undefined bits should be written as zero (0)\r
  ///\r
  UINT32    Flags;\r
  ///\r
  /// The length in bytes (27,415 for an image containing 27,415 bytes) of the entire image\r
  /// including all headers. If this value is greater than the size of the data presented in\r
  /// the capsule body, the image is separated across multiple media. If this\r
  /// value is less than the size of the data, it is an error.\r
  ///\r
  UINT32    CapsuleImageSize;\r
  ///\r
  /// A zero-based number that enables a capsule to be split into pieces and then\r
  /// recombined for easier transfer across media with limited size. The lower the\r
  /// SequenceNumber, the earlier in the final image that the part of the capsule is to\r
  /// appear. In capsules that are not split, this value shall be zero.\r
  ///\r
  UINT32    SequenceNumber;\r
  ///\r
  /// Used to group the various pieces of a split capsule to ensure that they comprise the\r
  /// same base image. It is valid for this item to be zero, in which case the capsule cannot\r
  /// be split into components.\r
  ///\r
  EFI_GUID  InstanceId;\r
  ///\r
  /// The offset in bytes from the beginning of the header to the start of an EFI string that\r
  /// contains a description of the identity of the subcapsules that make up the capsule. If\r
  /// the capsule is not split, this value should be zero. The same string should be\r
  /// presented for all subcapsules that constitute the same capsule.\r
  ///\r
  UINT32    OffsetToSplitInformation;\r
  ///\r
  /// The offset in bytes from the beginning of the header to the start of the part of the\r
  /// capsule that is to be transferred to DXE.\r
  ///\r
  UINT32    OffsetToCapsuleBody;\r
  ///\r
  /// The offset in bytes from the beginning of the header to the start of the OEM-defined\r
  /// header. This value must be less than OffsetToCapsuleBody.\r
  ///\r
  UINT32    OffsetToOemDefinedHeader;\r
  ///\r
  /// The offset in bytes from the beginning of the header to the start of human-readable\r
  /// text that describes the entity that created the capsule. This value must be less than OffsetToCapsuleBody.\r
  ///\r
  UINT32    OffsetToAuthorInformation;\r
  ///\r
  /// The offset in bytes from the beginning of the header to the start of human-readable\r
  /// text that describes the revision of the capsule and/or the capsule's contents. This\r
  /// value must be less than OffsetToCapsuleBody.\r
  ///\r
  UINT32    OffsetToRevisionInformation;\r
  ///\r
  /// The offset in bytes from the beginning of the header to the start of a one-line (less\r
  /// than 40 Unicode characters in any language) description of the capsule. It is intended\r
  /// to be used by OS-present applications when providing a list of capsules from which\r
  /// the user can choose. This value must be less than OffsetToCapsuleBody.\r
  ///\r
  UINT32    OffsetToShortDescription;\r
  ///\r
  /// The offset in bytes from the beginning of the header to the start of an EFI string\r
  ///\r
  UINT32    OffsetToLongDescription;\r
  ///\r
  /// This field is reserved for future use by this specification. For future compatibility,\r
  /// this field must be set to zero\r
  ///\r
  UINT32    OffsetToApplicableDevices;\r
} FRAMEWORK_EFI_CAPSULE_HEADER;\r
\r
extern EFI_GUID gEfiCapsuleGuid;\r
extern EFI_GUID gEfiConfigFileNameGuid;\r
\r
#endif\r