MdePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / MdePkg / Include / Pi / PiHob.h

/** @file\r
  HOB related definitions in PI.\r
\r
Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
  @par Revision Reference:\r
  PI Version 1.6\r
\r
**/\r
\r
#ifndef __PI_HOB_H__\r
#define __PI_HOB_H__\r
\r
//\r
// HobType of EFI_HOB_GENERIC_HEADER.\r
//\r
#define EFI_HOB_TYPE_HANDOFF              0x0001\r
#define EFI_HOB_TYPE_MEMORY_ALLOCATION    0x0002\r
#define EFI_HOB_TYPE_RESOURCE_DESCRIPTOR  0x0003\r
#define EFI_HOB_TYPE_GUID_EXTENSION       0x0004\r
#define EFI_HOB_TYPE_FV                   0x0005\r
#define EFI_HOB_TYPE_CPU                  0x0006\r
#define EFI_HOB_TYPE_MEMORY_POOL          0x0007\r
#define EFI_HOB_TYPE_FV2                  0x0009\r
#define EFI_HOB_TYPE_LOAD_PEIM_UNUSED     0x000A\r
#define EFI_HOB_TYPE_UEFI_CAPSULE         0x000B\r
#define EFI_HOB_TYPE_FV3                  0x000C\r
#define EFI_HOB_TYPE_UNUSED               0xFFFE\r
#define EFI_HOB_TYPE_END_OF_HOB_LIST      0xFFFF\r
\r
///\r
/// Describes the format and size of the data inside the HOB.\r
/// All HOBs must contain this generic HOB header.\r
///\r
typedef struct {\r
  ///\r
  /// Identifies the HOB data structure type.\r
  ///\r
  UINT16    HobType;\r
  ///\r
  /// The length in bytes of the HOB.\r
  ///\r
  UINT16    HobLength;\r
  ///\r
  /// This field must always be set to zero.\r
  ///\r
  UINT32    Reserved;\r
} EFI_HOB_GENERIC_HEADER;\r
\r
\r
///\r
/// Value of version  in EFI_HOB_HANDOFF_INFO_TABLE.\r
///\r
#define EFI_HOB_HANDOFF_TABLE_VERSION 0x0009\r
\r
///\r
/// Contains general state information used by the HOB producer phase.\r
/// This HOB must be the first one in the HOB list.\r
///\r
typedef struct {\r
  ///\r
  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_HANDOFF.\r
  ///\r
  EFI_HOB_GENERIC_HEADER  Header;\r
  ///\r
  /// The version number pertaining to the PHIT HOB definition.\r
  /// This value is four bytes in length to provide an 8-byte aligned entry\r
  /// when it is combined with the 4-byte BootMode.\r
  ///\r
  UINT32                  Version;\r
  ///\r
  /// The system boot mode as determined during the HOB producer phase.\r
  ///\r
  EFI_BOOT_MODE           BootMode;\r
  ///\r
  /// The highest address location of memory that is allocated for use by the HOB producer\r
  /// phase. This address must be 4-KB aligned to meet page restrictions of UEFI.\r
  ///\r
  EFI_PHYSICAL_ADDRESS    EfiMemoryTop;\r
  ///\r
  /// The lowest address location of memory that is allocated for use by the HOB producer phase.\r
  ///\r
  EFI_PHYSICAL_ADDRESS    EfiMemoryBottom;\r
  ///\r
  /// The highest address location of free memory that is currently available\r
  /// for use by the HOB producer phase.\r
  ///\r
  EFI_PHYSICAL_ADDRESS    EfiFreeMemoryTop;\r
  ///\r
  /// The lowest address location of free memory that is available for use by the HOB producer phase.\r
  ///\r
  EFI_PHYSICAL_ADDRESS    EfiFreeMemoryBottom;\r
  ///\r
  /// The end of the HOB list.\r
  ///\r
  EFI_PHYSICAL_ADDRESS    EfiEndOfHobList;\r
} EFI_HOB_HANDOFF_INFO_TABLE;\r
\r
///\r
/// EFI_HOB_MEMORY_ALLOCATION_HEADER describes the\r
/// various attributes of the logical memory allocation. The type field will be used for\r
/// subsequent inclusion in the UEFI memory map.\r
///\r
typedef struct {\r
  ///\r
  /// A GUID that defines the memory allocation region's type and purpose, as well as\r
  /// other fields within the memory allocation HOB. This GUID is used to define the\r
  /// additional data within the HOB that may be present for the memory allocation HOB.\r
  /// Type EFI_GUID is defined in InstallProtocolInterface() in the UEFI 2.0\r
  /// specification.\r
  ///\r
  EFI_GUID              Name;\r
\r
  ///\r
  /// The base address of memory allocated by this HOB. Type\r
  /// EFI_PHYSICAL_ADDRESS is defined in AllocatePages() in the UEFI 2.0\r
  /// specification.\r
  ///\r
  EFI_PHYSICAL_ADDRESS  MemoryBaseAddress;\r
\r
  ///\r
  /// The length in bytes of memory allocated by this HOB.\r
  ///\r
  UINT64                MemoryLength;\r
\r
  ///\r
  /// Defines the type of memory allocated by this HOB. The memory type definition\r
  /// follows the EFI_MEMORY_TYPE definition. Type EFI_MEMORY_TYPE is defined\r
  /// in AllocatePages() in the UEFI 2.0 specification.\r
  ///\r
  EFI_MEMORY_TYPE       MemoryType;\r
\r
  ///\r
  /// Padding for Itanium processor family\r
  ///\r
  UINT8                 Reserved[4];\r
} EFI_HOB_MEMORY_ALLOCATION_HEADER;\r
\r
///\r
/// Describes all memory ranges used during the HOB producer\r
/// phase that exist outside the HOB list. This HOB type\r
/// describes how memory is used, not the physical attributes of memory.\r
///\r
typedef struct {\r
  ///\r
  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_ALLOCATION.\r
  ///\r
  EFI_HOB_GENERIC_HEADER            Header;\r
  ///\r
  /// An instance of the EFI_HOB_MEMORY_ALLOCATION_HEADER that describes the\r
  /// various attributes of the logical memory allocation.\r
  ///\r
  EFI_HOB_MEMORY_ALLOCATION_HEADER  AllocDescriptor;\r
  //\r
  // Additional data pertaining to the "Name" Guid memory\r
  // may go here.\r
  //\r
} EFI_HOB_MEMORY_ALLOCATION;\r
\r
\r
///\r
/// Describes the memory stack that is produced by the HOB producer\r
/// phase and upon which all post-memory-installed executable\r
/// content in the HOB producer phase is executing.\r
///\r
typedef struct {\r
  ///\r
  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_ALLOCATION.\r
  ///\r
  EFI_HOB_GENERIC_HEADER            Header;\r
  ///\r
  /// An instance of the EFI_HOB_MEMORY_ALLOCATION_HEADER that describes the\r
  /// various attributes of the logical memory allocation.\r
  ///\r
  EFI_HOB_MEMORY_ALLOCATION_HEADER  AllocDescriptor;\r
} EFI_HOB_MEMORY_ALLOCATION_STACK;\r
\r
///\r
/// Defines the location of the boot-strap\r
/// processor (BSP) BSPStore ("Backing Store Pointer Store").\r
/// This HOB is valid for the Itanium processor family only\r
/// register overflow store.\r
///\r
typedef struct {\r
  ///\r
  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_ALLOCATION.\r
  ///\r
  EFI_HOB_GENERIC_HEADER            Header;\r
  ///\r
  /// An instance of the EFI_HOB_MEMORY_ALLOCATION_HEADER that describes the\r
  /// various attributes of the logical memory allocation.\r
  ///\r
  EFI_HOB_MEMORY_ALLOCATION_HEADER  AllocDescriptor;\r
} EFI_HOB_MEMORY_ALLOCATION_BSP_STORE;\r
\r
///\r
/// Defines the location and entry point of the HOB consumer phase.\r
///\r
typedef struct {\r
  ///\r
  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_ALLOCATION.\r
  ///\r
  EFI_HOB_GENERIC_HEADER            Header;\r
  ///\r
  /// An instance of the EFI_HOB_MEMORY_ALLOCATION_HEADER that describes the\r
  /// various attributes of the logical memory allocation.\r
  ///\r
  EFI_HOB_MEMORY_ALLOCATION_HEADER  MemoryAllocationHeader;\r
  ///\r
  /// The GUID specifying the values of the firmware file system name\r
  /// that contains the HOB consumer phase component.\r
  ///\r
  EFI_GUID                          ModuleName;\r
  ///\r
  /// The address of the memory-mapped firmware volume\r
  /// that contains the HOB consumer phase firmware file.\r
  ///\r
  EFI_PHYSICAL_ADDRESS              EntryPoint;\r
} EFI_HOB_MEMORY_ALLOCATION_MODULE;\r
\r
///\r
/// The resource type.\r
///\r
typedef UINT32 EFI_RESOURCE_TYPE;\r
\r
//\r
// Value of ResourceType in EFI_HOB_RESOURCE_DESCRIPTOR.\r
//\r
#define EFI_RESOURCE_SYSTEM_MEMORY          0x00000000\r
#define EFI_RESOURCE_MEMORY_MAPPED_IO       0x00000001\r
#define EFI_RESOURCE_IO                     0x00000002\r
#define EFI_RESOURCE_FIRMWARE_DEVICE        0x00000003\r
#define EFI_RESOURCE_MEMORY_MAPPED_IO_PORT  0x00000004\r
#define EFI_RESOURCE_MEMORY_RESERVED        0x00000005\r
#define EFI_RESOURCE_IO_RESERVED            0x00000006\r
#define EFI_RESOURCE_MAX_MEMORY_TYPE        0x00000007\r
\r
///\r
/// A type of recount attribute type.\r
///\r
typedef UINT32 EFI_RESOURCE_ATTRIBUTE_TYPE;\r
\r
//\r
// These types can be ORed together as needed.\r
//\r
// The following attributes are used to describe settings\r
//\r
#define EFI_RESOURCE_ATTRIBUTE_PRESENT                  0x00000001\r
#define EFI_RESOURCE_ATTRIBUTE_INITIALIZED              0x00000002\r
#define EFI_RESOURCE_ATTRIBUTE_TESTED                   0x00000004\r
#define EFI_RESOURCE_ATTRIBUTE_READ_PROTECTED           0x00000080\r
//\r
// This is typically used as memory cacheability attribute today.\r
// NOTE: Since PI spec 1.4, please use EFI_RESOURCE_ATTRIBUTE_READ_ONLY_PROTECTED\r
// as Physical write protected attribute, and EFI_RESOURCE_ATTRIBUTE_WRITE_PROTECTED\r
// means Memory cacheability attribute: The memory supports being programmed with\r
// a writeprotected cacheable attribute.\r
//\r
#define EFI_RESOURCE_ATTRIBUTE_WRITE_PROTECTED          0x00000100\r
#define EFI_RESOURCE_ATTRIBUTE_EXECUTION_PROTECTED      0x00000200\r
#define EFI_RESOURCE_ATTRIBUTE_PERSISTENT               0x00800000\r
//\r
// The rest of the attributes are used to describe capabilities\r
//\r
#define EFI_RESOURCE_ATTRIBUTE_SINGLE_BIT_ECC           0x00000008\r
#define EFI_RESOURCE_ATTRIBUTE_MULTIPLE_BIT_ECC         0x00000010\r
#define EFI_RESOURCE_ATTRIBUTE_ECC_RESERVED_1           0x00000020\r
#define EFI_RESOURCE_ATTRIBUTE_ECC_RESERVED_2           0x00000040\r
#define EFI_RESOURCE_ATTRIBUTE_UNCACHEABLE              0x00000400\r
#define EFI_RESOURCE_ATTRIBUTE_WRITE_COMBINEABLE        0x00000800\r
#define EFI_RESOURCE_ATTRIBUTE_WRITE_THROUGH_CACHEABLE  0x00001000\r
#define EFI_RESOURCE_ATTRIBUTE_WRITE_BACK_CACHEABLE     0x00002000\r
#define EFI_RESOURCE_ATTRIBUTE_16_BIT_IO                0x00004000\r
#define EFI_RESOURCE_ATTRIBUTE_32_BIT_IO                0x00008000\r
#define EFI_RESOURCE_ATTRIBUTE_64_BIT_IO                0x00010000\r
#define EFI_RESOURCE_ATTRIBUTE_UNCACHED_EXPORTED        0x00020000\r
#define EFI_RESOURCE_ATTRIBUTE_READ_PROTECTABLE         0x00100000\r
//\r
// This is typically used as memory cacheability attribute today.\r
// NOTE: Since PI spec 1.4, please use EFI_RESOURCE_ATTRIBUTE_READ_ONLY_PROTECTABLE\r
// as Memory capability attribute: The memory supports being protected from processor\r
// writes, and EFI_RESOURCE_ATTRIBUTE_WRITE_PROTEC TABLE means Memory cacheability attribute:\r
// The memory supports being programmed with a writeprotected cacheable attribute.\r
//\r
#define EFI_RESOURCE_ATTRIBUTE_WRITE_PROTECTABLE        0x00200000\r
#define EFI_RESOURCE_ATTRIBUTE_EXECUTION_PROTECTABLE    0x00400000\r
#define EFI_RESOURCE_ATTRIBUTE_PERSISTABLE              0x01000000\r
\r
#define EFI_RESOURCE_ATTRIBUTE_READ_ONLY_PROTECTED      0x00040000\r
#define EFI_RESOURCE_ATTRIBUTE_READ_ONLY_PROTECTABLE    0x00080000\r
\r
//\r
// Physical memory relative reliability attribute. This\r
// memory provides higher reliability relative to other\r
// memory in the system. If all memory has the same\r
// reliability, then this bit is not used.\r
//\r
#define EFI_RESOURCE_ATTRIBUTE_MORE_RELIABLE            0x02000000\r
\r
///\r
/// Describes the resource properties of all fixed,\r
/// nonrelocatable resource ranges found on the processor\r
/// host bus during the HOB producer phase.\r
///\r
typedef struct {\r
  ///\r
  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_RESOURCE_DESCRIPTOR.\r
  ///\r
  EFI_HOB_GENERIC_HEADER      Header;\r
  ///\r
  /// A GUID representing the owner of the resource. This GUID is used by HOB\r
  /// consumer phase components to correlate device ownership of a resource.\r
  ///\r
  EFI_GUID                    Owner;\r
  ///\r
  /// The resource type enumeration as defined by EFI_RESOURCE_TYPE.\r
  ///\r
  EFI_RESOURCE_TYPE           ResourceType;\r
  ///\r
  /// Resource attributes as defined by EFI_RESOURCE_ATTRIBUTE_TYPE.\r
  ///\r
  EFI_RESOURCE_ATTRIBUTE_TYPE ResourceAttribute;\r
  ///\r
  /// The physical start address of the resource region.\r
  ///\r
  EFI_PHYSICAL_ADDRESS        PhysicalStart;\r
  ///\r
  /// The number of bytes of the resource region.\r
  ///\r
  UINT64                      ResourceLength;\r
} EFI_HOB_RESOURCE_DESCRIPTOR;\r
\r
///\r
/// Allows writers of executable content in the HOB producer phase to\r
/// maintain and manage HOBs with specific GUID.\r
///\r
typedef struct {\r
  ///\r
  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_GUID_EXTENSION.\r
  ///\r
  EFI_HOB_GENERIC_HEADER      Header;\r
  ///\r
  /// A GUID that defines the contents of this HOB.\r
  ///\r
  EFI_GUID                    Name;\r
  //\r
  // Guid specific data goes here\r
  //\r
} EFI_HOB_GUID_TYPE;\r
\r
///\r
/// Details the location of firmware volumes that contain firmware files.\r
///\r
typedef struct {\r
  ///\r
  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_FV.\r
  ///\r
  EFI_HOB_GENERIC_HEADER Header;\r
  ///\r
  /// The physical memory-mapped base address of the firmware volume.\r
  ///\r
  EFI_PHYSICAL_ADDRESS   BaseAddress;\r
  ///\r
  /// The length in bytes of the firmware volume.\r
  ///\r
  UINT64                 Length;\r
} EFI_HOB_FIRMWARE_VOLUME;\r
\r
///\r
/// Details the location of a firmware volume that was extracted\r
/// from a file within another firmware volume.\r
///\r
typedef struct {\r
  ///\r
  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_FV2.\r
  ///\r
  EFI_HOB_GENERIC_HEADER  Header;\r
  ///\r
  /// The physical memory-mapped base address of the firmware volume.\r
  ///\r
  EFI_PHYSICAL_ADDRESS    BaseAddress;\r
  ///\r
  /// The length in bytes of the firmware volume.\r
  ///\r
  UINT64                  Length;\r
  ///\r
  /// The name of the firmware volume.\r
  ///\r
  EFI_GUID                FvName;\r
  ///\r
  /// The name of the firmware file that contained this firmware volume.\r
  ///\r
  EFI_GUID                FileName;\r
} EFI_HOB_FIRMWARE_VOLUME2;\r
\r
///\r
/// Details the location of a firmware volume that was extracted\r
/// from a file within another firmware volume.\r
///\r
typedef struct {\r
  ///\r
  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_FV3.\r
  ///\r
  EFI_HOB_GENERIC_HEADER  Header;\r
  ///\r
  /// The physical memory-mapped base address of the firmware volume.\r
  ///\r
  EFI_PHYSICAL_ADDRESS    BaseAddress;\r
  ///\r
  /// The length in bytes of the firmware volume.\r
  ///\r
  UINT64                  Length;\r
  ///\r
  /// The authentication status.\r
  ///\r
  UINT32                  AuthenticationStatus;\r
  ///\r
  /// TRUE if the FV was extracted as a file within another firmware volume.\r
  /// FALSE otherwise.\r
  ///\r
  BOOLEAN                 ExtractedFv;\r
  ///\r
  /// The name of the firmware volume.\r
  /// Valid only if IsExtractedFv is TRUE.\r
  ///\r
  EFI_GUID                FvName;\r
  ///\r
  /// The name of the firmware file that contained this firmware volume.\r
  /// Valid only if IsExtractedFv is TRUE.\r
  ///\r
  EFI_GUID                FileName;\r
} EFI_HOB_FIRMWARE_VOLUME3;\r
\r
///\r
/// Describes processor information, such as address space and I/O space capabilities.\r
///\r
typedef struct {\r
  ///\r
  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_CPU.\r
  ///\r
  EFI_HOB_GENERIC_HEADER  Header;\r
  ///\r
  /// Identifies the maximum physical memory addressability of the processor.\r
  ///\r
  UINT8                   SizeOfMemorySpace;\r
  ///\r
  /// Identifies the maximum physical I/O addressability of the processor.\r
  ///\r
  UINT8                   SizeOfIoSpace;\r
  ///\r
  /// This field will always be set to zero.\r
  ///\r
  UINT8                   Reserved[6];\r
} EFI_HOB_CPU;\r
\r
\r
///\r
/// Describes pool memory allocations.\r
///\r
typedef struct {\r
  ///\r
  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_POOL.\r
  ///\r
  EFI_HOB_GENERIC_HEADER  Header;\r
} EFI_HOB_MEMORY_POOL;\r
\r
///\r
/// Each UEFI capsule HOB details the location of a UEFI capsule. It includes a base address and length\r
/// which is based upon memory blocks with a EFI_CAPSULE_HEADER and the associated\r
/// CapsuleImageSize-based payloads. These HOB's shall be created by the PEI PI firmware\r
/// sometime after the UEFI UpdateCapsule service invocation with the\r
/// CAPSULE_FLAGS_POPULATE_SYSTEM_TABLE flag set in the EFI_CAPSULE_HEADER.\r
///\r
typedef struct {\r
  ///\r
  /// The HOB generic header where Header.HobType = EFI_HOB_TYPE_UEFI_CAPSULE.\r
  ///\r
  EFI_HOB_GENERIC_HEADER Header;\r
\r
  ///\r
  /// The physical memory-mapped base address of an UEFI capsule. This value is set to\r
  /// point to the base of the contiguous memory of the UEFI capsule.\r
  /// The length of the contiguous memory in bytes.\r
  ///\r
  EFI_PHYSICAL_ADDRESS   BaseAddress;\r
  UINT64                 Length;\r
} EFI_HOB_UEFI_CAPSULE;\r
\r
///\r
/// Union of all the possible HOB Types.\r
///\r
typedef union {\r
  EFI_HOB_GENERIC_HEADER              *Header;\r
  EFI_HOB_HANDOFF_INFO_TABLE          *HandoffInformationTable;\r
  EFI_HOB_MEMORY_ALLOCATION           *MemoryAllocation;\r
  EFI_HOB_MEMORY_ALLOCATION_BSP_STORE *MemoryAllocationBspStore;\r
  EFI_HOB_MEMORY_ALLOCATION_STACK     *MemoryAllocationStack;\r
  EFI_HOB_MEMORY_ALLOCATION_MODULE    *MemoryAllocationModule;\r
  EFI_HOB_RESOURCE_DESCRIPTOR         *ResourceDescriptor;\r
  EFI_HOB_GUID_TYPE                   *Guid;\r
  EFI_HOB_FIRMWARE_VOLUME             *FirmwareVolume;\r
  EFI_HOB_FIRMWARE_VOLUME2            *FirmwareVolume2;\r
  EFI_HOB_FIRMWARE_VOLUME3            *FirmwareVolume3;\r
  EFI_HOB_CPU                         *Cpu;\r
  EFI_HOB_MEMORY_POOL                 *Pool;\r
  EFI_HOB_UEFI_CAPSULE                *Capsule;\r
  UINT8                               *Raw;\r
} EFI_PEI_HOB_POINTERS;\r
\r
\r
#endif\r