From f1004231ee519fc24c3ad5e90289f5d9445ac9d2 Mon Sep 17 00:00:00 2001 From: lgao4 Date: Wed, 19 Nov 2008 14:24:27 +0000 Subject: [PATCH] Update comments for Protocol definitions to match UEFI spec. And add the missing comments for the data structure. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6636 6f19259b-4bc3-4df7-8a09-765794883524 --- MdePkg/Include/Protocol/AcpiTable.h | 2 +- MdePkg/Include/Protocol/Arp.h | 66 +++ MdePkg/Include/Protocol/AuthenticationInfo.h | 79 +++ MdePkg/Include/Protocol/Bis.h | 69 ++- MdePkg/Include/Protocol/BlockIo.h | 26 +- .../Protocol/BusSpecificDriverOverride.h | 11 +- MdePkg/Include/Protocol/Cpu.h | 3 +- MdePkg/Include/Protocol/Decompress.h | 4 +- MdePkg/Include/Protocol/DeviceIo.h | 26 +- MdePkg/Include/Protocol/DevicePath.h | 510 +++++++++++++++++- MdePkg/Include/Protocol/DevicePathUtilities.h | 22 +- .../Protocol/PlatformToDriverConfiguration.h | 7 +- MdePkg/Include/Protocol/PxeBaseCodeCallBack.h | 6 +- MdePkg/Include/Protocol/Reset.h | 2 - MdePkg/Include/Protocol/Runtime.h | 61 ++- MdePkg/Include/Protocol/Security.h | 6 +- MdePkg/Include/Protocol/ServiceBinding.h | 36 +- 17 files changed, 816 insertions(+), 120 deletions(-) diff --git a/MdePkg/Include/Protocol/AcpiTable.h b/MdePkg/Include/Protocol/AcpiTable.h index 01583365c0..ebeb59f517 100644 --- a/MdePkg/Include/Protocol/AcpiTable.h +++ b/MdePkg/Include/Protocol/AcpiTable.h @@ -31,7 +31,7 @@ typedef struct _EFI_ACPI_TABLE_PROTOCOL EFI_ACPI_TABLE_PROTOCOL; copy into the RSDT/XSDT. InstallAcpiTable() must insert the new table at the end of the RSDT/XSDT. To prevent namespace collision, ACPI tables may be created using UEFI ACPI table - format. See Appendix O. On successful output, TableKey is + format. On successful output, TableKey is initialized with a unique key. Its value may be used in a subsequent call to UninstallAcpiTable to remove an ACPI table. If an EFI application is running at the time of this call, the diff --git a/MdePkg/Include/Protocol/Arp.h b/MdePkg/Include/Protocol/Arp.h index edf204ebe3..9232bda07e 100644 --- a/MdePkg/Include/Protocol/Arp.h +++ b/MdePkg/Include/Protocol/Arp.h @@ -36,21 +36,81 @@ typedef struct _EFI_ARP_PROTOCOL EFI_ARP_PROTOCOL; typedef struct { + /// + /// Length in bytes of this entry. + /// UINT32 Size; + + /// + /// Set to TRUE if this entry is a "deny" entry. + /// Set to FALSE if this entry is a "normal" entry. + /// BOOLEAN DenyFlag; + + /// + /// Set to TRUE if this entry will not time out. + /// Set to FALSE if this entry will time out. + /// BOOLEAN StaticFlag; + + /// + /// 16-bit ARP hardware identifier number. + /// UINT16 HwAddressType; + + /// + /// 16-bit protocol type number. + /// UINT16 SwAddressType; + + /// + /// Length of the hardware address. + /// UINT8 HwAddressLength; + + /// + /// Length of the protocol address. + /// UINT8 SwAddressLength; } EFI_ARP_FIND_DATA; typedef struct { + /// + /// 16-bit protocol type number in host byte order. + /// UINT16 SwAddressType; ///< Host byte order + + /// + /// Length in bytes of the station's protocol address to register. + /// UINT8 SwAddressLength; + + /// + /// Pointer to the first byte of the protocol address to register. For + /// example, if SwAddressType is 0x0800 (IP), then + /// StationAddress points to the first byte of this station¡¯s IP + /// address stored in network byte order. + /// VOID *StationAddress; ///< Network byte order + + /// + /// The timeout value in 100-ns units that is associated with each + /// new dynamic ARP cache entry. If it is set to zero, the value is + /// implementation-specific. + /// UINT32 EntryTimeOut; + + /// + /// The number of retries before a MAC address is resolved. If it is + /// set to zero, the value is implementation-specific. + /// UINT32 RetryCount; + + /// + /// The timeout value in 100-ns units that is used to wait for the ARP + /// reply packet or the timeout value between two retries. Set to zero + /// to use implementation-specific value. + /// UINT32 RetryTimeOut; } EFI_ARP_CONFIG_DATA; @@ -63,6 +123,9 @@ typedef struct { @retval EFI_SUCCESS The new station address was successfully registered. @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + This is NULL. + SwAddressLength is zero when ConfigData is not NULL. + StationAddress is NULL when ConfigData is not NULL. @retval EFI_ACCESS_DENIED The SwAddressType, SwAddressLength, or StationAddress is different from the one that is already registered. @@ -236,6 +299,9 @@ EFI_STATUS @retval EFI_SUCCESS The pending request session(s) is/are aborted and corresponding event(s) is/are signaled. @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + This is NULL. + TargetSwAddress is not NULL and ResolvedEvent is NULL. + TargetSwAddress is NULL and ResolvedEvent is not NULL @retval EFI_NOT_STARTED The ARP driver instance has not been configured. @retval EFI_NOT_FOUND The request is not issued by EFI_ARP_PROTOCOL.Request(). diff --git a/MdePkg/Include/Protocol/AuthenticationInfo.h b/MdePkg/Include/Protocol/AuthenticationInfo.h index d2cd444685..8f62bc99cf 100644 --- a/MdePkg/Include/Protocol/AuthenticationInfo.h +++ b/MdePkg/Include/Protocol/AuthenticationInfo.h @@ -35,33 +35,112 @@ typedef struct _EFI_AUTHENTICATION_INFO_PROTOCOL EFI_AUTHENTICATION_INFO_PROTOCOL; typedef struct { + /// + /// Authentication Type GUID. + /// EFI_GUID Guid; + + /// + /// Length of this structure in bytes. + /// UINT16 Length; } AUTH_NODE_HEADER; typedef struct { AUTH_NODE_HEADER Header; + + /// + /// RADIUS Server IPv4 or IPv6 Address + /// EFI_IPv6_ADDRESS RadiusIpAddr; ///< IPv4 or IPv6 address + + /// + /// Reserved for future use + /// UINT16 Reserved; + + /// + /// Network Access Server IPv4 or IPv6 Address (OPTIONAL) + /// EFI_IPv6_ADDRESS NasIpAddr; ///< IPv4 or IPv6 address + + /// + /// Network Access Server Secret Length in bytes (OPTIONAL) + /// UINT16 NasSecretLength; + + /// + /// Network Access Server secret (OPTIONAL) + /// UINT8 *NasSecret; + + /// + /// CHAP Initiator Secret length in bytes + /// UINT16 ChapSecretLength; + + /// + /// CHAP Initiator Secret + /// UINT8 *ChapSecret; + + /// + /// CHAP Initiator Name Length in bytes + /// UINT16 ChapNameLength; + + /// + /// CHAP Initiator Name + /// UINT8 *ChapName; } CHAP_RADIUS_AUTH_NODE; typedef struct { AUTH_NODE_HEADER Header; + + /// + /// Reserved for future use + /// UINT16 Reserved; + + /// + /// User Secret Length in bytes + /// UINT16 UserSecretLength; + + /// + /// User Secret + /// UINT8 *UserSecret; + + /// + /// User Name Length in bytes + /// UINT16 UserNameLength; + + /// + /// User Name + /// UINT8 *UserName; + + /// + /// CHAP Initiator Secret length in bytes + /// UINT16 ChapSecretLength; + + /// + /// CHAP Initiator Secret + /// UINT8 *ChapSecret; + + /// + /// CHAP Initiator Name Length in bytes + /// UINT16 ChapNameLength; + + /// + /// CHAP Initiator Name + /// UINT8 *ChapName; } CHAP_LOCAL_AUTH_NODE; diff --git a/MdePkg/Include/Protocol/Bis.h b/MdePkg/Include/Protocol/Bis.h index a7c16584f6..194a0b526c 100644 --- a/MdePkg/Include/Protocol/Bis.h +++ b/MdePkg/Include/Protocol/Bis.h @@ -57,8 +57,8 @@ typedef struct { /// EFI_BIS_VERSION type. /// typedef struct { - UINT32 Major; ///< BIS Interface version number. - UINT32 Minor; ///< Build number. + UINT32 Major; ///< the major BIS version number. + UINT32 Minor; ///< a minor BIS version number. } EFI_BIS_VERSION; // @@ -132,19 +132,33 @@ typedef struct { interface version desired. On output, both the major and minor version numbers are updated with the major and minor version - numbers of the interface + numbers of the interface. This update is done whether or not the + initialization was successful. @param TargetAddress Indicates a network or device address of the BIS platform to connect to. @retval EFI_SUCCESS The function completed successfully. @retval EFI_INCOMPATIBLE_VERSION The InterfaceVersion.Major requested by the caller was not compatible with the interface version of the + implementation. The InterfaceVersion.Major has + been updated with the current interface version. @retval EFI_UNSUPPORTED This is a local-platform implementation and TargetAddress.Data was not NULL, or TargetAddress.Data was any other value that was not supported by the implementation. @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. - @retval EFI_DEVICE_ERROR The function encountered an unexpected internal failure. - @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + @retval EFI_DEVICE_ERROR The function encountered an unexpected internal failure while + initializing a cryptographic software module, or + No cryptographic software module with compatible version was + found, or A resource limitation was encountered while using a + cryptographic software module. + @retval EFI_INVALID_PARAMETER The This parameter supplied by the caller is NULL or does not + reference a valid EFI_BIS_PROTOCOL object, or + The AppHandle parameter supplied by the caller is NULL or + an invalid memory reference, or + The InterfaceVersion parameter supplied by the caller + is NULL or an invalid memory reference, or + The TargetAddress parameter supplied by the caller is + NULL or an invalid memory reference. **/ typedef @@ -161,7 +175,8 @@ EFI_STATUS @param AppHandle An opaque handle that identifies the caller's instance of initialization of the BIS service. - @param ToFree An EFI_BIS_DATA* and associated memory block to be freed. + @param ToFree An EFI_BIS_DATA* and associated memory block to be freed. + This EFI_BIS_DATA* must have been allocated by one of the other BIS functions. @retval EFI_SUCCESS The function completed successfully. @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid @@ -189,9 +204,10 @@ EFI_STATUS @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol. @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. - @retval EFI_DEVICE_ERROR The function encountered an unexpected internal failure. - -**/ + @retval EFI_DEVICE_ERROR The function encountered an unexpected internal failure while + returning resources associated with a cryptographic software module, or + while trying to shut down a cryptographic software module. +**/ typedef EFI_STATUS (EFIAPI *EFI_BIS_SHUTDOWN)( @@ -205,7 +221,8 @@ EFI_STATUS @param AppHandle An opaque handle that identifies the caller's instance of initialization of the BIS service. @param Certificate The function writes an allocated EFI_BIS_DATA* containing the Boot - Object Authorization Certificate object. + Object Authorization Certificate object. The caller must + eventually free the memory allocated by this function using the function Free(). @retval EFI_SUCCESS The function completed successfully. @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid @@ -285,7 +302,8 @@ EFI_STATUS @param AppHandle An opaque handle that identifies the caller's instance of initialization of the BIS service. @param UpdateToken The function writes an allocated EFI_BIS_DATA* containing the new - unique update token value. + unique update token value. The caller must + eventually free the memory allocated by this function using the function Free(). @retval EFI_SUCCESS The function completed successfully. @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid @@ -311,7 +329,8 @@ EFI_STATUS @param RequestCredential This is a Signed Manifest with embedded attributes that carry the details of the requested update. @param NewUpdateToken The function writes an allocated EFI_BIS_DATA* containing the new - unique update token value. + unique update token value. The caller must + eventually free the memory allocated by this function using the function Free(). @retval EFI_SUCCESS The function completed successfully. @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid @@ -320,7 +339,10 @@ EFI_STATUS @retval EFI_INVALID_PARAMETER One or more parameters are invalid. @retval EFI_SECURITY_VIOLATION The signed manifest supplied as the RequestCredential parameter was invalid (could not be parsed) or Platform-specific authorization failed, etc. - @retval EFI_DEVICE_ERROR An unexpected internal error occurred. + @retval EFI_DEVICE_ERROR An unexpected internal error occurred while analyzing the new + certificate's key algorithm, or while attempting to retrieve + the public key algorithm of the manifest's signer's certificate, + or An unexpected internal error occurred in a cryptographic software module. **/ typedef @@ -357,8 +379,9 @@ EFI_STATUS or the AuthorityCertificate supplied by the caller was invalid (could not be parsed), or Platform-specific authorization failed, etc. - @retval EFI_DEVICE_ERROR An unexpected internal error occurred. - + @retval EFI_DEVICE_ERROR An unexpected internal error occurred while attempting to retrieve + the public key algorithm of the manifest¡¯s signer¡¯s certificate, + or An unexpected internal error occurred in a cryptographic software module. **/ typedef EFI_STATUS @@ -374,21 +397,25 @@ EFI_STATUS /** Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength combinations that the platform supports. - + @param AppHandle An opaque handle that identifies the caller's instance of initialization of the BIS service. @param SignatureInfo The function writes an allocated EFI_BIS_DATA* containing the array of EFI_BIS_SIGNATURE_INFO structures representing the supported - digital certificate identifier, algorithm, and key length combinations. - + digital certificate identifier, algorithm, and key length combinations. + The caller must eventually free the memory allocated by this function using the function Free(). + @retval EFI_SUCCESS The function completed successfully. @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol. @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. @retval EFI_INVALID_PARAMETER The SignatureInfo parameter supplied by the caller is NULL - or an invalid memory reference. - @retval EFI_DEVICE_ERROR An unexpected internal error occurred. - + or an invalid memory reference. + @retval EFI_DEVICE_ERROR An unexpected internal error occurred in a + cryptographic software module, or + The function encountered an unexpected internal consistency check + failure (possible corruption of stored Boot Object Authorization Certificate). + **/ typedef EFI_STATUS diff --git a/MdePkg/Include/Protocol/BlockIo.h b/MdePkg/Include/Protocol/BlockIo.h index adbeedc289..ba3cae2082 100644 --- a/MdePkg/Include/Protocol/BlockIo.h +++ b/MdePkg/Include/Protocol/BlockIo.h @@ -38,7 +38,7 @@ typedef EFI_BLOCK_IO_PROTOCOL EFI_BLOCK_IO; /** Reset the Block Device. - @param This Protocol instance pointer. + @param This Indicates a pointer to the calling context. @param ExtendedVerification Driver may perform diagnostics on reset. @retval EFI_SUCCESS The device was reset. @@ -56,19 +56,20 @@ EFI_STATUS /** Read BufferSize bytes from Lba into Buffer. - @param This Protocol instance pointer. + @param This Indicates a pointer to the calling context. @param MediaId Id of the media, changes every time the media is replaced. @param Lba The starting Logical Block Address to read from @param BufferSize Size of Buffer, must be a multiple of device block size. - @param Buffer Buffer containing read data + @param Buffer A pointer to the destination buffer for the data. The caller is + responsible for either having implicit or explicit ownership of the buffer. @retval EFI_SUCCESS The data was read correctly from the device. @retval EFI_DEVICE_ERROR The device reported an error while performing the read. @retval EFI_NO_MEDIA There is no media in the device. @retval EFI_MEDIA_CHANGED The MediaId does not matched the current device. @retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device. - @retval EFI_INVALID_PARAMETER The read request contains device addresses that are not - valid for the device. + @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid, + or the buffer is not on proper alignment. **/ typedef @@ -84,11 +85,12 @@ EFI_STATUS /** Write BufferSize bytes from Lba into Buffer. - @param This Protocol instance pointer. - @param MediaId Id of the media, changes every time the media is replaced. - @param Lba The starting Logical Block Address to read from + @param This Indicates a pointer to the calling context. + @param MediaId The media ID that the write request is for. + @param Lba The starting logical block address to be written. The caller is + responsible for writing to only legitimate locations. @param BufferSize Size of Buffer, must be a multiple of device block size. - @param Buffer Buffer containing read data + @param Buffer A pointer to the source buffer for the data. @retval EFI_SUCCESS The data was written correctly to the device. @retval EFI_WRITE_PROTECTED The device can not be written to. @@ -96,8 +98,8 @@ EFI_STATUS @retval EFI_NO_MEDIA There is no media in the device. @retval EFI_MEDIA_CHNAGED The MediaId does not matched the current device. @retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device. - @retval EFI_INVALID_PARAMETER The write request contains a LBA that is not - valid for the device. + @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid, + or the buffer is not on proper alignment. **/ typedef @@ -113,7 +115,7 @@ EFI_STATUS /** Flush the Block Device. - @param This Protocol instance pointer. + @param This Indicates a pointer to the calling context. @retval EFI_SUCCESS All outstanding data was written to the device @retval EFI_DEVICE_ERROR The device reported an error while writting back the data diff --git a/MdePkg/Include/Protocol/BusSpecificDriverOverride.h b/MdePkg/Include/Protocol/BusSpecificDriverOverride.h index 83a87c6711..4b87710dd1 100644 --- a/MdePkg/Include/Protocol/BusSpecificDriverOverride.h +++ b/MdePkg/Include/Protocol/BusSpecificDriverOverride.h @@ -42,14 +42,15 @@ typedef struct _EFI_BUS_SPECIFIC_DRIVER_OVERRIDE_PROTOCOL EFI_BUS_SPECIFIC_DRIV @param DriverImageHandle On input, a pointer to the previous driver image handle returned by GetDriver(). On output, a pointer to the next driver image handle. Passing in a NULL, will return the first driver - image handle. - + image handle. + @retval EFI_SUCCESS A bus specific override driver is returned in DriverImageHandle. @retval EFI_NOT_FOUND The end of the list of override drivers was reached. + A bus specific override driver is not returned in DriverImageHandle. @retval EFI_INVALID_PARAMETER DriverImageHandle is not a handle that was returned on a - previous call to GetDriver(). - -**/ + previous call to GetDriver(). + +**/ typedef EFI_STATUS (EFIAPI *EFI_BUS_SPECIFIC_DRIVER_OVERRIDE_GET_DRIVER)( diff --git a/MdePkg/Include/Protocol/Cpu.h b/MdePkg/Include/Protocol/Cpu.h index 53ad24d6d5..1f3a3c1523 100644 --- a/MdePkg/Include/Protocol/Cpu.h +++ b/MdePkg/Include/Protocol/Cpu.h @@ -206,7 +206,8 @@ EFI_STATUS must be between 0 and NumberOfTimers-1. @param TimerValue Pointer to the returned timer value. @param TimerPeriod A pointer to the amount of time that passes in femtoseconds for each increment - of TimerValue. + of TimerValue. If TimerValue does not increment at a predictable rate, then 0 is + returned. This parameter is optional and may be NULL. @retval EFI_SUCCESS The processor timer value specified by TimerIndex was returned in TimerValue. @retval EFI_DEVICE_ERROR An error occurred attempting to read one of the processor's timers. diff --git a/MdePkg/Include/Protocol/Decompress.h b/MdePkg/Include/Protocol/Decompress.h index b5a0668982..ed1e4220e1 100644 --- a/MdePkg/Include/Protocol/Decompress.h +++ b/MdePkg/Include/Protocol/Decompress.h @@ -38,7 +38,7 @@ typedef struct _EFI_DECOMPRESS_PROTOCOL EFI_DECOMPRESS_PROTOCOL; output it as DestinationSize. And ScratchSize is specific to the decompression implementation. - @param This The protocol instance pointer + @param This A pointer to the EFI_DECOMPRESS_PROTOCOL instance. @param Source The source buffer containing the compressed data. @param SourceSize The size, in bytes, of source buffer. @param DestinationSize A pointer to the size, in bytes, of the uncompressed buffer @@ -79,7 +79,7 @@ EFI_STATUS If the compressed source data specified by Source and SourceSize is not in a valid compressed data format, then EFI_INVALID_PARAMETER is returned. - @param This The protocol instance pointer + @param This A pointer to the EFI_DECOMPRESS_PROTOCOL instance. @param Source The source buffer containing the compressed data. @param SourceSize The size of source data. @param Destination On output, the destination buffer that contains diff --git a/MdePkg/Include/Protocol/DeviceIo.h b/MdePkg/Include/Protocol/DeviceIo.h index f2dd067bb7..d10cc6fa6f 100644 --- a/MdePkg/Include/Protocol/DeviceIo.h +++ b/MdePkg/Include/Protocol/DeviceIo.h @@ -36,14 +36,10 @@ typedef struct _EFI_DEVICE_IO_PROTOCOL EFI_DEVICE_IO_PROTOCOL; typedef EFI_DEVICE_IO_PROTOCOL EFI_DEVICE_IO_INTERFACE; typedef enum { - IO_UINT8, - IO_UINT16, - IO_UINT32, - IO_UINT64, - MMIO_COPY_UINT8, - MMIO_COPY_UINT16, - MMIO_COPY_UINT32, - MMIO_COPY_UINT64 + IO_UINT8 = 0, + IO_UINT16 = 1, + IO_UINT32 = 2, + IO_UINT64 = 3 } EFI_IO_WIDTH; /** @@ -99,8 +95,22 @@ EFI_STATUS ); typedef enum { + /// + /// A read operation from system memory by a bus master. + /// EfiBusMasterRead, + + /// + /// A write operation to system memory by a bus master. + /// EfiBusMasterWrite, + + /// + /// Provides both read and write access to system memory + /// by both the processor and a bus master. The buffer is + /// coherent from both the processor¡¯s and the bus master¡¯s + /// point of view. + /// EfiBusMasterCommonBuffer } EFI_IO_OPERATION_TYPE; diff --git a/MdePkg/Include/Protocol/DevicePath.h b/MdePkg/Include/Protocol/DevicePath.h index 2304205754..64e74d6b00 100644 --- a/MdePkg/Include/Protocol/DevicePath.h +++ b/MdePkg/Include/Protocol/DevicePath.h @@ -76,36 +76,80 @@ typedef EFI_DEVICE_PATH_PROTOCOL EFI_DEVICE_PATH; /// #define HARDWARE_DEVICE_PATH 0x01 +/// +/// PCI Device Path +/// #define HW_PCI_DP 0x01 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// PCI Function Number + /// UINT8 Function; + /// + /// PCI Device Number + /// UINT8 Device; } PCI_DEVICE_PATH; +/// +/// PCCARD Device Path +/// #define HW_PCCARD_DP 0x02 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Function Number (0 = First Function) + /// UINT8 FunctionNumber; } PCCARD_DEVICE_PATH; +/// +/// Memory Mapped Device Path +/// #define HW_MEMMAP_DP 0x03 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// EFI_MEMORY_TYPE + /// UINT32 MemoryType; + /// + /// Starting Memory Address. + /// EFI_PHYSICAL_ADDRESS StartingAddress; + /// + /// Ending Memory Address + /// EFI_PHYSICAL_ADDRESS EndingAddress; } MEMMAP_DEVICE_PATH; +/// +/// The Vendor Device Path allows the creation of vendor-defined Device Paths. A vendor must +/// allocate a Vendor GUID for a Device Path. The Vendor GUID can then be used to define the +/// contents on the n bytes that follow in the Vendor Device Path node. +/// #define HW_VENDOR_DP 0x04 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Vendor-assigned GUID that defines the data that follows. + /// EFI_GUID Guid; + /// + /// Vendor-defined variable size data. + /// } VENDOR_DEVICE_PATH; +/// +/// Controller Device Path +/// #define HW_CONTROLLER_DP 0x05 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Controller number. + /// UINT32 ControllerNumber; } CONTROLLER_DEVICE_PATH; @@ -114,18 +158,52 @@ typedef struct { /// #define ACPI_DEVICE_PATH 0x02 +/// +/// ACPI Device Path +/// #define ACPI_DP 0x01 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Device's PnP hardware ID stored in a numeric 32-bit + /// compressed EISA-type ID. This value must match the + /// corresponding _HID in the ACPI name space. + /// UINT32 HID; + /// + /// Unique ID that is required by ACPI if two devices have the + /// same _HID. This value must also match the corresponding + /// _UID/_HID pair in the ACPI name space. Only the 32-bit + /// numeric value type of _UID is supported; thus strings must + /// not be used for the _UID in the ACPI name space. + /// UINT32 UID; } ACPI_HID_DEVICE_PATH; +/// +/// Expanded ACPI Device Path. +/// #define ACPI_EXTENDED_DP 0x02 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Device's PnP hardware ID stored in a numeric 32-bit + /// compressed EISA-type ID. This value must match the + /// corresponding _HID in the ACPI name space. + /// UINT32 HID; + /// + /// Unique ID that is required by ACPI if two devices have the + /// same _HID. This value must also match the corresponding + /// _UID/_HID pair in the ACPI name space. + /// UINT32 UID; + /// + /// Device¡¯s compatible PnP hardware ID stored in a numeric + /// 32-bit compressed EISA-type ID. This value must match at + /// least one of the compatible device IDs returned by the + /// corresponding _CID in the ACPI name space. + /// UINT32 CID; /// /// Optional variable length _HIDSTR @@ -150,10 +228,23 @@ typedef struct { #define EISA_ID_TO_NUM(_Id) ((_Id) >> 16) +/// +/// The _ADR device path is used to contain video output device attributes to support the Graphics +/// Output Protocol. The device path can contain multiple _ADR entries if multiple video output +/// devices are displaying the same output. +/// #define ACPI_ADR_DP 0x03 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// _ADR value. For video output devices the value of this + /// field comes from Table B-2 ACPI 3.0 specification. At + /// least one _ADR value is required. + /// UINT32 ADR; + /// + /// This device path may optionally contain more than one _ADR entry. + /// } ACPI_ADR_DEVICE_PATH; #define ACPI_ADR_DISPLAY_TYPE_OTHER 0 @@ -174,122 +265,322 @@ typedef struct { /// /// Messaging Device Paths +/// This Device Path is used to describe the connection of devices outside the resource domain of the +/// system. This Device Path can describe physical messaging information like SCSI ID, or abstract +/// information like networking protocol IP addresses. /// #define MESSAGING_DEVICE_PATH 0x03 +/// +/// ATAPI Device Path +/// #define MSG_ATAPI_DP 0x01 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Set to zero for primary or one for secondary + /// UINT8 PrimarySecondary; + /// + /// Set to zero for master or one for slave mode + /// UINT8 SlaveMaster; + /// + /// Logical Unit Number + /// UINT16 Lun; } ATAPI_DEVICE_PATH; +/// +/// SCSI Device Path +/// #define MSG_SCSI_DP 0x02 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Target ID on the SCSI bus (PUN) + /// UINT16 Pun; + /// + /// Logical Unit Number (LUN) + /// UINT16 Lun; } SCSI_DEVICE_PATH; +/// +/// Fibre Channel +/// #define MSG_FIBRECHANNEL_DP 0x03 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Reserved for the future. + /// UINT32 Reserved; + /// + /// Fibre Channel World Wide Number. + /// UINT64 WWN; + /// + /// Fibre Channel Logical Unit Number. + /// UINT64 Lun; } FIBRECHANNEL_DEVICE_PATH; +/// +/// 1394 Device Path +/// #define MSG_1394_DP 0x04 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Reserved for the future. + /// UINT32 Reserved; + /// + /// 1394 Global Unique ID (GUID). + /// UINT64 Guid; } F1394_DEVICE_PATH; +/// +/// USB Device Path +/// #define MSG_USB_DP 0x05 typedef struct { - EFI_DEVICE_PATH_PROTOCOL Header; - UINT8 ParentPortNumber; - UINT8 InterfaceNumber; + EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// USB Parent Port Number + /// + UINT8 ParentPortNumber; + /// + /// USB Interface Number + /// + UINT8 InterfaceNumber; } USB_DEVICE_PATH; +/// +/// USB Class Device Path +/// #define MSG_USB_CLASS_DP 0x0f typedef struct { - EFI_DEVICE_PATH_PROTOCOL Header; - UINT16 VendorId; - UINT16 ProductId; - UINT8 DeviceClass; - UINT8 DeviceSubClass; - UINT8 DeviceProtocol; + EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Vendor ID assigned by USB-IF. A value of 0xFFFF will + /// match any Vendor ID. + /// + UINT16 VendorId; + /// + /// Product ID assigned by USB-IF. A value of 0xFFFF will + /// match any Product ID. + /// + UINT16 ProductId; + /// + /// The class code assigned by the USB-IF. A value of 0xFF + /// will match any class code. + /// + UINT8 DeviceClass; + /// + /// The subclass code assigned by the USB-IF. A value of + /// 0xFF will match any subclass code. + /// + UINT8 DeviceSubClass; + /// + /// The protocol code assigned by the USB-IF. A value of + /// 0xFF will match any protocol code. + /// + UINT8 DeviceProtocol; } USB_CLASS_DEVICE_PATH; +/// +/// This device path describes a USB device using its serial number. +/// USB WWID Device Path +/// #define MSG_USB_WWID_DP 0x10 typedef struct { - EFI_DEVICE_PATH_PROTOCOL Header; - UINT16 InterfaceNumber; - UINT16 VendorId; - UINT16 ProductId; - // CHAR16 SerialNumber[...]; + EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// USB interface number + /// + UINT16 InterfaceNumber; + /// + /// USB vendor id of the device + /// + UINT16 VendorId; + /// + /// USB product id of the device + /// + UINT16 ProductId; + /// + /// Last 64-or-fewer UTF-16 characters of the USB + /// serial number. The length of the string is + /// determined by the Length field less the offset of the + /// Serial Number field (10) + /// + /// CHAR16 SerialNumber[...]; } USB_WWID_DEVICE_PATH; - +/// +/// Device Logical Unit +/// #define MSG_DEVICE_LOGICAL_UNIT_DP 0x11 typedef struct { - EFI_DEVICE_PATH_PROTOCOL Header; - UINT8 Lun; + EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Logical Unit Number for the interface + /// + UINT8 Lun; } DEVICE_LOGICAL_UNIT_DEVICE_PATH; +/// +/// SATA Device Path +/// #define MSG_SATA_DP 0x12 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// The HBA port number that facilitates the connection to the + /// device or a port multiplier. The value 0xFFFF is reserved. + /// UINT16 HBAPortNumber; + /// + /// The Port multiplier port number that facilitates the connection + /// to the device. Bit 15 should be set if the device is directly + /// connected to the HBA. + /// UINT16 PortMultiplierPortNumber; + /// + /// Logical Unit Number. + /// UINT16 Lun; } SATA_DEVICE_PATH; +/// +/// I2O Device Path +/// #define MSG_I2O_DP 0x06 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Target ID (TID) for a device + /// UINT32 Tid; } I2O_DEVICE_PATH; +/// +/// MAC Address Device Path +/// #define MSG_MAC_ADDR_DP 0x0b typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// The MAC address for a network interface padded with 0s + /// EFI_MAC_ADDRESS MacAddress; + /// + /// Network interface type(i.e. 802.3, FDDI). + /// UINT8 IfType; } MAC_ADDR_DEVICE_PATH; +/// +/// IPv4 Device Path +/// #define MSG_IPv4_DP 0x0c typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// The local IPv4 address + /// EFI_IPv4_ADDRESS LocalIpAddress; + /// + /// The remote IPv4 address + /// EFI_IPv4_ADDRESS RemoteIpAddress; + /// + /// The local port number + /// UINT16 LocalPort; + /// + /// The remote port number + /// UINT16 RemotePort; + /// + /// The network protocol(i.e. UDP, TCP). + /// UINT16 Protocol; + /// + /// 0x00 - The Source IP Address was assigned though DHCP + /// 0x01 - The Source IP Address is statically bound + /// BOOLEAN StaticIpAddress; } IPv4_DEVICE_PATH; +/// +/// IPv6 Device Path +/// #define MSG_IPv6_DP 0x0d typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// The local IPv6 address + /// EFI_IPv6_ADDRESS LocalIpAddress; + /// + /// The remote IPv6 address + /// EFI_IPv6_ADDRESS RemoteIpAddress; + /// + /// The local port number + /// UINT16 LocalPort; + /// + /// The remote port number + /// UINT16 RemotePort; + /// + /// The network protocol(i.e. UDP, TCP). + /// UINT16 Protocol; + /// + /// 0x00 - The Source IP Address was assigned though DHCP + /// 0x01 - The Source IP Address is statically bound + /// BOOLEAN StaticIpAddress; } IPv6_DEVICE_PATH; +/// +/// InfiniBand Device Path +/// #define MSG_INFINIBAND_DP 0x09 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Flags to help identify/manage InfiniBand device path elements: + /// Bit 0 ¨C IOC/Service (0b = IOC, 1b = Service) + /// Bit 1 ¨C Extend Boot Environment + /// Bit 2 ¨C Console Protocol + /// Bit 3 ¨C Storage Protocol + /// Bit 4 ¨C Network Protocol + /// All other bits are reserved. + /// UINT32 ResourceFlags; + /// + /// 128-bit Global Identifier for remote fabric port + /// UINT8 PortGid[16]; + /// + /// 64-bit unique identifier to remote IOC or server process. + /// Interpretation of field specified by Resource Flags (bit 0) + /// UINT64 ServiceId; + /// + /// 64-bit persistent ID of remote IOC port + /// UINT64 TargetPortId; + /// + /// 64-bit persistent ID of remote device + /// UINT64 DeviceId; } INFINIBAND_DEVICE_PATH; @@ -299,13 +590,43 @@ typedef struct { #define INFINIBAND_RESOURCE_FLAG_STORAGE_PROTOCOL 0x08 #define INFINIBAND_RESOURCE_FLAG_NETWORK_PROTOCOL 0x10 +/// +/// UART Device Path +/// #define MSG_UART_DP 0x0e typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Reserved + /// UINT32 Reserved; + /// + /// The baud rate setting for the UART style device. A value of 0 + /// means that the device's default baud rate will be used. + /// UINT64 BaudRate; + /// + /// The number of data bits for the UART style device. A value + /// of 0 means that the device's default number of data bits will be used. + /// UINT8 DataBits; + /// + /// The parity setting for the UART style device. + /// Parity 0x00 - Default Parity + /// Parity 0x01 - No Parity + /// Parity 0x02 - Even Parity + /// Parity 0x03 - Odd Parity + /// Parity 0x04 - Mark Parity + /// Parity 0x05 - Space Parity + /// UINT8 Parity; + /// + /// The number of stop bits for the UART style device. + /// Stop Bits 0x00 - Default Stop Bits + /// Stop Bits 0x01 - 1 Stop Bit + /// Stop Bits 0x02 - 1.5 Stop Bits + /// Stop Bits 0x03 - 2 Stop Bits + /// UINT8 StopBits; } UART_DEVICE_PATH; @@ -320,34 +641,86 @@ typedef VENDOR_DEVICE_PATH VENDOR_DEFINED_DEVICE_PATH; #define DEVICE_PATH_MESSAGING_VT_100_PLUS EFI_VT_100_PLUS_GUID #define DEVICE_PATH_MESSAGING_VT_UTF8 EFI_VT_UTF8_GUID +/// +/// A new device path node is defined to declare flow control characteristics. +/// UART Flow Control Messaging Device Path +/// #define DEVICE_PATH_MESSAGING_UART_FLOW_CONTROL EFI_UART_DEVICE_PATH_GUID - typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// DEVICE_PATH_MESSAGING_UART_FLOW_CONTROL + /// EFI_GUID Guid; + /// + /// Bitmap of supported flow control types. + /// Bit 0 set indicates hardware flow control. + /// Bit 1 set indicates Xon/Xoff flow control. + /// All other bits are reserved and are clear. + /// UINT32 FlowControlMap; } UART_FLOW_CONTROL_DEVICE_PATH; +/// +/// Serial Attached SCSI (SAS) devices. +/// #define DEVICE_PATH_MESSAGING_SAS EFI_SAS_DEVICE_PATH_GUID - typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// DEVICE_PATH_MESSAGING_SAS + /// EFI_GUID Guid; + /// + /// Reserved for future use. + /// UINT32 Reserved; + /// + /// SAS Address for Serial Attached SCSI Target. + /// UINT64 SasAddress; + /// + /// SAS Logical Unit Number. + /// UINT64 Lun; + /// + /// More Information about the device and its interconnect + /// UINT16 DeviceTopology; + /// + /// Relative Target Port (RTP) + /// UINT16 RelativeTargetPort; } SAS_DEVICE_PATH; +/// +/// iSCSI Device Path Node (Base Information) +/// #define MSG_ISCSI_DP 0x13 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Network Protocol (0 = TCP, 1+ = reserved) + /// UINT16 NetworkProtocol; + /// + /// iSCSI Login Options + /// UINT16 LoginOption; + /// + /// iSCSI Logical Unit Number + /// UINT64 Lun; + /// + /// iSCSI Target Portal group tag the initiator intends + /// to establish a session with. + /// UINT16 TargetPortalGroupTag; - // CHAR8 iSCSI Target Name + /// + /// iSCSI NodeTarget Name. The length of the name + /// is determined by subtracting the offset of this field from Length. + /// + /// CHAR8 iSCSI Target Name } ISCSI_DEVICE_PATH; #define ISCSI_LOGIN_OPTION_NO_HEADER_DIGEST 0x0000 @@ -364,73 +737,154 @@ typedef struct { // #define MEDIA_DEVICE_PATH 0x04 +/// +/// The Hard Drive Media Device Path is used to represent a partition on a hard drive. +/// Hard Drive Media Device Path +/// #define MEDIA_HARDDRIVE_DP 0x01 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Describes the entry in a partition table, starting with entry 1. + /// Partition number zero represents the entire device. Valid + /// partition numbers for a MBR partition are [1, 4]. Valid + /// partition numbers for a GPT partition are [1, + /// NumberOfPartitionEntries]. + /// UINT32 PartitionNumber; + /// + /// Starting LBA of the partition on the hard drive + /// UINT64 PartitionStart; + /// + /// Size of the partition in units of Logical Blocks + /// UINT64 PartitionSize; + /// + /// Signature unique to this partition + /// UINT8 Signature[16]; + /// + /// Partition Format: (Unused values reserved) + /// 0x01 ¨C PC-AT compatible legacy MBR + /// 0x02 ¨C GUID Partition Table + /// UINT8 MBRType; + /// + /// Type of Disk Signature: (Unused values reserved) + /// 0x00 ¨C No Disk Signature. + /// 0x01 ¨C 32-bit signature from address 0x1b8 of the type 0x01 MBR. + /// 0x02 ¨C GUID signature. + /// UINT8 SignatureType; } HARDDRIVE_DEVICE_PATH; #define MBR_TYPE_PCAT 0x01 #define MBR_TYPE_EFI_PARTITION_TABLE_HEADER 0x02 +#define NO_DISK_SIGNATURE 0x00 #define SIGNATURE_TYPE_MBR 0x01 #define SIGNATURE_TYPE_GUID 0x02 +/// +/// The CD-ROM Media Device Path is used to define a system partition that exists on a CD-ROM. +/// CD-ROM Media Device Path +/// #define MEDIA_CDROM_DP 0x02 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Boot Entry number from the Boot Catalog. The Initial/Default entry is defined as zero. + /// UINT32 BootEntry; + /// + /// Starting RBA of the partition on the medium. CD-ROMs use Relative logical Block Addressing. + /// UINT64 PartitionStart; + /// + /// Size of the partition in units of Blocks, also called Sectors. + /// UINT64 PartitionSize; } CDROM_DEVICE_PATH; -// -// Use VENDOR_DEVICE_PATH struct -// +/// +/// Use VENDOR_DEVICE_PATH struct +/// #define MEDIA_VENDOR_DP 0x03 +/// +/// File Path Media Device Path +/// #define MEDIA_FILEPATH_DP 0x04 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// A NULL-terminated Unicode Path string including directory and file names. + /// CHAR16 PathName[1]; } FILEPATH_DEVICE_PATH; #define SIZE_OF_FILEPATH_DEVICE_PATH EFI_FIELD_OFFSET(FILEPATH_DEVICE_PATH,PathName) +/// +/// The Media Protocol Device Path is used to denote the protocol that is being +/// used in a device path at the location of the path specified. +/// Many protocols are inherent to the style of device path. +/// #define MEDIA_PROTOCOL_DP 0x05 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// The ID of the protocol. + /// EFI_GUID Protocol; } MEDIA_PROTOCOL_DEVICE_PATH; - +/// +/// This type is used by systems implementing the UEFI PI Specification 1.0 to describe a firmware volume. +/// PIWG Firmware Volume Device Path. +/// #define MEDIA_PIWG_FW_VOL_DP 0x7 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Firmware volume name. + /// EFI_GUID FvName; } MEDIA_FW_VOL_DEVICE_PATH; - +/// +/// This type is used by systems implementing the UEFI PI Specification 1.0 to describe a firmware file. +/// PIWG Firmware Volume Device Path +/// #define MEDIA_PIWG_FW_FILE_DP 0x6 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Firmware file name + /// EFI_GUID FvFileName; } MEDIA_FW_VOL_FILEPATH_DEVICE_PATH; -// -// BBS Device Path -// +/// +/// This Device Path is used to describe the booting of non-EFI-aware operating systems. +/// BIOS Boot Specification Device Path +/// #define BBS_DEVICE_PATH 0x05 #define BBS_BBS_DP 0x01 typedef struct { EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Device Type as defined by the BIOS Boot Specification. + /// UINT16 DeviceType; + /// + /// Status Flags as defined by the BIOS Boot Specification + /// UINT16 StatusFlag; + /// + /// ASCIIZ string that describes the boot device to a user. + /// CHAR8 String[1]; } BBS_BBS_DEVICE_PATH; diff --git a/MdePkg/Include/Protocol/DevicePathUtilities.h b/MdePkg/Include/Protocol/DevicePathUtilities.h index cf247d24ba..ba430d3a15 100644 --- a/MdePkg/Include/Protocol/DevicePathUtilities.h +++ b/MdePkg/Include/Protocol/DevicePathUtilities.h @@ -32,7 +32,8 @@ @param DevicePath Points to the start of the EFI device path. - @retval Size Size of the specified device path, in bytes, including the end-of-path tag. + @return Size Size of the specified device path, in bytes, including the end-of-path tag. + @retval 0 DevicePath is NULL **/ typedef @@ -48,7 +49,7 @@ UINTN @param DevicePath Points to the source EFI device path. @retval Pointer A pointer to the duplicate device path. - @retval NULL insufficient memory + @retval NULL insufficient memory or DevicePath is NULL **/ typedef @@ -59,13 +60,15 @@ EFI_DEVICE_PATH_PROTOCOL* /** Create a new path by appending the second device path to the first. + If Src1 is NULL and Src2 is non-NULL, then a duplicate of Src2 is returned. + If Src1 is non-NULL and Src2 is NULL, then a duplicate of Src1 is returned. + If Src1 and Src2 are both NULL, then a copy of an end-of-device-path is returned. - @param Src1 Points to the first device path. If NULL, then it is ignored. - @param Src2 Points to the second device path. If NULL, then it is ignored. + @param Src1 Points to the first device path. + @param Src2 Points to the second device path. @retval Pointer A pointer to the newly created device path. @retval NULL Memory could not be allocated - or either DevicePath or DeviceNode is NULL. **/ typedef @@ -77,13 +80,15 @@ EFI_DEVICE_PATH_PROTOCOL* /** Creates a new path by appending the device node to the device path. + If DeviceNode is NULL then a copy of DevicePath is returned. + If DevicePath is NULL then a copy of DeviceNode, followed by an end-of-device path device node is returned. + If both DeviceNode and DevicePath are NULL then a copy of an end-of-device-path device node is returned. @param DevicePath Points to the device path. @param DeviceNode Points to the device node. @retval Pointer A pointer to the allocated device node. - @retval NULL Memory could not be allocated - or either DevicePath or DeviceNode is NULL. + @retval NULL There was insufficient memory. **/ typedef @@ -119,7 +124,8 @@ EFI_DEVICE_PATH_PROTOCOL* device path instance or NULL if there are no more device path instances in the device path. @param DevicePathInstanceSize On output, this holds the size of the device path instance, - in bytes or zero, if DevicePathInstance is zero. + in bytes or zero, if DevicePathInstance is NULL. + If NULL, then the instance size is not output. @retval Pointer A pointer to the copy of the current device path instance. @retval NULL DevicePathInstace was NULL on entry or there was insufficient memory. diff --git a/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h b/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h index dc66659348..510e78f442 100644 --- a/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h +++ b/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h @@ -1,6 +1,9 @@ /** @file - The file provides the protocol to retrieve configuration - information for a device that a UEFI driver is about to start. + UEFI Platform to Driver Configuration Protocol is defined in UEFI specification. + + This is a protocol that is optionally produced by the platform and optionally consumed + by a UEFI Driver in its Start() function. This protocol allows the driver to receive + configuration information as part of being started. Copyright (c) 2006 - 2008, Intel Corporation All rights reserved. This program and the accompanying materials diff --git a/MdePkg/Include/Protocol/PxeBaseCodeCallBack.h b/MdePkg/Include/Protocol/PxeBaseCodeCallBack.h index fb030b24bd..8fe8f0be3f 100644 --- a/MdePkg/Include/Protocol/PxeBaseCodeCallBack.h +++ b/MdePkg/Include/Protocol/PxeBaseCodeCallBack.h @@ -26,9 +26,13 @@ } // -// Revision Number +// UEFI Revision Number Definition // #define EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL_REVISION 0x00010000 + +// +// EFI 1.1 Revision Number defintion +// #define EFI_PXE_BASE_CODE_CALLBACK_INTERFACE_REVISION \ EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL_REVISION diff --git a/MdePkg/Include/Protocol/Reset.h b/MdePkg/Include/Protocol/Reset.h index c82a92c87f..66512fea47 100644 --- a/MdePkg/Include/Protocol/Reset.h +++ b/MdePkg/Include/Protocol/Reset.h @@ -6,8 +6,6 @@ The ResetSystem () UEFI 2.0 service is added to the EFI system table and the EFI_RESET_ARCH_PROTOCOL_GUID protocol is registered with a NULL pointer. - No CRC of the EFI system table is required, as it is done in the DXE core. - Copyright (c) 2006 - 2008, Intel Corporation All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License diff --git a/MdePkg/Include/Protocol/Runtime.h b/MdePkg/Include/Protocol/Runtime.h index 718f9dca5c..68d2b3c8e8 100644 --- a/MdePkg/Include/Protocol/Runtime.h +++ b/MdePkg/Include/Protocol/Runtime.h @@ -1,17 +1,14 @@ /** @file Runtime Architectural Protocol as defined in PI Specification VOLUME 2 DXE - This code is used to produce the UEFI 2.0 runtime virtual switch over - - This driver must add SetVirtualAddressMap () and ConvertPointer () to - the EFI system table. This driver is not responcible for CRCing the - EFI system table. - - This driver will add EFI_RUNTIME_ARCH_PROTOCOL_GUID protocol with a - pointer to the Runtime Arch Protocol instance structure. The protocol - member functions are used by the DXE core to export information need - by this driver to produce the runtime transition to virtual mode - calling. + Allows the runtime functionality of the DXE Foundation to be contained + in a separate driver. It also provides hooks for the DXE Foundation to + export information that is needed at runtime. As such, this protocol allows + services to the DXE Foundation to manage runtime drivers and events. + This protocol also implies that the runtime services required to transition + to virtual mode, SetVirtualAddressMap() and ConvertPointer(), have been + registered into the UEFI Runtime Table in the UEFI System Table. This protocol + must be produced by a runtime DXE driver and may only be consumed by the DXE Foundation. Copyright (c) 2006 - 2008, Intel Corporation All rights reserved. This program and the accompanying materials @@ -42,22 +39,64 @@ typedef LIST_ENTRY EFI_LIST_ENTRY; typedef struct _EFI_RUNTIME_IMAGE_ENTRY EFI_RUNTIME_IMAGE_ENTRY; +/// +/// EFI_RUNTIME_IMAGE_ENTRY +/// struct _EFI_RUNTIME_IMAGE_ENTRY { + /// + /// Start of image that has been loaded in memory. It is a pointer + /// to either the DOS header or PE header of the image. + /// VOID *ImageBase; + /// + /// Size in bytes of the image represented by ImageBase. + /// UINT64 ImageSize; + /// + /// Information about the fix-ups that were performed on ImageBase when it was + /// loaded into memory. + /// VOID *RelocationData; + /// + /// The ImageHandle passed into ImageBase when it was loaded. + /// EFI_HANDLE Handle; + /// + /// Entry for this node in the EFI_RUNTIME_ARCHITECTURE_PROTOCOL.ImageHead list. + /// EFI_LIST_ENTRY Link; }; typedef struct _EFI_RUNTIME_EVENT_ENTRY EFI_RUNTIME_EVENT_ENTRY; +/// +/// EFI_RUNTIME_EVENT_ENTRY +/// struct _EFI_RUNTIME_EVENT_ENTRY { + /// + /// The same as Type passed into CreateEvent(). + /// UINT32 Type; + /// + /// The same as NotifyTpl passed into CreateEvent(). + /// EFI_TPL NotifyTpl; + /// + /// The same as NotifyFunction passed into CreateEvent(). + /// EFI_EVENT_NOTIFY NotifyFunction; + /// + /// The same as NotifyContext passed into CreateEvent(). + /// VOID *NotifyContext; + /// + /// The EFI_EVENT returned by CreateEvent(). Event must be in runtime memory. + /// EFI_EVENT *Event; + /// + /// Entry for this node in the + /// EFI_RUNTIME_ARCHITECTURE_PROTOCOL.EventHead list. + /// EFI_LIST_ENTRY Link; }; diff --git a/MdePkg/Include/Protocol/Security.h b/MdePkg/Include/Protocol/Security.h index 71c236f151..d39f08a6c3 100644 --- a/MdePkg/Include/Protocol/Security.h +++ b/MdePkg/Include/Protocol/Security.h @@ -84,9 +84,9 @@ typedef struct _EFI_SECURITY_ARCH_PROTOCOL EFI_SECURITY_ARCH_PROTOCOL; typedef EFI_STATUS (EFIAPI *EFI_SECURITY_FILE_AUTHENTICATION_STATE)( - IN EFI_SECURITY_ARCH_PROTOCOL *This, - IN UINT32 AuthenticationStatus, - IN EFI_DEVICE_PATH_PROTOCOL *File + IN CONST EFI_SECURITY_ARCH_PROTOCOL *This, + IN UINT32 AuthenticationStatus, + IN CONST EFI_DEVICE_PATH_PROTOCOL *File ); /// diff --git a/MdePkg/Include/Protocol/ServiceBinding.h b/MdePkg/Include/Protocol/ServiceBinding.h index afd25efb57..abd4a404c5 100644 --- a/MdePkg/Include/Protocol/ServiceBinding.h +++ b/MdePkg/Include/Protocol/ServiceBinding.h @@ -1,4 +1,5 @@ -/** @file +/** @file + UEFI Service Binding Protocol is defined in UEFI specification. The file defines the generic Service Binding Protocol functions. It provides services that are required to create and destroy child @@ -24,14 +25,17 @@ typedef struct _EFI_SERVICE_BINDING_PROTOCOL EFI_SERVICE_BINDING_PROTOCOL; /** - Creates a child handle with a set of I/O services. + Creates a child handle and installs a protocol. + The CreateChild() function installs a protocol on ChildHandle. + If ChildHandle is a pointer to NULL, then a new handle is created and returned in ChildHandle. + If ChildHandle is not a pointer to NULL, then the protocol installs on the existing ChildHandle. - @param This Protocol instance pointer. - @param ChildHandle Pointer to the handle of the child to create. If it is NULL, - then a new handle is created. If it is not NULL, then the - I/O services are added to the existing child handle. + @param This Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance. + @param ChildHandle Pointer to the handle of the child to create. If it is NULL, + then a new handle is created. If it is a pointer to an existing UEFI handle, + then the protocol is added to the existing UEFI handle. - @retval EFI_SUCCES The child handle was created with the I/O services + @retval EFI_SUCCES The protocol was added to ChildHandle. @retval EFI_INVALID_PARAMETER ChildHandle is NULL. @retval EFI_OUT_OF_RESOURCES There are not enough resources availabe to create the child @@ -46,17 +50,19 @@ EFI_STATUS ); /** - Destroys a child handle with a set of I/O services. + Destroys a child handle with a protocol installed on it. + The DestroyChild() function does the opposite of CreateChild(). It removes a protocol + that was installed by CreateChild() from ChildHandle. If the removed protocol is the + last protocol on ChildHandle, then ChildHandle is destroyed. - @param This Protocol instance pointer. + @param This Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance. @param ChildHandle Handle of the child to destroy - @retval EFI_SUCCES The I/O services were removed from the child handle - @retval EFI_UNSUPPORTED The child handle does not support the I/O services - that are being removed. - @retval EFI_INVALID_PARAMETER Child handle is not a valid EFI Handle. - @retval EFI_ACCESS_DENIED The child handle could not be destroyed because its - I/O services are being used. + @retval EFI_SUCCES The protocol was removed from ChildHandle. + @retval EFI_UNSUPPORTED ChildHandle does not support the protocol that is being removed. + @retval EFI_INVALID_PARAMETER Child handle is not a valid UEFI Handle. + @retval EFI_ACCESS_DENIED The protocol could not be removed from the ChildHandle + because its services are being used. @retval other The child handle was not destroyed **/ -- 2.39.2