diff options
Diffstat (limited to 'MdePkg/Include/Protocol')
253 files changed, 11978 insertions, 8565 deletions
diff --git a/MdePkg/Include/Protocol/AbsolutePointer.h b/MdePkg/Include/Protocol/AbsolutePointer.h index 42693ab20b65..ff8f37b27e80 100644 --- a/MdePkg/Include/Protocol/AbsolutePointer.h +++ b/MdePkg/Include/Protocol/AbsolutePointer.h @@ -1,15 +1,12 @@ /** @file The file provides services that allow information about an absolute pointer device to be retrieved. - - Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.3. **/ @@ -38,25 +35,25 @@ typedef struct { UINT64 AbsoluteMinX; ///< The Absolute Minimum of the device on the x-axis UINT64 AbsoluteMinY; ///< The Absolute Minimum of the device on the y axis. UINT64 AbsoluteMinZ; ///< The Absolute Minimum of the device on the z-axis - UINT64 AbsoluteMaxX; ///< The Absolute Maximum of the device on the x-axis. If 0, and the + UINT64 AbsoluteMaxX; ///< The Absolute Maximum of the device on the x-axis. If 0, and the ///< AbsoluteMinX is 0, then the pointer device does not support a xaxis - UINT64 AbsoluteMaxY; ///< The Absolute Maximum of the device on the y -axis. If 0, and the + UINT64 AbsoluteMaxY; ///< The Absolute Maximum of the device on the y -axis. If 0, and the ///< AbsoluteMinX is 0, then the pointer device does not support a yaxis. - UINT64 AbsoluteMaxZ; ///< The Absolute Maximum of the device on the z-axis. If 0 , and the + UINT64 AbsoluteMaxZ; ///< The Absolute Maximum of the device on the z-axis. If 0 , and the ///< AbsoluteMinX is 0, then the pointer device does not support a zaxis - UINT32 Attributes; ///< The following bits are set as needed (or'd together) to indicate the - ///< capabilities of the device supported. The remaining bits are undefined + UINT32 Attributes; ///< The following bits are set as needed (or'd together) to indicate the + ///< capabilities of the device supported. The remaining bits are undefined ///< and should be 0 } EFI_ABSOLUTE_POINTER_MODE; /// -/// If set, indicates this device supports an alternate button input. -/// +/// If set, indicates this device supports an alternate button input. +/// #define EFI_ABSP_SupportsAltActive 0x00000001 /// /// If set, indicates this device returns pressure data in parameter CurrentZ. -/// +/// #define EFI_ABSP_SupportsPressureAsZ 0x00000002 @@ -80,7 +77,7 @@ typedef struct { device during reset. @retval EFI_SUCCESS The device was reset. - + @retval EFI_DEVICE_ERROR The device is not functioning correctly and could not be reset. @@ -95,11 +92,11 @@ EFI_STATUS /// /// This bit is set if the touch sensor is active. /// -#define EFI_ABSP_TouchActive 0x00000001 +#define EFI_ABSP_TouchActive 0x00000001 /// /// This bit is set if the alt sensor, such as pen-side button, is active -/// +/// #define EFI_ABS_AltActive 0x00000002 @@ -108,29 +105,29 @@ EFI_STATUS **/ typedef struct { /// - /// The unsigned position of the activation on the x axis. If the AboluteMinX - /// and the AboluteMaxX fields of the EFI_ABSOLUTE_POINTER_MODE structure are + /// The unsigned position of the activation on the x axis. If the AboluteMinX + /// and the AboluteMaxX fields of the EFI_ABSOLUTE_POINTER_MODE structure are /// both 0, then this pointer device does not support an x-axis, and this field /// must be ignored. /// UINT64 CurrentX; - + /// - /// The unsigned position of the activation on the y axis. If the AboluteMinY - /// and the AboluteMaxY fields of the EFI_ABSOLUTE_POINTER_MODE structure are + /// The unsigned position of the activation on the y axis. If the AboluteMinY + /// and the AboluteMaxY fields of the EFI_ABSOLUTE_POINTER_MODE structure are /// both 0, then this pointer device does not support an y-axis, and this field - /// must be ignored. + /// must be ignored. /// UINT64 CurrentY; - + /// - /// The unsigned position of the activation on the z axis, or the pressure - /// measurement. If the AboluteMinZ and the AboluteMaxZ fields of the - /// EFI_ABSOLUTE_POINTER_MODE structure are both 0, then this pointer device - /// does not support an z-axis, and this field must be ignored. + /// The unsigned position of the activation on the z axis, or the pressure + /// measurement. If the AboluteMinZ and the AboluteMaxZ fields of the + /// EFI_ABSOLUTE_POINTER_MODE structure are both 0, then this pointer device + /// does not support an z-axis, and this field must be ignored. /// UINT64 CurrentZ; - + /// /// Bits are set to 1 in this structure item to indicate that device buttons are /// active. @@ -172,7 +169,7 @@ typedef EFI_STATUS (EFIAPI *EFI_ABSOLUTE_POINTER_GET_STATE)( IN EFI_ABSOLUTE_POINTER_PROTOCOL *This, - IN OUT EFI_ABSOLUTE_POINTER_STATE *State + OUT EFI_ABSOLUTE_POINTER_STATE *State ); @@ -188,7 +185,7 @@ struct _EFI_ABSOLUTE_POINTER_PROTOCOL { EFI_ABSOLUTE_POINTER_RESET Reset; EFI_ABSOLUTE_POINTER_GET_STATE GetState; /// - /// Event to use with WaitForEvent() to wait for input from the pointer device. + /// Event to use with WaitForEvent() to wait for input from the pointer device. /// EFI_EVENT WaitForInput; /// diff --git a/MdePkg/Include/Protocol/AcpiSystemDescriptionTable.h b/MdePkg/Include/Protocol/AcpiSystemDescriptionTable.h index b98862f6d840..e837167605ff 100644 --- a/MdePkg/Include/Protocol/AcpiSystemDescriptionTable.h +++ b/MdePkg/Include/Protocol/AcpiSystemDescriptionTable.h @@ -1,14 +1,11 @@ /** @file This protocol provides services for creating ACPI system description tables. - - Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in PI Specification 1.2. **/ @@ -17,7 +14,7 @@ #define EFI_ACPI_SDT_PROTOCOL_GUID \ { 0xeb97088e, 0xcfdf, 0x49c6, { 0xbe, 0x4b, 0xd9, 0x6, 0xa5, 0xb2, 0xe, 0x86 }} - + typedef UINT32 EFI_ACPI_TABLE_VERSION; typedef VOID *EFI_ACPI_HANDLE; @@ -27,7 +24,7 @@ typedef VOID *EFI_ACPI_HANDLE; #define EFI_ACPI_TABLE_VERSION_3_0 (1 << 3) #define EFI_ACPI_TABLE_VERSION_4_0 (1 << 4) #define EFI_ACPI_TABLE_VERSION_5_0 (1 << 5) - + typedef UINT32 EFI_ACPI_DATA_TYPE; #define EFI_ACPI_DATA_TYPE_NONE 0 #define EFI_ACPI_DATA_TYPE_OPCODE 1 @@ -36,7 +33,7 @@ typedef UINT32 EFI_ACPI_DATA_TYPE; #define EFI_ACPI_DATA_TYPE_UINT 4 #define EFI_ACPI_DATA_TYPE_STRING 5 #define EFI_ACPI_DATA_TYPE_CHILD 6 - + typedef struct { UINT32 Signature; UINT32 Length; @@ -48,7 +45,7 @@ typedef struct { UINT32 CreatorId; UINT32 CreatorRevision; } EFI_ACPI_SDT_HEADER; - + typedef EFI_STATUS (EFIAPI *EFI_ACPI_NOTIFICATION_FN)( @@ -56,10 +53,10 @@ EFI_STATUS IN EFI_ACPI_TABLE_VERSION Version, ///< The ACPI table's version. IN UINTN TableKey ///< The table key for this ACPI table. ); - + /** Returns a requested ACPI table. - + The GetAcpiTable() function returns a pointer to a buffer containing the ACPI table associated with the Index that was input. The following structures are not considered elements in the list of ACPI tables: @@ -69,20 +66,20 @@ EFI_STATUS Version is updated with a bit map containing all the versions of ACPI of which the table is a member. For tables installed via the EFI_ACPI_TABLE_PROTOCOL.InstallAcpiTable() interface, the function returns the value of EFI_ACPI_STD_PROTOCOL.AcpiVersion. - + @param[in] Index The zero-based index of the table to retrieve. @param[out] Table Pointer for returning the table buffer. @param[out] Version On return, updated with the ACPI versions to which this table belongs. Type EFI_ACPI_TABLE_VERSION is defined in "Related Definitions" in the - EFI_ACPI_SDT_PROTOCOL. + EFI_ACPI_SDT_PROTOCOL. @param[out] TableKey On return, points to the table key for the specified ACPI system definition table. This is identical to the table key used in the EFI_ACPI_TABLE_PROTOCOL. The TableKey can be passed to EFI_ACPI_TABLE_PROTOCOL.UninstallAcpiTable() to uninstall the table. @retval EFI_SUCCESS The function completed successfully. - @retval EFI_NOT_FOUND The requested index is too large and a table was not found. -**/ + @retval EFI_NOT_FOUND The requested index is too large and a table was not found. +**/ typedef EFI_STATUS (EFIAPI *EFI_ACPI_GET_ACPI_TABLE2)( @@ -94,17 +91,17 @@ EFI_STATUS /** Register or unregister a callback when an ACPI table is installed. - + This function registers or unregisters a function which will be called whenever a new ACPI table is installed. - + @param[in] Register If TRUE, then the specified function will be registered. If FALSE, then the specified function will be unregistered. @param[in] Notification Points to the callback function to be registered or unregistered. - + @retval EFI_SUCCESS Callback successfully registered or unregistered. @retval EFI_INVALID_PARAMETER Notification is NULL - @retval EFI_INVALID_PARAMETER Register is FALSE and Notification does not match a known registration function. + @retval EFI_INVALID_PARAMETER Register is FALSE and Notification does not match a known registration function. **/ typedef EFI_STATUS @@ -115,30 +112,30 @@ EFI_STATUS /** Create a handle from an ACPI opcode - + @param[in] Buffer Points to the ACPI opcode. @param[out] Handle Upon return, holds the handle. - + @retval EFI_SUCCESS Success @retval EFI_INVALID_PARAMETER Buffer is NULL or Handle is NULL or Buffer points to an invalid opcode. - + **/ typedef EFI_STATUS (EFIAPI *EFI_ACPI_OPEN)( IN VOID *Buffer, - OUT EFI_ACPI_HANDLE *Handle + OUT EFI_ACPI_HANDLE *Handle ); /** Create a handle for the first ACPI opcode in an ACPI system description table. - + @param[in] TableKey The table key for the ACPI table, as returned by GetTable(). @param[out] Handle On return, points to the newly created ACPI handle. @retval EFI_SUCCESS Handle created successfully. - @retval EFI_NOT_FOUND TableKey does not refer to a valid ACPI table. + @retval EFI_NOT_FOUND TableKey does not refer to a valid ACPI table. **/ typedef EFI_STATUS @@ -149,11 +146,11 @@ EFI_STATUS /** Close an ACPI handle. - + @param[in] Handle Returns the handle. - + @retval EFI_SUCCESS Success - @retval EFI_INVALID_PARAMETER Handle is NULL or does not refer to a valid ACPI object. + @retval EFI_INVALID_PARAMETER Handle is NULL or does not refer to a valid ACPI object. **/ typedef EFI_STATUS @@ -163,14 +160,14 @@ EFI_STATUS /** Return the child ACPI objects. - + @param[in] ParentHandle Parent handle. @param[in, out] Handle On entry, points to the previously returned handle or NULL to start with the first handle. On return, points to the next returned ACPI handle or NULL if there are no child objects. @retval EFI_SUCCESS Success - @retval EFI_INVALID_PARAMETER ParentHandle is NULL or does not refer to a valid ACPI object. + @retval EFI_INVALID_PARAMETER ParentHandle is NULL or does not refer to a valid ACPI object. **/ typedef EFI_STATUS @@ -181,7 +178,7 @@ EFI_STATUS /** Retrieve information about an ACPI object. - + @param[in] Handle ACPI object handle. @param[in] Index Index of the data to retrieve from the object. In general, indexes read from left-to-right in the ACPI encoding, with index 0 always being the ACPI opcode. @@ -189,8 +186,8 @@ EFI_STATUS for the specified index. @param[out] Data Upon return, points to the pointer to the data. @param[out] DataSize Upon return, points to the size of Data. - - @retval + + @retval **/ typedef EFI_STATUS @@ -204,7 +201,7 @@ EFI_STATUS /** Change information about an ACPI object. - + @param[in] Handle ACPI object handle. @param[in] Index Index of the data to retrieve from the object. In general, indexes read from left-to-right in the ACPI encoding, with index 0 always being the ACPI opcode. @@ -228,14 +225,14 @@ EFI_STATUS /** Returns the handle of the ACPI object representing the specified ACPI path - + @param[in] HandleIn Points to the handle of the object representing the starting point for the path search. @param[in] AcpiPath Points to the ACPI path, which conforms to the ACPI encoded path format. @param[out] HandleOut On return, points to the ACPI object which represents AcpiPath, relative to HandleIn. - + @retval EFI_SUCCESS Success - @retval EFI_INVALID_PARAMETER HandleIn is NULL or does not refer to a valid ACPI object. + @retval EFI_INVALID_PARAMETER HandleIn is NULL or does not refer to a valid ACPI object. **/ typedef EFI_STATUS diff --git a/MdePkg/Include/Protocol/AcpiTable.h b/MdePkg/Include/Protocol/AcpiTable.h index c6081823268b..a428ea1b9db4 100644 --- a/MdePkg/Include/Protocol/AcpiTable.h +++ b/MdePkg/Include/Protocol/AcpiTable.h @@ -1,15 +1,12 @@ /** @file The file provides the protocol to install or remove an ACPI - table from a platform. - - Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + table from a platform. - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.3. **/ @@ -24,24 +21,24 @@ typedef struct _EFI_ACPI_TABLE_PROTOCOL EFI_ACPI_TABLE_PROTOCOL; /** - The InstallAcpiTable() function allows a caller to install an - ACPI table. When successful, the table will be linked by the - RSDT/XSDT. AcpiTableBuffer specifies the table to be installed. - InstallAcpiTable() will make a copy of the table and insert the - 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 + The InstallAcpiTable() function allows a caller to install an + ACPI table. When successful, the table will be linked by the + RSDT/XSDT. AcpiTableBuffer specifies the table to be installed. + InstallAcpiTable() will make a copy of the table and insert the + 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. If this protocol is used to install a table with a signature already present in the system, the new table will not replace the existing table. It is a platform implementation decision to add a new table with a signature matching an existing table or disallow duplicate table signatures and - return EFI_ACCESS_DENIED. 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 - relevant EFI_CONFIGURATION_TABLE pointer to the RSDT is no - longer considered valid. + return EFI_ACCESS_DENIED. 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 + relevant EFI_CONFIGURATION_TABLE pointer to the RSDT is no + longer considered valid. @param This A pointer to a EFI_ACPI_TABLE_PROTOCOL. @@ -54,16 +51,16 @@ typedef struct _EFI_ACPI_TABLE_PROTOCOL EFI_ACPI_TABLE_PROTOCOL; @param TableKey Returns a key to refer to the ACPI table. - + @retval EFI_SUCCESS The table was successfully inserted - + @retval EFI_INVALID_PARAMETER Either AcpiTableBuffer is NULL, TableKey is NULL, or AcpiTableBufferSize and the size field embedded in the ACPI table pointed to by AcpiTableBuffer are not in sync. - + @retval EFI_OUT_OF_RESOURCES Insufficient resources exist to complete the request. @retval EFI_ACCESS_DENIED The table signature matches a table already @@ -82,7 +79,7 @@ EFI_STATUS /** - + The UninstallAcpiTable() function allows a caller to remove an ACPI table. The routine will remove its reference from the RSDT/XSDT. A table is referenced by the TableKey parameter @@ -103,7 +100,7 @@ EFI_STATUS @retval EFI_OUT_OF_RESOURCES Insufficient resources exist to complete the request. - + **/ typedef EFI_STATUS diff --git a/MdePkg/Include/Protocol/AdapterInformation.h b/MdePkg/Include/Protocol/AdapterInformation.h index 92fd11d7706c..c0cff5ae05b9 100644 --- a/MdePkg/Include/Protocol/AdapterInformation.h +++ b/MdePkg/Include/Protocol/AdapterInformation.h @@ -3,14 +3,8 @@ The EFI Adapter Information Protocol is used to dynamically and quickly discover or set device information for an adapter. - Copyright (c) 2014 - 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2014 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.4 @@ -46,6 +40,12 @@ 0x4bd56be3, 0x4975, 0x4d8a, {0xa0, 0xad, 0xc4, 0x91, 0x20, 0x4b, 0x5d, 0x4d} \ } +#define EFI_ADAPTER_INFO_MEDIA_TYPE_GUID \ + { \ + 0x8484472f, 0x71ec, 0x411a, { 0xb3, 0x9c, 0x62, 0xcd, 0x94, 0xd9, 0x91, 0x6e } \ + } + + typedef struct _EFI_ADAPTER_INFORMATION_PROTOCOL EFI_ADAPTER_INFORMATION_PROTOCOL; /// @@ -53,15 +53,28 @@ typedef struct _EFI_ADAPTER_INFORMATION_PROTOCOL EFI_ADAPTER_INFORMATION_PROTOCO /// typedef struct { /// - /// Returns the current media state status. MediaState can have any of the following values: - /// EFI_SUCCESS: There is media attached to the network adapter. EFI_NOT_READY: This detects a bounced state. - /// There was media attached to the network adapter, but it was removed and reattached. EFI_NO_MEDIA: There is + /// Returns the current media state status. MediaState can have any of the following values: + /// EFI_SUCCESS: There is media attached to the network adapter. EFI_NOT_READY: This detects a bounced state. + /// There was media attached to the network adapter, but it was removed and reattached. EFI_NO_MEDIA: There is /// not any media attached to the network. /// EFI_STATUS MediaState; } EFI_ADAPTER_INFO_MEDIA_STATE; /// +/// EFI_ADAPTER_INFO_MEDIA_TYPE +/// +typedef struct { + /// + /// Indicates the current media type. MediaType can have any of the following values: + /// 1: Ethernet Network Adapter + /// 2: Ethernet Wireless Network Adapter + /// 3~255: Reserved + /// + UINT8 MediaType; +} EFI_ADAPTER_INFO_MEDIA_TYPE; + +/// /// EFI_ADAPTER_INFO_NETWORK_BOOT /// typedef struct { @@ -121,7 +134,7 @@ typedef struct { /// /// Returns capability of UNDI to support IPv6 traffic. /// - BOOLEAN Ipv6Support; + BOOLEAN Ipv6Support; } EFI_ADAPTER_INFO_UNDI_IPV6_SUPPORT; /** @@ -129,7 +142,7 @@ typedef struct { This function returns information of type InformationType from the adapter. If an adapter does not support the requested informational type, then - EFI_UNSUPPORTED is returned. + EFI_UNSUPPORTED is returned. @param[in] This A pointer to the EFI_ADAPTER_INFORMATION_PROTOCOL instance. @param[in] InformationType A pointer to an EFI_GUID that defines the contents of InformationBlock. @@ -141,8 +154,8 @@ typedef struct { @retval EFI_UNSUPPORTED The InformationType is not known. @retval EFI_DEVICE_ERROR The device reported an error. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER InformationBlock is NULL. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER InformationBlock is NULL. @retval EFI_INVALID_PARAMETER InformationBlockSize is NULL. **/ diff --git a/MdePkg/Include/Protocol/Arp.h b/MdePkg/Include/Protocol/Arp.h index 0295cc644ddc..d6b109e3ab33 100644 --- a/MdePkg/Include/Protocol/Arp.h +++ b/MdePkg/Include/Protocol/Arp.h @@ -1,22 +1,16 @@ -/** @file +/** @file EFI ARP Protocol Definition - + The EFI ARP Service Binding Protocol is used to locate EFI ARP Protocol drivers to create and destroy child of the driver to communicate with other host using ARP protocol. The EFI ARP Protocol provides services to map IP network address to hardware address used by a data link protocol. - -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: + +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: This Protocol was introduced in UEFI Specification 2.0. **/ @@ -119,13 +113,13 @@ typedef struct { /** This function is used to assign a station address to the ARP cache for this instance of the ARP driver. - - Each ARP instance has one station address. The EFI_ARP_PROTOCOL driver will - respond to ARP requests that match this registered station address. A call to + + Each ARP instance has one station address. The EFI_ARP_PROTOCOL driver will + respond to ARP requests that match this registered station address. A call to this function with the ConfigData field set to NULL will reset this ARP instance. - - Once a protocol type and station address have been assigned to this ARP instance, - all the following ARP functions will use this information. Attempting to change + + Once a protocol type and station address have been assigned to this ARP instance, + all the following ARP functions will use this information. Attempting to change the protocol type or station address to a configured ARP instance will result in errors. @param This The pointer to the EFI_ARP_PROTOCOL instance. @@ -134,8 +128,8 @@ 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. + * 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 @@ -144,27 +138,27 @@ typedef struct { allocated. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_ARP_CONFIGURE)( IN EFI_ARP_PROTOCOL *This, IN EFI_ARP_CONFIG_DATA *ConfigData OPTIONAL - ); + ); /** This function is used to insert entries into the ARP cache. - ARP cache entries are typically inserted and updated by network protocol drivers - as network traffic is processed. Most ARP cache entries will time out and be - deleted if the network traffic stops. ARP cache entries that were inserted + ARP cache entries are typically inserted and updated by network protocol drivers + as network traffic is processed. Most ARP cache entries will time out and be + deleted if the network traffic stops. ARP cache entries that were inserted by the Add() function may be static (will not time out) or dynamic (will time out). - Default ARP cache timeout values are not covered in most network protocol - specifications (although RFC 1122 comes pretty close) and will only be - discussed in general terms in this specification. The timeout values that are - used in the EFI Sample Implementation should be used only as a guideline. - Final product implementations of the EFI network stack should be tuned for + Default ARP cache timeout values are not covered in most network protocol + specifications (although RFC 1122 comes pretty close) and will only be + discussed in general terms in this specification. The timeout values that are + used in the EFI Sample Implementation should be used only as a guideline. + Final product implementations of the EFI network stack should be tuned for their expected network environments. - + @param This Pointer to the EFI_ARP_PROTOCOL instance. @param DenyFlag Set to TRUE if this entry is a deny entry. Set to FALSE if this entry is a normal entry. @@ -184,10 +178,10 @@ EFI_STATUS @retval EFI_SUCCESS The entry has been added or updated. @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: - * This is NULL. - * DenyFlag is FALSE and TargetHwAddress is NULL. - * DenyFlag is FALSE and TargetSwAddress is NULL. - * TargetHwAddress is NULL and TargetSwAddress is NULL. + * This is NULL. + * DenyFlag is FALSE and TargetHwAddress is NULL. + * DenyFlag is FALSE and TargetSwAddress is NULL. + * TargetHwAddress is NULL and TargetSwAddress is NULL. * Neither TargetSwAddress nor TargetHwAddress are NULL when DenyFlag is TRUE. @retval EFI_OUT_OF_RESOURCES The new ARP cache entry could not be allocated. @@ -205,24 +199,24 @@ EFI_STATUS IN VOID *TargetHwAddress OPTIONAL, IN UINT32 TimeoutValue, IN BOOLEAN Overwrite - ); + ); /** This function searches the ARP cache for matching entries and allocates a buffer into which those entries are copied. - - The first part of the allocated buffer is EFI_ARP_FIND_DATA, following which + + The first part of the allocated buffer is EFI_ARP_FIND_DATA, following which are protocol address pairs and hardware address pairs. - When finding a specific protocol address (BySwAddress is TRUE and AddressBuffer - is not NULL), the ARP cache timeout for the found entry is reset if Refresh is - set to TRUE. If the found ARP cache entry is a permanent entry, it is not + When finding a specific protocol address (BySwAddress is TRUE and AddressBuffer + is not NULL), the ARP cache timeout for the found entry is reset if Refresh is + set to TRUE. If the found ARP cache entry is a permanent entry, it is not affected by Refresh. - + @param This The pointer to the EFI_ARP_PROTOCOL instance. @param BySwAddress Set to TRUE to look for matching software protocol addresses. Set to FALSE to look for matching hardware protocol addresses. - @param AddressBuffer The pointer to the address buffer. Set to NULL + @param AddressBuffer The pointer to the address buffer. Set to NULL to match all addresses. @param EntryLength The size of an entry in the entries buffer. @param EntryCount The number of ARP cache entries that are found by @@ -241,7 +235,7 @@ EFI_STATUS @retval EFI_NOT_STARTED The ARP driver instance has not been configured. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_ARP_FIND)( IN EFI_ARP_PROTOCOL *This, @@ -251,7 +245,7 @@ EFI_STATUS OUT UINT32 *EntryCount OPTIONAL, OUT EFI_ARP_FIND_DATA **Entries OPTIONAL, IN BOOLEAN Refresh - ); + ); /** @@ -277,7 +271,7 @@ EFI_STATUS IN EFI_ARP_PROTOCOL *This, IN BOOLEAN BySwAddress, IN VOID *AddressBuffer OPTIONAL - ); + ); /** This function delete all dynamic entries from the ARP cache that match the specified @@ -295,7 +289,7 @@ typedef EFI_STATUS (EFIAPI *EFI_ARP_FLUSH)( IN EFI_ARP_PROTOCOL *This - ); + ); /** This function tries to resolve the TargetSwAddress and optionally returns a @@ -322,22 +316,22 @@ EFI_STATUS typedef EFI_STATUS (EFIAPI *EFI_ARP_REQUEST)( - IN EFI_ARP_PROTOCOL *This, + IN EFI_ARP_PROTOCOL *This, IN VOID *TargetSwAddress OPTIONAL, IN EFI_EVENT ResolvedEvent OPTIONAL, - OUT VOID *TargetHwAddress - ); + OUT VOID *TargetHwAddress + ); /** This function aborts the previous ARP request (identified by This, TargetSwAddress and ResolvedEvent) that is issued by EFI_ARP_PROTOCOL.Request(). - - If the request is in the internal ARP request queue, the request is aborted - immediately and its ResolvedEvent is signaled. Only an asynchronous address - request needs to be canceled. If TargeSwAddress and ResolveEvent are both - NULL, all the pending asynchronous requests that have been issued by This + + If the request is in the internal ARP request queue, the request is aborted + immediately and its ResolvedEvent is signaled. Only an asynchronous address + request needs to be canceled. If TargeSwAddress and ResolveEvent are both + NULL, all the pending asynchronous requests that have been issued by This instance will be cancelled and their corresponding events will be signaled. - + @param This The pointer to the EFI_ARP_PROTOCOL instance. @param TargetSwAddress The pointer to the protocol address in previous request session. @@ -359,13 +353,13 @@ EFI_STATUS typedef EFI_STATUS (EFIAPI *EFI_ARP_CANCEL)( - IN EFI_ARP_PROTOCOL *This, + IN EFI_ARP_PROTOCOL *This, IN VOID *TargetSwAddress OPTIONAL, IN EFI_EVENT ResolvedEvent OPTIONAL - ); + ); /// -/// ARP is used to resolve local network protocol addresses into +/// ARP is used to resolve local network protocol addresses into /// network hardware addresses. /// struct _EFI_ARP_PROTOCOL { diff --git a/MdePkg/Include/Protocol/AtaPassThru.h b/MdePkg/Include/Protocol/AtaPassThru.h index 1cc596f9e424..06b7c31d09ea 100644 --- a/MdePkg/Include/Protocol/AtaPassThru.h +++ b/MdePkg/Include/Protocol/AtaPassThru.h @@ -3,14 +3,11 @@ to send ATA Command Blocks to any ATA device attached to that ATA controller. The information includes the attributes of the ATA controller. - Copyright (c) 2009 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.3. **/ @@ -56,7 +53,7 @@ typedef struct _EFI_ATA_COMMAND_BLOCK { UINT8 AtaDeviceHead; UINT8 AtaSectorNumberExp; UINT8 AtaCylinderLowExp; - UINT8 AtaCylinderHighExp; + UINT8 AtaCylinderHighExp; UINT8 AtaFeaturesExp; UINT8 AtaSectorCount; UINT8 AtaSectorCountExp; @@ -73,7 +70,7 @@ typedef struct _EFI_ATA_STATUS_BLOCK { UINT8 AtaDeviceHead; UINT8 AtaSectorNumberExp; UINT8 AtaCylinderLowExp; - UINT8 AtaCylinderHighExp; + UINT8 AtaCylinderHighExp; UINT8 Reserved2; UINT8 AtaSectorCount; UINT8 AtaSectorCountExp; @@ -156,7 +153,7 @@ typedef struct { /// /// On Input, the size, in bytes of OutDataBuffer. On Output, the Number of bytes /// transferred between ATA Controller and the ATA device. If OutTransferLength is - /// larger than the ATA controller can handle, no data will be transferred, + /// larger than the ATA controller can handle, no data will be transferred, /// OutTransferLength will be updated to contain the number of bytes that the ATA /// controller is able to transfer, and EFI_BAD_BUFFER_SIZE will be returned. /// @@ -177,8 +174,8 @@ typedef struct { supports both blocking I/O and non-blocking I/O. The blocking I/O functionality is required, and the non-blocking I/O functionality is optional. - @param[in] This A pointer to the EFI_ATA_PASS_THRU_PROTOCOL instance. - @param[in] Port The port number of the ATA device to send the command. + @param[in] This A pointer to the EFI_ATA_PASS_THRU_PROTOCOL instance. + @param[in] Port The port number of the ATA device to send the command. @param[in] PortMultiplierPort The port multiplier port number of the ATA device to send the command. If there is no port multiplier, then specify 0xFFFF. @param[in,out] Packet A pointer to the ATA command to send to the ATA device specified by Port @@ -188,11 +185,11 @@ typedef struct { Event is not NULL and non blocking I/O is supported, then non-blocking I/O is performed, and Event will be signaled when the ATA command completes. - @retval EFI_SUCCESS The ATA command was sent by the host. For bi-directional commands, + @retval EFI_SUCCESS The ATA command was sent by the host. For bi-directional commands, InTransferLength bytes were transferred from InDataBuffer. For write and bi-directional commands, OutTransferLength bytes were transferred by OutDataBuffer. @retval EFI_BAD_BUFFER_SIZE The ATA command was not executed. The number of bytes that could be transferred - is returned in InTransferLength. For write and bi-directional commands, + is returned in InTransferLength. For write and bi-directional commands, OutTransferLength bytes were transferred by OutDataBuffer. @retval EFI_NOT_READY The ATA command could not be sent because there are too many ATA commands already queued. The caller may retry again later. @@ -230,7 +227,7 @@ EFI_STATUS If Port is the port number of the last port on the ATA controller, then EFI_NOT_FOUND is returned. - @param[in] This A pointer to the EFI_ATA_PASS_THRU_PROTOCOL instance. + @param[in] This A pointer to the EFI_ATA_PASS_THRU_PROTOCOL instance. @param[in,out] Port On input, a pointer to the port number on the ATA controller. On output, a pointer to the next port number on the ATA controller. An input value of 0xFFFF retrieves the first port @@ -250,36 +247,36 @@ EFI_STATUS ); /** - Used to retrieve the list of legal port multiplier port numbers for ATA devices on a port of an ATA - controller. These can either be the list of port multiplier ports where ATA devices are actually - present on port or the list of legal port multiplier ports on that port. Regardless, the caller of this - function must probe the port number and port multiplier port number returned to see if an ATA + Used to retrieve the list of legal port multiplier port numbers for ATA devices on a port of an ATA + controller. These can either be the list of port multiplier ports where ATA devices are actually + present on port or the list of legal port multiplier ports on that port. Regardless, the caller of this + function must probe the port number and port multiplier port number returned to see if an ATA device is actually present. - The GetNextDevice() function retrieves the port multiplier port number of an ATA device + The GetNextDevice() function retrieves the port multiplier port number of an ATA device present on a port of an ATA controller. - - If PortMultiplierPort points to a port multiplier port number value that was returned on a + + If PortMultiplierPort points to a port multiplier port number value that was returned on a previous call to GetNextDevice(), then the port multiplier port number of the next ATA device on the port of the ATA controller is returned in PortMultiplierPort, and EFI_SUCCESS is returned. - - If PortMultiplierPort points to 0xFFFF, then the port multiplier port number of the first - ATA device on port of the ATA controller is returned in PortMultiplierPort and + + If PortMultiplierPort points to 0xFFFF, then the port multiplier port number of the first + ATA device on port of the ATA controller is returned in PortMultiplierPort and EFI_SUCCESS is returned. - + If PortMultiplierPort is not 0xFFFF and the value pointed to by PortMultiplierPort was not returned on a previous call to GetNextDevice(), then EFI_INVALID_PARAMETER is returned. - - If PortMultiplierPort is the port multiplier port number of the last ATA device on the port of + + If PortMultiplierPort is the port multiplier port number of the last ATA device on the port of the ATA controller, then EFI_NOT_FOUND is returned. @param[in] This A pointer to the EFI_ATA_PASS_THRU_PROTOCOL instance. @param[in] Port The port number present on the ATA controller. @param[in,out] PortMultiplierPort On input, a pointer to the port multiplier port number of an - ATA device present on the ATA controller. - If on input a PortMultiplierPort of 0xFFFF is specified, + ATA device present on the ATA controller. + If on input a PortMultiplierPort of 0xFFFF is specified, then the port multiplier port number of the first ATA device is returned. On output, a pointer to the port multiplier port number of the next ATA device present on an ATA controller. @@ -318,7 +315,7 @@ EFI_STATUS @param[in] PortMultiplierPort The port multiplier port number of the ATA device for which a device path node is to be allocated and built. If there is no port multiplier, then specify 0xFFFF. - @param[in,out] DevicePath A pointer to a single device path node that describes the ATA + @param[out] DevicePath A pointer to a single device path node that describes the ATA device specified by Port and PortMultiplierPort. This function is responsible for allocating the buffer DevicePath with the boot service AllocatePool(). It is the caller's responsibility @@ -337,7 +334,7 @@ EFI_STATUS IN EFI_ATA_PASS_THRU_PROTOCOL *This, IN UINT16 Port, IN UINT16 PortMultiplierPort, - IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath + OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath ); /** @@ -345,7 +342,7 @@ EFI_STATUS The GetDevice() function determines the port and port multiplier port number associated with the ATA device described by DevicePath. If DevicePath is a device path node type that the - ATA Pass Thru driver supports, then the ATA Pass Thru driver will attempt to translate the contents + ATA Pass Thru driver supports, then the ATA Pass Thru driver will attempt to translate the contents DevicePath into a port number and port multiplier port number. If this translation is successful, then that port number and port multiplier port number are returned @@ -353,11 +350,11 @@ EFI_STATUS If DevicePath, Port, or PortMultiplierPort are NULL, then EFI_INVALID_PARAMETER is returned. - If DevicePath is not a device path node type that the ATA Pass Thru driver supports, then + If DevicePath is not a device path node type that the ATA Pass Thru driver supports, then EFI_UNSUPPORTED is returned. - If DevicePath is a device path node type that the ATA Pass Thru driver supports, but there is not - a valid translation from DevicePath to a port number and port multiplier port number, then + If DevicePath is a device path node type that the ATA Pass Thru driver supports, but there is not + a valid translation from DevicePath to a port number and port multiplier port number, then EFI_NOT_FOUND is returned. @param[in] This A pointer to the EFI_ATA_PASS_THRU_PROTOCOL instance. @@ -423,7 +420,7 @@ EFI_STATUS If this ATA controller does not support a device reset operation, then EFI_UNSUPPORTED is returned. - If Port or PortMultiplierPort are not in a valid range for this ATA controller, then + If Port or PortMultiplierPort are not in a valid range for this ATA controller, then EFI_INVALID_PARAMETER is returned. If a device error occurs while executing that device reset operation, then EFI_DEVICE_ERROR diff --git a/MdePkg/Include/Protocol/AuthenticationInfo.h b/MdePkg/Include/Protocol/AuthenticationInfo.h index 99e20235913a..fe85c2a0a16d 100644 --- a/MdePkg/Include/Protocol/AuthenticationInfo.h +++ b/MdePkg/Include/Protocol/AuthenticationInfo.h @@ -1,16 +1,10 @@ /** @file EFI_AUTHENTICATION_INFO_PROTOCOL as defined in UEFI 2.0. - This protocol is used on any device handle to obtain authentication information + This protocol is used on any device handle to obtain authentication information associated with the physical or logical device. -Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -21,7 +15,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. { \ 0x7671d9d0, 0x53db, 0x4173, {0xaa, 0x69, 0x23, 0x27, 0xf2, 0x1f, 0x0b, 0xc7 } \ } - + #define EFI_AUTHENTICATION_CHAP_RADIUS_GUID \ { \ 0xd6062b50, 0x15ca, 0x11da, {0x92, 0x19, 0x00, 0x10, 0x83, 0xff, 0xca, 0x4d } \ @@ -75,7 +69,7 @@ typedef struct { /// UINT8 NasSecret[1]; - /// + /// /// CHAP Initiator Secret Length in bytes on offset NasSecret + NasSecretLength. /// /// UINT16 ChapSecretLength; @@ -181,11 +175,11 @@ typedef struct { responsible for allocating the buffer and it is the caller's responsibility to free buffer when the caller is finished with buffer. - @retval EFI_SUCCESS Successfully retrieved authentication information + @retval EFI_SUCCESS Successfully retrieved authentication information for the given ControllerHandle. - @retval EFI_INVALID_PARAMETER No matching authentication information found for + @retval EFI_INVALID_PARAMETER No matching authentication information found for the given ControllerHandle. - @retval EFI_DEVICE_ERROR The authentication information could not be retrieved + @retval EFI_DEVICE_ERROR The authentication information could not be retrieved due to a hardware error. **/ @@ -203,12 +197,12 @@ EFI_STATUS @param[in] This The pointer to the EFI_AUTHENTICATION_INFO_PROTOCOL. @param[in] ControllerHandle The handle to the Controller. @param[in] Buffer The pointer to the authentication information. - - @retval EFI_SUCCESS Successfully set authentication information for the + + @retval EFI_SUCCESS Successfully set authentication information for the given ControllerHandle. - @retval EFI_UNSUPPORTED If the platform policies do not allow setting of + @retval EFI_UNSUPPORTED If the platform policies do not allow setting of the authentication information. - @retval EFI_DEVICE_ERROR The authentication information could not be configured + @retval EFI_DEVICE_ERROR The authentication information could not be configured due to a hardware error. @retval EFI_OUT_OF_RESOURCES Not enough storage is available to hold the data. @@ -219,10 +213,10 @@ EFI_STATUS IN EFI_AUTHENTICATION_INFO_PROTOCOL *This, IN EFI_HANDLE ControllerHandle, IN VOID *Buffer - ); + ); /// -/// This protocol is used on any device handle to obtain authentication +/// This protocol is used on any device handle to obtain authentication /// information associated with the physical or logical device. /// struct _EFI_AUTHENTICATION_INFO_PROTOCOL { diff --git a/MdePkg/Include/Protocol/Bds.h b/MdePkg/Include/Protocol/Bds.h index 0ecc66c8cab3..7ca7777c9ea0 100644 --- a/MdePkg/Include/Protocol/Bds.h +++ b/MdePkg/Include/Protocol/Bds.h @@ -3,14 +3,8 @@ When the DXE core is done it calls the BDS via this protocol. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -29,19 +23,19 @@ typedef struct _EFI_BDS_ARCH_PROTOCOL EFI_BDS_ARCH_PROTOCOL; /** - This function uses policy data from the platform to determine what operating - system or system utility should be loaded and invoked. This function call - also optionally make the use of user input to determine the operating system - or system utility to be loaded and invoked. When the DXE Core has dispatched - all the drivers on the dispatch queue, this function is called. This - function will attempt to connect the boot devices required to load and invoke - the selected operating system or system utility. During this process, - additional firmware volumes may be discovered that may contain addition DXE - drivers that can be dispatched by the DXE Core. If a boot device cannot be - fully connected, this function calls the DXE Service Dispatch() to allow the - DXE drivers from any newly discovered firmware volumes to be dispatched. - Then the boot device connection can be attempted again. If the same boot - device connection operation fails twice in a row, then that boot device has + This function uses policy data from the platform to determine what operating + system or system utility should be loaded and invoked. This function call + also optionally make the use of user input to determine the operating system + or system utility to be loaded and invoked. When the DXE Core has dispatched + all the drivers on the dispatch queue, this function is called. This + function will attempt to connect the boot devices required to load and invoke + the selected operating system or system utility. During this process, + additional firmware volumes may be discovered that may contain addition DXE + drivers that can be dispatched by the DXE Core. If a boot device cannot be + fully connected, this function calls the DXE Service Dispatch() to allow the + DXE drivers from any newly discovered firmware volumes to be dispatched. + Then the boot device connection can be attempted again. If the same boot + device connection operation fails twice in a row, then that boot device has failed, and should be skipped. This function should never return. @param This The EFI_BDS_ARCH_PROTOCOL instance. @@ -56,11 +50,11 @@ VOID ); /// -/// The EFI_BDS_ARCH_PROTOCOL transfers control from DXE to an operating -/// system or a system utility. If there are not enough drivers initialized -/// when this protocol is used to access the required boot device(s), then -/// this protocol should add drivers to the dispatch queue and return control -/// back to the dispatcher. Once the required boot devices are available, then +/// The EFI_BDS_ARCH_PROTOCOL transfers control from DXE to an operating +/// system or a system utility. If there are not enough drivers initialized +/// when this protocol is used to access the required boot device(s), then +/// this protocol should add drivers to the dispatch queue and return control +/// back to the dispatcher. Once the required boot devices are available, then /// the boot device can be used to load and invoke an OS or a system utility. /// struct _EFI_BDS_ARCH_PROTOCOL { diff --git a/MdePkg/Include/Protocol/Bis.h b/MdePkg/Include/Protocol/Bis.h index b3ac58ec0302..23dc6577fbf0 100644 --- a/MdePkg/Include/Protocol/Bis.h +++ b/MdePkg/Include/Protocol/Bis.h @@ -1,18 +1,12 @@ /** @file - The EFI_BIS_PROTOCOL is used to check a digital signature of a data block + The EFI_BIS_PROTOCOL is used to check a digital signature of a data block against a digital certificate for the purpose of an integrity and authorization check. -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent - @par Revision Reference: - This Protocol is introduced in EFI Specification 1.10. + @par Revision Reference: + This Protocol is introduced in EFI Specification 1.10. **/ @@ -122,32 +116,32 @@ typedef struct { #define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE \ BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID -/** +/** Initializes the BIS service, checking that it is compatible with the version requested by the caller. - After this call, other BIS functions may be invoked. - + After this call, other BIS functions may be invoked. + @param This A pointer to the EFI_BIS_PROTOCOL object. - @param AppHandle The function writes the new BIS_APPLICATION_HANDLE if + @param AppHandle The function writes the new BIS_APPLICATION_HANDLE if successful, otherwise it writes NULL. The caller must eventually - destroy this handle by calling Shutdown(). + destroy this handle by calling Shutdown(). @param InterfaceVersion On input, the caller supplies the major version number of the - interface version desired. - On output, both the major and minor + interface version desired. + On output, both the major and minor version numbers are updated with the major and minor version 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. + 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 + @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 + @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. + supported by the implementation. + @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. @retval EFI_DEVICE_ERROR One of the following device errors: * The function encountered an unexpected internal failure while initializing a cryptographic software module * No cryptographic software module with compatible version was found @@ -161,51 +155,51 @@ typedef struct { is NULL or an invalid memory reference. Or, the TargetAddress parameter supplied by the caller is NULL or an invalid memory reference. - -**/ + +**/ typedef EFI_STATUS (EFIAPI *EFI_BIS_INITIALIZE)( - IN EFI_BIS_PROTOCOL *This, - OUT BIS_APPLICATION_HANDLE *AppHandle, - IN OUT EFI_BIS_VERSION *InterfaceVersion, - IN EFI_BIS_DATA *TargetAddress + IN EFI_BIS_PROTOCOL *This, + OUT BIS_APPLICATION_HANDLE *AppHandle, + IN OUT EFI_BIS_VERSION *InterfaceVersion, + IN EFI_BIS_DATA *TargetAddress ); -/** - Frees memory structures allocated and returned by other functions in the EFI_BIS protocol. - +/** + Frees memory structures allocated and returned by other functions in the EFI_BIS protocol. + @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. + of the BIS service. + @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 - 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. + 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 ToFree parameter is not or is no longer a memory resource - associated with this AppHandle. - -**/ + associated with this AppHandle. + +**/ typedef EFI_STATUS (EFIAPI *EFI_BIS_FREE)( - IN BIS_APPLICATION_HANDLE AppHandle, - IN EFI_BIS_DATA *ToFree + IN BIS_APPLICATION_HANDLE AppHandle, + IN EFI_BIS_DATA *ToFree ); -/** +/** Shuts down an application's instance of the BIS service, invalidating the application handle. After - this call, other BIS functions may no longer be invoked using the application handle value. - + this call, other BIS functions may no longer be invoked using the application handle value. + @param AppHandle An opaque handle that identifies the caller's instance of initialization - of the BIS service. + of the BIS service. @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. + 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 while returning resources associated with a cryptographic software module, or while trying to shut down a cryptographic software module. @@ -213,206 +207,206 @@ EFI_STATUS typedef EFI_STATUS (EFIAPI *EFI_BIS_SHUTDOWN)( - IN BIS_APPLICATION_HANDLE AppHandle + IN BIS_APPLICATION_HANDLE AppHandle ); -/** +/** Retrieves the certificate that has been configured as the identity of the organization designated as the source of authorization for signatures of boot objects. - + @param AppHandle An opaque handle that identifies the caller's instance of initialization - of the BIS service. + of the BIS service. @param Certificate The function writes an allocated EFI_BIS_DATA* containing the Boot 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 - application instance handle associated with the EFI_BIS protocol. - @retval EFI_NOT_FOUND There is no Boot Object Authorization Certificate currently installed. - @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. + application instance handle associated with the EFI_BIS protocol. + @retval EFI_NOT_FOUND There is no Boot Object Authorization Certificate currently installed. + @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. @retval EFI_INVALID_PARAMETER The Certificate parameter supplied by the caller is NULL or - an invalid memory reference. - -**/ + an invalid memory reference. + +**/ typedef EFI_STATUS (EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE)( - IN BIS_APPLICATION_HANDLE AppHandle, - OUT EFI_BIS_DATA **Certificate + IN BIS_APPLICATION_HANDLE AppHandle, + OUT EFI_BIS_DATA **Certificate ); -/** +/** Verifies the integrity and authorization of the indicated data object according to the - indicated credentials. - + indicated credentials. + @param AppHandle An opaque handle that identifies the caller's instance of initialization - of the BIS service. + of the BIS service. @param Credentials A Signed Manifest containing verification information for the indicated - data object. + data object. @param DataObject An in-memory copy of the raw data object to be verified. @param IsVerified The function writes TRUE if the verification succeeded, otherwise - FALSE. - + FALSE. + @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. + 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 One or more parameters are invalid. @retval EFI_SECURITY_VIOLATION The signed manifest supplied as the Credentials 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. + +**/ typedef EFI_STATUS (EFIAPI *EFI_BIS_VERIFY_BOOT_OBJECT)( - IN BIS_APPLICATION_HANDLE AppHandle, - IN EFI_BIS_DATA *Credentials, - IN EFI_BIS_DATA *DataObject, - OUT BOOLEAN *IsVerified + IN BIS_APPLICATION_HANDLE AppHandle, + IN EFI_BIS_DATA *Credentials, + IN EFI_BIS_DATA *DataObject, + OUT BOOLEAN *IsVerified ); -/** +/** Retrieves the current status of the Boot Authorization Check Flag. - + @param AppHandle An opaque handle that identifies the caller's instance of initialization - of the BIS service. + of the BIS service. @param CheckIsRequired The function writes the value TRUE if a Boot Authorization Check is - currently required on this platform, otherwise the function writes - FALSE. - + currently required on this platform, otherwise the function writes + FALSE. + @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. + 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 CheckIsRequired parameter supplied by the caller is - NULL or an invalid memory reference. - -**/ + NULL or an invalid memory reference. + +**/ typedef EFI_STATUS (EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG)( - IN BIS_APPLICATION_HANDLE AppHandle, - OUT BOOLEAN *CheckIsRequired + IN BIS_APPLICATION_HANDLE AppHandle, + OUT BOOLEAN *CheckIsRequired ); -/** +/** Retrieves a unique token value to be included in the request credential for the next update of any - parameter in the Boot Object Authorization set - - @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 newunique update token value. - The caller musteventually free the memory allocated + parameter in the Boot Object Authorization set + + @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 newunique update token value. + The caller musteventually 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. + 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 UpdateToken parameter supplied by the caller is NULL or - an invalid memory reference. - @retval EFI_DEVICE_ERROR An unexpected internal error occurred. - -**/ + an invalid memory reference. + @retval EFI_DEVICE_ERROR An unexpected internal error occurred. + +**/ typedef EFI_STATUS (EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN)( - IN BIS_APPLICATION_HANDLE AppHandle, - OUT EFI_BIS_DATA **UpdateToken + IN BIS_APPLICATION_HANDLE AppHandle, + OUT EFI_BIS_DATA **UpdateToken ); -/** +/** Updates one of the configurable parameters of the Boot Object Authorization set. - - @param AppHandle An opaque handle that identifies the caller's - instance of initialization of the BIS service. - @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. - The caller must eventually free the memory allocated + + @param AppHandle An opaque handle that identifies the caller's + instance of initialization of the BIS service. + @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. + 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 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_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 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 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. - -**/ + or An unexpected internal error occurred in a cryptographic software module. + +**/ typedef EFI_STATUS (EFIAPI *EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION)( - IN BIS_APPLICATION_HANDLE AppHandle, - IN EFI_BIS_DATA *RequestCredential, - OUT EFI_BIS_DATA **NewUpdateToken + IN BIS_APPLICATION_HANDLE AppHandle, + IN EFI_BIS_DATA *RequestCredential, + OUT EFI_BIS_DATA **NewUpdateToken ); -/** +/** Verifies the integrity and authorization of the indicated data object according to the indicated - credentials and authority certificate. - + credentials and authority certificate. + @param AppHandle An opaque handle that identifies the caller's instance of initialization - of the BIS service. + of the BIS service. @param Credentials A Signed Manifest containing verification information for the - indicated data object. + indicated data object. @param DataObject An in-memory copy of the raw data object to be verified. - @param SectionName An ASCII string giving the section name in the + @param SectionName An ASCII string giving the section name in the manifest holding the verification information (in other words, - hash value) that corresponds to DataObject. - @param AuthorityCertificate A digital certificate whose public key must match the signer's - public key which is found in the credentials. + hash value) that corresponds to DataObject. + @param AuthorityCertificate A digital certificate whose public key must match the signer's + public key which is found in the credentials. @param IsVerified The function writes TRUE if the verification was successful. - Otherwise, the function writes FALSE. - - @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 One or more parameters are invalid. + Otherwise, the function writes FALSE. + + @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 One or more parameters are invalid. @retval EFI_SECURITY_VIOLATION The Credentials.Data supplied by the caller is NULL, - or the AuthorityCertificate supplied by the caller was - invalid (could not be parsed), - or Platform-specific authorization failed, etc. + 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 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. -**/ + or An unexpected internal error occurred in a cryptographic software module. +**/ typedef EFI_STATUS (EFIAPI *EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL)( - IN BIS_APPLICATION_HANDLE AppHandle, - IN EFI_BIS_DATA *Credentials, - IN EFI_BIS_DATA *DataObject, - IN EFI_BIS_DATA *SectionName, - IN EFI_BIS_DATA *AuthorityCertificate, - OUT BOOLEAN *IsVerified + IN BIS_APPLICATION_HANDLE AppHandle, + IN EFI_BIS_DATA *Credentials, + IN EFI_BIS_DATA *DataObject, + IN EFI_BIS_DATA *SectionName, + IN EFI_BIS_DATA *AuthorityCertificate, + OUT BOOLEAN *IsVerified ); -/** +/** Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength - combinations that the platform supports. + combinations that the platform supports. @param AppHandle An opaque handle that identifies the caller's instance of initialization - of the BIS service. + 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 + of EFI_BIS_SIGNATURE_INFO structures representing the supported 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_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 in a @@ -424,8 +418,8 @@ EFI_STATUS typedef EFI_STATUS (EFIAPI *EFI_BIS_GET_SIGNATURE_INFO)( - IN BIS_APPLICATION_HANDLE AppHandle, - OUT EFI_BIS_DATA **SignatureInfo + IN BIS_APPLICATION_HANDLE AppHandle, + OUT EFI_BIS_DATA **SignatureInfo ); /// diff --git a/MdePkg/Include/Protocol/BlockIo.h b/MdePkg/Include/Protocol/BlockIo.h index 4bc2109db122..460b616fdd8b 100644 --- a/MdePkg/Include/Protocol/BlockIo.h +++ b/MdePkg/Include/Protocol/BlockIo.h @@ -4,14 +4,8 @@ The Block IO protocol is used to abstract block devices like hard drives, DVD-ROMs and floppy drives. - Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -27,12 +21,12 @@ typedef struct _EFI_BLOCK_IO_PROTOCOL EFI_BLOCK_IO_PROTOCOL; /// /// Protocol GUID name defined in EFI1.1. -/// +/// #define BLOCK_IO_PROTOCOL EFI_BLOCK_IO_PROTOCOL_GUID /// /// Protocol defined in EFI1.1. -/// +/// typedef EFI_BLOCK_IO_PROTOCOL EFI_BLOCK_IO; /** @@ -68,7 +62,7 @@ EFI_STATUS @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 LBAs that are not valid, + @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid, or the buffer is not on proper alignment. **/ @@ -98,7 +92,7 @@ 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 LBAs that are not valid, + @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid, or the buffer is not on proper alignment. **/ @@ -135,17 +129,17 @@ typedef struct { /// /// The curent media Id. If the media changes, this value is changed. /// - UINT32 MediaId; - + UINT32 MediaId; + /// /// TRUE if the media is removable; otherwise, FALSE. - /// + /// BOOLEAN RemovableMedia; - + /// /// TRUE if there is a media currently present in the device; /// othersise, FALSE. THis field shows the media present status - /// as of the most recent ReadBlocks() or WriteBlocks() call. + /// as of the most recent ReadBlocks() or WriteBlocks() call. /// BOOLEAN MediaPresent; @@ -154,45 +148,45 @@ typedef struct { /// FALSE. For media with only one partition this would be TRUE. /// BOOLEAN LogicalPartition; - + /// /// TRUE if the media is marked read-only otherwise, FALSE. /// This field shows the read-only status as of the most recent WriteBlocks () call. /// BOOLEAN ReadOnly; - + /// /// TRUE if the WriteBlock () function caches write data. /// - BOOLEAN WriteCaching; - + BOOLEAN WriteCaching; + /// /// The intrinsic block size of the device. If the media changes, then - /// this field is updated. + /// this field is updated. /// - UINT32 BlockSize; - + UINT32 BlockSize; + /// /// Supplies the alignment requirement for any buffer to read or write block(s). /// - UINT32 IoAlign; - + UINT32 IoAlign; + /// /// The last logical block address on the device. - /// If the media changes, then this field is updated. + /// If the media changes, then this field is updated. /// - EFI_LBA LastBlock; + EFI_LBA LastBlock; /// /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to - /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the first LBA is aligned to - /// a physical block boundary. + /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the first LBA is aligned to + /// a physical block boundary. /// EFI_LBA LowestAlignedLba; /// /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to - /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the number of logical blocks + /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the number of logical blocks /// per physical block. /// UINT32 LogicalBlocksPerPhysicalBlock; @@ -211,7 +205,7 @@ typedef struct { /// /// Revision defined in EFI1.1. -/// +/// #define EFI_BLOCK_IO_INTERFACE_REVISION EFI_BLOCK_IO_PROTOCOL_REVISION /// diff --git a/MdePkg/Include/Protocol/BlockIo2.h b/MdePkg/Include/Protocol/BlockIo2.h index 0e4bb289cffd..75ea914ffcdf 100644 --- a/MdePkg/Include/Protocol/BlockIo2.h +++ b/MdePkg/Include/Protocol/BlockIo2.h @@ -5,14 +5,8 @@ enables the ability to read and write data at a block level in a non-blocking manner. - Copyright (c) 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -69,7 +63,7 @@ EFI_STATUS /** Read BufferSize bytes from Lba into Buffer. - + This function reads the requested number of blocks from the device. All the blocks are read, or an error is returned. If EFI_DEVICE_ERROR, EFI_NO_MEDIA,_or EFI_MEDIA_CHANGED is returned and @@ -77,13 +71,13 @@ EFI_STATUS not be signaled. @param[in] This Indicates a pointer to the calling context. - @param[in] MediaId Id of the media, changes every time the media is + @param[in] MediaId Id of the media, changes every time the media is replaced. @param[in] Lba The starting Logical Block Address to read from. - @param[in, out] Token A pointer to the token associated with the transaction. - @param[in] BufferSize Size of Buffer, must be a multiple of device block size. - @param[out] Buffer A pointer to the destination buffer for the data. The - caller is responsible for either having implicit or + @param[in, out] Token A pointer to the token associated with the transaction. + @param[in] BufferSize Size of Buffer, must be a multiple of device block size. + @param[out] 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 read request was queued if Token->Event is @@ -95,7 +89,7 @@ EFI_STATUS @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. @retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic block size of the device. - @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid, + @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid, or the buffer is not on proper alignment. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @@ -136,7 +130,7 @@ EFI_STATUS @retval EFI_MEDIA_CHNAGED The MediaId does not matched the current device. @retval EFI_DEVICE_ERROR The device reported an error while performing the write. @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 LBAs that are not valid, + @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid, or the buffer is not on proper alignment. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @@ -155,10 +149,10 @@ EFI_STATUS /** Flush the Block Device. - + If EFI_DEVICE_ERROR, EFI_NO_MEDIA,_EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED is returned and non-blocking I/O is being used, the Event associated with - this request will not be signaled. + this request will not be signaled. @param[in] This Indicates a pointer to the calling context. @param[in,out] Token A pointer to the token associated with the transaction @@ -189,9 +183,9 @@ EFI_STATUS /// struct _EFI_BLOCK_IO2_PROTOCOL { /// - /// A pointer to the EFI_BLOCK_IO_MEDIA data for this device. + /// A pointer to the EFI_BLOCK_IO_MEDIA data for this device. /// Type EFI_BLOCK_IO_MEDIA is defined in BlockIo.h. - /// + /// EFI_BLOCK_IO_MEDIA *Media; EFI_BLOCK_RESET_EX Reset; diff --git a/MdePkg/Include/Protocol/BlockIoCrypto.h b/MdePkg/Include/Protocol/BlockIoCrypto.h index ffac54b3b157..178d31830ff9 100644 --- a/MdePkg/Include/Protocol/BlockIoCrypto.h +++ b/MdePkg/Include/Protocol/BlockIoCrypto.h @@ -2,14 +2,11 @@ The UEFI Inline Cryptographic Interface protocol provides services to abstract access to inline cryptographic capabilities. - Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2015-2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.5. **/ diff --git a/MdePkg/Include/Protocol/BluetoothAttribute.h b/MdePkg/Include/Protocol/BluetoothAttribute.h new file mode 100644 index 000000000000..eb39ea27f096 --- /dev/null +++ b/MdePkg/Include/Protocol/BluetoothAttribute.h @@ -0,0 +1,277 @@ +/** @file + EFI Bluetooth Attribute Protocol as defined in UEFI 2.7. + This protocol provides service for Bluetooth ATT (Attribute Protocol) and GATT (Generic + Attribute Profile) based protocol interfaces. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol is introduced in UEFI Specification 2.7 + +**/ + +#ifndef __EFI_BLUETOOTH_ATTRIBUTE_H__ +#define __EFI_BLUETOOTH_ATTRIBUTE_H__ + +#define EFI_BLUETOOTH_ATTRIBUTE_SERVICE_BINDING_PROTOCOL_GUID \ + { \ + 0x5639867a, 0x8c8e, 0x408d, { 0xac, 0x2f, 0x4b, 0x61, 0xbd, 0xc0, 0xbb, 0xbb } \ + } + +#define EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL_GUID \ + { \ + 0x898890e9, 0x84b2, 0x4f3a, { 0x8c, 0x58, 0xd8, 0x57, 0x78, 0x13, 0xe0, 0xac } \ + } + +typedef struct _EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL; + +#pragma pack(1) + +// +// Bluetooth UUID +// +typedef struct { + UINT8 Length; + union { + UINT16 Uuid16; + UINT32 Uuid32; + UINT8 Uuid128[16]; + } Data; +} EFI_BLUETOOTH_UUID; + + +#define UUID_16BIT_TYPE_LEN 2 +#define UUID_32BIT_TYPE_LEN 4 +#define UUID_128BIT_TYPE_LEN 16 + +#define BLUETOOTH_IS_ATTRIBUTE_OF_TYPE(a,t) ((a)->Type.Length == UUID_16BIT_TYPE_LEN && (a)->Type.Data.Uuid16 == (t)) + +// +// Bluetooth Attribute Permission +// +typedef union { + struct { + UINT16 Readable : 1; + UINT16 ReadEncryption : 1; + UINT16 ReadAuthentication : 1; + UINT16 ReadAuthorization : 1; + UINT16 ReadKeySize : 5; + UINT16 Reserved1 : 7; + UINT16 Writeable : 1; + UINT16 WriteEncryption : 1; + UINT16 WriteAuthentication : 1; + UINT16 WriteAuthorization : 1; + UINT16 WriteKeySize : 5; + UINT16 Reserved2 : 7; + } Permission; + UINT32 Data32; +} EFI_BLUETOOTH_ATTRIBUTE_PERMISSION; + +typedef struct { + EFI_BLUETOOTH_UUID Type; + UINT16 Length; + UINT16 AttributeHandle; + EFI_BLUETOOTH_ATTRIBUTE_PERMISSION AttributePermission; +} EFI_BLUETOOTH_ATTRIBUTE_HEADER; + +typedef struct { + EFI_BLUETOOTH_ATTRIBUTE_HEADER Header; + UINT16 EndGroupHandle; + EFI_BLUETOOTH_UUID ServiceUuid; +} EFI_BLUETOOTH_GATT_PRIMARY_SERVICE_INFO; + +typedef struct { + EFI_BLUETOOTH_ATTRIBUTE_HEADER Header; + UINT16 StartGroupHandle; + UINT16 EndGroupHandle; + EFI_BLUETOOTH_UUID ServiceUuid; +} EFI_BLUETOOTH_GATT_INCLUDE_SERVICE_INFO; + +typedef struct { + EFI_BLUETOOTH_ATTRIBUTE_HEADER Header; + UINT8 CharacteristicProperties; + UINT16 CharacteristicValueHandle; + EFI_BLUETOOTH_UUID CharacteristicUuid; +} EFI_BLUETOOTH_GATT_CHARACTERISTIC_INFO; + +typedef struct { + EFI_BLUETOOTH_ATTRIBUTE_HEADER Header; + EFI_BLUETOOTH_UUID CharacteristicDescriptorUuid; +} EFI_BLUETOOTH_GATT_CHARACTERISTIC_DESCRIPTOR_INFO; + +#pragma pack() + +typedef struct { + UINT16 AttributeHandle; +} EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER_NOTIFICATION; + +typedef struct { + UINT16 AttributeHandle; +} EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER_INDICATION; + +typedef struct { + UINT32 Version; + UINT8 AttributeOpCode; + union { + EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER_NOTIFICATION Notification; + EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER_INDICATION Indication; + } Parameter; +} EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER; + +typedef struct { + UINT32 Version; + BLUETOOTH_LE_ADDRESS BD_ADDR; + BLUETOOTH_LE_ADDRESS DirectAddress; + UINT8 RSSI; + UINTN AdvertisementDataSize; + VOID *AdvertisementData; +} EFI_BLUETOOTH_LE_DEVICE_INFO; + +/** + The callback function to send request. + + @param[in] This Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance. + @param[in] Data Data received. The first byte is the attribute opcode, followed by opcode specific + fields. See Bluetooth specification, Vol 3, Part F, Attribute Protocol. It might be a + normal RESPONSE message, or ERROR RESPONSE messag + @param[in] DataLength The length of Data in bytes. + @param[in] Context The context passed from the callback registration request. + + @retval EFI_SUCCESS The callback function complete successfully. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_FUNCTION) ( + IN EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL *This, + IN VOID *Data, + IN UINTN DataLength, + IN VOID *Context + ); + +/** + Send a "REQUEST" or "COMMAND" message to remote server and receive a "RESPONSE" message + for "REQUEST" from remote server according to Bluetooth attribute protocol data unit(PDU). + + @param[in] This Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance. + @param[in] Data Data of a REQUEST or COMMAND message. The first byte is the attribute PDU + related opcode, followed by opcode specific fields. See Bluetooth specification, + Vol 3, Part F, Attribute Protocol. + @param[in] DataLength The length of Data in bytes. + @param[in] Callback Callback function to notify the RESPONSE is received to the caller, with the + response buffer. Caller must check the response buffer content to know if the + request action is success or fail. It may be NULL if the data is a COMMAND. + @param[in] Context Data passed into Callback function. It is optional parameter and may be NULL. + + @retval EFI_SUCCESS The request is sent successfully. + @retval EFI_INVALID_PARAMETER One or more parameters are invalid due to following conditions: + - The Buffer is NULL. + - The BufferLength is 0. + - The opcode in Buffer is not a valid OPCODE according to Bluetooth specification. + - The Callback is NULL. + @retval EFI_DEVICE_ERROR Sending the request failed due to the host controller or the device error. + @retval EFI_NOT_READY A GATT operation is already underway for this device. + @retval EFI_UNSUPPORTED The attribute does not support the corresponding operation. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_SEND_REQUEST) ( + IN EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL *This, + IN VOID *Data, + IN UINTN DataLength, + IN EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_FUNCTION Callback, + IN VOID *Context + ); + +/** + Register or unregister a server initiated message, such as NOTIFICATION or INDICATION, on a + characteristic value on remote server. + + @param[in] This Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance. + @param[in] CallbackParameter The parameter of the callback. + @param[in] Callback Callback function for server initiated attribute protocol. NULL callback + function means unregister the server initiated callback. + @param[in] Context Data passed into Callback function. It is optional parameter and may be NULL. + + @retval EFI_SUCCESS The callback function is registered or unregistered successfully + @retval EFI_INVALID_PARAMETER The attribute opcode is not server initiated message opcode. See + Bluetooth specification, Vol 3, Part F, Attribute Protocol. + @retval EFI_ALREADY_STARTED A callback function is already registered on the same attribute + opcode and attribute handle, when the Callback is not NULL. + @retval EFI_NOT_STARTED A callback function is not registered on the same attribute opcode + and attribute handle, when the Callback is NULL. + @retval EFI_NOT_READY A GATT operation is already underway for this device. + @retval EFI_UNSUPPORTED The attribute does not support notification. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_REGISTER_FOR_SERVER_NOTIFICATION)( + IN EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL *This, + IN EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER *CallbackParameter, + IN EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_FUNCTION Callback, + IN VOID *Context + ); + +/** + Get Bluetooth discovered service information. + + @param[in] This Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance. + @param[out] ServiceInfoSize A pointer to the size, in bytes, of the ServiceInfo buffer. + @param[out] ServiceInfo A pointer to a callee allocated buffer that returns Bluetooth + discovered service information. Callee allocates this buffer by + using EFI Boot Service AllocatePool(). + + @retval EFI_SUCCESS The Bluetooth discovered service information is returned successfully. + @retval EFI_DEVICE_ERROR A hardware error occurred trying to retrieve the Bluetooth discovered + service information. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_GET_SERVICE_INFO)( + IN EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL *This, + OUT UINTN *ServiceInfoSize, + OUT VOID **ServiceInfo + ); + +/** + Get Bluetooth device information. + + @param[in] This Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance. + @param[out] DeviceInfoSize A pointer to the size, in bytes, of the DeviceInfo buffer. + @param[out] DeviceInfo A pointer to a callee allocated buffer that returns Bluetooth + device information. Callee allocates this buffer by using EFI Boot + Service AllocatePool(). If this device is Bluetooth classic + device, EFI_BLUETOOTH_DEVICE_INFO should be used. If + this device is Bluetooth LE device, EFI_BLUETOOTH_LE_DEVICE_INFO + should be used. + + @retval EFI_SUCCESS The Bluetooth device information is returned successfully. + @retval EFI_DEVICE_ERROR A hardware error occurred trying to retrieve the Bluetooth device + information + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_GET_DEVICE_INFO)( + IN EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL *This, + OUT UINTN *DeviceInfoSize, + OUT VOID **DeviceInfo + ); + +struct _EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL { + EFI_BLUETOOTH_ATTRIBUTE_SEND_REQUEST SendRequest; + EFI_BLUETOOTH_ATTRIBUTE_REGISTER_FOR_SERVER_NOTIFICATION RegisterForServerNotification; + EFI_BLUETOOTH_ATTRIBUTE_GET_SERVICE_INFO GetServiceInfo; + EFI_BLUETOOTH_ATTRIBUTE_GET_DEVICE_INFO GetDeviceInfo; +}; + + +extern EFI_GUID gEfiBluetoothAttributeProtocolGuid; +extern EFI_GUID gEfiBluetoothAttributeServiceBindingProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/BluetoothConfig.h b/MdePkg/Include/Protocol/BluetoothConfig.h index cc72b1e21a6a..8a6013173448 100644 --- a/MdePkg/Include/Protocol/BluetoothConfig.h +++ b/MdePkg/Include/Protocol/BluetoothConfig.h @@ -1,18 +1,12 @@ /** @file - EFI Bluetooth Configuration Protocol as defined in UEFI 2.5. + EFI Bluetooth Configuration Protocol as defined in UEFI 2.7. This protocol abstracts user interface configuration for Bluetooth device. - Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials are licensed and made available under - the terms and conditions of the BSD License that accompanies this distribution. - The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php. - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent - @par Revision Reference: - This Protocol is introduced in UEFI Specification 2.5 + @par Revision Reference: + This Protocol is introduced in UEFI Specification 2.7 **/ @@ -25,7 +19,7 @@ { \ 0x62960cf3, 0x40ff, 0x4263, { 0xa7, 0x7c, 0xdf, 0xde, 0xbd, 0x19, 0x1b, 0x4b } \ } - + typedef struct _EFI_BLUETOOTH_CONFIG_PROTOCOL EFI_BLUETOOTH_CONFIG_PROTOCOL; typedef UINT32 EFI_BLUETOOTH_CONFIG_REMOTE_DEVICE_STATE_TYPE; @@ -41,7 +35,7 @@ typedef struct { /// BLUETOOTH_ADDRESS BDAddr; /// - /// State of the remote deive + /// State of the remote deive /// UINT8 RemoteDeviceState; /// @@ -69,7 +63,7 @@ typedef enum { /// /// Remote Bluetooth device state. Data structure is EFI_BLUETOOTH_CONFIG_REMOTE_DEVICE_STATE_TYPE. /// - EfiBluetoothConfigDataTypeRemoteDeviceState, + EfiBluetoothConfigDataTypeRemoteDeviceState, /* Relevant for LE*/ /// /// Local/Remote Bluetooth device SDP information. Data structure is UINT8[]. /// @@ -77,11 +71,11 @@ typedef enum { /// /// Local Bluetooth device address. Data structure is BLUETOOTH_ADDRESS. /// - EfiBluetoothConfigDataTypeBDADDR, + EfiBluetoothConfigDataTypeBDADDR, /* Relevant for LE*/ /// /// Local Bluetooth discoverable state. Data structure is UINT8. (Page scan and/or Inquiry scan) /// - EfiBluetoothConfigDataTypeDiscoverable, + EfiBluetoothConfigDataTypeDiscoverable, /* Relevant for LE*/ /// /// Local Bluetooth controller stored paired device list. Data structure is BLUETOOTH_ADDRESS[]. /// @@ -90,6 +84,21 @@ typedef enum { /// Local available device list. Data structure is BLUETOOTH_ADDRESS[]. /// EfiBluetoothConfigDataTypeAvailableDeviceList, + EfiBluetoothConfigDataTypeRandomAddress, /* Relevant for LE*/ + EfiBluetoothConfigDataTypeRSSI, /* Relevant for LE*/ + /// + /// Advertisement report. Data structure is UNIT8[]. + /// + EfiBluetoothConfigDataTypeAdvertisementData, /* Relevant for LE*/ + EfiBluetoothConfigDataTypeIoCapability, /* Relevant for LE*/ + EfiBluetoothConfigDataTypeOOBDataFlag, /* Relevant for LE*/ + /// + /// KeyType of Authentication Requirements flag of local + /// device as UINT8, indicating requested security properties. + /// See Bluetooth specification 3.H.3.5.1. BIT0: MITM, BIT1:SC. + /// + EfiBluetoothConfigDataTypeKeyType, /* Relevant for LE*/ + EfiBluetoothConfigDataTypeEncKeySize, /* Relevant for LE*/ EfiBluetoothConfigDataTypeMax, } EFI_BLUETOOTH_CONFIG_DATA_TYPE; @@ -98,12 +107,12 @@ typedef enum { /// typedef enum { /// - /// For SSP - passkey entry. Input buffer is Passkey (4 bytes). No output buffer. + /// For SSP - passkey entry. Input buffer is Passkey (4 bytes). No output buffer. /// See Bluetooth HCI command for detail. /// EfiBluetoothCallbackTypeUserPasskeyNotification, /// - /// For SSP - just work and numeric comparison. Input buffer is numeric value (4 bytes). + /// For SSP - just work and numeric comparison. Input buffer is numeric value (4 bytes). /// Output buffer is BOOLEAN (1 byte). See Bluetooth HCI command for detail. /// EfiBluetoothCallbackTypeUserConfirmationRequest, @@ -112,7 +121,7 @@ typedef enum { /// EfiBluetoothCallbackTypeOOBDataRequest, /// - /// For legacy paring. No input buffer. Output buffer is PIN code( <= 16 bytes). + /// For legacy paring. No input buffer. Output buffer is PIN code( <= 16 bytes). /// See Bluetooth HCI command for detail. /// EfiBluetoothCallbackTypePinCodeRequest, @@ -124,44 +133,44 @@ typedef enum { /// typedef enum { /// - /// This callback is called when Bluetooth receive Disconnection_Complete event. Input buffer is Event + /// This callback is called when Bluetooth receive Disconnection_Complete event. Input buffer is Event /// Parameters of Disconnection_Complete Event defined in Bluetooth specification. /// EfiBluetoothConnCallbackTypeDisconnected, /// - /// This callback is called when Bluetooth receive Connection_Complete event. Input buffer is Event + /// This callback is called when Bluetooth receive Connection_Complete event. Input buffer is Event /// Parameters of Connection_Complete Event defined in Bluetooth specification. /// EfiBluetoothConnCallbackTypeConnected, /// - /// This callback is called when Bluetooth receive Authentication_Complete event. Input buffer is Event + /// This callback is called when Bluetooth receive Authentication_Complete event. Input buffer is Event /// Parameters of Authentication_Complete Event defined in Bluetooth specification. /// EfiBluetoothConnCallbackTypeAuthenticated, /// - /// This callback is called when Bluetooth receive Encryption_Change event. Input buffer is Event + /// This callback is called when Bluetooth receive Encryption_Change event. Input buffer is Event /// Parameters of Encryption_Change Event defined in Bluetooth specification. /// EfiBluetoothConnCallbackTypeEncrypted } EFI_BLUETOOTH_CONNECT_COMPLETE_CALLBACK_TYPE; - + /** Initialize Bluetooth host controller and local device. @param This Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance. @retval EFI_SUCCESS The Bluetooth host controller and local device is initialized successfully. - @retval EFI_DEVICE_ERROR A hardware error occurred trying to initialize the Bluetooth host controller + @retval EFI_DEVICE_ERROR A hardware error occurred trying to initialize the Bluetooth host controller and local device. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_INIT)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This ); - + /** Callback function, it is called if a Bluetooth device is found during scan process. @@ -179,16 +188,16 @@ EFI_STATUS IN VOID *Context, IN EFI_BLUETOOTH_SCAN_CALLBACK_INFORMATION *CallbackInfo ); - + /** Scan Bluetooth device. @param This Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance. - @param ReScan If TRUE, a new scan request is submitted no matter there is scan result before. - If FALSE and there is scan result, the previous scan result is returned and no scan request + @param ReScan If TRUE, a new scan request is submitted no matter there is scan result before. + If FALSE and there is scan result, the previous scan result is returned and no scan request is submitted. @param ScanType Bluetooth scan type, Inquiry and/or Page. See Bluetooth specification for detail. - @param Callback The callback function. This function is called if a Bluetooth device is found during scan + @param Callback The callback function. This function is called if a Bluetooth device is found during scan process. @param Context Data passed into Callback function. This is optional parameter and may be NULL. @@ -196,7 +205,7 @@ EFI_STATUS @retval EFI_DEVICE_ERROR A hardware error occurred trying to scan the Bluetooth device. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_SCAN)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This, @@ -205,7 +214,7 @@ EFI_STATUS IN EFI_BLUETOOTH_CONFIG_SCAN_CALLBACK_FUNCTION Callback, IN VOID *Context ); - + /** Connect a Bluetooth device. @@ -218,7 +227,7 @@ EFI_STATUS @retval EFI_DEVICE_ERROR A hardware error occurred trying to connect the Bluetooth device. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_CONNECT)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This, @@ -238,14 +247,14 @@ EFI_STATUS @retval EFI_DEVICE_ERROR A hardware error occurred trying to disconnect the Bluetooth device. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_DISCONNECT)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This, IN BLUETOOTH_ADDRESS *BD_ADDR, IN UINT8 Reason ); - + /** Get Bluetooth configuration data. @@ -258,14 +267,14 @@ EFI_STATUS @retval EFI_SUCCESS The Bluetooth configuration data is returned successfully. @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: - DataSize is NULL. - - *DataSize is 0. - - Data is NULL. + - *DataSize is not 0 and Data is NULL. @retval EFI_UNSUPPORTED The DataType is unsupported. @retval EFI_NOT_FOUND The DataType is not found. @retval EFI_BUFFER_TOO_SMALL The buffer is too small to hold the buffer. + *DataSize has been updated with the size needed to complete the request. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_GET_DATA)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This, @@ -273,7 +282,7 @@ EFI_STATUS IN OUT UINTN *DataSize, IN OUT VOID *Data ); - + /** Set Bluetooth configuration data. @@ -290,7 +299,7 @@ EFI_STATUS @retval EFI_BUFFER_TOO_SMALL Cannot set configuration data. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_SET_DATA)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This, @@ -298,7 +307,7 @@ EFI_STATUS IN UINTN DataSize, IN VOID *Data ); - + /** Get remove Bluetooth device configuration data. @@ -312,23 +321,23 @@ EFI_STATUS @retval EFI_SUCCESS The remote Bluetooth device configuration data is returned successfully. @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: - DataSize is NULL. - - *DataSize is 0. - - Data is NULL. + - *DataSize is not 0 and Data is NULL. @retval EFI_UNSUPPORTED The DataType is unsupported. @retval EFI_NOT_FOUND The DataType is not found. @retval EFI_BUFFER_TOO_SMALL The buffer is too small to hold the buffer. + *DataSize has been updated with the size needed to complete the request. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_GET_REMOTE_DATA)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This, IN EFI_BLUETOOTH_CONFIG_DATA_TYPE DataType, - IN BLUETOOTH_ADDRESS BDAddr, + IN BLUETOOTH_ADDRESS *BDAddr, IN OUT UINTN *DataSize, IN OUT VOID *Data ); - + /** The callback function for PIN code. @@ -337,14 +346,14 @@ EFI_STATUS @param CallbackType Callback type in EFI_BLUETOOTH_PIN_CALLBACK_TYPE. @param InputBuffer A pointer to the buffer of data that is input from callback caller. @param InputBufferSize Indicates the size, in bytes, of the data buffer specified by InputBuffer. - @param OutputBuffer A pointer to the buffer of data that will be output from callback callee. + @param OutputBuffer A pointer to the buffer of data that will be output from callback callee. Callee allocates this buffer by using EFI Boot Service AllocatePool(). @param OutputBufferSize Indicates the size, in bytes, of the data buffer specified by OutputBuffer. @retval EFI_SUCCESS The callback function complete successfully. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_PIN_CALLBACK_FUNCTION)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This, @@ -355,7 +364,7 @@ EFI_STATUS OUT VOID **OutputBuffer, OUT UINTN *OutputBufferSize ); - + /** Register PIN callback function. @@ -366,7 +375,7 @@ EFI_STATUS @retval EFI_SUCCESS The PIN callback function is registered successfully. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_PIN_CALLBACK)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This, @@ -385,7 +394,7 @@ EFI_STATUS @retval EFI_SUCCESS The callback function complete successfully. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_GET_LINK_KEY_CALLBACK_FUNCTION)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This, @@ -393,7 +402,7 @@ EFI_STATUS IN BLUETOOTH_ADDRESS *BDAddr, OUT UINT8 LinkKey[BLUETOOTH_HCI_LINK_KEY_SIZE] ); - + /** Register get link key callback function. @@ -404,14 +413,14 @@ EFI_STATUS @retval EFI_SUCCESS The link key callback function is registered successfully. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_GET_LINK_KEY_CALLBACK)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This, IN EFI_BLUETOOTH_CONFIG_REGISTER_GET_LINK_KEY_CALLBACK_FUNCTION Callback, IN VOID *Context ); - + /** The callback function to set link key. @@ -423,7 +432,7 @@ EFI_STATUS @retval EFI_SUCCESS The callback function complete successfully. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_SET_LINK_KEY_CALLBACK_FUNCTION)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This, @@ -431,7 +440,7 @@ EFI_STATUS IN BLUETOOTH_ADDRESS *BDAddr, IN UINT8 LinkKey[BLUETOOTH_HCI_LINK_KEY_SIZE] ); - + /** Register set link key callback function. @@ -442,14 +451,14 @@ EFI_STATUS @retval EFI_SUCCESS The link key callback function is registered successfully. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_SET_LINK_KEY_CALLBACK)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This, IN EFI_BLUETOOTH_CONFIG_REGISTER_SET_LINK_KEY_CALLBACK_FUNCTION Callback, IN VOID *Context ); - + /** The callback function. It is called after connect completed. @@ -463,7 +472,7 @@ EFI_STATUS @retval EFI_SUCCESS The callback function complete successfully. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_CONNECT_COMPLETE_CALLBACK_FUNCTION)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This, @@ -473,7 +482,7 @@ EFI_STATUS IN VOID *InputBuffer, IN UINTN InputBufferSize ); - + /** Register link connect complete callback function. @@ -484,14 +493,14 @@ EFI_STATUS @retval EFI_SUCCESS The link connect complete callback function is registered successfully. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_CONNECT_COMPLETE_CALLBACK)( IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This, IN EFI_BLUETOOTH_CONFIG_REGISTER_CONNECT_COMPLETE_CALLBACK_FUNCTION Callback, IN VOID *Context ); - + /// /// This protocol abstracts user interface configuration for Bluetooth device. /// diff --git a/MdePkg/Include/Protocol/BluetoothHc.h b/MdePkg/Include/Protocol/BluetoothHc.h index eb55079bb81c..9bcb777e7822 100644 --- a/MdePkg/Include/Protocol/BluetoothHc.h +++ b/MdePkg/Include/Protocol/BluetoothHc.h @@ -2,16 +2,10 @@ EFI Bluetooth Host Controller Protocol as defined in UEFI 2.5. This protocol abstracts the Bluetooth host controller layer message transmit and receive. - Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials are licensed and made available under - the terms and conditions of the BSD License that accompanies this distribution. - The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php. - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: + Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: This Protocol is introduced in UEFI Specification 2.5 **/ @@ -23,306 +17,402 @@ { \ 0xb3930571, 0xbeba, 0x4fc5, { 0x92, 0x3, 0x94, 0x27, 0x24, 0x2e, 0x6a, 0x43 } \ } - + typedef struct _EFI_BLUETOOTH_HC_PROTOCOL EFI_BLUETOOTH_HC_PROTOCOL; /** Send HCI command packet. - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. - On output, indicates the amount of data actually transferred. - @param Buffer A pointer to the buffer of data that will be transmitted to Bluetooth host - controller. - @param Timeout Indicating the transfer should be completed within this time frame. The units are - in milliseconds. If Timeout is 0, then the caller must wait for the function to - be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. - - @retval EFI_SUCCESS The HCI command packet is sent successfully. - @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: - - BufferSize is NULL. - - *BufferSize is 0. - - Buffer is NULL. - @retval EFI_TIMEOUT Sending HCI command packet fail due to timeout. - @retval EFI_DEVICE_ERROR Sending HCI command packet fail due to host controller or device error. + The SendCommand() function sends HCI command packet. Buffer holds the whole HCI + command packet, including OpCode, OCF, OGF, parameter length, and parameters. When + this function is returned, it just means the HCI command packet is sent, it does not mean + the command is success or complete. Caller might need to wait a command status event + to know the command status, or wait a command complete event to know if the + command is completed. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. + @param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer + specified by Buffer. On output, indicates the amount of + data actually transferred. + @param[in] Buffer A pointer to the buffer of data that will be transmitted to + Bluetooth host controller. + @param[in] Timeout Indicating the transfer should be completed within this + time frame. The units are in milliseconds. If Timeout is 0, + then the caller must wait for the function to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. + + @retval EFI_SUCCESS The HCI command packet is sent successfully. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + BufferSize is NULL. + *BufferSize is 0. + Buffer is NULL. + @retval EFI_TIMEOUT Sending HCI command packet fail due to timeout. + @retval EFI_DEVICE_ERROR Sending HCI command packet fail due to host controller or device + error. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_HC_SEND_COMMAND)( - IN EFI_BLUETOOTH_HC_PROTOCOL *This, - IN OUT UINTN *BufferSize, - IN VOID *Buffer, - IN UINTN Timeout + IN EFI_BLUETOOTH_HC_PROTOCOL *This, + IN OUT UINTN *BufferSize, + IN VOID *Buffer, + IN UINTN Timeout ); - /** Receive HCI event packet. - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. - On output, indicates the amount of data actually transferred. - @param Buffer A pointer to the buffer of data that will be received from Bluetooth host controller. - @param Timeout Indicating the transfer should be completed within this time frame. The units are - in milliseconds. If Timeout is 0, then the caller must wait for the function to - be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. - - @retval EFI_SUCCESS The HCI event packet is received successfully. - @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: - - BufferSize is NULL. - - *BufferSize is 0. - - Buffer is NULL. - @retval EFI_TIMEOUT Receiving HCI event packet fail due to timeout. - @retval EFI_DEVICE_ERROR Receiving HCI event packet fail due to host controller or device error. + The ReceiveEvent() function receives HCI event packet. Buffer holds the whole HCI event + packet, including EventCode, parameter length, and parameters. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. + @param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer + specified by Buffer. On output, indicates the amount of + data actually transferred. + @param[out] Buffer A pointer to the buffer of data that will be received from + Bluetooth host controller. + @param[in] Timeout Indicating the transfer should be completed within this + time frame. The units are in milliseconds. If Timeout is 0, + then the caller must wait for the function to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. + + @retval EFI_SUCCESS The HCI event packet is received successfully. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + BufferSize is NULL. + *BufferSize is 0. + Buffer is NULL. + @retval EFI_TIMEOUT Receiving HCI event packet fail due to timeout. + @retval EFI_DEVICE_ERROR Receiving HCI event packet fail due to host controller or device + error. **/ typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_EVENT)( - IN EFI_BLUETOOTH_HC_PROTOCOL *This, - IN OUT UINTN *BufferSize, - OUT VOID *Buffer, - IN UINTN Timeout + IN EFI_BLUETOOTH_HC_PROTOCOL *This, + IN OUT UINTN *BufferSize, + OUT VOID *Buffer, + IN UINTN Timeout ); - + /** - Callback function, it is called when asynchronous transfer is completed. + The async callback of AsyncReceiveEvent(). - @param Data Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param DataLength Specifies the length, in bytes, of the data to be received. - @param Context Data passed into Callback function. This is optional parameter and may be NULL. + @param[in] Data Data received via asynchronous transfer. + @param[in] DataLength The length of Data in bytes, received via asynchronous + transfer. + @param[in] Context Context passed from asynchronous transfer request. - @retval EFI_SUCCESS The callback function complete successfully. + @retval EFI_SUCCESS The callback does execute successfully. + @retval Others The callback doesn't execute successfully. **/ typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK) ( - IN VOID *Data, - IN UINTN DataLength, - IN VOID *Context + IN VOID *Data, + IN UINTN DataLength, + IN VOID *Context ); - + /** Receive HCI event packet in non-blocking way. - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the request is deleted. - @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be executed. - @param DataLength Specifies the length, in bytes, of the data to be received. - @param Callback The callback function. This function is called if the asynchronous transfer is - completed. - @param Context Data passed into Callback function. This is optional parameter and may be NULL. - - @retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully. - @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: - - DataLength is 0. - - If IsNewTransfer is TRUE, and an asynchronous receive request already exists. - + The AsyncReceiveEvent() function receives HCI event packet in non-blocking way. Data + in Callback function holds the whole HCI event packet, including EventCode, parameter + length, and parameters. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. + @param[in] IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the + request is deleted. + @param[in] PollingInterval Indicates the periodic rate, in milliseconds, that the + transfer is to be executed. + @param[in] DataLength Specifies the length, in bytes, of the data to be received. + @param[in] Callback The callback function. This function is called if the + asynchronous transfer is completed. + @param[in] Context Data passed into Callback function. This is optional + parameter and may be NULL. + + @retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + DataLength is 0. + If IsNewTransfer is TRUE, and an asynchronous receive + request already exists. **/ typedef EFI_STATUS -(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT)( - IN EFI_BLUETOOTH_HC_PROTOCOL *This, - IN BOOLEAN IsNewTransfer, - IN UINTN PollingInterval, - IN UINTN DataLength, - IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback, - IN VOID *Context +(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT) ( + IN EFI_BLUETOOTH_HC_PROTOCOL *This, + IN BOOLEAN IsNewTransfer, + IN UINTN PollingInterval, + IN UINTN DataLength, + IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback, + IN VOID *Context ); - + /** Send HCI ACL data packet. - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. - On output, indicates the amount of data actually transferred. - @param Buffer A pointer to the buffer of data that will be transmitted to Bluetooth host - controller. - @param Timeout Indicating the transfer should be completed within this time frame. The units are - in milliseconds. If Timeout is 0, then the caller must wait for the function to - be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. - - @retval EFI_SUCCESS The HCI ACL data packet is sent successfully. - @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: - - BufferSize is NULL. - - *BufferSize is 0. - - Buffer is NULL. - @retval EFI_TIMEOUT Sending HCI ACL data packet fail due to timeout. - @retval EFI_DEVICE_ERROR Sending HCI ACL data packet fail due to host controller or device error. + The SendACLData() function sends HCI ACL data packet. Buffer holds the whole HCI ACL + data packet, including Handle, PB flag, BC flag, data length, and data. + + The SendACLData() function and ReceiveACLData() function just send and receive data + payload from application layer. In order to protect the payload data, the Bluetooth bus is + required to call HCI_Set_Connection_Encryption command to enable hardware based + encryption after authentication completed, according to pairing mode and host + capability. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. + @param[in, out] BufferSize On input, indicates the size, in bytes, of the data buffer + specified by Buffer. On output, indicates the amount of + data actually transferred. + @param[in] Buffer A pointer to the buffer of data that will be transmitted to + Bluetooth host controller. + @param[in] Timeout Indicating the transfer should be completed within this + time frame. The units are in milliseconds. If Timeout is 0, + then the caller must wait for the function to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. + + @retval EFI_SUCCESS The HCI ACL data packet is sent successfully. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + BufferSize is NULL. + *BufferSize is 0. + Buffer is NULL. + @retval EFI_TIMEOUT Sending HCI ACL data packet fail due to timeout. + @retval EFI_DEVICE_ERROR Sending HCI ACL data packet fail due to host controller or device + error. **/ typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_HC_SEND_ACL_DATA)( - IN EFI_BLUETOOTH_HC_PROTOCOL *This, - IN OUT UINTN *BufferSize, - IN VOID *Buffer, - IN UINTN Timeout + IN EFI_BLUETOOTH_HC_PROTOCOL *This, + IN OUT UINTN *BufferSize, + IN VOID *Buffer, + IN UINTN Timeout ); - + /** Receive HCI ACL data packet. - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. - On output, indicates the amount of data actually transferred. - @param Buffer A pointer to the buffer of data that will be received from Bluetooth host controller. - @param Timeout Indicating the transfer should be completed within this time frame. The units are - in milliseconds. If Timeout is 0, then the caller must wait for the function to - be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. - - @retval EFI_SUCCESS The HCI ACL data packet is received successfully. - @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: - - BufferSize is NULL. - - *BufferSize is 0. - - Buffer is NULL. - @retval EFI_TIMEOUT Receiving HCI ACL data packet fail due to timeout. - @retval EFI_DEVICE_ERROR Receiving HCI ACL data packet fail due to host controller or device error. + The ReceiveACLData() function receives HCI ACL data packet. Buffer holds the whole HCI + ACL data packet, including Handle, PB flag, BC flag, data length, and data. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. + @param[in, out] BufferSize On input, indicates the size, in bytes, of the data buffer + specified by Buffer. On output, indicates the amount of + data actually transferred. + @param[out] Buffer A pointer to the buffer of data that will be received from + Bluetooth host controller. + @param[in] Timeout Indicating the transfer should be completed within this + time frame. The units are in milliseconds. If Timeout is 0, + then the caller must wait for the function to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. + + @retval EFI_SUCCESS The HCI ACL data packet is received successfully. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + BufferSize is NULL. + *BufferSize is 0. + Buffer is NULL. + @retval EFI_TIMEOUT Receiving HCI ACL data packet fail due to timeout. + @retval EFI_DEVICE_ERROR Receiving HCI ACL data packet fail due to host controller or device + error. **/ typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA)( - IN EFI_BLUETOOTH_HC_PROTOCOL *This, - IN OUT UINTN *BufferSize, - OUT VOID *Buffer, - IN UINTN Timeout + IN EFI_BLUETOOTH_HC_PROTOCOL *This, + IN OUT UINTN *BufferSize, + OUT VOID *Buffer, + IN UINTN Timeout ); - /** Receive HCI ACL data packet in non-blocking way. - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the request is deleted. - @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be executed. - @param DataLength Specifies the length, in bytes, of the data to be received. - @param Callback The callback function. This function is called if the asynchronous transfer is - completed. - @param Context Data passed into Callback function. This is optional parameter and may be NULL. - - @retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully. - @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: - - DataLength is 0. - - If IsNewTransfer is TRUE, and an asynchronous receive request already exists. - + The AsyncReceiveACLData() function receives HCI ACL data packet in non-blocking way. + Data in Callback holds the whole HCI ACL data packet, including Handle, PB flag, BC flag, + data length, and data. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. + @param[in] IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the + request is deleted. + @param[in] PollingInterval Indicates the periodic rate, in milliseconds, that the + transfer is to be executed. + @param[in] DataLength Specifies the length, in bytes, of the data to be received. + @param[in] Callback The callback function. This function is called if the + asynchronous transfer is completed. + @param[in] Context Data passed into Callback function. This is optional + parameter and may be NULL. + + @retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + DataLength is 0. + If IsNewTransfer is TRUE, and an asynchronous receive + request already exists. **/ typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA) ( - IN EFI_BLUETOOTH_HC_PROTOCOL *This, - IN BOOLEAN IsNewTransfer, - IN UINTN PollingInterval, - IN UINTN DataLength, - IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback, - IN VOID *Context + IN EFI_BLUETOOTH_HC_PROTOCOL *This, + IN BOOLEAN IsNewTransfer, + IN UINTN PollingInterval, + IN UINTN DataLength, + IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback, + IN VOID *Context ); - + /** Send HCI SCO data packet. - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. - On output, indicates the amount of data actually transferred. - @param Buffer A pointer to the buffer of data that will be transmitted to Bluetooth host - controller. - @param Timeout Indicating the transfer should be completed within this time frame. The units are - in milliseconds. If Timeout is 0, then the caller must wait for the function to - be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. - - @retval EFI_SUCCESS The HCI SCO data packet is sent successfully. - @retval EFI_UNSUPPORTED The implementation does not support HCI SCO transfer. - @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: - - BufferSize is NULL. - - *BufferSize is 0. - - Buffer is NULL. - @retval EFI_TIMEOUT Sending HCI SCO data packet fail due to timeout. - @retval EFI_DEVICE_ERROR Sending HCI SCO data packet fail due to host controller or device error. - + The SendSCOData() function sends HCI SCO data packet. Buffer holds the whole HCI SCO + data packet, including ConnectionHandle, PacketStatus flag, data length, and data. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. + @param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer + specified by Buffer. On output, indicates the amount of + data actually transferred. + @param[in] Buffer A pointer to the buffer of data that will be transmitted to + Bluetooth host controller. + @param[in] Timeout Indicating the transfer should be completed within this + time frame. The units are in milliseconds. If Timeout is 0, + then the caller must wait for the function to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. + + @retval EFI_SUCCESS The HCI SCO data packet is sent successfully. + @retval EFI_UNSUPPORTED The implementation does not support HCI SCO transfer. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + BufferSize is NULL. + *BufferSize is 0. + Buffer is NULL. + @retval EFI_TIMEOUT Sending HCI SCO data packet fail due to timeout. + @retval EFI_DEVICE_ERROR Sending HCI SCO data packet fail due to host controller or device + error. **/ typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_HC_SEND_SCO_DATA)( - IN EFI_BLUETOOTH_HC_PROTOCOL *This, - IN OUT UINTN *BufferSize, - IN VOID *Buffer, - IN UINTN Timeout + IN EFI_BLUETOOTH_HC_PROTOCOL *This, + IN OUT UINTN *BufferSize, + IN VOID *Buffer, + IN UINTN Timeout ); - + /** Receive HCI SCO data packet. - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. - On output, indicates the amount of data actually transferred. - @param Buffer A pointer to the buffer of data that will be received from Bluetooth host controller. - @param Timeout Indicating the transfer should be completed within this time frame. The units are - in milliseconds. If Timeout is 0, then the caller must wait for the function to - be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. - - @retval EFI_SUCCESS The HCI SCO data packet is received successfully. - @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: - - BufferSize is NULL. - - *BufferSize is 0. - - Buffer is NULL. - @retval EFI_TIMEOUT Receiving HCI SCO data packet fail due to timeout - @retval EFI_DEVICE_ERROR Receiving HCI SCO data packet fail due to host controller or device error. - + The ReceiveSCOData() function receives HCI SCO data packet. Buffer holds the whole HCI + SCO data packet, including ConnectionHandle, PacketStatus flag, data length, and data. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. + @param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer + specified by Buffer. On output, indicates the amount of + data actually transferred. + @param[out] Buffer A pointer to the buffer of data that will be received from + Bluetooth host controller. + @param[in] Timeout Indicating the transfer should be completed within this + time frame. The units are in milliseconds. If Timeout is 0, + then the caller must wait for the function to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. + + @retval EFI_SUCCESS The HCI SCO data packet is received successfully. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + BufferSize is NULL. + *BufferSize is 0. + Buffer is NULL. + @retval EFI_TIMEOUT Receiving HCI SCO data packet fail due to timeout. + @retval EFI_DEVICE_ERROR Receiving HCI SCO data packet fail due to host controller or device + error. **/ typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA)( - IN EFI_BLUETOOTH_HC_PROTOCOL *This, - IN OUT UINTN *BufferSize, - OUT VOID *Buffer, - IN UINTN Timeout + IN EFI_BLUETOOTH_HC_PROTOCOL *This, + IN OUT UINTN *BufferSize, + OUT VOID *Buffer, + IN UINTN Timeout ); /** Receive HCI SCO data packet in non-blocking way. - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the request is deleted. - @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be executed. - @param DataLength Specifies the length, in bytes, of the data to be received. - @param Callback The callback function. This function is called if the asynchronous transfer is - completed. - @param Context Data passed into Callback function. This is optional parameter and may be NULL. - - @retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully. - @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: - - DataLength is 0. - - If IsNewTransfer is TRUE, and an asynchronous receive request already exists. - + The AsyncReceiveSCOData() function receives HCI SCO data packet in non-blocking way. + Data in Callback holds the whole HCI SCO data packet, including ConnectionHandle, + PacketStatus flag, data length, and data. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. + @param[in] IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the + request is deleted. + @param[in] PollingInterval Indicates the periodic rate, in milliseconds, that the + transfer is to be executed. + @param[in] DataLength Specifies the length, in bytes, of the data to be received. + @param[in] Callback The callback function. This function is called if the + asynchronous transfer is completed. + @param[in] Context Data passed into Callback function. This is optional + parameter and may be NULL. + + @retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + DataLength is 0. + If IsNewTransfer is TRUE, and an asynchronous receive + request already exists. **/ typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA) ( - IN EFI_BLUETOOTH_HC_PROTOCOL *This, - IN BOOLEAN IsNewTransfer, - IN UINTN PollingInterval, - IN UINTN DataLength, - IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback, - IN VOID *Context + IN EFI_BLUETOOTH_HC_PROTOCOL *This, + IN BOOLEAN IsNewTransfer, + IN UINTN PollingInterval, + IN UINTN DataLength, + IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback, + IN VOID *Context ); - -/// -/// This protocol abstracts the Bluetooth host controller layer message transmit and receive. -/// + +// +// The EFI_BLUETOOTH_HC_PROTOCOL is used to transmit or receive HCI layer data packets. +// struct _EFI_BLUETOOTH_HC_PROTOCOL { + // + // Send HCI command packet. + // EFI_BLUETOOTH_HC_SEND_COMMAND SendCommand; + // + // Receive HCI event packets. + // EFI_BLUETOOTH_HC_RECEIVE_EVENT ReceiveEvent; + // + // Non-blocking receive HCI event packets. + // EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT AsyncReceiveEvent; + // + // Send HCI ACL (asynchronous connection-oriented) data packets. + // EFI_BLUETOOTH_HC_SEND_ACL_DATA SendACLData; + // + // Receive HCI ACL data packets. + // EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA ReceiveACLData; + // + // Non-blocking receive HCI ACL data packets. + // EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA AsyncReceiveACLData; + // + // Send HCI synchronous (SCO and eSCO) data packets. + // EFI_BLUETOOTH_HC_SEND_SCO_DATA SendSCOData; + // + // Receive HCI synchronous data packets. + // EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA ReceiveSCOData; + // + // Non-blocking receive HCI synchronous data packets. + // EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA AsyncReceiveSCOData; }; - + extern EFI_GUID gEfiBluetoothHcProtocolGuid; #endif + diff --git a/MdePkg/Include/Protocol/BluetoothIo.h b/MdePkg/Include/Protocol/BluetoothIo.h index 652de57a95d6..6530d8e10421 100644 --- a/MdePkg/Include/Protocol/BluetoothIo.h +++ b/MdePkg/Include/Protocol/BluetoothIo.h @@ -1,19 +1,13 @@ /** @file EFI Bluetooth IO Service Binding Protocol as defined in UEFI 2.5. EFI Bluetooth IO Protocol as defined in UEFI 2.5. - The EFI Bluetooth IO Service Binding Protocol is used to locate EFI Bluetooth IO Protocol drivers to + The EFI Bluetooth IO Service Binding Protocol is used to locate EFI Bluetooth IO Protocol drivers to create and destroy child of the driver to communicate with other Bluetooth device by using Bluetooth IO protocol. - Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials are licensed and made available under - the terms and conditions of the BSD License that accompanies this distribution. - The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php. - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2015 - 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent - @par Revision Reference: + @par Revision Reference: This Protocol is introduced in UEFI Specification 2.5 **/ @@ -25,14 +19,14 @@ #define EFI_BLUETOOTH_IO_SERVICE_BINDING_PROTOCOL_GUID \ { \ - 0x388278d3, 0x7b85, 0x42f0, { 0xab, 0xa9, 0xfb, 0x4b, 0xfd, 0x69, 0xf5, 0xab } \ + 0x388278d3, 0x7b85, 0x42f0, { 0xab, 0xa9, 0xfb, 0x4b, 0xfd, 0x69, 0xf5, 0xab } \ } - + #define EFI_BLUETOOTH_IO_PROTOCOL_GUID \ { \ - 0x467313de, 0x4e30, 0x43f1, { 0x94, 0x3e, 0x32, 0x3f, 0x89, 0x84, 0x5d, 0xb5 } \ + 0x467313de, 0x4e30, 0x43f1, { 0x94, 0x3e, 0x32, 0x3f, 0x89, 0x84, 0x5d, 0xb5 } \ } - + typedef struct _EFI_BLUETOOTH_IO_PROTOCOL EFI_BLUETOOTH_IO_PROTOCOL; /// @@ -72,51 +66,51 @@ typedef struct { /** Get Bluetooth device information. - @param This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. - @param DeviceInfoSize A pointer to the size, in bytes, of the DeviceInfo buffer. - @param DeviceInfo A pointer to a callee allocated buffer that returns Bluetooth device information. + @param[in] This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. + @param[out] DeviceInfoSize A pointer to the size, in bytes, of the DeviceInfo buffer. + @param[out] DeviceInfo A pointer to a callee allocated buffer that returns Bluetooth device information. - @retval EFI_SUCCESS The Bluetooth device information is returned successfully. - @retval EFI_DEVICE_ERROR A hardware error occurred trying to retrieve the Bluetooth device information. + @retval EFI_SUCCESS The Bluetooth device information is returned successfully. + @retval EFI_DEVICE_ERROR A hardware error occurred trying to retrieve the Bluetooth device information. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_IO_GET_DEVICE_INFO)( - IN EFI_BLUETOOTH_IO_PROTOCOL *This, - OUT UINTN *DeviceInfoSize, - OUT VOID **DeviceInfo + IN EFI_BLUETOOTH_IO_PROTOCOL *This, + OUT UINTN *DeviceInfoSize, + OUT VOID **DeviceInfo ); - + /** Get Bluetooth SDP information. - @param This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. - @param SdpInfoSize A pointer to the size, in bytes, of the SdpInfo buffer. - @param SdpInfo A pointer to a callee allocated buffer that returns Bluetooth SDP information. + @param[in] This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. + @param[out] SdpInfoSize A pointer to the size, in bytes, of the SdpInfo buffer. + @param[out] SdpInfo A pointer to a callee allocated buffer that returns Bluetooth SDP information. - @retval EFI_SUCCESS The Bluetooth device information is returned successfully. - @retval EFI_DEVICE_ERROR A hardware error occurred trying to retrieve the Bluetooth SDP information. + @retval EFI_SUCCESS The Bluetooth device information is returned successfully. + @retval EFI_DEVICE_ERROR A hardware error occurred trying to retrieve the Bluetooth SDP information. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_IO_GET_SDP_INFO)( - IN EFI_BLUETOOTH_IO_PROTOCOL *This, - OUT UINTN *SdpInfoSize, - OUT VOID **SdpInfo + IN EFI_BLUETOOTH_IO_PROTOCOL *This, + OUT UINTN *SdpInfoSize, + OUT VOID **SdpInfo ); - + /** Send L2CAP message (including L2CAP header). - @param This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. - @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. - On output, indicates the amount of data actually transferred. - @param Buffer A pointer to the buffer of data that will be transmitted to Bluetooth L2CAP layer. - @param Timeout Indicating the transfer should be completed within this time frame. The units are in - milliseconds. If Timeout is 0, then the caller must wait for the function to be completed - until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. + @param[in] This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. + @param[in, out] BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. + On output, indicates the amount of data actually transferred. + @param[in] Buffer A pointer to the buffer of data that will be transmitted to Bluetooth L2CAP layer. + @param[in] Timeout Indicating the transfer should be completed within this time frame. The units are in + milliseconds. If Timeout is 0, then the caller must wait for the function to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. @retval EFI_SUCCESS The L2CAP message is sent successfully. @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: @@ -127,25 +121,25 @@ EFI_STATUS @retval EFI_DEVICE_ERROR Sending L2CAP message fail due to host controller or device error. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_RAW_SEND)( - IN EFI_BLUETOOTH_IO_PROTOCOL *This, - IN OUT UINTN *BufferSize, - IN VOID *Buffer, - IN UINTN Timeout + IN EFI_BLUETOOTH_IO_PROTOCOL *This, + IN OUT UINTN *BufferSize, + IN VOID *Buffer, + IN UINTN Timeout ); - + /** Receive L2CAP message (including L2CAP header). - @param This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. - @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. - On output, indicates the amount of data actually transferred. - @param Buffer A pointer to the buffer of data that will be received from Bluetooth L2CAP layer. - @param Timeout Indicating the transfer should be completed within this time frame. The units are in - milliseconds. If Timeout is 0, then the caller must wait for the function to be completed - until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. + @param[in] This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. + @param[in] BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. + On output, indicates the amount of data actually transferred. + @param[out] Buffer A pointer to the buffer of data that will be received from Bluetooth L2CAP layer. + @param[in] Timeout Indicating the transfer should be completed within this time frame. The units are in + milliseconds. If Timeout is 0, then the caller must wait for the function to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. @retval EFI_SUCCESS The L2CAP message is received successfully. @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: @@ -156,7 +150,7 @@ EFI_STATUS @retval EFI_DEVICE_ERROR Receiving L2CAP message fail due to host controller or device error. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_RAW_RECEIVE)( IN EFI_BLUETOOTH_IO_PROTOCOL *This, @@ -164,16 +158,16 @@ EFI_STATUS OUT VOID *Buffer, IN UINTN Timeout ); - + /** Callback function, it is called when asynchronous transfer is completed. - @param ChannelID Bluetooth L2CAP message channel ID. - @param Data Data received via asynchronous transfer. - @param DataLength The length of Data in bytes, received via asynchronous transfer. - @param Context Context passed from asynchronous transfer request. + @param[in] ChannelID Bluetooth L2CAP message channel ID. + @param[in] Data Data received via asynchronous transfer. + @param[in] DataLength The length of Data in bytes, received via asynchronous transfer. + @param[in] Context Context passed from asynchronous transfer request. - @retval EFI_SUCCESS The callback function complete successfully. + @retval EFI_SUCCESS The callback function complete successfully. **/ typedef @@ -184,25 +178,25 @@ EFI_STATUS IN UINTN DataLength, IN VOID *Context ); - + /** Receive L2CAP message (including L2CAP header) in non-blocking way. - @param This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. - @param IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the request is deleted. - @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be executed. - @param DataLength Specifies the length, in bytes, of the data to be received. - @param Callback The callback function. This function is called if the asynchronous transfer is - completed. - @param Context Data passed into Callback function. This is optional parameter and may be NULL. - + @param[in] This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. + @param[in] IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the request is deleted. + @param[in] PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be executed. + @param[in] DataLength Specifies the length, in bytes, of the data to be received. + @param[in] Callback The callback function. This function is called if the asynchronous transfer is + completed. + @param[in] Context Data passed into Callback function. This is optional parameter and may be NULL. + @retval EFI_SUCCESS The L2CAP asynchronous receive request is submitted successfully. @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: - DataLength is 0. - If IsNewTransfer is TRUE, and an asynchronous receive request already exists. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_RAW_ASYNC_RECEIVE)( IN EFI_BLUETOOTH_IO_PROTOCOL *This, @@ -216,14 +210,14 @@ EFI_STATUS /** Send L2CAP message (excluding L2CAP header) to a specific channel. - @param This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. - @param Handle A handle created by EFI_BLUETOOTH_IO_PROTOCOL.L2CapConnect indicates which channel to send. - @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. - On output, indicates the amount of data actually transferred. - @param Buffer A pointer to the buffer of data that will be transmitted to Bluetooth L2CAP layer. - @param Timeout Indicating the transfer should be completed within this time frame. The units are in - milliseconds. If Timeout is 0, then the caller must wait for the function to be completed - until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. + @param[in] This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. + @param[in] Handle A handle created by EFI_BLUETOOTH_IO_PROTOCOL.L2CapConnect indicates which channel to send. + @param[in, out] BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. + On output, indicates the amount of data actually transferred. + @param[in] Buffer A pointer to the buffer of data that will be transmitted to Bluetooth L2CAP layer. + @param[in] Timeout Indicating the transfer should be completed within this time frame. The units are in + milliseconds. If Timeout is 0, then the caller must wait for the function to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. @retval EFI_SUCCESS The L2CAP message is sent successfully. @retval EFI_NOT_FOUND Handle is invalid or not found. @@ -235,26 +229,26 @@ EFI_STATUS @retval EFI_DEVICE_ERROR Sending L2CAP message fail due to host controller or device error. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_SEND)( - IN EFI_BLUETOOTH_IO_PROTOCOL *This, - IN EFI_HANDLE Handle, - IN OUT UINTN *BufferSize, - IN VOID *Buffer, - IN UINTN Timeout + IN EFI_BLUETOOTH_IO_PROTOCOL *This, + IN EFI_HANDLE Handle, + IN OUT UINTN *BufferSize, + IN VOID *Buffer, + IN UINTN Timeout ); - + /** Receive L2CAP message (excluding L2CAP header) from a specific channel. - @param This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. - @param Handle A handle created by EFI_BLUETOOTH_IO_PROTOCOL.L2CapConnect indicates which channel to receive. - @param BufferSize Indicates the size, in bytes, of the data buffer specified by Buffer. - @param Buffer A pointer to the buffer of data that will be received from Bluetooth L2CAP layer. - @param Timeout Indicating the transfer should be completed within this time frame. The units are in - milliseconds. If Timeout is 0, then the caller must wait for the function to be completed - until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. + @param[in] This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. + @param[in] Handle A handle created by EFI_BLUETOOTH_IO_PROTOCOL.L2CapConnect indicates which channel to receive. + @param[out] BufferSize Indicates the size, in bytes, of the data buffer specified by Buffer. + @param[out] Buffer A pointer to the buffer of data that will be received from Bluetooth L2CAP layer. + @param[in] Timeout Indicating the transfer should be completed within this time frame. The units are in + milliseconds. If Timeout is 0, then the caller must wait for the function to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. @retval EFI_SUCCESS The L2CAP message is received successfully. @retval EFI_NOT_FOUND Handle is invalid or not found. @@ -266,22 +260,22 @@ EFI_STATUS @retval EFI_DEVICE_ERROR Receiving L2CAP message fail due to host controller or device error. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_RECEIVE)( - IN EFI_BLUETOOTH_IO_PROTOCOL *This, - IN EFI_HANDLE Handle, - OUT UINTN *BufferSize, - OUT VOID **Buffer, - IN UINTN Timeout + IN EFI_BLUETOOTH_IO_PROTOCOL *This, + IN EFI_HANDLE Handle, + OUT UINTN *BufferSize, + OUT VOID **Buffer, + IN UINTN Timeout ); - + /** Callback function, it is called when asynchronous transfer is completed. - @param Data Data received via asynchronous transfer. - @param DataLength The length of Data in bytes, received via asynchronous transfer. - @param Context Context passed from asynchronous transfer request. + @param[in] Data Data received via asynchronous transfer. + @param[in] DataLength The length of Data in bytes, received via asynchronous transfer. + @param[in] Context Context passed from asynchronous transfer request. @retval EFI_SUCCESS The callback function complete successfully. @@ -289,20 +283,21 @@ EFI_STATUS typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_IO_CHANNEL_SERVICE_CALLBACK) ( - IN VOID *Data, - IN UINTN DataLength, - IN VOID *Context + IN VOID *Data, + IN UINTN DataLength, + IN VOID *Context ); - + /** Receive L2CAP message (excluding L2CAP header) in non-blocking way from a specific channel. - @param This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. - @param Handel A handle created by EFI_BLUETOOTH_IO_PROTOCOL.L2CapConnect indicates which channel to receive. - @param Callback The callback function. This function is called if the asynchronous transfer is - completed. - @param Context Data passed into Callback function. This is optional parameter and may be NULL. - + @param[in] This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. + @param[in] Handel A handle created by EFI_BLUETOOTH_IO_PROTOCOL.L2CapConnect indicates which channel + to receive. + @param[in] Callback The callback function. This function is called if the asynchronous transfer is + completed. + @param[in] Context Data passed into Callback function. This is optional parameter and may be NULL. + @retval EFI_SUCCESS The L2CAP asynchronous receive request is submitted successfully. @retval EFI_NOT_FOUND Handle is invalid or not found. @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: @@ -310,33 +305,33 @@ EFI_STATUS - If an asynchronous receive request already exists on same Handle. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_ASYNC_RECEIVE)( - IN EFI_BLUETOOTH_IO_PROTOCOL *This, - IN EFI_HANDLE Handle, - IN EFI_BLUETOOTH_IO_CHANNEL_SERVICE_CALLBACK Callback, - IN VOID *Context + IN EFI_BLUETOOTH_IO_PROTOCOL *This, + IN EFI_HANDLE Handle, + IN EFI_BLUETOOTH_IO_CHANNEL_SERVICE_CALLBACK Callback, + IN VOID* Context ); - + /** Do L2CAP connection. - @param This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. - @param Handel A handle to indicate this L2CAP connection. - @param Psm Bluetooth PSM. See Bluetooth specification for detail. - @param Mtu Bluetooth MTU. See Bluetooth specification for detail. - @param Callback The callback function. This function is called whenever there is message received - in this channel. - @param Context Data passed into Callback function. This is optional parameter and may be NULL. - + @param[in] This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. + @param[out] Handel A handle to indicate this L2CAP connection. + @param[in] Psm Bluetooth PSM. See Bluetooth specification for detail. + @param[in] Mtu Bluetooth MTU. See Bluetooth specification for detail. + @param[in] Callback The callback function. This function is called whenever there is message received + in this channel. + @param[in] Context Data passed into Callback function. This is optional parameter and may be NULL. + @retval EFI_SUCCESS The Bluetooth L2CAP layer connection is created successfully. @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: - Handle is NULL. @retval EFI_DEVICE_ERROR A hardware error occurred trying to do Bluetooth L2CAP connection. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_CONNECT)( IN EFI_BLUETOOTH_IO_PROTOCOL *This, @@ -346,42 +341,42 @@ EFI_STATUS IN EFI_BLUETOOTH_IO_CHANNEL_SERVICE_CALLBACK Callback, IN VOID *Context ); - + /** Do L2CAP disconnection. - @param This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. - @param Handel A handle to indicate this L2CAP connection. - + @param[in] This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. + @param[in] Handel A handle to indicate this L2CAP connection. + @retval EFI_SUCCESS The Bluetooth L2CAP layer is disconnected successfully. @retval EFI_NOT_FOUND Handle is invalid or not found. @retval EFI_DEVICE_ERROR A hardware error occurred trying to do Bluetooth L2CAP disconnection. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_DISCONNECT)( IN EFI_BLUETOOTH_IO_PROTOCOL *This, IN EFI_HANDLE Handle ); - + /** Register L2CAP callback function for special channel. - @param This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. - @param Handel A handle to indicate this L2CAP connection. - @param Psm Bluetooth PSM. See Bluetooth specification for detail. - @param Mtu Bluetooth MTU. See Bluetooth specification for detail. - @param Callback The callback function. This function is called whenever there is message received - in this channel. NULL means unregister. - @param Context Data passed into Callback function. This is optional parameter and may be NULL. - + @param[in] This Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance. + @param[out] Handel A handle to indicate this L2CAP connection. + @param[in] Psm Bluetooth PSM. See Bluetooth specification for detail. + @param[in] Mtu Bluetooth MTU. See Bluetooth specification for detail. + @param[in] Callback The callback function. This function is called whenever there is message received + in this channel. NULL means unregister. + @param[in] Context Data passed into Callback function. This is optional parameter and may be NULL. + @retval EFI_SUCCESS The Bluetooth L2CAP callback function is registered successfully. @retval EFI_ALREADY_STARTED The callback function already exists when register. @retval EFI_NOT_FOUND The callback function does not exist when unregister. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_REGISTER_SERVICE)( IN EFI_BLUETOOTH_IO_PROTOCOL *This, @@ -391,9 +386,9 @@ EFI_STATUS IN EFI_BLUETOOTH_IO_CHANNEL_SERVICE_CALLBACK Callback, IN VOID *Context ); - + /// -/// This protocol provides service for Bluetooth L2CAP (Logical Link Control and Adaptation Protocol) +/// This protocol provides service for Bluetooth L2CAP (Logical Link Control and Adaptation Protocol) /// and SDP (Service Discovery Protocol). /// struct _EFI_BLUETOOTH_IO_PROTOCOL { diff --git a/MdePkg/Include/Protocol/BluetoothLeConfig.h b/MdePkg/Include/Protocol/BluetoothLeConfig.h new file mode 100644 index 000000000000..eb92015d9ca0 --- /dev/null +++ b/MdePkg/Include/Protocol/BluetoothLeConfig.h @@ -0,0 +1,630 @@ +/** @file + EFI Bluetooth LE Config Protocol as defined in UEFI 2.7. + This protocol abstracts user interface configuration for BluetoothLe device. + + Copyright (c) 2017 - 2019, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol is introduced in UEFI Specification 2.7 + +**/ + +#ifndef __EFI_BLUETOOTH_LE_CONFIG_H__ +#define __EFI_BLUETOOTH_LE_CONFIG_H__ + +#include <Protocol/BluetoothConfig.h> +#include <Protocol/BluetoothAttribute.h> + +#define EFI_BLUETOOTH_LE_CONFIG_PROTOCOL_GUID \ + { \ + 0x8f76da58, 0x1f99, 0x4275, { 0xa4, 0xec, 0x47, 0x56, 0x51, 0x5b, 0x1c, 0xe8 } \ + } + +typedef struct _EFI_BLUETOOTH_LE_CONFIG_PROTOCOL EFI_BLUETOOTH_LE_CONFIG_PROTOCOL; + +/** + Initialize BluetoothLE host controller and local device. + + The Init() function initializes BluetoothLE host controller and local device. + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + + @retval EFI_SUCCESS The BluetoothLE host controller and local device is initialized successfully. + @retval EFI_DEVICE_ERROR A hardware error occurred trying to initialize the BluetoothLE host controller + and local device. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_INIT)( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This + ); + +typedef struct { + /// + /// The version of the structure. A value of zero represents the EFI_BLUETOOTH_LE_CONFIG_SCAN_PARAMETER + /// structure as defined here. Future version of this specification may extend this data structure in a + /// backward compatible way and increase the value of Version. + /// + UINT32 Version; + /// + /// Passive scanning or active scanning. See Bluetooth specification. + /// + UINT8 ScanType; + /// + /// Recommended scan interval to be used while performing scan. + /// + UINT16 ScanInterval; + /// + /// Recommended scan window to be used while performing a scan. + /// + UINT16 ScanWindow; + /// + /// Recommended scanning filter policy to be used while performing a scan. + /// + UINT8 ScanningFilterPolicy; + /// + /// This is one byte flag to serve as a filter to remove unneeded scan + /// result. For example, set BIT0 means scan in LE Limited Discoverable + /// Mode. Set BIT1 means scan in LE General Discoverable Mode. + /// + UINT8 AdvertisementFlagFilter; +} EFI_BLUETOOTH_LE_CONFIG_SCAN_PARAMETER; + +typedef struct{ + BLUETOOTH_LE_ADDRESS BDAddr; + BLUETOOTH_LE_ADDRESS DirectAddress; + UINT8 RemoteDeviceState; + INT8 RSSI; + UINTN AdvertisementDataSize; + VOID *AdvertisementData; +} EFI_BLUETOOTH_LE_SCAN_CALLBACK_INFORMATION; + +/** + Callback function, it is called if a BluetoothLE device is found during scan process. + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] Context Context passed from scan request. + @param[in] CallbackInfo Data related to scan result. NULL CallbackInfo means scan complete. + + @retval EFI_SUCCESS The callback function complete successfully. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_SCAN_CALLBACK_FUNCTION) ( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN VOID *Context, + IN EFI_BLUETOOTH_LE_SCAN_CALLBACK_INFORMATION *CallbackInfo + ); + +/** + Scan BluetoothLE device. + + The Scan() function scans BluetoothLE device. When this function is returned, it just means scan + request is submitted. It does not mean scan process is started or finished. Whenever there is a + BluetoothLE device is found, the Callback function will be called. Callback function might be + called before this function returns or after this function returns + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] ReScan If TRUE, a new scan request is submitted no matter there is scan result before. + If FALSE and there is scan result, the previous scan result is returned and no scan request + is submitted. + @param[in] Timeout Duration in milliseconds for which to scan. + @param[in] ScanParameter If it is not NULL, the ScanParameter is used to perform a scan by the BluetoothLE bus driver. + If it is NULL, the default parameter is used. + @param[in] Callback The callback function. This function is called if a BluetoothLE device is found during + scan process. + @param[in] Context Data passed into Callback function. This is optional parameter and may be NULL. + + @retval EFI_SUCCESS The Bluetooth scan request is submitted. + @retval EFI_DEVICE_ERROR A hardware error occurred trying to scan the BluetoothLE device. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_SCAN)( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN BOOLEAN ReScan, + IN UINT32 Timeout, + IN EFI_BLUETOOTH_LE_CONFIG_SCAN_PARAMETER *ScanParameter, OPTIONAL + IN EFI_BLUETOOTH_LE_CONFIG_SCAN_CALLBACK_FUNCTION Callback, + IN VOID *Context + ); + +typedef struct { + /// + /// The version of the structure. A value of zero represents the + /// EFI_BLUETOOTH_LE_CONFIG_CONNECT_PARAMETER + /// structure as defined here. Future version of this specification may + /// extend this data structure in a backward compatible way and + /// increase the value of Version. + /// + UINT32 Version; + /// + /// Recommended scan interval to be used while performing scan before connect. + /// + UINT16 ScanInterval; + /// + /// Recommended scan window to be used while performing a connection + /// + UINT16 ScanWindow; + /// + /// Minimum allowed connection interval. Shall be less than or equal to ConnIntervalMax. + /// + UINT16 ConnIntervalMin; + /// + /// Maximum allowed connection interval. Shall be greater than or equal to ConnIntervalMin. + /// + UINT16 ConnIntervalMax; + /// + /// Slave latency for the connection in number of connection events. + /// + UINT16 ConnLatency; + /// + /// Link supervision timeout for the connection. + /// + UINT16 SupervisionTimeout; +} EFI_BLUETOOTH_LE_CONFIG_CONNECT_PARAMETER; + +/** + Connect a BluetoothLE device. + + The Connect() function connects a Bluetooth device. When this function is returned successfully, + a new EFI_BLUETOOTH_IO_PROTOCOL is created. + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] AutoReconnect If TRUE, the BluetoothLE host controller needs to do an auto + reconnect. If FALSE, the BluetoothLE host controller does not do + an auto reconnect. + @param[in] DoBonding If TRUE, the BluetoothLE host controller needs to do a bonding. + If FALSE, the BluetoothLE host controller does not do a bonding. + @param[in] ConnectParameter If it is not NULL, the ConnectParameter is used to perform a + scan by the BluetoothLE bus driver. If it is NULL, the default + parameter is used. + @param[in] BD_ADDR The address of the BluetoothLE device to be connected. + + @retval EFI_SUCCESS The BluetoothLE device is connected successfully. + @retval EFI_ALREADY_STARTED The BluetoothLE device is already connected. + @retval EFI_NOT_FOUND The BluetoothLE device is not found. + @retval EFI_DEVICE_ERROR A hardware error occurred trying to connect the BluetoothLE device. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_CONNECT)( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN BOOLEAN AutoReconnect, + IN BOOLEAN DoBonding, + IN EFI_BLUETOOTH_LE_CONFIG_CONNECT_PARAMETER *ConnectParameter, OPTIONAL + IN BLUETOOTH_LE_ADDRESS *BD_ADDR + ); + +/** + Disconnect a BluetoothLE device. + + The Disconnect() function disconnects a BluetoothLE device. When this function is returned + successfully, the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL associated with this device is + destroyed and all services associated are stopped. + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] BD_ADDR The address of BluetoothLE device to be connected. + @param[in] Reason Bluetooth disconnect reason. See Bluetooth specification for detail. + + @retval EFI_SUCCESS The BluetoothLE device is disconnected successfully. + @retval EFI_NOT_STARTED The BluetoothLE device is not connected. + @retval EFI_NOT_FOUND The BluetoothLE device is not found. + @retval EFI_DEVICE_ERROR A hardware error occurred trying to disconnect the BluetoothLE device. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_DISCONNECT)( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN BLUETOOTH_LE_ADDRESS *BD_ADDR, + IN UINT8 Reason + ); + +/** + Get BluetoothLE configuration data. + + The GetData() function returns BluetoothLE configuration data. For remote BluetoothLE device + configuration data, please use GetRemoteData() function with valid BD_ADDR. + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] DataType Configuration data type. + @param[in, out] DataSize On input, indicates the size, in bytes, of the data buffer specified by Data. + On output, indicates the amount of data actually returned. + @param[in, out] Data A pointer to the buffer of data that will be returned. + + @retval EFI_SUCCESS The BluetoothLE configuration data is returned successfully. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + - DataSize is NULL. + - *DataSize is 0. + - Data is NULL. + @retval EFI_UNSUPPORTED The DataType is unsupported. + @retval EFI_NOT_FOUND The DataType is not found. + @retval EFI_BUFFER_TOO_SMALL The buffer is too small to hold the buffer. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_GET_DATA) ( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN EFI_BLUETOOTH_CONFIG_DATA_TYPE DataType, + IN OUT UINTN *DataSize, + IN OUT VOID *Data OPTIONAL + ); + +/** + Set BluetoothLE configuration data. + + The SetData() function sets local BluetoothLE device configuration data. Not all DataType can be + set. + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] DataType Configuration data type. + @param[in] DataSize Indicates the size, in bytes, of the data buffer specified by Data. + @param[in] Data A pointer to the buffer of data that will be set. + + @retval EFI_SUCCESS The BluetoothLE configuration data is set successfully. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + - DataSize is 0. + - Data is NULL. + @retval EFI_UNSUPPORTED The DataType is unsupported. + @retval EFI_WRITE_PROTECTED Cannot set configuration data. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_SET_DATA) ( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN EFI_BLUETOOTH_CONFIG_DATA_TYPE DataType, + IN UINTN DataSize, + IN VOID *Data + ); + +/** + Get remove BluetoothLE device configuration data. + + The GetRemoteData() function returns remote BluetoothLE device configuration data. + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] DataType Configuration data type. + @param[in] BDAddr Remote BluetoothLE device address. + @param[in, out] DataSize On input, indicates the size, in bytes, of the data buffer specified by Data. + On output, indicates the amount of data actually returned. + @param[in, out] Data A pointer to the buffer of data that will be returned. + + @retval EFI_SUCCESS The remote BluetoothLE device configuration data is returned successfully. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + - DataSize is NULL. + - *DataSize is 0. + - Data is NULL. + @retval EFI_UNSUPPORTED The DataType is unsupported. + @retval EFI_NOT_FOUND The DataType is not found. + @retval EFI_BUFFER_TOO_SMALL The buffer is too small to hold the buffer. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_GET_REMOTE_DATA) ( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN EFI_BLUETOOTH_CONFIG_DATA_TYPE DataType, + IN BLUETOOTH_LE_ADDRESS *BDAddr, + IN OUT UINTN *DataSize, + IN OUT VOID *Data + ); + +typedef enum { + /// + /// It indicates an authorization request. No data is associated with the callback + /// input. In the output data, the application should return the authorization value. + /// The data structure is BOOLEAN. TRUE means YES. FALSE means NO. + /// + EfiBluetoothSmpAuthorizationRequestEvent, + /// + /// It indicates that a passkey has been generated locally by the driver, and the same + /// passkey should be entered at the remote device. The callback input data is the + /// passkey of type UINT32, to be displayed by the application. No output data + /// should be returned. + /// + EfiBluetoothSmpPasskeyReadyEvent, + /// + /// It indicates that the driver is requesting for the passkey has been generated at + /// the remote device. No data is associated with the callback input. The output data + /// is the passkey of type UINT32, to be entered by the user. + /// + EfiBluetoothSmpPasskeyRequestEvent, + /// + /// It indicates that the driver is requesting for the passkey that has been pre-shared + /// out-of-band with the remote device. No data is associated with the callback + /// input. The output data is the stored OOB data of type UINT8[16]. + /// + EfiBluetoothSmpOOBDataRequestEvent, + /// + /// In indicates that a number have been generated locally by the bus driver, and + /// also at the remote device, and the bus driver wants to know if the two numbers + /// match. The callback input data is the number of type UINT32. The output data + /// is confirmation value of type BOOLEAN. TRUE means comparison pass. FALSE + /// means comparison fail. + /// + EfiBluetoothSmpNumericComparisonEvent, +} EFI_BLUETOOTH_LE_SMP_EVENT_DATA_TYPE; + +/** + The callback function for SMP. + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] Context Data passed into callback function. This is optional parameter + and may be NULL. + @param[in] BDAddr Remote BluetoothLE device address. + @param[in] EventDataType Event data type in EFI_BLUETOOTH_LE_SMP_EVENT_DATA_TYPE. + @param[in] DataSize Indicates the size, in bytes, of the data buffer specified by Data. + @param[in] Data A pointer to the buffer of data. + + @retval EFI_SUCCESS The callback function complete successfully. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_LE_SMP_CALLBACK) ( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN VOID *Context, + IN BLUETOOTH_LE_ADDRESS *BDAddr, + IN EFI_BLUETOOTH_LE_SMP_EVENT_DATA_TYPE EventDataType, + IN UINTN DataSize, + IN VOID *Data + ); + +/** + Register Security Manager Protocol callback function for user authentication/authorization. + + The RegisterSmpAuthCallback() function register Security Manager Protocol callback + function for user authentication/authorization. + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] Callback Callback function for user authentication/authorization. + @param[in] Context Data passed into Callback function. This is optional parameter and may be NULL. + + @retval EFI_SUCCESS The SMP callback function is registered successfully. + @retval EFI_ALREADY_STARTED A callback function is already registered on the same attribute + opcode and attribute handle, when the Callback is not NULL. + @retval EFI_NOT_STARTED A callback function is not registered on the same attribute opcode + and attribute handle, when the Callback is NULL. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_LE_REGISTER_SMP_AUTH_CALLBACK) ( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN EFI_BLUETOOTH_LE_SMP_CALLBACK Callback, + IN VOID *Context + ); + +/** + Send user authentication/authorization to remote device. + + The SendSmpAuthData() function sends user authentication/authorization to remote device. It + should be used to send these information after the caller gets the request data from the callback + function by RegisterSmpAuthCallback(). + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] BDAddr Remote BluetoothLE device address. + @param[in] EventDataType Event data type in EFI_BLUETOOTH_LE_SMP_EVENT_DATA_TYPE. + @param[in] DataSize The size of Data in bytes, of the data buffer specified by Data. + @param[in] Data A pointer to the buffer of data that will be sent. The data format + depends on the type of SMP event data being responded to. + + @retval EFI_SUCCESS The SMP authorization data is sent successfully. + @retval EFI_NOT_READY SMP is not in the correct state to receive the auth data. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_LE_SEND_SMP_AUTH_DATA) ( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN BLUETOOTH_LE_ADDRESS *BDAddr, + IN EFI_BLUETOOTH_LE_SMP_EVENT_DATA_TYPE EventDataType, + IN UINTN DataSize, + IN VOID *Data + ); + +typedef enum { + // For local device only + EfiBluetoothSmpLocalIR, /* If Key hierarchy is supported */ + EfiBluetoothSmpLocalER, /* If Key hierarchy is supported */ + EfiBluetoothSmpLocalDHK, /* If Key hierarchy is supported. OPTIONAL */ + // For peer specific + EfiBluetoothSmpKeysDistributed = 0x1000, + EfiBluetoothSmpKeySize, + EfiBluetoothSmpKeyType, + EfiBluetoothSmpPeerLTK, + EfiBluetoothSmpPeerIRK, + EfiBluetoothSmpPeerCSRK, + EfiBluetoothSmpPeerRand, + EfiBluetoothSmpPeerEDIV, + EfiBluetoothSmpPeerSignCounter, + EfiBluetoothSmpLocalLTK, /* If Key hierarchy not supported */ + EfiBluetoothSmpLocalIRK, /* If Key hierarchy not supported */ + EfiBluetoothSmpLocalCSRK, /* If Key hierarchy not supported */ + EfiBluetoothSmpLocalSignCounter, + EfiBluetoothSmpLocalDIV, + EfiBluetoothSmpPeerAddressList, + EfiBluetoothSmpMax, +} EFI_BLUETOOTH_LE_SMP_DATA_TYPE; + +/** + The callback function to get SMP data. + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] Context Data passed into callback function. This is optional parameter + and may be NULL. + @param[in] BDAddr Remote BluetoothLE device address. For Local device setting, it + should be NULL. + @param[in] DataType Data type in EFI_BLUETOOTH_LE_SMP_DATA_TYPE. + @param[in, out] DataSize On input, indicates the size, in bytes, of the data buffer specified + by Data. On output, indicates the amount of data actually returned. + @param[out] Data A pointer to the buffer of data that will be returned. + + @retval EFI_SUCCESS The callback function complete successfully. + +**/ +typedef +EFI_STATUS +(EFIAPI * EFI_BLUETOOTH_LE_CONFIG_SMP_GET_DATA_CALLBACK) ( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN VOID *Context, + IN BLUETOOTH_LE_ADDRESS *BDAddr, + IN EFI_BLUETOOTH_LE_SMP_DATA_TYPE DataType, + IN OUT UINTN *DataSize, + OUT VOID *Data + ); + +/** + Register a callback function to get SMP related data. + + The RegisterSmpGetDataCallback() function registers a callback function to get SMP related data. + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] Callback Callback function for SMP get data. + @param[in] Context Data passed into Callback function. This is optional parameter and may be NULL. + + @retval EFI_SUCCESS The SMP get data callback function is registered successfully. + @retval EFI_ALREADY_STARTED A callback function is already registered on the same attribute + opcode and attribute handle, when the Callback is not NULL. + @retval EFI_NOT_STARTED A callback function is not registered on the same attribute opcode + and attribute handle, when the Callback is NULL +**/ +typedef +EFI_STATUS +(EFIAPI * EFI_BLUETOOTH_LE_CONFIG_REGISTER_SMP_GET_DATA_CALLBACK) ( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN EFI_BLUETOOTH_LE_CONFIG_SMP_GET_DATA_CALLBACK Callback, + IN VOID *Context + ); + +/** + The callback function to set SMP data. + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] Context Data passed into callback function. This is optional parameter + and may be NULL. + @param[in] BDAddr Remote BluetoothLE device address. + @param[in] DataType Data type in EFI_BLUETOOTH_LE_SMP_DATA_TYPE. + @param[in] DataSize Indicates the size, in bytes, of the data buffer specified by Data. + @param[in] Data A pointer to the buffer of data. + + @retval EFI_SUCCESS The callback function complete successfully. + +**/ +typedef +EFI_STATUS +(EFIAPI * EFI_BLUETOOTH_LE_CONFIG_SMP_SET_DATA_CALLBACK) ( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN VOID *Context, + IN BLUETOOTH_LE_ADDRESS *BDAddr, + IN EFI_BLUETOOTH_LE_SMP_DATA_TYPE Type, + IN UINTN DataSize, + IN VOID *Data + ); + +/** + Register a callback function to set SMP related data. + + The RegisterSmpSetDataCallback() function registers a callback function to set SMP related data. + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] Callback Callback function for SMP set data. + @param[in] Context Data passed into Callback function. This is optional parameter and may be NULL. + + @retval EFI_SUCCESS The SMP set data callback function is registered successfully. + @retval EFI_ALREADY_STARTED A callback function is already registered on the same attribute + opcode and attribute handle, when the Callback is not NULL. + @retval EFI_NOT_STARTED A callback function is not registered on the same attribute opcode + and attribute handle, when the Callback is NULL +**/ +typedef +EFI_STATUS +(EFIAPI * EFI_BLUETOOTH_LE_CONFIG_REGISTER_SMP_SET_DATA_CALLBACK) ( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN EFI_BLUETOOTH_LE_CONFIG_SMP_SET_DATA_CALLBACK Callback, + IN VOID *Context + ); + +/** + The callback function to hook connect complete event. + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] Context Data passed into callback function. This is optional parameter + and may be NULL. + @param[in] CallbackType The value defined in EFI_BLUETOOTH_CONNECT_COMPLETE_CALLBACK_TYPE. + @param[in] BDAddr Remote BluetoothLE device address. + @param[in] InputBuffer A pointer to the buffer of data that is input from callback caller. + @param[in] InputBufferSize Indicates the size, in bytes, of the data buffer specified by InputBuffer. + + @retval EFI_SUCCESS The callback function complete successfully. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_CONNECT_COMPLETE_CALLBACK) ( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN VOID *Context, + IN EFI_BLUETOOTH_CONNECT_COMPLETE_CALLBACK_TYPE CallbackType, + IN BLUETOOTH_LE_ADDRESS *BDAddr, + IN VOID *InputBuffer, + IN UINTN InputBufferSize + ); + +/** + Register link connect complete callback function. + + The RegisterLinkConnectCompleteCallback() function registers Bluetooth link connect + complete callback function. The Bluetooth Configuration driver may call + RegisterLinkConnectCompleteCallback() to register a callback function. During pairing, + Bluetooth bus driver must trigger this callback function to report device state, if it is registered. + Then Bluetooth Configuration driver will get information on device connection, according to + CallbackType defined by EFI_BLUETOOTH_CONNECT_COMPLETE_CALLBACK_TYPE + + @param[in] This Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance. + @param[in] Callback The callback function. NULL means unregister. + @param[in] Context Data passed into Callback function. This is optional parameter and may be NULL. + + @retval EFI_SUCCESS The link connect complete callback function is registered successfully. + @retval EFI_ALREADY_STARTED A callback function is already registered on the same attribute + opcode and attribute handle, when the Callback is not NULL. + @retval EFI_NOT_STARTED A callback function is not registered on the same attribute opcode + and attribute handle, when the Callback is NULL +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_REGISTER_CONNECT_COMPLETE_CALLBACK) ( + IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This, + IN EFI_BLUETOOTH_LE_CONFIG_CONNECT_COMPLETE_CALLBACK Callback, + IN VOID *Context + ); + +/// +/// This protocol abstracts user interface configuration for BluetoothLe device. +/// +struct _EFI_BLUETOOTH_LE_CONFIG_PROTOCOL { + EFI_BLUETOOTH_LE_CONFIG_INIT Init; + EFI_BLUETOOTH_LE_CONFIG_SCAN Scan; + EFI_BLUETOOTH_LE_CONFIG_CONNECT Connect; + EFI_BLUETOOTH_LE_CONFIG_DISCONNECT Disconnect; + EFI_BLUETOOTH_LE_CONFIG_GET_DATA GetData; + EFI_BLUETOOTH_LE_CONFIG_SET_DATA SetData; + EFI_BLUETOOTH_LE_CONFIG_GET_REMOTE_DATA GetRemoteData; + EFI_BLUETOOTH_LE_REGISTER_SMP_AUTH_CALLBACK RegisterSmpAuthCallback; + EFI_BLUETOOTH_LE_SEND_SMP_AUTH_DATA SendSmpAuthData; + EFI_BLUETOOTH_LE_CONFIG_REGISTER_SMP_GET_DATA_CALLBACK RegisterSmpGetDataCallback; + EFI_BLUETOOTH_LE_CONFIG_REGISTER_SMP_SET_DATA_CALLBACK RegisterSmpSetDataCallback; + EFI_BLUETOOTH_LE_CONFIG_REGISTER_CONNECT_COMPLETE_CALLBACK RegisterLinkConnectCompleteCallback; +}; + +extern EFI_GUID gEfiBluetoothLeConfigProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/BootManagerPolicy.h b/MdePkg/Include/Protocol/BootManagerPolicy.h index f348e3f101da..42e90fdedeeb 100644 --- a/MdePkg/Include/Protocol/BootManagerPolicy.h +++ b/MdePkg/Include/Protocol/BootManagerPolicy.h @@ -4,14 +4,8 @@ This protocol is used by EFI Applications to request the UEFI Boot Manager to connect devices using platform policy. - Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef __BOOT_MANAGER_POLICY_H__ @@ -53,7 +47,7 @@ typedef struct _EFI_BOOT_MANAGER_POLICY_PROTOCOL EFI_BOOT_MANAGER_POLICY_PROTOCO system will be connected using the platforms EFI Boot Manager policy. @param[in] Recursive If TRUE, then ConnectController() is called recursively - until the entire tree of controllers below the + until the entire tree of controllers below the controller specified by DevicePath have been created. If FALSE, then the tree of controllers is only expanded one level. If DevicePath is NULL then Recursive is ignored. @@ -61,7 +55,7 @@ typedef struct _EFI_BOOT_MANAGER_POLICY_PROTOCOL EFI_BOOT_MANAGER_POLICY_PROTOCO @retval EFI_SUCCESS The DevicePath was connected. @retval EFI_NOT_FOUND The DevicePath was not found. @retval EFI_NOT_FOUND No driver was connected to DevicePath. - @retval EFI_SECURITY_VIOLATION The user has no permission to start UEFI device + @retval EFI_SECURITY_VIOLATION The user has no permission to start UEFI device drivers on the DevicePath. @retval EFI_UNSUPPORTED The current TPL is not TPL_APPLICATION. **/ @@ -80,7 +74,7 @@ EFI_STATUS Manager connect a class of devices. If Class is EFI_BOOT_MANAGER_POLICY_CONSOLE_GUID then the Boot Manager will - use platform policy to connect consoles. Some platforms may restrict the + use platform policy to connect consoles. Some platforms may restrict the number of consoles connected as they attempt to fast boot, and calling ConnectDeviceClass() with a Class value of EFI_BOOT_MANAGER_POLICY_CONSOLE_GUID must connect the set of consoles that follow the Boot Manager platform policy, @@ -98,7 +92,7 @@ EFI_STATUS application that called ConnectDeviceClass() may need to use the published protocols to establish the network connection. The Boot Manager can optionally have a policy to establish a network connection. - + If Class is EFI_BOOT_MANAGER_POLICY_CONNECT_ALL_GUID then the Boot Manager will connect all UEFI drivers using the UEFI Boot Service EFI_BOOT_SERVICES.ConnectController(). If the Boot Manager has policy @@ -115,7 +109,7 @@ EFI_STATUS @retval EFI_DEVICE_ERROR Devices were not connected due to an error. @retval EFI_NOT_FOUND The Class is not supported by the platform. @retval EFI_UNSUPPORTED The current TPL is not TPL_APPLICATION. -**/ +**/ typedef EFI_STATUS (EFIAPI *EFI_BOOT_MANAGER_POLICY_CONNECT_DEVICE_CLASS)( diff --git a/MdePkg/Include/Protocol/BusSpecificDriverOverride.h b/MdePkg/Include/Protocol/BusSpecificDriverOverride.h index dcaeb9c53574..878458e9c8ea 100644 --- a/MdePkg/Include/Protocol/BusSpecificDriverOverride.h +++ b/MdePkg/Include/Protocol/BusSpecificDriverOverride.h @@ -6,14 +6,8 @@ instance of this protocol for every PCI controller that has a PCI option ROM that contains one or more UEFI drivers. The protocol instance is attached to the handle of the PCI controller. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -34,14 +28,14 @@ typedef struct _EFI_BUS_SPECIFIC_DRIVER_OVERRIDE_PROTOCOL EFI_BUS_SPECIFIC_DRIV // Prototypes for the Bus Specific Driver Override Protocol // -/** +/** Uses a bus specific algorithm to retrieve a driver image handle for a controller. - + @param This A pointer to the EFI_BUS_SPECIFIC_DRIVER_ - OVERRIDE_PROTOCOL instance. + OVERRIDE_PROTOCOL instance. @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 + by GetDriver(). On output, a pointer to the next driver + image handle. Passing in a NULL, will return the first driver image handle. @retval EFI_SUCCESS A bus specific override driver is returned in DriverImageHandle. diff --git a/MdePkg/Include/Protocol/Capsule.h b/MdePkg/Include/Protocol/Capsule.h index e35035da6a29..0122b6ebcdf4 100644 --- a/MdePkg/Include/Protocol/Capsule.h +++ b/MdePkg/Include/Protocol/Capsule.h @@ -1,23 +1,17 @@ /** @file Capsule Architectural Protocol as defined in PI1.0a Specification VOLUME 2 DXE - The DXE Driver that produces this protocol must be a runtime driver. - The driver is responsible for initializing the CapsuleUpdate() and - QueryCapsuleCapabilities() fields of the UEFI Runtime Services Table. - After the two fields of the UEFI Runtime Services Table have been initialized, - the driver must install the EFI_CAPSULE_ARCH_PROTOCOL_GUID on a new handle - with a NULL interface pointer. The installation of this protocol informs - the DXE Foundation that the Capsule related services are now available and + The DXE Driver that produces this protocol must be a runtime driver. + The driver is responsible for initializing the CapsuleUpdate() and + QueryCapsuleCapabilities() fields of the UEFI Runtime Services Table. + After the two fields of the UEFI Runtime Services Table have been initialized, + the driver must install the EFI_CAPSULE_ARCH_PROTOCOL_GUID on a new handle + with a NULL interface pointer. The installation of this protocol informs + the DXE Foundation that the Capsule related services are now available and that the DXE Foundation must update the 32-bit CRC of the UEFI Runtime Services Table. -Copyright (c) 2006 - 2009, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Protocol/ComponentName.h b/MdePkg/Include/Protocol/ComponentName.h index cdd87fce3157..91344fc576c6 100644 --- a/MdePkg/Include/Protocol/ComponentName.h +++ b/MdePkg/Include/Protocol/ComponentName.h @@ -1,16 +1,10 @@ /** @file EFI Component Name Protocol as defined in the EFI 1.1 specification. - This protocol is used to retrieve user readable names of EFI Drivers + This protocol is used to retrieve user readable names of EFI Drivers and controllers managed by EFI Drivers. -Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -110,7 +104,7 @@ EFI_STATUS ); /// -/// This protocol is used to retrieve user readable names of drivers +/// This protocol is used to retrieve user readable names of drivers /// and controllers managed by UEFI Drivers. /// struct _EFI_COMPONENT_NAME_PROTOCOL { @@ -119,7 +113,7 @@ struct _EFI_COMPONENT_NAME_PROTOCOL { /// /// A Null-terminated ASCII string that contains one or more /// ISO 639-2 language codes. This is the list of language codes - /// that this protocol supports. + /// that this protocol supports. /// CHAR8 *SupportedLanguages; }; diff --git a/MdePkg/Include/Protocol/ComponentName2.h b/MdePkg/Include/Protocol/ComponentName2.h index d005b02b873f..3d201501708a 100644 --- a/MdePkg/Include/Protocol/ComponentName2.h +++ b/MdePkg/Include/Protocol/ComponentName2.h @@ -1,16 +1,10 @@ /** @file UEFI Component Name 2 Protocol as defined in the UEFI 2.1 specification. - This protocol is used to retrieve user readable names of drivers + This protocol is used to retrieve user readable names of drivers and controllers managed by UEFI Drivers. - Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -32,7 +26,7 @@ typedef struct _EFI_COMPONENT_NAME2_PROTOCOL EFI_COMPONENT_NAME2_PROTOCOL; @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL instance. - + @param Language A pointer to a Null-terminated ASCII string array indicating the language. This is the language of the driver name that the caller @@ -42,7 +36,7 @@ typedef struct _EFI_COMPONENT_NAME2_PROTOCOL EFI_COMPONENT_NAME2_PROTOCOL; driver is up to the driver writer. Language is specified in RFC 4646 language code format. - + @param DriverName A pointer to the string to return. This string is the name of the driver specified by This in the language @@ -52,11 +46,11 @@ typedef struct _EFI_COMPONENT_NAME2_PROTOCOL EFI_COMPONENT_NAME2_PROTOCOL; Driver specified by This and the language specified by Language was returned in DriverName. - + @retval EFI_INVALID_PARAMETER Language is NULL. - + @retval EFI_INVALID_PARAMETER DriverName is NULL. - + @retval EFI_UNSUPPORTED The driver specified by This does not support the language specified by Language. @@ -150,7 +144,7 @@ EFI_STATUS ); /// -/// This protocol is used to retrieve user readable names of drivers +/// This protocol is used to retrieve user readable names of drivers /// and controllers managed by UEFI Drivers. /// struct _EFI_COMPONENT_NAME2_PROTOCOL { @@ -162,7 +156,7 @@ struct _EFI_COMPONENT_NAME2_PROTOCOL { /// supported language codes. This is the list of language codes that /// this protocol supports. The number of languages supported by a /// driver is up to the driver writer. SupportedLanguages is - /// specified in RFC 4646 format. + /// specified in RFC 4646 format. /// CHAR8 *SupportedLanguages; }; diff --git a/MdePkg/Include/Protocol/Cpu.h b/MdePkg/Include/Protocol/Cpu.h index cfb2e7570155..72e061252326 100644 --- a/MdePkg/Include/Protocol/Cpu.h +++ b/MdePkg/Include/Protocol/Cpu.h @@ -3,14 +3,8 @@ This code abstracts the DXE core from processor implementation details. - Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -61,14 +55,14 @@ VOID ); /** - This function flushes the range of addresses from Start to Start+Length - from the processor's data cache. If Start is not aligned to a cache line - boundary, then the bytes before Start to the preceding cache line boundary - are also flushed. If Start+Length is not aligned to a cache line boundary, - then the bytes past Start+Length to the end of the next cache line boundary - are also flushed. The FlushType of EfiCpuFlushTypeWriteBackInvalidate must be - supported. If the data cache is fully coherent with all DMA operations, then - this function can just return EFI_SUCCESS. If the processor does not support + This function flushes the range of addresses from Start to Start+Length + from the processor's data cache. If Start is not aligned to a cache line + boundary, then the bytes before Start to the preceding cache line boundary + are also flushed. If Start+Length is not aligned to a cache line boundary, + then the bytes past Start+Length to the end of the next cache line boundary + are also flushed. The FlushType of EfiCpuFlushTypeWriteBackInvalidate must be + supported. If the data cache is fully coherent with all DMA operations, then + this function can just return EFI_SUCCESS. If the processor does not support flushing a range of the data cache, then the entire data cache can be flushed. @param This The EFI_CPU_ARCH_PROTOCOL instance. @@ -98,7 +92,7 @@ EFI_STATUS /** - This function enables interrupt processing by the processor. + This function enables interrupt processing by the processor. @param This The EFI_CPU_ARCH_PROTOCOL instance. @@ -130,8 +124,8 @@ EFI_STATUS /** - This function retrieves the processor's current interrupt state a returns it in - State. If interrupts are currently enabled, then TRUE is returned. If interrupts + This function retrieves the processor's current interrupt state a returns it in + State. If interrupts are currently enabled, then TRUE is returned. If interrupts are currently disabled, then FALSE is returned. @param This The EFI_CPU_ARCH_PROTOCOL instance. @@ -152,9 +146,9 @@ EFI_STATUS /** This function generates an INIT on the processor. If this function succeeds, then the - processor will be reset, and control will not be returned to the caller. If InitType is - not supported by this processor, or the processor cannot programmatically generate an - INIT without help from external hardware, then EFI_UNSUPPORTED is returned. If an error + processor will be reset, and control will not be returned to the caller. If InitType is + not supported by this processor, or the processor cannot programmatically generate an + INIT without help from external hardware, then EFI_UNSUPPORTED is returned. If an error occurs attempting to generate an INIT, then EFI_DEVICE_ERROR is returned. @param This The EFI_CPU_ARCH_PROTOCOL instance. @@ -175,9 +169,9 @@ EFI_STATUS /** - This function registers and enables the handler specified by InterruptHandler for a processor - interrupt or exception type specified by InterruptType. If InterruptHandler is NULL, then the - handler for the processor interrupt or exception type specified by InterruptType is uninstalled. + This function registers and enables the handler specified by InterruptHandler for a processor + interrupt or exception type specified by InterruptType. If InterruptHandler is NULL, then the + handler for the processor interrupt or exception type specified by InterruptType is uninstalled. The installed handler is called once for each processor interrupt or exception. @param This The EFI_CPU_ARCH_PROTOCOL instance. @@ -280,17 +274,17 @@ struct _EFI_CPU_ARCH_PROTOCOL { EFI_CPU_GET_TIMER_VALUE GetTimerValue; EFI_CPU_SET_MEMORY_ATTRIBUTES SetMemoryAttributes; /// - /// The number of timers that are available in a processor. The value in this - /// field is a constant that must not be modified after the CPU Architectural + /// The number of timers that are available in a processor. The value in this + /// field is a constant that must not be modified after the CPU Architectural /// Protocol is installed. All consumers must treat this as a read-only field. /// UINT32 NumberOfTimers; /// - /// The size, in bytes, of the alignment required for DMA buffer allocations. - /// This is typically the size of the largest data cache line in the platform. - /// The value in this field is a constant that must not be modified after the - /// CPU Architectural Protocol is installed. All consumers must treat this as - /// a read-only field. + /// The size, in bytes, of the alignment required for DMA buffer allocations. + /// This is typically the size of the largest data cache line in the platform. + /// The value in this field is a constant that must not be modified after the + /// CPU Architectural Protocol is installed. All consumers must treat this as + /// a read-only field. /// UINT32 DmaBufferAlignment; }; diff --git a/MdePkg/Include/Protocol/CpuIo2.h b/MdePkg/Include/Protocol/CpuIo2.h index 49fb470713e7..173b00d5c3a4 100644 --- a/MdePkg/Include/Protocol/CpuIo2.h +++ b/MdePkg/Include/Protocol/CpuIo2.h @@ -1,28 +1,22 @@ /** @file This files describes the CPU I/O 2 Protocol. - + This protocol provides an I/O abstraction for a system processor. This protocol is used by a PCI root bridge I/O driver to perform memory-mapped I/O and I/O transactions. The I/O or memory primitives can be used by the consumer of the protocol to materialize bus-specific configuration cycles, such as the transitional configuration address and data - ports for PCI. Only drivers that require direct access to the entire system should use this - protocol. - + ports for PCI. Only drivers that require direct access to the entire system should use this + protocol. + Note: This is a boot-services only protocol and it may not be used by runtime drivers after ExitBootServices(). It is different from the Framework CPU I/O Protocol, which is a runtime protocol and can be used by runtime drivers after ExitBootServices(). - Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: - This Protocol is defined in UEFI Platform Initialization Specification 1.2 + This Protocol is defined in UEFI Platform Initialization Specification 1.2 Volume 5: Standards **/ @@ -57,35 +51,35 @@ typedef enum { } EFI_CPU_IO_PROTOCOL_WIDTH; /** - Enables a driver to access registers in the PI CPU I/O space. + Enables a driver to access registers in the PI CPU I/O space. - The Io.Read() and Io.Write() functions enable a driver to access PCI controller - registers in the PI CPU I/O space. + The Io.Read() and Io.Write() functions enable a driver to access PCI controller + registers in the PI CPU I/O space. - The I/O operations are carried out exactly as requested. The caller is responsible - for satisfying any alignment and I/O width restrictions that a PI System on a - platform might require. For example on some platforms, width requests of - EfiCpuIoWidthUint64 do not work. Misaligned buffers, on the other hand, will + The I/O operations are carried out exactly as requested. The caller is responsible + for satisfying any alignment and I/O width restrictions that a PI System on a + platform might require. For example on some platforms, width requests of + EfiCpuIoWidthUint64 do not work. Misaligned buffers, on the other hand, will be handled by the driver. - - If Width is EfiCpuIoWidthUint8, EfiCpuIoWidthUint16, EfiCpuIoWidthUint32, - or EfiCpuIoWidthUint64, then both Address and Buffer are incremented for + + If Width is EfiCpuIoWidthUint8, EfiCpuIoWidthUint16, EfiCpuIoWidthUint32, + or EfiCpuIoWidthUint64, then both Address and Buffer are incremented for each of the Count operations that is performed. - - If Width is EfiCpuIoWidthFifoUint8, EfiCpuIoWidthFifoUint16, - EfiCpuIoWidthFifoUint32, or EfiCpuIoWidthFifoUint64, then only Buffer is - incremented for each of the Count operations that is performed. The read or + + If Width is EfiCpuIoWidthFifoUint8, EfiCpuIoWidthFifoUint16, + EfiCpuIoWidthFifoUint32, or EfiCpuIoWidthFifoUint64, then only Buffer is + incremented for each of the Count operations that is performed. The read or write operation is performed Count times on the same Address. - - If Width is EfiCpuIoWidthFillUint8, EfiCpuIoWidthFillUint16, - EfiCpuIoWidthFillUint32, or EfiCpuIoWidthFillUint64, then only Address is - incremented for each of the Count operations that is performed. The read or + + If Width is EfiCpuIoWidthFillUint8, EfiCpuIoWidthFillUint16, + EfiCpuIoWidthFillUint32, or EfiCpuIoWidthFillUint64, then only Address is + incremented for each of the Count operations that is performed. The read or write operation is performed Count times from the first element of Buffer. @param[in] This A pointer to the EFI_CPU_IO2_PROTOCOL instance. @param[in] Width Signifies the width of the I/O or Memory operation. - @param[in] Address The base address of the I/O operation. - @param[in] Count The number of I/O operations to perform. The number + @param[in] Address The base address of the I/O operation. + @param[in] Count The number of I/O operations to perform. The number of bytes moved is Width size * Count, starting at Address. @param[in, out] Buffer For read operations, the destination buffer to store the results. For write operations, the source buffer from which to write data. @@ -94,7 +88,7 @@ typedef enum { @retval EFI_INVALID_PARAMETER Width is invalid for this PI system. @retval EFI_INVALID_PARAMETER Buffer is NULL. @retval EFI_UNSUPPORTED The Buffer is not aligned for the given Width. - @retval EFI_UNSUPPORTED The address range specified by Address, Width, + @retval EFI_UNSUPPORTED The address range specified by Address, Width, and Count is not valid for this PI system. **/ diff --git a/MdePkg/Include/Protocol/DebugPort.h b/MdePkg/Include/Protocol/DebugPort.h index ba14591107e7..d3aa3bbf2a4f 100644 --- a/MdePkg/Include/Protocol/DebugPort.h +++ b/MdePkg/Include/Protocol/DebugPort.h @@ -1,17 +1,11 @@ /** @file - + The file defines the EFI Debugport protocol. This protocol is used by debug agent to communicate with the remote debug host. - - Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -35,14 +29,14 @@ typedef struct _EFI_DEBUGPORT_PROTOCOL EFI_DEBUGPORT_PROTOCOL; // DebugPort member functions // -/** +/** Resets the debugport. - + @param This A pointer to the EFI_DEBUGPORT_PROTOCOL instance. - + @retval EFI_SUCCESS The debugport device was reset and is in usable state. @retval EFI_DEVICE_ERROR The debugport device could not be reset and is unusable. - + **/ typedef EFI_STATUS @@ -50,19 +44,19 @@ EFI_STATUS IN EFI_DEBUGPORT_PROTOCOL *This ); -/** +/** Writes data to the debugport. - + @param This A pointer to the EFI_DEBUGPORT_PROTOCOL instance. @param Timeout The number of microseconds to wait before timing out a write operation. @param BufferSize On input, the requested number of bytes of data to write. On output, the number of bytes of data actually written. - @param Buffer A pointer to a buffer containing the data to write. - + @param Buffer A pointer to a buffer containing the data to write. + @retval EFI_SUCCESS The data was written. @retval EFI_DEVICE_ERROR The device reported an error. @retval EFI_TIMEOUT The data write was stopped due to a timeout. - + **/ typedef EFI_STATUS @@ -73,20 +67,20 @@ EFI_STATUS IN VOID *Buffer ); -/** +/** Reads data from the debugport. - + @param This A pointer to the EFI_DEBUGPORT_PROTOCOL instance. @param Timeout The number of microseconds to wait before timing out a read operation. @param BufferSize On input, the requested number of bytes of data to read. On output, the number of bytes of data actually number of bytes of data read and returned in Buffer. @param Buffer A pointer to a buffer into which the data read will be saved. - + @retval EFI_SUCCESS The data was read. @retval EFI_DEVICE_ERROR The device reported an error. @retval EFI_TIMEOUT The operation was stopped due to a timeout or overrun. - + **/ typedef EFI_STATUS @@ -97,15 +91,15 @@ EFI_STATUS OUT VOID *Buffer ); -/** +/** Checks to see if any data is available to be read from the debugport device. - + @param This A pointer to the EFI_DEBUGPORT_PROTOCOL instance. - + @retval EFI_SUCCESS At least one byte of data is available to be read. @retval EFI_DEVICE_ERROR The debugport device is not functioning correctly. @retval EFI_NOT_READY No data is available to be read. - + **/ typedef EFI_STATUS diff --git a/MdePkg/Include/Protocol/DebugSupport.h b/MdePkg/Include/Protocol/DebugSupport.h index 80f87061bd0e..3ab78ee1baf3 100644 --- a/MdePkg/Include/Protocol/DebugSupport.h +++ b/MdePkg/Include/Protocol/DebugSupport.h @@ -5,16 +5,11 @@ The DebugSupport protocol is used by source level debuggers to abstract the processor and handle context save and restore operations. -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> Portions copyright (c) 2011 - 2013, ARM Ltd. All rights reserved.<BR> +Copyright (c) 2020, Hewlett Packard Enterprise Development LP. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -183,7 +178,7 @@ typedef struct { UINT8 Xmm6[16]; UINT8 Xmm7[16]; // - // NOTE: UEFI 2.0 spec definition as follows. + // NOTE: UEFI 2.0 spec definition as follows. // UINT8 Reserved11[14 * 16]; } EFI_FX_SAVE_STATE_X64; @@ -609,6 +604,59 @@ typedef struct { UINT64 FAR; // Fault Address Register } EFI_SYSTEM_CONTEXT_AARCH64; +/// +/// RISC-V processor exception types. +/// +#define EXCEPT_RISCV_INST_MISALIGNED 0 +#define EXCEPT_RISCV_INST_ACCESS_FAULT 1 +#define EXCEPT_RISCV_ILLEGAL_INST 2 +#define EXCEPT_RISCV_BREAKPOINT 3 +#define EXCEPT_RISCV_LOAD_ADDRESS_MISALIGNED 4 +#define EXCEPT_RISCV_LOAD_ACCESS_FAULT 5 +#define EXCEPT_RISCV_STORE_AMO_ADDRESS_MISALIGNED 6 +#define EXCEPT_RISCV_STORE_AMO_ACCESS_FAULT 7 +#define EXCEPT_RISCV_ENV_CALL_FROM_UMODE 8 +#define EXCEPT_RISCV_ENV_CALL_FROM_SMODE 9 +#define EXCEPT_RISCV_ENV_CALL_FROM_HMODE 10 +#define EXCEPT_RISCV_ENV_CALL_FROM_MMODE 11 + +#define EXCEPT_RISCV_SOFTWARE_INT 0x0 +#define EXCEPT_RISCV_TIMER_INT 0x1 + +typedef struct { + UINT64 X0; + UINT64 X1; + UINT64 X2; + UINT64 X3; + UINT64 X4; + UINT64 X5; + UINT64 X6; + UINT64 X7; + UINT64 X8; + UINT64 X9; + UINT64 X10; + UINT64 X11; + UINT64 X12; + UINT64 X13; + UINT64 X14; + UINT64 X15; + UINT64 X16; + UINT64 X17; + UINT64 X18; + UINT64 X19; + UINT64 X20; + UINT64 X21; + UINT64 X22; + UINT64 X23; + UINT64 X24; + UINT64 X25; + UINT64 X26; + UINT64 X27; + UINT64 X28; + UINT64 X29; + UINT64 X30; + UINT64 X31; +} EFI_SYSTEM_CONTEXT_RISCV64; /// /// Universal EFI_SYSTEM_CONTEXT definition. @@ -620,18 +668,19 @@ typedef union { EFI_SYSTEM_CONTEXT_IPF *SystemContextIpf; EFI_SYSTEM_CONTEXT_ARM *SystemContextArm; EFI_SYSTEM_CONTEXT_AARCH64 *SystemContextAArch64; + EFI_SYSTEM_CONTEXT_RISCV64 *SystemContextRiscV64; } EFI_SYSTEM_CONTEXT; // // DebugSupport callback function prototypes // -/** +/** Registers and enables an exception callback function for the specified exception. - + @param ExceptionType Exception types in EBC, IA-32, x64, or IPF. @param SystemContext Exception content. - + **/ typedef VOID @@ -640,11 +689,11 @@ VOID IN OUT EFI_SYSTEM_CONTEXT SystemContext ); -/** +/** Registers and enables the on-target debug agent's periodic entry point. - + @param SystemContext Exception content. - + **/ typedef VOID @@ -669,16 +718,16 @@ typedef enum { // DebugSupport member function definitions // -/** +/** Returns the maximum value that may be used for the ProcessorIndex parameter in - RegisterPeriodicCallback() and RegisterExceptionCallback(). - + RegisterPeriodicCallback() and RegisterExceptionCallback(). + @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance. @param MaxProcessorIndex Pointer to a caller-allocated UINTN in which the maximum supported - processor index is returned. - - @retval EFI_SUCCESS The function completed successfully. - + processor index is returned. + + @retval EFI_SUCCESS The function completed successfully. + **/ typedef EFI_STATUS @@ -687,20 +736,20 @@ EFI_STATUS OUT UINTN *MaxProcessorIndex ); -/** +/** Registers a function to be called back periodically in interrupt context. - + @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance. @param ProcessorIndex Specifies which processor the callback function applies to. @param PeriodicCallback A pointer to a function of type PERIODIC_CALLBACK that is the main periodic entry point of the debug agent. - - @retval EFI_SUCCESS The function completed successfully. + + @retval EFI_SUCCESS The function completed successfully. @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback - function was previously registered. - @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback - function. - + function was previously registered. + @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback + function. + **/ typedef EFI_STATUS @@ -710,21 +759,21 @@ EFI_STATUS IN EFI_PERIODIC_CALLBACK PeriodicCallback ); -/** +/** Registers a function to be called when a given processor exception occurs. - + @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance. @param ProcessorIndex Specifies which processor the callback function applies to. @param ExceptionCallback A pointer to a function of type EXCEPTION_CALLBACK that is called - when the processor exception specified by ExceptionType occurs. - @param ExceptionType Specifies which processor exception to hook. - - @retval EFI_SUCCESS The function completed successfully. + when the processor exception specified by ExceptionType occurs. + @param ExceptionType Specifies which processor exception to hook. + + @retval EFI_SUCCESS The function completed successfully. @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback - function was previously registered. - @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback - function. - + function was previously registered. + @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback + function. + **/ typedef EFI_STATUS @@ -735,18 +784,18 @@ EFI_STATUS IN EFI_EXCEPTION_TYPE ExceptionType ); -/** +/** Invalidates processor instruction cache for a memory range. Subsequent execution in this range - causes a fresh memory fetch to retrieve code to be executed. - + causes a fresh memory fetch to retrieve code to be executed. + @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance. @param ProcessorIndex Specifies which processor's instruction cache is to be invalidated. - @param Start Specifies the physical base of the memory range to be invalidated. + @param Start Specifies the physical base of the memory range to be invalidated. @param Length Specifies the minimum number of bytes in the processor's instruction - cache to invalidate. - - @retval EFI_SUCCESS The function completed successfully. - + cache to invalidate. + + @retval EFI_SUCCESS The function completed successfully. + **/ typedef EFI_STATUS @@ -758,8 +807,8 @@ EFI_STATUS ); /// -/// This protocol provides the services to allow the debug agent to register -/// callback functions that are called either periodically or when specific +/// This protocol provides the services to allow the debug agent to register +/// callback functions that are called either periodically or when specific /// processor exceptions occur. /// struct _EFI_DEBUG_SUPPORT_PROTOCOL { @@ -775,4 +824,4 @@ struct _EFI_DEBUG_SUPPORT_PROTOCOL { extern EFI_GUID gEfiDebugSupportProtocolGuid; -#endif +#endif diff --git a/MdePkg/Include/Protocol/Decompress.h b/MdePkg/Include/Protocol/Decompress.h index 965b7d2f45ae..9ca3e14b5ab0 100644 --- a/MdePkg/Include/Protocol/Decompress.h +++ b/MdePkg/Include/Protocol/Decompress.h @@ -1,14 +1,8 @@ /** @file The Decompress Protocol Interface as defined in UEFI spec - Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -23,16 +17,16 @@ typedef struct _EFI_DECOMPRESS_PROTOCOL EFI_DECOMPRESS_PROTOCOL; /** - The GetInfo() function retrieves the size of the uncompressed buffer - and the temporary scratch buffer required to decompress the buffer + The GetInfo() function retrieves the size of the uncompressed buffer + and the temporary scratch buffer required to decompress the buffer specified by Source and SourceSize. If the size of the uncompressed - buffer or the size of the scratch buffer cannot be determined from - the compressed data specified by Source and SourceData, then + buffer or the size of the scratch buffer cannot be determined from + the compressed data specified by Source and SourceData, then EFI_INVALID_PARAMETER is returned. Otherwise, the size of the uncompressed - buffer is returned in DestinationSize, the size of the scratch buffer is + buffer is returned in DestinationSize, the size of the scratch buffer is returned in ScratchSize, and EFI_SUCCESS is returned. - The GetInfo() function does not have a scratch buffer available to perform + The GetInfo() function does not have a scratch buffer available to perform a thorough checking of the validity of the source data. It just retrieves the 'Original Size' field from the beginning bytes of the source data and output it as DestinationSize. And ScratchSize is specific to the decompression @@ -68,15 +62,15 @@ EFI_STATUS /** The Decompress() function extracts decompressed data to its original form. - This protocol is designed so that the decompression algorithm can be - implemented without using any memory services. As a result, the - Decompress() function is not allowed to call AllocatePool() or - AllocatePages() in its implementation. It is the caller's responsibility + This protocol is designed so that the decompression algorithm can be + implemented without using any memory services. As a result, the + Decompress() function is not allowed to call AllocatePool() or + AllocatePages() in its implementation. It is the caller's responsibility to allocate and free the Destination and Scratch buffers. - If the compressed source data specified by Source and SourceSize is - successfully decompressed into Destination, then EFI_SUCCESS is returned. - If the compressed source data specified by Source and SourceSize is not in + If the compressed source data specified by Source and SourceSize is + successfully decompressed into Destination, then EFI_SUCCESS is returned. + 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 A pointer to the EFI_DECOMPRESS_PROTOCOL instance. @@ -87,7 +81,7 @@ EFI_STATUS @param DestinationSize The size of destination buffer. The size of destination buffer needed is obtained from GetInfo(). @param Scratch A temporary scratch buffer that is used to perform the - decompression. + decompression. @param ScratchSize The size of scratch buffer. The size of scratch buffer needed is obtained from GetInfo(). diff --git a/MdePkg/Include/Protocol/DeferredImageLoad.h b/MdePkg/Include/Protocol/DeferredImageLoad.h index 4d1bbf0ed402..7161ce02fe3c 100644 --- a/MdePkg/Include/Protocol/DeferredImageLoad.h +++ b/MdePkg/Include/Protocol/DeferredImageLoad.h @@ -1,19 +1,13 @@ /** @file UEFI 2.2 Deferred Image Load Protocol definition. - This protocol returns information about images whose load was denied because of security - considerations. This information can be used by the Boot Manager or another agent to reevaluate the - images when the current security profile has been changed, such as when the current user profile + This protocol returns information about images whose load was denied because of security + considerations. This information can be used by the Boot Manager or another agent to reevaluate the + images when the current security profile has been changed, such as when the current user profile changes. There can be more than one instance of this protocol installed. - Copyright (c) 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -33,28 +27,28 @@ typedef struct _EFI_DEFERRED_IMAGE_LOAD_PROTOCOL EFI_DEFERRED_IMAGE_LOAD_PROTOC /** Returns information about a deferred image. - This function returns information about a single deferred image. The deferred images are numbered - consecutively, starting with 0. If there is no image which corresponds to ImageIndex, then - EFI_NOT_FOUND is returned. All deferred images may be returned by iteratively calling this + This function returns information about a single deferred image. The deferred images are numbered + consecutively, starting with 0. If there is no image which corresponds to ImageIndex, then + EFI_NOT_FOUND is returned. All deferred images may be returned by iteratively calling this function until EFI_NOT_FOUND is returned. - Image may be NULL and ImageSize set to 0 if the decision to defer execution was made because + Image may be NULL and ImageSize set to 0 if the decision to defer execution was made because of the location of the executable image rather than its actual contents. record handle until - there are no more, at which point UserInfo will point to NULL. + there are no more, at which point UserInfo will point to NULL. @param[in] This Points to this instance of the EFI_DEFERRED_IMAGE_LOAD_PROTOCOL. @param[in] ImageIndex Zero-based index of the deferred index. - @param[out] ImageDevicePath On return, points to a pointer to the device path of the image. - The device path should not be freed by the caller. - @param[out] Image On return, points to the first byte of the image or NULL if the - image is not available. The image should not be freed by the caller - unless LoadImage() has been called successfully. + @param[out] ImageDevicePath On return, points to a pointer to the device path of the image. + The device path should not be freed by the caller. + @param[out] Image On return, points to the first byte of the image or NULL if the + image is not available. The image should not be freed by the caller + unless LoadImage() has been called successfully. @param[out] ImageSize On return, the size of the image, or 0 if the image is not available. - @param[out] BootOption On return, points to TRUE if the image was intended as a boot option - or FALSE if it was not intended as a boot option. - + @param[out] BootOption On return, points to TRUE if the image was intended as a boot option + or FALSE if it was not intended as a boot option. + @retval EFI_SUCCESS Image information returned successfully. @retval EFI_NOT_FOUND ImageIndex does not refer to a valid image. - @retval EFI_INVALID_PARAMETER ImageDevicePath is NULL or Image is NULL or ImageSize is NULL or + @retval EFI_INVALID_PARAMETER ImageDevicePath is NULL or Image is NULL or ImageSize is NULL or BootOption is NULL. **/ typedef diff --git a/MdePkg/Include/Protocol/DeviceIo.h b/MdePkg/Include/Protocol/DeviceIo.h index d84a6202effd..7d52f1238bea 100644 --- a/MdePkg/Include/Protocol/DeviceIo.h +++ b/MdePkg/Include/Protocol/DeviceIo.h @@ -4,14 +4,8 @@ Device IO is used to abstract hardware access to devices. It includes memory mapped IO, IO, PCI Config space, and DMA. - Copyright (c) 2006 - 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -27,16 +21,16 @@ typedef struct _EFI_DEVICE_IO_PROTOCOL EFI_DEVICE_IO_PROTOCOL; /// /// Protocol GUID name defined in EFI1.1. -/// +/// #define DEVICE_IO_PROTOCOL EFI_DEVICE_IO_PROTOCOL_GUID /// /// Protocol defined in EFI1.1. -/// +/// typedef EFI_DEVICE_IO_PROTOCOL EFI_DEVICE_IO_INTERFACE; /// -/// Device IO Access Width +/// Device IO Access Width /// typedef enum { IO_UINT8 = 0, @@ -44,7 +38,7 @@ typedef enum { IO_UINT32 = 2, IO_UINT64 = 3, // - // Below enumerations are added in "Extensible Firmware Interface Specification, + // Below enumerations are added in "Extensible Firmware Interface Specification, // Version 1.10, Specification Update, Version 001". // MMIO_COPY_UINT8 = 4, @@ -53,23 +47,23 @@ typedef enum { MMIO_COPY_UINT64 = 7 } EFI_IO_WIDTH; -/** +/** Enables a driver to access device registers in the appropriate memory or I/O space. - + @param This A pointer to the EFI_DEVICE_IO_INTERFACE instance. - @param Width Signifies the width of the I/O operations. - @param Address The base address of the I/O operations. + @param Width Signifies the width of the I/O operations. + @param Address The base address of the I/O operations. @param Count The number of I/O operations to perform. @param Buffer For read operations, the destination buffer to store the results. For write operations, the source buffer to write data from. If Width is MMIO_COPY_UINT8, MMIO_COPY_UINT16, MMIO_COPY_UINT32, or MMIO_COPY_UINT64, then - Buffer is interpreted as a base address of an I/O operation such as Address. + Buffer is interpreted as a base address of an I/O operation such as Address. @retval EFI_SUCCESS The data was read from or written to the device. - @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @retval EFI_INVALID_PARAMETER Width is invalid. - + **/ typedef EFI_STATUS @@ -86,19 +80,19 @@ typedef struct { EFI_DEVICE_IO Write; } EFI_IO_ACCESS; -/** +/** Provides an EFI Device Path for a PCI device with the given PCI configuration space address. - + @param This A pointer to the EFI_DEVICE_IO_INTERFACE instance. @param PciAddress The PCI configuration space address of the device whose Device Path - is going to be returned. + is going to be returned. @param PciDevicePath A pointer to the pointer for the EFI Device Path for PciAddress. - Memory for the Device Path is allocated from the pool. + Memory for the Device Path is allocated from the pool. @retval EFI_SUCCESS The PciDevicePath returns a pointer to a valid EFI Device Path. - @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @retval EFI_UNSUPPORTED The PciAddress does not map to a valid EFI Device Path. - + **/ typedef EFI_STATUS @@ -118,7 +112,7 @@ typedef enum { /// 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 @@ -128,9 +122,9 @@ typedef enum { EfiBusMasterCommonBuffer } EFI_IO_OPERATION_TYPE; -/** +/** Provides the device-specific addresses needed to access system memory. - + @param This A pointer to the EFI_DEVICE_IO_INTERFACE instance. @param Operation Indicates if the bus master is going to read or write to system memory. @param HostAddress The system memory address to map to the device. @@ -141,11 +135,11 @@ typedef enum { @param Mapping A resulting value to pass to Unmap(). @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes. - @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer. @retval EFI_INVALID_PARAMETER The Operation or HostAddress is undefined. @retval EFI_DEVICE_ERROR The system hardware could not map the requested address. - + **/ typedef EFI_STATUS @@ -158,15 +152,15 @@ EFI_STATUS OUT VOID **Mapping ); -/** +/** Completes the Map() operation and releases any corresponding resources. - + @param This A pointer to the EFI_DEVICE_IO_INTERFACE instance. @param Mapping A resulting value to pass to Unmap(). @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes. @retval EFI_DEVICE_ERROR The system hardware could not map the requested address. - + **/ typedef EFI_STATUS @@ -175,22 +169,22 @@ EFI_STATUS IN VOID *Mapping ); -/** +/** Allocates pages that are suitable for an EFIBusMasterCommonBuffer mapping. - + @param This A pointer to the EFI_DEVICE_IO_INTERFACE instance. @param Type The type allocation to perform. @param MemoryType The type of memory to allocate, EfiBootServicesData or EfiRuntimeServicesData. @param Pages The number of pages to allocate. - @param HostAddress A pointer to store the base address of the allocated range. + @param HostAddress A pointer to store the base address of the allocated range. @retval EFI_SUCCESS The requested memory pages were allocated. @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated. @retval EFI_INVALID_PARAMETER The requested memory type is invalid. @retval EFI_UNSUPPORTED The requested HostAddress is not supported on - this platform. - + this platform. + **/ typedef EFI_STATUS @@ -202,14 +196,14 @@ EFI_STATUS IN OUT EFI_PHYSICAL_ADDRESS *HostAddress ); -/** +/** Flushes any posted write data to the device. - + @param This A pointer to the EFI_DEVICE_IO_INTERFACE instance. @retval EFI_SUCCESS The buffers were flushed. - @retval EFI_DEVICE_ERROR The buffers were not flushed due to a hardware error. - + @retval EFI_DEVICE_ERROR The buffers were not flushed due to a hardware error. + **/ typedef EFI_STATUS @@ -217,18 +211,18 @@ EFI_STATUS IN EFI_DEVICE_IO_PROTOCOL *This ); -/** +/** Frees pages that were allocated with AllocateBuffer(). - - @param This A pointer to the EFI_DEVICE_IO_INTERFACE instance. + + @param This A pointer to the EFI_DEVICE_IO_INTERFACE instance. @param Pages The number of pages to free. @param HostAddress The base address of the range to free. @retval EFI_SUCCESS The requested memory pages were allocated. @retval EFI_NOT_FOUND The requested memory pages were not allocated with - AllocateBuffer(). + AllocateBuffer(). @retval EFI_INVALID_PARAMETER HostAddress is not page aligned or Pages is invalid. - + **/ typedef EFI_STATUS @@ -239,7 +233,7 @@ EFI_STATUS ); /// -/// This protocol provides the basic Memory, I/O, and PCI interfaces that +/// This protocol provides the basic Memory, I/O, and PCI interfaces that /// are used to abstract accesses to devices. /// struct _EFI_DEVICE_IO_PROTOCOL { diff --git a/MdePkg/Include/Protocol/DevicePath.h b/MdePkg/Include/Protocol/DevicePath.h index 1958a3dd180f..5eeca70c8bce 100644 --- a/MdePkg/Include/Protocol/DevicePath.h +++ b/MdePkg/Include/Protocol/DevicePath.h @@ -2,17 +2,11 @@ The device path protocol as defined in UEFI 2.0. The device path represents a programmatic path to a device, - from a software point of view. The path must persist from boot to boot, so + from a software point of view. The path must persist from boot to boot, so it can not contain things like PCI bus numbers that change from boot to boot. -Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -39,11 +33,11 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #pragma pack(1) /** - This protocol can be used on any device handle to obtain generic path/location - information concerning the physical device or logical device. If the handle does - not logically map to a physical device, the handle may not necessarily support - the device path protocol. The device path describes the location of the device - the handle is for. The size of the Device Path can be determined from the structures + This protocol can be used on any device handle to obtain generic path/location + information concerning the physical device or logical device. If the handle does + not logically map to a physical device, the handle may not necessarily support + the device path protocol. The device path describes the location of the device + the handle is for. The size of the Device Path can be determined from the structures that make up the Device Path. **/ typedef struct { @@ -53,20 +47,20 @@ typedef struct { ///< 0x04 Media Device Path. ///< 0x05 BIOS Boot Specification Device Path. ///< 0x7F End of Hardware Device Path. - + UINT8 SubType; ///< Varies by Type ///< 0xFF End Entire Device Path, or ///< 0x01 End This Instance of a Device Path and start a new ///< Device Path. - + UINT8 Length[2]; ///< Specific Device Path data. Type and Sub-Type define ///< type of data. Size of data is included in Length. - + } EFI_DEVICE_PATH_PROTOCOL; /// /// Device Path protocol definition for backward-compatible with EFI1.1. -/// +/// typedef EFI_DEVICE_PATH_PROTOCOL EFI_DEVICE_PATH; /// @@ -288,6 +282,21 @@ typedef struct { // } ACPI_ADR_DEVICE_PATH; +/// +/// ACPI NVDIMM Device Path SubType. +/// +#define ACPI_NVDIMM_DP 0x04 +/// +/// +typedef struct { + EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// NFIT Device Handle, the _ADR of the NVDIMM device. + /// The value of this field comes from Section 9.20.3 of the ACPI 6.2A specification. + /// + UINT32 NFITDeviceHandle; +} ACPI_NVDIMM_DEVICE_PATH; + #define ACPI_ADR_DISPLAY_TYPE_OTHER 0 #define ACPI_ADR_DISPLAY_TYPE_VGA 1 #define ACPI_ADR_DISPLAY_TYPE_TV 2 @@ -718,6 +727,18 @@ typedef struct { UINT8 StopBits; } UART_DEVICE_PATH; +/// +/// NVDIMM Namespace Device Path SubType. +/// +#define NVDIMM_NAMESPACE_DP 0x20 +typedef struct { + EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Namespace unique label identifier UUID. + /// + EFI_GUID Uuid; +} NVDIMM_NAMESPACE_DEVICE_PATH; + // // Use VENDOR_DEVICE_PATH struct // @@ -818,6 +839,22 @@ typedef struct { } NVME_NAMESPACE_DEVICE_PATH; /// +/// DNS Device Path SubType +/// +#define MSG_DNS_DP 0x1F +typedef struct { + EFI_DEVICE_PATH_PROTOCOL Header; + /// + /// Indicates the DNS server address is IPv4 or IPv6 address. + /// + UINT8 IsIPv6; + /// + /// Instance of the DNS server address. + /// + EFI_IP_ADDRESS DnsServerIp[]; +} DNS_DEVICE_PATH; + +/// /// Uniform Resource Identifiers (URI) Device Path SubType /// #define MSG_URI_DP 0x18 @@ -938,6 +975,15 @@ typedef struct { UINT8 SSId[32]; } WIFI_DEVICE_PATH; +/// +/// Bluetooth LE Device Path SubType. +/// +#define MSG_BLUETOOTH_LE_DP 0x1E +typedef struct { + EFI_DEVICE_PATH_PROTOCOL Header; + BLUETOOTH_LE_ADDRESS Address; +} BLUETOOTH_LE_DEVICE_PATH; + // // Media Device Path // @@ -1047,8 +1093,8 @@ typedef struct { #define MEDIA_PROTOCOL_DP 0x05 /// -/// 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. +/// 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. /// typedef struct { @@ -1243,6 +1289,7 @@ typedef union { SAS_DEVICE_PATH Sas; SASEX_DEVICE_PATH SasEx; NVME_NAMESPACE_DEVICE_PATH NvmeNamespace; + DNS_DEVICE_PATH Dns; URI_DEVICE_PATH Uri; BLUETOOTH_DEVICE_PATH Bluetooth; WIFI_DEVICE_PATH WiFi; @@ -1300,6 +1347,7 @@ typedef union { SAS_DEVICE_PATH *Sas; SASEX_DEVICE_PATH *SasEx; NVME_NAMESPACE_DEVICE_PATH *NvmeNamespace; + DNS_DEVICE_PATH *Dns; URI_DEVICE_PATH *Uri; BLUETOOTH_DEVICE_PATH *Bluetooth; WIFI_DEVICE_PATH *WiFi; @@ -1321,7 +1369,7 @@ typedef union { } EFI_DEV_PATH_PTR; #pragma pack() - + #define END_DEVICE_PATH_TYPE 0x7f #define END_ENTIRE_DEVICE_PATH_SUBTYPE 0xFF #define END_INSTANCE_DEVICE_PATH_SUBTYPE 0x01 diff --git a/MdePkg/Include/Protocol/DevicePathFromText.h b/MdePkg/Include/Protocol/DevicePathFromText.h index cbdbc466dcad..998fa5cd6562 100644 --- a/MdePkg/Include/Protocol/DevicePathFromText.h +++ b/MdePkg/Include/Protocol/DevicePathFromText.h @@ -1,15 +1,9 @@ /** @file - EFI_DEVICE_PATH_FROM_TEXT_PROTOCOL as defined in UEFI 2.0. + EFI_DEVICE_PATH_FROM_TEXT_PROTOCOL as defined in UEFI 2.0. This protocol provides service to convert text to device paths and device nodes. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -39,8 +33,8 @@ typedef EFI_DEVICE_PATH_PROTOCOL* (EFIAPI *EFI_DEVICE_PATH_FROM_TEXT_NODE)( IN CONST CHAR16 *TextDeviceNode - ); - + ); + /** Convert text to the binary representation of a device node. @@ -57,7 +51,7 @@ typedef EFI_DEVICE_PATH_PROTOCOL* (EFIAPI *EFI_DEVICE_PATH_FROM_TEXT_PATH)( IN CONST CHAR16 *TextDevicePath - ); + ); /// /// This protocol converts text to device paths and device nodes. diff --git a/MdePkg/Include/Protocol/DevicePathToText.h b/MdePkg/Include/Protocol/DevicePathToText.h index 923ee648404f..4a8cdaffb330 100644 --- a/MdePkg/Include/Protocol/DevicePathToText.h +++ b/MdePkg/Include/Protocol/DevicePathToText.h @@ -1,15 +1,9 @@ /** @file - EFI_DEVICE_PATH_TO_TEXT_PROTOCOL as defined in UEFI 2.0. + EFI_DEVICE_PATH_TO_TEXT_PROTOCOL as defined in UEFI 2.0. This protocol provides service to convert device nodes and paths to text. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -45,7 +39,7 @@ CHAR16* IN CONST EFI_DEVICE_PATH_PROTOCOL *DeviceNode, IN BOOLEAN DisplayOnly, IN BOOLEAN AllowShortcuts - ); + ); /** Convert a device path to its text representation. @@ -54,7 +48,7 @@ CHAR16* @param DisplayOnly If DisplayOnly is TRUE, then the shorter text representation of the display node is used, where applicable. If DisplayOnly is FALSE, then the longer text representation of the display node - is used. + is used. @param AllowShortcuts The AllowShortcuts is FALSE, then the shortcut forms of text representation for a device node cannot be used. @@ -68,7 +62,7 @@ CHAR16* IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, IN BOOLEAN DisplayOnly, IN BOOLEAN AllowShortcuts - ); + ); /// /// This protocol converts device paths and device nodes to text. diff --git a/MdePkg/Include/Protocol/DevicePathUtilities.h b/MdePkg/Include/Protocol/DevicePathUtilities.h index 35fd624f2c39..68c91f05f1a0 100644 --- a/MdePkg/Include/Protocol/DevicePathUtilities.h +++ b/MdePkg/Include/Protocol/DevicePathUtilities.h @@ -1,15 +1,9 @@ /** @file - EFI_DEVICE_PATH_UTILITIES_PROTOCOL as defined in UEFI 2.0. + EFI_DEVICE_PATH_UTILITIES_PROTOCOL as defined in UEFI 2.0. Use to create and manipulate device paths and device nodes. - Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -30,15 +24,15 @@ @param DevicePath Points to the start of the EFI device path. @return Size Size of the specified device path, in bytes, including the end-of-path tag. - @retval 0 DevicePath is NULL + @retval 0 DevicePath is NULL **/ typedef UINTN (EFIAPI *EFI_DEVICE_PATH_UTILS_GET_DEVICE_PATH_SIZE)( IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath - ); - + ); + /** Create a duplicate of the specified path. @@ -53,11 +47,11 @@ typedef EFI_DEVICE_PATH_PROTOCOL* (EFIAPI *EFI_DEVICE_PATH_UTILS_DUP_DEVICE_PATH)( IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath - ); + ); /** 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 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. @@ -73,11 +67,11 @@ EFI_DEVICE_PATH_PROTOCOL* (EFIAPI *EFI_DEVICE_PATH_UTILS_APPEND_PATH)( IN CONST EFI_DEVICE_PATH_PROTOCOL *Src1, IN CONST EFI_DEVICE_PATH_PROTOCOL *Src2 - ); - + ); + /** 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 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. @@ -110,7 +104,7 @@ EFI_DEVICE_PATH_PROTOCOL* (EFIAPI *EFI_DEVICE_PATH_UTILS_APPEND_INSTANCE)( IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathInstance - ); + ); /** Creates a copy of the current device path instance and returns a pointer to the next device path @@ -119,7 +113,7 @@ EFI_DEVICE_PATH_PROTOCOL* @param DevicePathInstance On input, this holds the pointer to the current device path instance. On output, this holds the pointer to the next device path instance or NULL if there are no more device - path instances in the device path. + 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 NULL. If NULL, then the instance size is not output. @@ -133,7 +127,7 @@ EFI_DEVICE_PATH_PROTOCOL* (EFIAPI *EFI_DEVICE_PATH_UTILS_GET_NEXT_INSTANCE)( IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePathInstance, OUT UINTN *DevicePathInstanceSize - ); + ); /** Creates a device node @@ -156,7 +150,7 @@ EFI_DEVICE_PATH_PROTOCOL* IN UINT8 NodeType, IN UINT8 NodeSubType, IN UINT16 NodeLength -); +); /** Returns whether a device path is multi-instance. @@ -171,11 +165,11 @@ typedef BOOLEAN (EFIAPI *EFI_DEVICE_PATH_UTILS_IS_MULTI_INSTANCE)( IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath - ); - + ); + /// /// This protocol is used to creates and manipulates device paths and device nodes. -/// +/// typedef struct { EFI_DEVICE_PATH_UTILS_GET_DEVICE_PATH_SIZE GetDevicePathSize; EFI_DEVICE_PATH_UTILS_DUP_DEVICE_PATH DuplicateDevicePath; @@ -187,6 +181,6 @@ typedef struct { EFI_DEVICE_PATH_UTILS_CREATE_NODE CreateDeviceNode; } EFI_DEVICE_PATH_UTILITIES_PROTOCOL; -extern EFI_GUID gEfiDevicePathUtilitiesProtocolGuid; +extern EFI_GUID gEfiDevicePathUtilitiesProtocolGuid; #endif diff --git a/MdePkg/Include/Protocol/Dhcp4.h b/MdePkg/Include/Protocol/Dhcp4.h index 5dcd47c76b85..05a0a6e20403 100644 --- a/MdePkg/Include/Protocol/Dhcp4.h +++ b/MdePkg/Include/Protocol/Dhcp4.h @@ -4,16 +4,10 @@ These protocols are used to collect configuration information for the EFI IPv4 Protocol drivers and to provide DHCPv4 server and PXE boot server discovery services. -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: This Protocol was introduced in UEFI Specification 2.0. **/ @@ -82,7 +76,7 @@ typedef struct { /// UINT32 Size; /// - /// Length of the EFI_DHCP4_PACKET from the first byte of the Header field + /// Length of the EFI_DHCP4_PACKET from the first byte of the Header field /// to the last byte of the Option[] field. /// UINT32 Length; @@ -183,24 +177,24 @@ typedef enum{ /// Dhcp4BoundCompleted = 0x08, /// - /// It is time to enter the Dhcp4Renewing state and to contact the server + /// It is time to enter the Dhcp4Renewing state and to contact the server /// that originally issued the network address. No packet is associated with this event. /// Dhcp4EnterRenewing = 0x09, /// - /// It is time to enter the Dhcp4Rebinding state and to contact any server. + /// It is time to enter the Dhcp4Rebinding state and to contact any server. /// No packet is associated with this event. /// Dhcp4EnterRebinding = 0x0a, /// - /// The configured IP address was lost either because the lease has expired, - /// the user released the configuration, or a DHCPNAK packet was received in + /// The configured IP address was lost either because the lease has expired, + /// the user released the configuration, or a DHCPNAK packet was received in /// the Dhcp4Renewing or Dhcp4Rebinding state. No packet is associated with this event. /// Dhcp4AddressLost = 0x0b, /// - /// The DHCP process failed because a DHCPNAK packet was received or the user - /// aborted the DHCP process at a time when the configuration was not available yet. + /// The DHCP process failed because a DHCPNAK packet was received or the user + /// aborted the DHCP process at a time when the configuration was not available yet. /// No packet is associated with this event. /// Dhcp4Fail = 0x0c @@ -208,7 +202,7 @@ typedef enum{ /** Callback routine. - + EFI_DHCP4_CALLBACK is provided by the consumer of the EFI DHCPv4 Protocol driver to intercept events that occurred in the configuration process. This structure provides advanced control of each state transition of the DHCP process. The @@ -257,8 +251,8 @@ typedef struct { /// UINT32 DiscoverTryCount; /// - /// The maximum amount of time (in seconds) to wait for returned packets in each - /// of the retries. Timeout values of zero will default to a timeout value + /// The maximum amount of time (in seconds) to wait for returned packets in each + /// of the retries. Timeout values of zero will default to a timeout value /// of one second. Set to NULL to use default timeout values. /// UINT32 *DiscoverTimeout; @@ -269,21 +263,21 @@ typedef struct { /// UINT32 RequestTryCount; /// - /// The maximum amount of time (in seconds) to wait for return packets in each of the retries. - /// Timeout values of zero will default to a timeout value of one second. + /// The maximum amount of time (in seconds) to wait for return packets in each of the retries. + /// Timeout values of zero will default to a timeout value of one second. /// Set to NULL to use default timeout values. /// UINT32 *RequestTimeout; /// /// For a DHCPDISCOVER, setting this parameter to the previously allocated IP - /// address will cause the EFI DHCPv4 Protocol driver to enter the Dhcp4InitReboot state. + /// address will cause the EFI DHCPv4 Protocol driver to enter the Dhcp4InitReboot state. /// And set this field to 0.0.0.0 to enter the Dhcp4Init state. /// For a DHCPINFORM this parameter should be set to the client network address /// which was assigned to the client during a DHCPDISCOVER. /// EFI_IPv4_ADDRESS ClientAddress; /// - /// The callback function to intercept various events that occurred in + /// The callback function to intercept various events that occurred in /// the DHCP configuration process. Set to NULL to ignore all those events. /// EFI_DHCP4_CALLBACK Dhcp4Callback; @@ -308,7 +302,7 @@ typedef struct { typedef struct { /// - /// The EFI DHCPv4 Protocol driver operating state. + /// The EFI DHCPv4 Protocol driver operating state. /// EFI_DHCP4_STATE State; /// @@ -329,7 +323,7 @@ typedef struct { /// EFI_IPv4_ADDRESS ServerAddress; /// - /// The router IP address that was acquired from the DHCP server. + /// The router IP address that was acquired from the DHCP server. /// May be zero if the server does not offer this address. /// EFI_IPv4_ADDRESS RouterAddress; @@ -338,8 +332,8 @@ typedef struct { /// EFI_IPv4_ADDRESS SubnetMask; /// - /// The lease time (in 1-second units) of the configured IP address. - /// The value 0xFFFFFFFF means that the lease time is infinite. + /// The lease time (in 1-second units) of the configured IP address. + /// The value 0xFFFFFFFF means that the lease time is infinite. /// A default lease of 7 days is used if the DHCP server does not provide a value. /// UINT32 LeaseTime; @@ -356,12 +350,12 @@ typedef struct { /// EFI_IPv4_ADDRESS ListenAddress; /// - /// The subnet mask of above listening unicast/broadcast IP address. + /// The subnet mask of above listening unicast/broadcast IP address. /// Ignored if ListenAddress is a multicast address. /// EFI_IPv4_ADDRESS SubnetMask; /// - /// Alternate station source (or listening) port number. + /// Alternate station source (or listening) port number. /// If zero, then the default station port number (68) will be used. /// UINT16 ListenPort; @@ -374,7 +368,7 @@ typedef struct { /// EFI_STATUS Status; /// - /// If not NULL, the event that will be signaled when the collection process + /// If not NULL, the event that will be signaled when the collection process /// completes. If NULL, this function will busy-wait until the collection process competes. /// EFI_EVENT CompletionEvent; @@ -395,7 +389,7 @@ typedef struct { /// UINT32 ListenPointCount; /// - /// An array of station address and port number pairs that are used as receiving filters. + /// An array of station address and port number pairs that are used as receiving filters. /// The first entry is also used as the source address and source port of the outgoing packet. /// EFI_DHCP4_LISTEN_POINT *ListenPoints; @@ -420,7 +414,7 @@ typedef struct { /** Returns the current operating mode and cached data packet for the EFI DHCPv4 Protocol driver. - + The GetModeData() function returns the current operating mode and cached data packet for the EFI DHCPv4 Protocol driver. @@ -510,7 +504,7 @@ EFI_STATUS time when each event occurs in this process, the callback function that was set by EFI_DHCP4_PROTOCOL.Configure() will be called and the user can take this opportunity to control the process. - + @param This The pointer to the EFI_DHCP4_PROTOCOL instance. @param CompletionEvent If not NULL, it indicates the event that will be signaled when the EFI DHCPv4 Protocol driver is transferred into the @@ -544,7 +538,7 @@ EFI_STATUS /** Extends the lease time by sending a request packet. - + The RenewRebind() function is used to manually extend the lease time when the EFI DHCPv4 Protocol driver is in the Dhcp4Bound state, and the lease time has not expired yet. This function will send a request packet to the previously @@ -617,7 +611,7 @@ EFI_STATUS /** Stops the current address configuration. - + The Stop() function is used to stop the DHCP configuration process. After this function is called successfully, the EFI DHCPv4 Protocol driver is transferred into the Dhcp4Stopped state. EFI_DHCP4_PROTOCOL.Configure() needs to be called @@ -686,7 +680,7 @@ EFI_STATUS /** Transmits a DHCP formatted packet and optionally waits for responses. - + The TransmitReceive() function is used to transmit a DHCP packet and optionally wait for the response from servers. This function does not change the state of the EFI DHCPv4 Protocol driver. It can be used at any time because of this. @@ -719,7 +713,7 @@ EFI_STATUS /** Parses the packed DHCP option data. - + The Parse() function is used to retrieve the option list from a DHCP packet. If *OptionCount isn't zero, and there is enough space for all the DHCP options in the Packet, each element of PacketOptionList is set to point to somewhere in diff --git a/MdePkg/Include/Protocol/Dhcp6.h b/MdePkg/Include/Protocol/Dhcp6.h index 8e0ae27eb934..ca79afa2d546 100644 --- a/MdePkg/Include/Protocol/Dhcp6.h +++ b/MdePkg/Include/Protocol/Dhcp6.h @@ -2,16 +2,10 @@ UEFI Dynamic Host Configuration Protocol 6 Definition, which is used to get IPv6 addresses and other configuration parameters from DHCPv6 servers. - Copyright (c) 2008 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: + Copyright (c) 2008 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: This Protocol is introduced in UEFI Specification 2.2 **/ @@ -31,9 +25,9 @@ typedef struct _EFI_DHCP6_PROTOCOL EFI_DHCP6_PROTOCOL; -typedef enum { +typedef enum { /// - /// The EFI DHCPv6 Protocol instance is configured, and start() needs + /// The EFI DHCPv6 Protocol instance is configured, and start() needs /// to be called /// Dhcp6Init = 0x0, @@ -43,7 +37,7 @@ typedef enum { /// Dhcp6Selecting = 0x1, /// - /// A Request is sent out to the DHCPv6 server, and the EFI DHCPv6 + /// A Request is sent out to the DHCPv6 server, and the EFI DHCPv6 /// Protocol instance is waiting for Reply packet. /// Dhcp6Requesting = 0x2, @@ -54,7 +48,7 @@ typedef enum { /// Dhcp6Declining = 0x3, /// - /// A Confirm packet is sent out to confirm the IPv6 addresses of the + /// A Confirm packet is sent out to confirm the IPv6 addresses of the /// configured IA, and the EFI DHCPv6 Protocol instance is waiting for Reply packet. /// Dhcp6Confirming = 0x4, @@ -80,55 +74,55 @@ typedef enum { } EFI_DHCP6_STATE; typedef enum { - /// + /// /// A Solicit packet is about to be sent. The packet is passed to Dhcp6Callback and /// can be modified or replaced in Dhcp6Callback. /// Dhcp6SendSolicit = 0x0, - /// + /// /// An Advertise packet is received and will be passed to Dhcp6Callback. /// Dhcp6RcvdAdvertise = 0x1, - /// + /// /// It is time for Dhcp6Callback to determine whether select the default Advertise /// packet by RFC 3315 policy, or overwrite it by specific user policy. /// Dhcp6SelectAdvertise = 0x2, - /// + /// /// A Request packet is about to be sent. The packet is passed to Dhcp6Callback and /// can be modified or replaced in Dhcp6Callback. /// Dhcp6SendRequest = 0x3, - /// + /// /// A Reply packet is received and will be passed to Dhcp6Callback. /// Dhcp6RcvdReply = 0x4, - /// + /// /// A Reconfigure packet is received and will be passed to Dhcp6Callback. /// Dhcp6RcvdReconfigure = 0x5, - /// + /// /// A Decline packet is about to be sent. The packet is passed to Dhcp6Callback and /// can be modified or replaced in Dhcp6Callback. /// Dhcp6SendDecline = 0x6, - /// + /// /// A Confirm packet is about to be sent. The packet is passed to Dhcp6Callback and /// can be modified or replaced in Dhcp6Callback. /// Dhcp6SendConfirm = 0x7, - /// + /// /// A Release packet is about to be sent. The packet is passed to Dhcp6Callback and /// can be modified or replaced in Dhcp6Callback. /// Dhcp6SendRelease = 0x8, - /// + /// /// A Renew packet is about to be sent. The packet is passed to Dhcp6Callback and - /// can be modified or replaced in Dhcp6Callback. + /// can be modified or replaced in Dhcp6Callback. /// Dhcp6EnterRenewing = 0x9, - /// - /// A Rebind packet is about to be sent. The packet is passed to Dhcp6Callback and + /// + /// A Rebind packet is about to be sent. The packet is passed to Dhcp6Callback and /// can be modified or replaced in Dhcp6Callback. /// Dhcp6EnterRebinding = 0xa @@ -147,7 +141,7 @@ typedef enum { /// /// EFI_DHCP6_PACKET_OPTION /// defines the format of the DHCPv6 option, See RFC 3315 for more information. -/// This data structure is used to reference option data that is packed in the DHCPv6 packet. +/// This data structure is used to reference option data that is packed in the DHCPv6 packet. /// typedef struct { /// @@ -167,7 +161,7 @@ typedef struct { /// /// EFI_DHCP6_HEADER -/// defines the format of the DHCPv6 header. See RFC 3315 for more information. +/// defines the format of the DHCPv6 header. See RFC 3315 for more information. /// typedef struct{ /// @@ -181,7 +175,7 @@ typedef struct{ } EFI_DHCP6_HEADER; /// -/// EFI_DHCP6_PACKET +/// EFI_DHCP6_PACKET /// defines the format of the DHCPv6 packet. See RFC 3315 for more information. /// typedef struct { @@ -225,19 +219,19 @@ typedef struct { /// UINT32 Irt; /// - /// Maximum retransmission count for one packet. If Mrc is zero, there's no upper limit + /// Maximum retransmission count for one packet. If Mrc is zero, there's no upper limit /// for retransmission count. /// UINT32 Mrc; /// - /// Maximum retransmission timeout for each retry. It's the upper bound of the number of - /// retransmission timeout. If Mrt is zero, there is no upper limit for retransmission + /// Maximum retransmission timeout for each retry. It's the upper bound of the number of + /// retransmission timeout. If Mrt is zero, there is no upper limit for retransmission /// timeout. /// UINT32 Mrt; /// - /// Maximum retransmission duration for one packet. It's the upper bound of the numbers - /// the client may retransmit a message. If Mrd is zero, there's no upper limit for + /// Maximum retransmission duration for one packet. It's the upper bound of the numbers + /// the client may retransmit a message. If Mrd is zero, there's no upper limit for /// retransmission duration. /// UINT32 Mrd; @@ -281,7 +275,7 @@ typedef struct { /// UINT32 IaAddressCount; /// - /// List of the IPv6 addresses of the configured IA. When the state of the configured IA is + /// List of the IPv6 addresses of the configured IA. When the state of the configured IA is /// in Dhcp6Bound, Dhcp6Renewing and Dhcp6Rebinding, the IPv6 addresses are usable. /// EFI_DHCP6_IA_ADDRESS IaAddress[1]; @@ -300,39 +294,39 @@ typedef struct { } EFI_DHCP6_MODE_DATA; /** - EFI_DHCP6_CALLBACK is provided by the consumer of the EFI DHCPv6 Protocol instance to + EFI_DHCP6_CALLBACK is provided by the consumer of the EFI DHCPv6 Protocol instance to intercept events that occurs in the DHCPv6 S.A.R.R process. - @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance that is used to configure this + @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance that is used to configure this callback function. @param[in] Context Pointer to the context that is initialized by EFI_DHCP6_PROTOCOL.Configure(). @param[in] CurrentState The current state of the configured IA. @param[in] Dhcp6Event The event that occurs in the current state, which usually means a state transition. @param[in] Packet Pointer to the DHCPv6 packet that is about to be sent or has been received. - The EFI DHCPv6 Protocol instance is responsible for freeing the buffer. - @param[out] NewPacket Pointer to the new DHCPv6 packet to overwrite the Packet. NewPacket can not - share the buffer with Packet. If *NewPacket is not NULL, the EFI DHCPv6 + The EFI DHCPv6 Protocol instance is responsible for freeing the buffer. + @param[out] NewPacket Pointer to the new DHCPv6 packet to overwrite the Packet. NewPacket can not + share the buffer with Packet. If *NewPacket is not NULL, the EFI DHCPv6 Protocol instance is responsible for freeing the buffer. @retval EFI_SUCCESS Tell the EFI DHCPv6 Protocol instance to continue the DHCPv6 S.A.R.R process. - @retval EFI_ABORTED Tell the EFI DHCPv6 Protocol instance to abort the DHCPv6 S.A.R.R process, + @retval EFI_ABORTED Tell the EFI DHCPv6 Protocol instance to abort the DHCPv6 S.A.R.R process, and the state of the configured IA will be transferred to Dhcp6Init. **/ -typedef -EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_DHCP6_CALLBACK)( IN EFI_DHCP6_PROTOCOL *This, IN VOID *Context, IN EFI_DHCP6_STATE CurrentState, IN EFI_DHCP6_EVENT Dhcp6Event, - IN EFI_DHCP6_PACKET *Packet, + IN EFI_DHCP6_PACKET *Packet, OUT EFI_DHCP6_PACKET **NewPacket OPTIONAL ); typedef struct { /// - /// The callback function is to intercept various events that occur in the DHCPv6 S.A.R.R + /// The callback function is to intercept various events that occur in the DHCPv6 S.A.R.R /// process. Set to NULL to ignore all those events. /// EFI_DHCP6_CALLBACK Dhcp6Callback; @@ -345,11 +339,11 @@ typedef struct { /// UINT32 OptionCount; /// - /// List of the DHCPv6 options to be included in Solicit and Request packet. The buffer - /// can be freed after EFI_DHCP6_PROTOCOL.Configure() returns. Ignored if - /// OptionCount is zero. OptionList should not contain Client Identifier option - /// and any IA option, which will be appended by EFI DHCPv6 Protocol instance - /// automatically. + /// List of the DHCPv6 options to be included in Solicit and Request packet. The buffer + /// can be freed after EFI_DHCP6_PROTOCOL.Configure() returns. Ignored if + /// OptionCount is zero. OptionList should not contain Client Identifier option + /// and any IA option, which will be appended by EFI DHCPv6 Protocol instance + /// automatically. /// EFI_DHCP6_PACKET_OPTION **OptionList; /// @@ -357,40 +351,40 @@ typedef struct { /// EFI_DHCP6_IA_DESCRIPTOR IaDescriptor; /// - /// If not NULL, the event will be signaled when any IPv6 address information of the - /// configured IA is updated, including IPv6 address, preferred lifetime and valid - /// lifetime, or the DHCPv6 S.A.R.R process fails. Otherwise, Start(), - /// renewrebind(), decline(), release() and stop() will be blocking + /// If not NULL, the event will be signaled when any IPv6 address information of the + /// configured IA is updated, including IPv6 address, preferred lifetime and valid + /// lifetime, or the DHCPv6 S.A.R.R process fails. Otherwise, Start(), + /// renewrebind(), decline(), release() and stop() will be blocking /// operations, and they will wait for the exchange process completion or failure. /// EFI_EVENT IaInfoEvent; /// - /// If TRUE, the EFI DHCPv6 Protocol instance is willing to accept Reconfigure packet. - /// Otherwise, it will ignore it. Reconfigure Accept option can not be specified through + /// If TRUE, the EFI DHCPv6 Protocol instance is willing to accept Reconfigure packet. + /// Otherwise, it will ignore it. Reconfigure Accept option can not be specified through /// OptionList parameter. /// BOOLEAN ReconfigureAccept; /// - /// If TRUE, the EFI DHCPv6 Protocol instance will send Solicit packet with Rapid - /// Commit option. Otherwise, Rapid Commit option will not be included in Solicit + /// If TRUE, the EFI DHCPv6 Protocol instance will send Solicit packet with Rapid + /// Commit option. Otherwise, Rapid Commit option will not be included in Solicit /// packet. Rapid Commit option can not be specified through OptionList parameter. /// BOOLEAN RapidCommit; /// - /// Parameter to control Solicit packet retransmission behavior. The + /// Parameter to control Solicit packet retransmission behavior. The /// buffer can be freed after EFI_DHCP6_PROTOCOL.Configure() returns. /// EFI_DHCP6_RETRANSMISSION *SolicitRetransmission; } EFI_DHCP6_CONFIG_DATA; /** - EFI_DHCP6_INFO_CALLBACK is provided by the consumer of the EFI DHCPv6 Protocol + EFI_DHCP6_INFO_CALLBACK is provided by the consumer of the EFI DHCPv6 Protocol instance to intercept events that occurs in the DHCPv6 Information Request exchange process. - @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance that is used to configure this + @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance that is used to configure this callback function. @param[in] Context Pointer to the context that is initialized in the EFI_DHCP6_PROTOCOL.InfoRequest(). - @param[in] Packet Pointer to Reply packet that has been received. The EFI DHCPv6 Protocol instance is + @param[in] Packet Pointer to Reply packet that has been received. The EFI DHCPv6 Protocol instance is responsible for freeing the buffer. @retval EFI_SUCCESS Tell the EFI DHCPv6 Protocol instance to finish Information Request exchange process. @@ -410,20 +404,20 @@ EFI_STATUS Retrieve the current operating mode data and configuration data for the EFI DHCPv6 Protocol instance. @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance. - @param[out] Dhcp6ModeData Pointer to the DHCPv6 mode data structure. The caller is responsible for freeing this + @param[out] Dhcp6ModeData Pointer to the DHCPv6 mode data structure. The caller is responsible for freeing this structure and each reference buffer. - @param[out] Dhcp6ConfigData Pointer to the DHCPv6 configuration data structure. The caller is responsible for + @param[out] Dhcp6ConfigData Pointer to the DHCPv6 configuration data structure. The caller is responsible for freeing this structure and each reference buffer. @retval EFI_SUCCESS The mode data was returned. @retval EFI_ACCESS_DENIED The EFI DHCPv6 Protocol instance has not been configured when Dhcp6ConfigData is not NULL. @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE: - - This is NULL. + - This is NULL. - Both Dhcp6ConfigData and Dhcp6ModeData are NULL. **/ -typedef -EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_DHCP6_GET_MODE_DATA)( IN EFI_DHCP6_PROTOCOL *This, OUT EFI_DHCP6_MODE_DATA *Dhcp6ModeData OPTIONAL, @@ -433,15 +427,15 @@ EFI_STATUS /** Initialize or clean up the configuration data for the EFI DHCPv6 Protocol instance. - The Configure() function is used to initialize or clean up the configuration data of the EFI + The Configure() function is used to initialize or clean up the configuration data of the EFI DHCPv6 Protocol instance. - - When Dhcp6CfgData is not NULL and Configure() is called successfully, the - configuration data will be initialized in the EFI DHCPv6 Protocol instance and the state of the + - When Dhcp6CfgData is not NULL and Configure() is called successfully, the + configuration data will be initialized in the EFI DHCPv6 Protocol instance and the state of the configured IA will be transferred into Dhcp6Init. - - When Dhcp6CfgData is NULL and Configure() is called successfully, the configuration + - When Dhcp6CfgData is NULL and Configure() is called successfully, the configuration data will be cleaned up and no IA will be associated with the EFI DHCPv6 Protocol instance. - To update the configuration data for an EFI DCHPv6 Protocol instance, the original data must be + To update the configuration data for an EFI DCHPv6 Protocol instance, the original data must be cleaned up before setting the new configuration data. @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance. @@ -449,24 +443,24 @@ EFI_STATUS @retval EFI_SUCCESS The mode data was returned. @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE - - This is NULL. + - This is NULL. - OptionCount > 0 and OptionList is NULL. - OptionList is not NULL, and Client Id option, Reconfigure Accept option, Rapid Commit option or any IA option is specified in the OptionList. - IaDescriptor.Type is neither EFI_DHCP6_IA_TYPE_NA nor EFI_DHCP6_IA_TYPE_NA. - IaDescriptor is not unique. - Both IaInfoEvent and SolicitRetransimssion are NULL. - - SolicitRetransmission is not NULL, and both SolicitRetransimssion->Mrc and + - SolicitRetransmission is not NULL, and both SolicitRetransimssion->Mrc and SolicitRetransmission->Mrd are zero. - @retval EFI_ACCESS_DENIED The EFI DHCPv6 Protocol instance has been already configured + @retval EFI_ACCESS_DENIED The EFI DHCPv6 Protocol instance has been already configured when Dhcp6CfgData is not NULL. - The EFI DHCPv6 Protocol instance has already started the + The EFI DHCPv6 Protocol instance has already started the DHCPv6 S.A.R.R when Dhcp6CfgData is NULL. @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_DHCP6_CONFIGURE)( IN EFI_DHCP6_PROTOCOL *This, @@ -476,13 +470,13 @@ EFI_STATUS /** Start the DHCPv6 S.A.R.R process. - The Start() function starts the DHCPv6 S.A.R.R process. This function can be called only when + The Start() function starts the DHCPv6 S.A.R.R process. This function can be called only when the state of the configured IA is in the Dhcp6Init state. If the DHCPv6 S.A.R.R process completes - successfully, the state of the configured IA will be transferred through Dhcp6Selecting and - Dhcp6Requesting to Dhcp6Bound state. The update of the IPv6 addresses will be notified through - EFI_DHCP6_CONFIG_DATA.IaInfoEvent. At the time when each event occurs in this process, the - callback function set by EFI_DHCP6_PROTOCOL.Configure() will be called and the user can take - this opportunity to control the process. If EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL, the + successfully, the state of the configured IA will be transferred through Dhcp6Selecting and + Dhcp6Requesting to Dhcp6Bound state. The update of the IPv6 addresses will be notified through + EFI_DHCP6_CONFIG_DATA.IaInfoEvent. At the time when each event occurs in this process, the + callback function set by EFI_DHCP6_PROTOCOL.Configure() will be called and the user can take + this opportunity to control the process. If EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL, the Start() function call is a blocking operation. It will return after the DHCPv6 S.A.R.R process completes or aborted by users. If the process is aborted by system or network error, the state of the configured IA will be transferred to Dhcp6Init. The Start() function can be called again to @@ -490,10 +484,10 @@ EFI_STATUS @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance. - @retval EFI_SUCCESS The DHCPv6 S.A.R.R process is completed and at least one IPv6 - address has been bound to the configured IA when - EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL. - The DHCPv6 S.A.R.R process is started when + @retval EFI_SUCCESS The DHCPv6 S.A.R.R process is completed and at least one IPv6 + address has been bound to the configured IA when + EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL. + The DHCPv6 S.A.R.R process is started when EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL. @retval EFI_ACCESS_DENIED The EFI DHCPv6 Child instance hasn't been configured. @retval EFI_INVALID_PARAMETER This is NULL. @@ -501,13 +495,13 @@ EFI_STATUS @retval EFI_ALREADY_STARTED The DHCPv6 S.A.R.R process has already started. @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. @retval EFI_NO_RESPONSE The DHCPv6 S.A.R.R process failed because of no response. - @retval EFI_NO_MAPPING No IPv6 address has been bound to the configured IA after the + @retval EFI_NO_MAPPING No IPv6 address has been bound to the configured IA after the DHCPv6 S.A.R.R process. @retval EFI_ABORTED The DHCPv6 S.A.R.R process aborted by user. @retval EFI_NO_MEDIA There was a media error. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_DHCP6_START)( IN EFI_DHCP6_PROTOCOL *This @@ -517,19 +511,19 @@ EFI_STATUS Request configuration information without the assignment of any IA addresses of the client. The InfoRequest() function is used to request configuration information without the assignment - of any IPv6 address of the client. Client sends out Information Request packet to obtain - the required configuration information, and DHCPv6 server responds with Reply packet containing - the information for the client. The received Reply packet will be passed to the user by + of any IPv6 address of the client. Client sends out Information Request packet to obtain + the required configuration information, and DHCPv6 server responds with Reply packet containing + the information for the client. The received Reply packet will be passed to the user by ReplyCallback function. If user returns EFI_NOT_READY from ReplyCallback, the EFI DHCPv6 - Protocol instance will continue to receive other Reply packets unless timeout according to - the Retransmission parameter. Otherwise, the Information Request exchange process will be + Protocol instance will continue to receive other Reply packets unless timeout according to + the Retransmission parameter. Otherwise, the Information Request exchange process will be finished successfully if user returns EFI_SUCCESS from ReplyCallback. @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance. @param[in] SendClientId If TRUE, the EFI DHCPv6 Protocol instance will build Client Identifier option and include it into Information Request packet. If FALSE, Client Identifier option will not be included. - Client Identifier option can not be specified through OptionList + Client Identifier option can not be specified through OptionList parameter. @param[in] OptionRequest Pointer to the Option Request option in the Information Request packet. Option Request option can not be specified through @@ -543,29 +537,29 @@ EFI_STATUS returns. @param[in] TimeoutEvent If not NULL, this event is signaled when the information request exchange aborted because of no response. If NULL, the function - call is a blocking operation; and it will return after the + call is a blocking operation; and it will return after the information-request exchange process finish or aborted by users. @param[in] ReplyCallback The callback function is to intercept various events that occur in the Information Request exchange process. It should not be set to NULL. @param[in] CallbackContext Pointer to the context that will be passed to ReplyCallback. - @retval EFI_SUCCESS The DHCPv6 S.A.R.R process is completed and at least one IPv6 - @retval EFI_SUCCESS The DHCPv6 information request exchange process completed + @retval EFI_SUCCESS The DHCPv6 S.A.R.R process is completed and at least one IPv6 + @retval EFI_SUCCESS The DHCPv6 information request exchange process completed when TimeoutEvent is NULL. Information Request packet has been sent to DHCPv6 server when TimeoutEvent is not NULL. @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE: - - This is NULL. + - This is NULL. - OptionRequest is NULL or OptionRequest->OpCode is invalid. - OptionCount > 0 and OptionList is NULL. - - OptionList is not NULL, and Client Identify option or + - OptionList is not NULL, and Client Identify option or Option Request option is specified in the OptionList. - Retransimssion is NULL. - Both Retransimssion->Mrc and Retransmission->Mrd are zero. - ReplyCallback is NULL. @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. - @retval EFI_NO_RESPONSE The DHCPv6 information request exchange process failed - because of no response, or not all requested-options are + @retval EFI_NO_RESPONSE The DHCPv6 information request exchange process failed + because of no response, or not all requested-options are responded by DHCPv6 servers when Timeout happened. @retval EFI_ABORTED The DHCPv6 information request exchange process aborted by user. @@ -578,7 +572,7 @@ EFI_STATUS IN EFI_DHCP6_PACKET_OPTION *OptionRequest, IN UINT32 OptionCount, IN EFI_DHCP6_PACKET_OPTION *OptionList[] OPTIONAL, - IN EFI_DHCP6_RETRANSMISSION *Retransmission, + IN EFI_DHCP6_RETRANSMISSION *Retransmission, IN EFI_EVENT TimeoutEvent OPTIONAL, IN EFI_DHCP6_INFO_CALLBACK ReplyCallback, IN VOID *CallbackContext OPTIONAL @@ -588,38 +582,38 @@ EFI_STATUS Manually extend the valid and preferred lifetimes for the IPv6 addresses of the configured IA and update other configuration parameters by sending Renew or Rebind packet. - The RenewRebind() function is used to manually extend the valid and preferred lifetimes for the - IPv6 addresses of the configured IA and update other configuration parameters by sending Renew or - Rebind packet. - - When RebindRequest is FALSE and the state of the configured IA is Dhcp6Bound, it - will send Renew packet to the previously DHCPv6 server and transfer the state of the configured - IA to Dhcp6Renewing. If valid Reply packet received, the state transfers to Dhcp6Bound - and the valid and preferred timer restarts. If fails, the state transfers to Dhcp6Bound but the - timer continues. - - When RebindRequest is TRUE and the state of the configured IA is Dhcp6Bound, it will - send Rebind packet. If valid Reply packet received, the state transfers to Dhcp6Bound and the + The RenewRebind() function is used to manually extend the valid and preferred lifetimes for the + IPv6 addresses of the configured IA and update other configuration parameters by sending Renew or + Rebind packet. + - When RebindRequest is FALSE and the state of the configured IA is Dhcp6Bound, it + will send Renew packet to the previously DHCPv6 server and transfer the state of the configured + IA to Dhcp6Renewing. If valid Reply packet received, the state transfers to Dhcp6Bound + and the valid and preferred timer restarts. If fails, the state transfers to Dhcp6Bound but the + timer continues. + - When RebindRequest is TRUE and the state of the configured IA is Dhcp6Bound, it will + send Rebind packet. If valid Reply packet received, the state transfers to Dhcp6Bound and the valid and preferred timer restarts. If fails, the state transfers to Dhcp6Init and the IA can't be used. @param[in] This Pointer to the EFI_DHCP4_PROTOCOL instance. - @param[in] RebindRequest If TRUE, it will send Rebind packet and enter the Dhcp6Rebinding state. + @param[in] RebindRequest If TRUE, it will send Rebind packet and enter the Dhcp6Rebinding state. Otherwise, it will send Renew packet and enter the Dhcp6Renewing state. - @retval EFI_SUCCESS The DHCPv6 renew/rebind exchange process has completed and at + @retval EFI_SUCCESS The DHCPv6 renew/rebind exchange process has completed and at least one IPv6 address of the configured IA has been bound again - when EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL. - The EFI DHCPv6 Protocol instance has sent Renew or Rebind packet + when EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL. + The EFI DHCPv6 Protocol instance has sent Renew or Rebind packet when EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL. @retval EFI_ACCESS_DENIED The EFI DHCPv6 Child instance hasn't been configured, or the state of the configured IA is not in Dhcp6Bound. - @retval EFI_ALREADY_STARTED The state of the configured IA has already entered Dhcp6Renewing - when RebindRequest is FALSE. - The state of the configured IA has already entered Dhcp6Rebinding + @retval EFI_ALREADY_STARTED The state of the configured IA has already entered Dhcp6Renewing + when RebindRequest is FALSE. + The state of the configured IA has already entered Dhcp6Rebinding when RebindRequest is TRUE. @retval EFI_INVALID_PARAMETER This is NULL. @retval EFI_DEVICE_ERROR An unexpected system or system error occurred. @retval EFI_NO_RESPONSE The DHCPv6 renew/rebind exchange process failed because of no response. - @retval EFI_NO_MAPPING No IPv6 address has been bound to the configured IA after the DHCPv6 + @retval EFI_NO_MAPPING No IPv6 address has been bound to the configured IA after the DHCPv6 renew/rebind exchange process. @retval EFI_ABORTED The DHCPv6 renew/rebind exchange process aborted by user. @@ -635,34 +629,34 @@ EFI_STATUS Inform that one or more IPv6 addresses assigned by a server are already in use by another node. - The Decline() function is used to manually decline the assignment of IPv6 addresses, which - have been already used by another node. If all IPv6 addresses of the configured IA are declined - through this function, the state of the IA will switch through Dhcp6Declining to Dhcp6Init, - otherwise, the state of the IA will restore to Dhcp6Bound after the declining process. The - Decline() can only be called when the IA is in Dhcp6Bound state. If the - EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL, this function is a blocking operation. It + The Decline() function is used to manually decline the assignment of IPv6 addresses, which + have been already used by another node. If all IPv6 addresses of the configured IA are declined + through this function, the state of the IA will switch through Dhcp6Declining to Dhcp6Init, + otherwise, the state of the IA will restore to Dhcp6Bound after the declining process. The + Decline() can only be called when the IA is in Dhcp6Bound state. If the + EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL, this function is a blocking operation. It will return after the declining process finishes, or aborted by user. @param[in] This Pointer to the EFI_DHCP4_PROTOCOL instance. - @param[in] AddressCount Number of declining IPv6 addresses. + @param[in] AddressCount Number of declining IPv6 addresses. @param[in] Addresses Pointer to the buffer stored all the declining IPv6 addresses. - @retval EFI_SUCCESS The DHCPv6 decline exchange process has completed when + @retval EFI_SUCCESS The DHCPv6 decline exchange process has completed when EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL. - The EFI DHCPv6 Protocol instance has sent Decline packet when + The EFI DHCPv6 Protocol instance has sent Decline packet when EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL. @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE - - This is NULL. + - This is NULL. - AddressCount is zero or Addresses is NULL. - @retval EFI_NOT_FOUND Any specified IPv6 address is not correlated with the configured IA + @retval EFI_NOT_FOUND Any specified IPv6 address is not correlated with the configured IA for this instance. - @retval EFI_ACCESS_DENIED The EFI DHCPv6 Child instance hasn't been configured, or the + @retval EFI_ACCESS_DENIED The EFI DHCPv6 Child instance hasn't been configured, or the state of the configured IA is not in Dhcp6Bound. @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. @retval EFI_ABORTED The DHCPv6 decline exchange process aborted by user. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_DHCP6_DECLINE)( IN EFI_DHCP6_PROTOCOL *This, @@ -675,32 +669,32 @@ EFI_STATUS The Release() function is used to manually release the one or more IPv6 address. If AddressCount is zero, it will release all IPv6 addresses of the configured IA. If all IPv6 addresses of the IA - are released through this function, the state of the IA will switch through Dhcp6Releasing to + are released through this function, the state of the IA will switch through Dhcp6Releasing to Dhcp6Init, otherwise, the state of the IA will restore to Dhcp6Bound after the releasing process. The Release() can only be called when the IA is in Dhcp6Bound state. If the EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL, the function is a blocking operation. It will return - after the releasing process finishes, or aborted by user. + after the releasing process finishes, or aborted by user. @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance. - @param[in] AddressCount Number of releasing IPv6 addresses. + @param[in] AddressCount Number of releasing IPv6 addresses. @param[in] Addresses Pointer to the buffer stored all the releasing IPv6 addresses. Ignored if AddressCount is zero. - @retval EFI_SUCCESS The DHCPv6 release exchange process has completed when + @retval EFI_SUCCESS The DHCPv6 release exchange process has completed when EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL. - The EFI DHCPv6 Protocol instance has sent Release packet when + The EFI DHCPv6 Protocol instance has sent Release packet when EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL. @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE - - This is NULL. + - This is NULL. - AddressCount is not zero or Addresses is NULL. @retval EFI_NOT_FOUND Any specified IPv6 address is not correlated with the configured IA for this instance. - @retval EFI_ACCESS_DENIED The EFI DHCPv6 Child instance hasn't been configured, or the + @retval EFI_ACCESS_DENIED The EFI DHCPv6 Child instance hasn't been configured, or the state of the configured IA is not in Dhcp6Bound. @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. - @retval EFI_ABORTED The DHCPv6 release exchange process aborted by user. + @retval EFI_ABORTED The DHCPv6 release exchange process aborted by user. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_DHCP6_RELEASE)( IN EFI_DHCP6_PROTOCOL *This, @@ -713,7 +707,7 @@ EFI_STATUS The Stop() function is used to stop the DHCPv6 S.A.R.R process. If this function is called successfully, all the IPv6 addresses of the configured IA will be released and the state of - the configured IA will be transferred to Dhcp6Init. + the configured IA will be transferred to Dhcp6Init. @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance. @@ -725,7 +719,7 @@ EFI_STATUS @retval EFI_INVALID_PARAMETER This is NULL. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_DHCP6_STOP)( IN EFI_DHCP6_PROTOCOL *This @@ -734,7 +728,7 @@ EFI_STATUS /** Parse the option data in the DHCPv6 packet. - The Parse() function is used to retrieve the option list in the DHCPv6 packet. + The Parse() function is used to retrieve the option list in the DHCPv6 packet. @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance. @@ -751,7 +745,7 @@ EFI_STATUS - Packet is not a well-formed DHCPv6 packet. - OptionCount is NULL. - *OptionCount is not zero and PacketOptionList is NULL. - @retval EFI_BUFFER_TOO_SMALL *OptionCount is smaller than the number of options that were + @retval EFI_BUFFER_TOO_SMALL *OptionCount is smaller than the number of options that were found in the Packet. **/ diff --git a/MdePkg/Include/Protocol/DiskInfo.h b/MdePkg/Include/Protocol/DiskInfo.h index e60ae0e98921..e0215d61df00 100644 --- a/MdePkg/Include/Protocol/DiskInfo.h +++ b/MdePkg/Include/Protocol/DiskInfo.h @@ -1,20 +1,14 @@ /** @file - Provides the basic interfaces to abstract platform information regarding an - IDE controller. + Provides the basic interfaces to abstract platform information regarding an + IDE controller. - Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: - This Protocol is defined in UEFI Platform Initialization Specification 1.2 + This Protocol is defined in UEFI Platform Initialization Specification 1.6 Volume 5: Standards - + **/ #ifndef __DISK_INFO_H__ @@ -81,9 +75,17 @@ typedef struct _EFI_DISK_INFO_PROTOCOL EFI_DISK_INFO_PROTOCOL; 0x4b3029cc, 0x6b98, 0x47fb, { 0xbc, 0x96, 0x76, 0xdc, 0xb8, 0x4, 0x41, 0xf0 } \ } +/// +/// Global ID for an SD/MMC interface. Used to fill in EFI_DISK_INFO_PROTOCOL.Interface +/// +#define EFI_DISK_INFO_SD_MMC_INTERFACE_GUID \ + { \ + 0x8deec992, 0xd39c, 0x4a5c, { 0xab, 0x6b, 0x98, 0x6e, 0x14, 0x24, 0x2b, 0x9d } \ + } + /** Provides inquiry information for the controller type. - + This function is used by the IDE bus driver to get inquiry data. Data format of Identify data is defined by the Interface GUID. @@ -92,9 +94,9 @@ typedef struct _EFI_DISK_INFO_PROTOCOL EFI_DISK_INFO_PROTOCOL; @param[in,out] InquiryDataSize Pointer to the value for the inquiry data size. @retval EFI_SUCCESS The command was accepted without any errors. - @retval EFI_NOT_FOUND Device does not support this data class - @retval EFI_DEVICE_ERROR Error reading InquiryData from device - @retval EFI_BUFFER_TOO_SMALL InquiryDataSize not big enough + @retval EFI_NOT_FOUND Device does not support this data class + @retval EFI_DEVICE_ERROR Error reading InquiryData from device + @retval EFI_BUFFER_TOO_SMALL InquiryDataSize not big enough **/ typedef @@ -111,16 +113,16 @@ EFI_STATUS This function is used by the IDE bus driver to get identify data. Data format of Identify data is defined by the Interface GUID. - @param[in] This Pointer to the EFI_DISK_INFO_PROTOCOL + @param[in] This Pointer to the EFI_DISK_INFO_PROTOCOL instance. @param[in,out] IdentifyData Pointer to a buffer for the identify data. @param[in,out] IdentifyDataSize Pointer to the value for the identify data size. @retval EFI_SUCCESS The command was accepted without any errors. - @retval EFI_NOT_FOUND Device does not support this data class - @retval EFI_DEVICE_ERROR Error reading IdentifyData from device - @retval EFI_BUFFER_TOO_SMALL IdentifyDataSize not big enough + @retval EFI_NOT_FOUND Device does not support this data class + @retval EFI_DEVICE_ERROR Error reading IdentifyData from device + @retval EFI_BUFFER_TOO_SMALL IdentifyDataSize not big enough **/ typedef @@ -133,8 +135,8 @@ EFI_STATUS /** Provides sense data information for the controller type. - - This function is used by the IDE bus driver to get sense data. + + This function is used by the IDE bus driver to get sense data. Data format of Sense data is defined by the Interface GUID. @param[in] This Pointer to the EFI_DISK_INFO_PROTOCOL instance. @@ -160,7 +162,7 @@ EFI_STATUS /** This function is used by the IDE bus driver to get controller information. - @param[in] This Pointer to the EFI_DISK_INFO_PROTOCOL instance. + @param[in] This Pointer to the EFI_DISK_INFO_PROTOCOL instance. @param[out] IdeChannel Pointer to the Ide Channel number. Primary or secondary. @param[out] IdeDevice Pointer to the Ide Device number. Master or slave. @@ -181,7 +183,7 @@ EFI_STATUS /// struct _EFI_DISK_INFO_PROTOCOL { /// - /// A GUID that defines the format of buffers for the other member functions + /// A GUID that defines the format of buffers for the other member functions /// of this protocol. /// EFI_GUID Interface; @@ -201,7 +203,7 @@ struct _EFI_DISK_INFO_PROTOCOL { /// EFI_DISK_INFO_SENSE_DATA SenseData; /// - /// Specific controller. + /// Specific controller. /// EFI_DISK_INFO_WHICH_IDE WhichIde; }; @@ -214,5 +216,6 @@ extern EFI_GUID gEfiDiskInfoUsbInterfaceGuid; extern EFI_GUID gEfiDiskInfoAhciInterfaceGuid; extern EFI_GUID gEfiDiskInfoNvmeInterfaceGuid; extern EFI_GUID gEfiDiskInfoUfsInterfaceGuid; +extern EFI_GUID gEfiDiskInfoSdMmcInterfaceGuid; #endif diff --git a/MdePkg/Include/Protocol/DiskIo.h b/MdePkg/Include/Protocol/DiskIo.h index 9f2526161c7c..d6e6a47b31dd 100644 --- a/MdePkg/Include/Protocol/DiskIo.h +++ b/MdePkg/Include/Protocol/DiskIo.h @@ -5,14 +5,8 @@ oriented devices. The Disk IO protocol is intended to layer on top of the Block IO protocol. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -26,14 +20,14 @@ /// /// Protocol GUID name defined in EFI1.1. -/// +/// #define DISK_IO_PROTOCOL EFI_DISK_IO_PROTOCOL_GUID typedef struct _EFI_DISK_IO_PROTOCOL EFI_DISK_IO_PROTOCOL; /// /// Protocol defined in EFI1.1. -/// +/// typedef EFI_DISK_IO_PROTOCOL EFI_DISK_IO; /** @@ -95,7 +89,7 @@ EFI_STATUS /// /// Revision defined in EFI1.1 -/// +/// #define EFI_DISK_IO_INTERFACE_REVISION EFI_DISK_IO_PROTOCOL_REVISION /// diff --git a/MdePkg/Include/Protocol/DiskIo2.h b/MdePkg/Include/Protocol/DiskIo2.h index c2994c2facd5..b3dfb24be344 100644 --- a/MdePkg/Include/Protocol/DiskIo2.h +++ b/MdePkg/Include/Protocol/DiskIo2.h @@ -4,14 +4,8 @@ The Disk I/O 2 protocol defines an extension to the Disk I/O protocol to enable non-blocking / asynchronous byte-oriented disk operation. - Copyright (c) 2013, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Protocol/Dns4.h b/MdePkg/Include/Protocol/Dns4.h index 61c8e5c38ad5..d02713f706fd 100644 --- a/MdePkg/Include/Protocol/Dns4.h +++ b/MdePkg/Include/Protocol/Dns4.h @@ -4,14 +4,8 @@ DNSv4 Service Binding Protocol (DNSv4SB) DNSv4 Protocol (DNSv4) - Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.5 @@ -38,23 +32,23 @@ typedef struct _EFI_DNS4_PROTOCOL EFI_DNS4_PROTOCOL; /// typedef struct { /// - /// Count of the DNS servers. When used with GetModeData(), - /// this field is the count of originally configured servers when - /// Configure() was called for this instance. When used with - /// Configure() this is the count of caller-supplied servers. If the - /// DnsServerListCount is zero, the DNS server configuration + /// Count of the DNS servers. When used with GetModeData(), + /// this field is the count of originally configured servers when + /// Configure() was called for this instance. When used with + /// Configure() this is the count of caller-supplied servers. If the + /// DnsServerListCount is zero, the DNS server configuration /// will be retrieved from DHCP server automatically. /// UINTN DnsServerListCount; /// - /// Pointer to DNS server list containing DnsServerListCount entries or NULL - /// if DnsServerListCountis 0. For Configure(), this will be NULL when there are - /// no caller supplied server addresses, and, the DNS instance will retrieve - /// DNS server from DHCP Server. The provided DNS server list is - /// recommended to be filled up in the sequence of preference. When - /// used with GetModeData(), the buffer containing the list will - /// be allocated by the driver implementing this protocol and must be - /// freed by the caller. When used with Configure(), the buffer + /// Pointer to DNS server list containing DnsServerListCount entries or NULL + /// if DnsServerListCountis 0. For Configure(), this will be NULL when there are + /// no caller supplied server addresses, and, the DNS instance will retrieve + /// DNS server from DHCP Server. The provided DNS server list is + /// recommended to be filled up in the sequence of preference. When + /// used with GetModeData(), the buffer containing the list will + /// be allocated by the driver implementing this protocol and must be + /// freed by the caller. When used with Configure(), the buffer /// containing the list will be allocated and released by the caller. /// EFI_IPv4_ADDRESS *DnsServerList; @@ -68,10 +62,10 @@ typedef struct { /// BOOLEAN EnableDnsCache; /// - /// Use the protocol number defined in "Links to UEFI-Related - /// Documents"(http://uefi.org/uefi) under the heading "IANA - /// Protocol Numbers". Only TCP or UDP are supported, and other - /// protocol values are invalid. An implementation can choose to + /// Use the protocol number defined in "Links to UEFI-Related + /// Documents"(http://uefi.org/uefi) under the heading "IANA + /// Protocol Numbers". Only TCP or UDP are supported, and other + /// protocol values are invalid. An implementation can choose to /// support only UDP, or both TCP and UDP. /// UINT8 Protocol; @@ -135,10 +129,10 @@ typedef struct { /// UINT32 DnsServerCount; /// - /// Pointer to common list of addresses of all configured DNS server - /// used by EFI_DNS4_PROTOCOL instances. List will include - /// DNS servers configured by this or any other EFI_DNS4_PROTOCOL instance. - /// The storage for this list is allocated by the driver publishing this + /// Pointer to common list of addresses of all configured DNS server + /// used by EFI_DNS4_PROTOCOL instances. List will include + /// DNS servers configured by this or any other EFI_DNS4_PROTOCOL instance. + /// The storage for this list is allocated by the driver publishing this /// protocol, and must be freed by the caller. /// EFI_IPv4_ADDRESS *DnsServerList; @@ -147,8 +141,8 @@ typedef struct { /// UINT32 DnsCacheCount; /// - /// Pointer to a buffer containing DnsCacheCount DNS Cache - /// entry structures. The storage for this list is allocated by the driver + /// Pointer to a buffer containing DnsCacheCount DNS Cache + /// entry structures. The storage for this list is allocated by the driver /// publishing this protocol and must be freed by caller. /// EFI_DNS4_CACHE_ENTRY *DnsCacheList; @@ -311,7 +305,7 @@ EFI_STATUS @retval EFI_SUCCESS The operation completed successfully. @retval EFI_UNSUPPORTED The designated protocol is not supported. @retval EFI_INVALID_PARAMETER This is NULL. - The StationIp address provided in DnsConfigData is not a + The StationIp address provided in DnsConfigData is not a valid unicast. DnsServerList is NULL while DnsServerListCount is not ZERO. @@ -321,8 +315,8 @@ EFI_STATUS allocated. @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI DNSv4 Protocol instance is not configured. - @retval EFI_ALREADY_STARTED Second call to Configure() with DnsConfigData. To - reconfigure the instance the caller must call Configure() + @retval EFI_ALREADY_STARTED Second call to Configure() with DnsConfigData. To + reconfigure the instance the caller must call Configure() with NULL first to return driver to unconfigured state. **/ typedef @@ -363,7 +357,7 @@ EFI_STATUS /** IPv4 address to host name translation also known as Reverse DNS lookup. - The IpToHostName() function is used to translate the host address to host name. A type PTR + The IpToHostName() function is used to translate the host address to host name. A type PTR query is used to get the primary name of the host. Support of this function is optional. @param[in] This Pointer to EFI_DNS4_PROTOCOL instance. @@ -391,7 +385,7 @@ EFI_STATUS ); /** - Retrieve arbitrary information from the DNS server. + Retrieve arbitrary information from the DNS server. This GeneralLookup() function retrieves arbitrary information from the DNS. The caller supplies a QNAME, QTYPE, and QCLASS, and all of the matching RRs are returned. All diff --git a/MdePkg/Include/Protocol/Dns6.h b/MdePkg/Include/Protocol/Dns6.h index bf8814606e4d..9839b822c146 100644 --- a/MdePkg/Include/Protocol/Dns6.h +++ b/MdePkg/Include/Protocol/Dns6.h @@ -4,14 +4,8 @@ DNSv6 Service Binding Protocol (DNSv6SB) DNSv6 Protocol (DNSv6) - Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.5 @@ -49,8 +43,8 @@ typedef struct { /// UINT8 Protocol; /// - /// The local IP address to use. Set to zero to let the underlying IPv6 - /// driver choose a source address. If not zero it must be one of the + /// The local IP address to use. Set to zero to let the underlying IPv6 + /// driver choose a source address. If not zero it must be one of the /// configured IP addresses in the underlying IPv6 driver. /// EFI_IPv6_ADDRESS StationIp; @@ -59,23 +53,23 @@ typedef struct { /// UINT16 LocalPort; /// - /// Count of the DNS servers. When used with GetModeData(), - /// this field is the count of originally configured servers when - /// Configure() was called for this instance. When used with - /// Configure() this is the count of caller-supplied servers. If the - /// DnsServerListCount is zero, the DNS server configuration + /// Count of the DNS servers. When used with GetModeData(), + /// this field is the count of originally configured servers when + /// Configure() was called for this instance. When used with + /// Configure() this is the count of caller-supplied servers. If the + /// DnsServerListCount is zero, the DNS server configuration /// will be retrieved from DHCP server automatically. /// UINT32 DnsServerCount; /// /// Pointer to DNS server list containing DnsServerListCount - /// entries or NULL if DnsServerListCount is 0. For Configure(), - /// this will be NULL when there are no caller supplied server addresses - /// and the DNS instance will retrieve DNS server from DHCP Server. - /// The provided DNS server list is recommended to be filled up in the sequence - /// of preference. When used with GetModeData(), the buffer containing the list - /// will be allocated by the driver implementing this protocol and must be - /// freed by the caller. When used with Configure(), the buffer + /// entries or NULL if DnsServerListCount is 0. For Configure(), + /// this will be NULL when there are no caller supplied server addresses + /// and the DNS instance will retrieve DNS server from DHCP Server. + /// The provided DNS server list is recommended to be filled up in the sequence + /// of preference. When used with GetModeData(), the buffer containing the list + /// will be allocated by the driver implementing this protocol and must be + /// freed by the caller. When used with Configure(), the buffer /// containing the list will be allocated and released by the caller. /// EFI_IPv6_ADDRESS *DnsServerList; @@ -121,21 +115,21 @@ typedef struct { /// /// Number of configured DNS6 servers. /// - UINT32 DnsServerCount; + UINT32 DnsServerCount; /// - /// Pointer to common list of addresses of all configured DNS server used by EFI_DNS6_PROTOCOL - /// instances. List will include DNS servers configured by this or any other EFI_DNS6_PROTOCOL - /// instance. The storage for this list is allocated by the driver publishing this protocol, + /// Pointer to common list of addresses of all configured DNS server used by EFI_DNS6_PROTOCOL + /// instances. List will include DNS servers configured by this or any other EFI_DNS6_PROTOCOL + /// instance. The storage for this list is allocated by the driver publishing this protocol, /// and must be freed by the caller. /// - EFI_IPv6_ADDRESS *DnsServerList; + EFI_IPv6_ADDRESS *DnsServerList; /// /// Number of DNS Cache entries. The DNS Cache is shared among all DNS instances. /// UINT32 DnsCacheCount; /// - /// Pointer to a buffer containing DnsCacheCount DNS Cache - /// entry structures. The storage for thislist is allocated by the driver + /// Pointer to a buffer containing DnsCacheCount DNS Cache + /// entry structures. The storage for thislist is allocated by the driver /// publishing this protocol and must be freed by caller. /// EFI_DNS6_CACHE_ENTRY *DnsCacheList; @@ -272,7 +266,7 @@ typedef struct { This function is used to retrieve DNS mode data for this DNS instance. @param[in] This Pointer to EFI_DNS6_PROTOCOL instance. - @param[out] DnsModeData Pointer to the caller-allocated storage for the + @param[out] DnsModeData Pointer to the caller-allocated storage for the EFI_DNS6_MODE_DATA data. @retval EFI_SUCCESS The operation completed successfully. @@ -296,7 +290,7 @@ EFI_STATUS EFI DNSv6 Protocol driver instance. Reset the DNS instance if DnsConfigData is NULL. @param[in] This Pointer to EFI_DNS6_PROTOCOL instance. - @param[in] DnsConfigData Pointer to the configuration data structure. All associated + @param[in] DnsConfigData Pointer to the configuration data structure. All associated storage to be allocated and released by caller. @retval EFI_SUCCESS The operation completed successfully. @@ -308,8 +302,8 @@ EFI_STATUS @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI DNSv6 Protocol instance is not configured. @retval EFI_UNSUPPORTED The designated protocol is not supported. - @retval EFI_ALREADY_STARTED Second call to Configure() with DnsConfigData. To - reconfigure the instance the caller must call Configure() with + @retval EFI_ALREADY_STARTED Second call to Configure() with DnsConfigData. To + reconfigure the instance the caller must call Configure() with NULL first to return driver to unconfigured state. **/ typedef diff --git a/MdePkg/Include/Protocol/DriverBinding.h b/MdePkg/Include/Protocol/DriverBinding.h index b325c0ccf7a3..fca636f22dae 100644 --- a/MdePkg/Include/Protocol/DriverBinding.h +++ b/MdePkg/Include/Protocol/DriverBinding.h @@ -1,17 +1,11 @@ /** @file UEFI DriverBinding Protocol is defined in UEFI specification. - - This protocol is produced by every driver that follows the UEFI Driver Model, + + This protocol is produced by every driver that follows the UEFI Driver Model, and it is the central component that allows drivers and controllers to be managed. -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -29,33 +23,33 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. typedef struct _EFI_DRIVER_BINDING_PROTOCOL EFI_DRIVER_BINDING_PROTOCOL; /** - Tests to see if this driver supports a given controller. If a child device is provided, + Tests to see if this driver supports a given controller. If a child device is provided, it further tests to see if this driver supports creating a handle for the specified child device. - This function checks to see if the driver specified by This supports the device specified by - ControllerHandle. Drivers will typically use the device path attached to - ControllerHandle and/or the services from the bus I/O abstraction attached to - ControllerHandle to determine if the driver supports ControllerHandle. This function - may be called many times during platform initialization. In order to reduce boot times, the tests - performed by this function must be very small, and take as little time as possible to execute. This - function must not change the state of any hardware devices, and this function must be aware that the - device specified by ControllerHandle may already be managed by the same driver or a - different driver. This function must match its calls to AllocatePages() with FreePages(), - AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol(). - Because ControllerHandle may have been previously started by the same driver, if a protocol is - already in the opened state, then it must not be closed with CloseProtocol(). This is required + This function checks to see if the driver specified by This supports the device specified by + ControllerHandle. Drivers will typically use the device path attached to + ControllerHandle and/or the services from the bus I/O abstraction attached to + ControllerHandle to determine if the driver supports ControllerHandle. This function + may be called many times during platform initialization. In order to reduce boot times, the tests + performed by this function must be very small, and take as little time as possible to execute. This + function must not change the state of any hardware devices, and this function must be aware that the + device specified by ControllerHandle may already be managed by the same driver or a + different driver. This function must match its calls to AllocatePages() with FreePages(), + AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol(). + Because ControllerHandle may have been previously started by the same driver, if a protocol is + already in the opened state, then it must not be closed with CloseProtocol(). This is required to guarantee the state of ControllerHandle is not modified by this function. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. - @param[in] ControllerHandle The handle of the controller to test. This handle - must support a protocol interface that supplies + @param[in] ControllerHandle The handle of the controller to test. This handle + must support a protocol interface that supplies an I/O abstraction to the driver. - @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This - parameter is ignored by device drivers, and is optional for bus - drivers. For bus drivers, if this parameter is not NULL, then - the bus driver must determine if the bus controller specified - by ControllerHandle and the child controller specified - by RemainingDevicePath are both supported by this + @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This + parameter is ignored by device drivers, and is optional for bus + drivers. For bus drivers, if this parameter is not NULL, then + the bus driver must determine if the bus controller specified + by ControllerHandle and the child controller specified + by RemainingDevicePath are both supported by this bus driver. @retval EFI_SUCCESS The device specified by ControllerHandle and @@ -82,28 +76,28 @@ EFI_STATUS Starts a device controller or a bus controller. The Start() function is designed to be invoked from the EFI boot service ConnectController(). - As a result, much of the error checking on the parameters to Start() has been moved into this - common boot service. It is legal to call Start() from other locations, + As a result, much of the error checking on the parameters to Start() has been moved into this + common boot service. It is legal to call Start() from other locations, but the following calling restrictions must be followed, or the system behavior will not be deterministic. 1. ControllerHandle must be a valid EFI_HANDLE. 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned EFI_DEVICE_PATH_PROTOCOL. 3. Prior to calling Start(), the Supported() function for the driver specified by This must - have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS. + have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. - @param[in] ControllerHandle The handle of the controller to start. This handle - must support a protocol interface that supplies + @param[in] ControllerHandle The handle of the controller to start. This handle + must support a protocol interface that supplies an I/O abstraction to the driver. - @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This - parameter is ignored by device drivers, and is optional for bus - drivers. For a bus driver, if this parameter is NULL, then handles - for all the children of Controller are created by this driver. - If this parameter is not NULL and the first Device Path Node is - not the End of Device Path Node, then only the handle for the - child device specified by the first Device Path Node of + @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This + parameter is ignored by device drivers, and is optional for bus + drivers. For a bus driver, if this parameter is NULL, then handles + for all the children of Controller are created by this driver. + If this parameter is not NULL and the first Device Path Node is + not the End of Device Path Node, then only the handle for the + child device specified by the first Device Path Node of RemainingDevicePath is created by this driver. - If the first Device Path Node of RemainingDevicePath is + If the first Device Path Node of RemainingDevicePath is the End of Device Path Node, no child handle is created by this driver. @@ -123,10 +117,10 @@ EFI_STATUS /** Stops a device controller or a bus controller. - - The Stop() function is designed to be invoked from the EFI boot service DisconnectController(). - As a result, much of the error checking on the parameters to Stop() has been moved - into this common boot service. It is legal to call Stop() from other locations, + + The Stop() function is designed to be invoked from the EFI boot service DisconnectController(). + As a result, much of the error checking on the parameters to Stop() has been moved + into this common boot service. It is legal to call Stop() from other locations, but the following calling restrictions must be followed, or the system behavior will not be deterministic. 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this same driver's Start() function. @@ -134,13 +128,13 @@ EFI_STATUS EFI_HANDLE. In addition, all of these handles must have been created in this driver's Start() function, and the Start() function must have called OpenProtocol() on ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. - + @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. - @param[in] ControllerHandle A handle to the device being stopped. The handle must - support a bus specific I/O protocol for the driver + @param[in] ControllerHandle A handle to the device being stopped. The handle must + support a bus specific I/O protocol for the driver to use to stop the device. @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer. - @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL + @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL if NumberOfChildren is 0. @retval EFI_SUCCESS The device was stopped. @@ -157,14 +151,14 @@ EFI_STATUS ); /// -/// This protocol provides the services required to determine if a driver supports a given controller. +/// This protocol provides the services required to determine if a driver supports a given controller. /// If a controller is supported, then it also provides routines to start and stop the controller. /// struct _EFI_DRIVER_BINDING_PROTOCOL { EFI_DRIVER_BINDING_SUPPORTED Supported; EFI_DRIVER_BINDING_START Start; EFI_DRIVER_BINDING_STOP Stop; - + /// /// The version number of the UEFI driver that produced the /// EFI_DRIVER_BINDING_PROTOCOL. This field is used by @@ -178,20 +172,20 @@ struct _EFI_DRIVER_BINDING_PROTOCOL { /// 0xffffffef are reserved for IHV-developed drivers. /// UINT32 Version; - + /// /// The image handle of the UEFI driver that produced this instance /// of the EFI_DRIVER_BINDING_PROTOCOL. /// EFI_HANDLE ImageHandle; - + /// /// The handle on which this instance of the /// EFI_DRIVER_BINDING_PROTOCOL is installed. In most /// cases, this is the same handle as ImageHandle. However, for /// UEFI drivers that produce more than one instance of the /// EFI_DRIVER_BINDING_PROTOCOL, this value may not be - /// the same as ImageHandle. + /// the same as ImageHandle. /// EFI_HANDLE DriverBindingHandle; }; diff --git a/MdePkg/Include/Protocol/DriverConfiguration.h b/MdePkg/Include/Protocol/DriverConfiguration.h index 53c5296720b1..2a0018fabd30 100644 --- a/MdePkg/Include/Protocol/DriverConfiguration.h +++ b/MdePkg/Include/Protocol/DriverConfiguration.h @@ -1,14 +1,8 @@ /** @file EFI Driver Configuration Protocol - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -24,11 +18,11 @@ { \ 0x107a772b, 0xd5e1, 0x11d4, {0x9a, 0x46, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \ } - + typedef struct _EFI_DRIVER_CONFIGURATION_PROTOCOL EFI_DRIVER_CONFIGURATION_PROTOCOL; /** - Allows the user to set controller specific options for a controller that a + Allows the user to set controller specific options for a controller that a driver is currently managing. @param This A pointer to the EFI_DRIVER_CONFIGURATION_PROTOCOL instance. @@ -154,9 +148,9 @@ struct _EFI_DRIVER_CONFIGURATION_PROTOCOL { EFI_DRIVER_CONFIGURATION_OPTIONS_VALID OptionsValid; EFI_DRIVER_CONFIGURATION_FORCE_DEFAULTS ForceDefaults; /// - /// A Null-terminated ASCII string that contains one or more - /// ISO 639-2 language codes. This is the list of language - /// codes that this protocol supports. + /// A Null-terminated ASCII string that contains one or more + /// ISO 639-2 language codes. This is the list of language + /// codes that this protocol supports. /// CHAR8 *SupportedLanguages; }; diff --git a/MdePkg/Include/Protocol/DriverConfiguration2.h b/MdePkg/Include/Protocol/DriverConfiguration2.h index 1610eb4741af..066968670b16 100644 --- a/MdePkg/Include/Protocol/DriverConfiguration2.h +++ b/MdePkg/Include/Protocol/DriverConfiguration2.h @@ -1,14 +1,8 @@ /** @file UEFI Driver Configuration2 Protocol - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -22,7 +16,7 @@ { \ 0xbfd7dc1d, 0x24f1, 0x40d9, {0x82, 0xe7, 0x2e, 0x09, 0xbb, 0x6b, 0x4e, 0xbe } \ } - + typedef struct _EFI_DRIVER_CONFIGURATION2_PROTOCOL EFI_DRIVER_CONFIGURATION2_PROTOCOL; typedef enum { @@ -55,7 +49,7 @@ typedef enum { #define EFI_DRIVER_CONFIGURATION_PERORMANCE_DEFAULTS 0x00000003 /** - Allows the user to set controller specific options for a controller that a + Allows the user to set controller specific options for a controller that a driver is currently managing. @param This A pointer to the EFI_DRIVER_CONFIGURATION2_PROTOCOL instance. @@ -180,7 +174,7 @@ struct _EFI_DRIVER_CONFIGURATION2_PROTOCOL { EFI_DRIVER_CONFIGURATION2_FORCE_DEFAULTS ForceDefaults; /// /// A Null-terminated ASCII string that contains one or more RFC 4646 - /// language codes. This is the list of language codes that this protocol supports. + /// language codes. This is the list of language codes that this protocol supports. /// CHAR8 *SupportedLanguages; }; diff --git a/MdePkg/Include/Protocol/DriverDiagnostics.h b/MdePkg/Include/Protocol/DriverDiagnostics.h index 431b649223e5..53ebe0852901 100644 --- a/MdePkg/Include/Protocol/DriverDiagnostics.h +++ b/MdePkg/Include/Protocol/DriverDiagnostics.h @@ -1,14 +1,8 @@ /** @file EFI Driver Diagnostics Protocol -Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -41,7 +35,7 @@ typedef enum { /// EfiDriverDiagnosticTypeManufacturing= 2, /// - /// This is an optional diagnostic type that would only be used in the situation where an + /// This is an optional diagnostic type that would only be used in the situation where an /// EFI_NOT_READY had been returned by a previous call to RunDiagnostics() /// and there is a desire to cancel the current running diagnostics operation. /// @@ -121,8 +115,8 @@ struct _EFI_DRIVER_DIAGNOSTICS_PROTOCOL { EFI_DRIVER_DIAGNOSTICS_RUN_DIAGNOSTICS RunDiagnostics; /// /// A Null-terminated ASCII string that contains one or more ISO 639-2 - /// language codes. This is the list of language codes that this protocol supports. - /// + /// language codes. This is the list of language codes that this protocol supports. + /// CHAR8 *SupportedLanguages; }; diff --git a/MdePkg/Include/Protocol/DriverDiagnostics2.h b/MdePkg/Include/Protocol/DriverDiagnostics2.h index 78d5ec6fe93e..b0b4c8cd6789 100644 --- a/MdePkg/Include/Protocol/DriverDiagnostics2.h +++ b/MdePkg/Include/Protocol/DriverDiagnostics2.h @@ -1,14 +1,8 @@ /** @file UEFI Driver Diagnostics2 Protocol - Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -21,7 +15,7 @@ { \ 0x4d330321, 0x025f, 0x4aac, {0x90, 0xd8, 0x5e, 0xd9, 0x00, 0x17, 0x3b, 0x63 } \ } - + typedef struct _EFI_DRIVER_DIAGNOSTICS2_PROTOCOL EFI_DRIVER_DIAGNOSTICS2_PROTOCOL; /** @@ -31,7 +25,7 @@ typedef struct _EFI_DRIVER_DIAGNOSTICS2_PROTOCOL EFI_DRIVER_DIAGNOSTICS2_PROTOC @param ControllerHandle The handle of the controller to run diagnostics on. @param ChildHandle The handle of the child controller to run diagnostics on This is an optional parameter that may be NULL. It will - be NULL for device drivers. It will also be NULL for + be NULL for device drivers. It will also be NULL for bus drivers that wish to run diagnostics on the bus controller. It will not be NULL for a bus driver that wishes to run diagnostics on one of its child controllers. @@ -101,8 +95,8 @@ struct _EFI_DRIVER_DIAGNOSTICS2_PROTOCOL { EFI_DRIVER_DIAGNOSTICS2_RUN_DIAGNOSTICS RunDiagnostics; /// /// A Null-terminated ASCII string that contains one or more RFC 4646 - /// language codes. This is the list of language codes that this protocol supports. - /// + /// language codes. This is the list of language codes that this protocol supports. + /// CHAR8 *SupportedLanguages; }; diff --git a/MdePkg/Include/Protocol/DriverFamilyOverride.h b/MdePkg/Include/Protocol/DriverFamilyOverride.h index 868c7734117a..5b06f0b0e025 100644 --- a/MdePkg/Include/Protocol/DriverFamilyOverride.h +++ b/MdePkg/Include/Protocol/DriverFamilyOverride.h @@ -1,14 +1,8 @@ /** @file UEFI Driver Family Protocol -Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -19,14 +13,14 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. { \ 0xb1ee129e, 0xda36, 0x4181, { 0x91, 0xf8, 0x4, 0xa4, 0x92, 0x37, 0x66, 0xa7 } \ } - + typedef struct _EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL; // // Prototypes for the Driver Family Override Protocol // -// -/** +// +/** This function returns the version value associated with the driver specified by This. Retrieves the version of the driver that is used by the EFI Boot Service ConnectController() @@ -35,10 +29,10 @@ typedef struct _EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL EFI_DRIVER_FAMILY_OVERRIDE_ the drivers with higher values returned by GetVersion() are higher priority than drivers that return lower values from GetVersion(). - @param This A pointer to the EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL instance. - - @return The version value associated with the driver specified by This. - + @param This A pointer to the EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL instance. + + @return The version value associated with the driver specified by This. + **/ typedef UINT32 @@ -47,15 +41,15 @@ UINT32 ); /// -/// When installed, the Driver Family Override Protocol produces a GUID that represents -/// a family of drivers. Drivers with the same GUID are members of the same family -/// When drivers are connected to controllers, drivers with a higher revision value -/// in the same driver family are connected with a higher priority than drivers +/// When installed, the Driver Family Override Protocol produces a GUID that represents +/// a family of drivers. Drivers with the same GUID are members of the same family +/// When drivers are connected to controllers, drivers with a higher revision value +/// in the same driver family are connected with a higher priority than drivers /// with a lower revision value in the same driver family. The EFI Boot Service -/// Connect Controller uses five rules to build a prioritized list of drivers when +/// Connect Controller uses five rules to build a prioritized list of drivers when /// a request is made to connect a driver to a controller. The Driver Family Protocol -/// rule is between the Platform Specific Driver Override Protocol and above the -/// Bus Specific Driver Override Protocol. +/// rule is between the Platform Specific Driver Override Protocol and above the +/// Bus Specific Driver Override Protocol. /// struct _EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL { EFI_DRIVER_FAMILY_OVERRIDE_GET_VERSION GetVersion; diff --git a/MdePkg/Include/Protocol/DriverHealth.h b/MdePkg/Include/Protocol/DriverHealth.h index d23140d20bd1..691d205ec065 100644 --- a/MdePkg/Include/Protocol/DriverHealth.h +++ b/MdePkg/Include/Protocol/DriverHealth.h @@ -5,33 +5,27 @@ the health status for a controller to be retrieved. If a controller is not in a usable state, status messages may be reported to the user, repair operations can be invoked, and the user may be asked to make software and/or hardware configuration changes. - - The Driver Health Protocol is optionally produced by a driver that follows the - EFI Driver Model. If an EFI Driver needs to report health status to the platform, - provide warning or error messages to the user, perform length repair operations, - or request the user to make hardware or software configuration changes, then the + + The Driver Health Protocol is optionally produced by a driver that follows the + EFI Driver Model. If an EFI Driver needs to report health status to the platform, + provide warning or error messages to the user, perform length repair operations, + or request the user to make hardware or software configuration changes, then the Driver Health Protocol must be produced. - - A controller that is managed by driver that follows the EFI Driver Model and - produces the Driver Health Protocol must report the current health of the - controllers that the driver is currently managing. The controller can initially - be healthy, failed, require repair, or require configuration. If a controller - requires configuration, and the user make configuration changes, the controller - may then need to be reconnected or the system may need to be rebooted for the - configuration changes to take affect. - - Copyright (c) 2009 - 2013, Intel Corporation. All rights reserved.<BR> - Copyright (c) 2014, Hewlett-Packard Development Company, L.P.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + A controller that is managed by driver that follows the EFI Driver Model and + produces the Driver Health Protocol must report the current health of the + controllers that the driver is currently managing. The controller can initially + be healthy, failed, require repair, or require configuration. If a controller + requires configuration, and the user make configuration changes, the controller + may then need to be reconnected or the system may need to be rebooted for the + configuration changes to take affect. + + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + Copyright (c) 2014, Hewlett-Packard Development Company, L.P.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: - This Protocol is defined in UEFI Specification 2.3d + This Protocol is defined in UEFI Specification 2.3d **/ @@ -42,7 +36,7 @@ { \ 0x2a534210, 0x9280, 0x41d8, { 0xae, 0x79, 0xca, 0xda, 0x1, 0xa2, 0xb1, 0x27 } \ } - + typedef struct _EFI_DRIVER_HEALTH_PROTOCOL EFI_DRIVER_HEALTH_PROTOCOL; /// @@ -63,12 +57,12 @@ typedef enum { typedef struct { EFI_HII_HANDLE HiiHandle; EFI_STRING_ID StringId; - + /// - /// 64-bit numeric value of the warning/error specified by this message. - /// A value of 0x0000000000000000 is used to indicate that MessageCode is not specified. + /// 64-bit numeric value of the warning/error specified by this message. + /// A value of 0x0000000000000000 is used to indicate that MessageCode is not specified. /// The values 0x0000000000000001 to 0x0fffffffffffffff are reserved for allocation by the UEFI Specification. - /// The values 0x1000000000000000 to 0x1fffffffffffffff are reserved for IHV-developed drivers. + /// The values 0x1000000000000000 to 0x1fffffffffffffff are reserved for IHV-developed drivers. /// The values 0x8000000000000000 to 0x8fffffffffffffff is reserved for platform/OEM drivers. /// All other values are reserved and should not be used. /// @@ -78,11 +72,11 @@ typedef struct { /** Reports the progress of a repair operation - @param[in] Value A value between 0 and Limit that identifies the current + @param[in] Value A value between 0 and Limit that identifies the current progress of the repair operation. - + @param[in] Limit The maximum value of Value for the current repair operation. - For example, a driver that wants to specify progress in + For example, a driver that wants to specify progress in percent would use a Limit value of 100. **/ typedef @@ -93,88 +87,88 @@ EFI_STATUS ); /** - Retrieves the health status of a controller in the platform. This function can also - optionally return warning messages, error messages, and a set of HII Forms that may - be repair a controller that is not proper configured. - + Retrieves the health status of a controller in the platform. This function can also + optionally return warning messages, error messages, and a set of HII Forms that may + be repair a controller that is not proper configured. + @param[in] This A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance. - @param[in] ControllerHandle The handle of the controller to retrieve the health status - on. This is an optional parameter that may be NULL. If - this parameter is NULL, then the value of ChildHandle is - ignored, and the combined health status of all the devices + @param[in] ControllerHandle The handle of the controller to retrieve the health status + on. This is an optional parameter that may be NULL. If + this parameter is NULL, then the value of ChildHandle is + ignored, and the combined health status of all the devices that the driver is managing is returned. - @param[in] ChildHandle The handle of the child controller to retrieve the health - status on. This is an optional parameter that may be NULL. - This parameter is ignored of ControllerHandle is NULL. It - will be NULL for device drivers. It will also be NULL for - bus drivers when an attempt is made to collect the health - status of the bus controller. If will not be NULL when an - attempt is made to collect the health status for a child + @param[in] ChildHandle The handle of the child controller to retrieve the health + status on. This is an optional parameter that may be NULL. + This parameter is ignored of ControllerHandle is NULL. It + will be NULL for device drivers. It will also be NULL for + bus drivers when an attempt is made to collect the health + status of the bus controller. If will not be NULL when an + attempt is made to collect the health status for a child controller produced by the driver. - @param[out] HealthStatus A pointer to the health status that is returned by this - function. This is an optional parameter that may be NULL. - This parameter is ignored of ControllerHandle is NULL. - The health status for the controller specified by - ControllerHandle and ChildHandle is returned. - - @param[out] MessageList A pointer to an array of warning or error messages associated - with the controller specified by ControllerHandle and - ChildHandle. This is an optional parameter that may be NULL. - MessageList is allocated by this function with the EFI Boot - Service AllocatePool(), and it is the caller's responsibility - to free MessageList with the EFI Boot Service FreePool(). - Each message is specified by tuple of an EFI_HII_HANDLE and - an EFI_STRING_ID. The array of messages is terminated by tuple - containing a EFI_HII_HANDLE with a value of NULL. The - EFI_HII_STRING_PROTOCOL.GetString() function can be used to - retrieve the warning or error message as a Null-terminated - string in a specific language. Messages may be - returned for any of the HealthStatus values except - EfiDriverHealthStatusReconnectRequired and + @param[out] HealthStatus A pointer to the health status that is returned by this + function. This is an optional parameter that may be NULL. + This parameter is ignored of ControllerHandle is NULL. + The health status for the controller specified by + ControllerHandle and ChildHandle is returned. + + @param[out] MessageList A pointer to an array of warning or error messages associated + with the controller specified by ControllerHandle and + ChildHandle. This is an optional parameter that may be NULL. + MessageList is allocated by this function with the EFI Boot + Service AllocatePool(), and it is the caller's responsibility + to free MessageList with the EFI Boot Service FreePool(). + Each message is specified by tuple of an EFI_HII_HANDLE and + an EFI_STRING_ID. The array of messages is terminated by tuple + containing a EFI_HII_HANDLE with a value of NULL. The + EFI_HII_STRING_PROTOCOL.GetString() function can be used to + retrieve the warning or error message as a Null-terminated + string in a specific language. Messages may be + returned for any of the HealthStatus values except + EfiDriverHealthStatusReconnectRequired and EfiDriverHealthStatusRebootRequired. - @param[out] FormHiiHandle A pointer to the HII handle containing the HII form used when - configuration is required. The HII handle is associated with + @param[out] FormHiiHandle A pointer to the HII handle containing the HII form used when + configuration is required. The HII handle is associated with the controller specified by ControllerHandle and ChildHandle. If this is NULL, then no HII form is available. An HII handle - will only be returned with a HealthStatus value of + will only be returned with a HealthStatus value of EfiDriverHealthStatusConfigurationRequired. - @retval EFI_SUCCESS ControllerHandle is NULL, and all the controllers - managed by this driver specified by This have a health - status of EfiDriverHealthStatusHealthy with no warning - messages to be returned. The ChildHandle, HealthStatus, + @retval EFI_SUCCESS ControllerHandle is NULL, and all the controllers + managed by this driver specified by This have a health + status of EfiDriverHealthStatusHealthy with no warning + messages to be returned. The ChildHandle, HealthStatus, MessageList, and FormList parameters are ignored. - @retval EFI_DEVICE_ERROR ControllerHandle is NULL, and one or more of the - controllers managed by this driver specified by This - do not have a health status of EfiDriverHealthStatusHealthy. - The ChildHandle, HealthStatus, MessageList, and + @retval EFI_DEVICE_ERROR ControllerHandle is NULL, and one or more of the + controllers managed by this driver specified by This + do not have a health status of EfiDriverHealthStatusHealthy. + The ChildHandle, HealthStatus, MessageList, and FormList parameters are ignored. - @retval EFI_DEVICE_ERROR ControllerHandle is NULL, and one or more of the - controllers managed by this driver specified by This - have one or more warning and/or error messages. - The ChildHandle, HealthStatus, MessageList, and + @retval EFI_DEVICE_ERROR ControllerHandle is NULL, and one or more of the + controllers managed by this driver specified by This + have one or more warning and/or error messages. + The ChildHandle, HealthStatus, MessageList, and FormList parameters are ignored. - @retval EFI_SUCCESS ControllerHandle is not NULL and the health status - of the controller specified by ControllerHandle and - ChildHandle was returned in HealthStatus. A list - of warning and error messages may be optionally - returned in MessageList, and a list of HII Forms + @retval EFI_SUCCESS ControllerHandle is not NULL and the health status + of the controller specified by ControllerHandle and + ChildHandle was returned in HealthStatus. A list + of warning and error messages may be optionally + returned in MessageList, and a list of HII Forms may be optionally returned in FormList. - @retval EFI_UNSUPPORTED ControllerHandle is not NULL, and the controller - specified by ControllerHandle and ChildHandle is not + @retval EFI_UNSUPPORTED ControllerHandle is not NULL, and the controller + specified by ControllerHandle and ChildHandle is not currently being managed by the driver specified by This. @retval EFI_INVALID_PARAMETER HealthStatus is NULL. - @retval EFI_OUT_OF_RESOURCES MessageList is not NULL, and there are not enough + @retval EFI_OUT_OF_RESOURCES MessageList is not NULL, and there are not enough resource available to allocate memory for MessageList. **/ @@ -190,30 +184,30 @@ EFI_STATUS ); /** - Performs a repair operation on a controller in the platform. This function can - optionally report repair progress information back to the platform. - + Performs a repair operation on a controller in the platform. This function can + optionally report repair progress information back to the platform. + @param[in] This A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance. @param[in] ControllerHandle The handle of the controller to repair. - @param[in] ChildHandle The handle of the child controller to repair. This is - an optional parameter that may be NULL. It will be NULL - for device drivers. It will also be NULL for bus + @param[in] ChildHandle The handle of the child controller to repair. This is + an optional parameter that may be NULL. It will be NULL + for device drivers. It will also be NULL for bus drivers when an attempt is made to repair a bus controller. - If will not be NULL when an attempt is made to repair a + If will not be NULL when an attempt is made to repair a child controller produced by the driver. - @param[in] RepairNotify A notification function that may be used by a driver to - report the progress of the repair operation. This is - an optional parameter that may be NULL. + @param[in] RepairNotify A notification function that may be used by a driver to + report the progress of the repair operation. This is + an optional parameter that may be NULL. - @retval EFI_SUCCESS An attempt to repair the controller specified by - ControllerHandle and ChildHandle was performed. - The result of the repair operation can bet + @retval EFI_SUCCESS An attempt to repair the controller specified by + ControllerHandle and ChildHandle was performed. + The result of the repair operation can bet determined by calling GetHealthStatus(). - @retval EFI_UNSUPPORTED The driver specified by This is not currently - managing the controller specified by ControllerHandle + @retval EFI_UNSUPPORTED The driver specified by This is not currently + managing the controller specified by ControllerHandle and ChildHandle. - @retval EFI_OUT_OF_RESOURCES There are not enough resources to perform the + @retval EFI_OUT_OF_RESOURCES There are not enough resources to perform the repair operation. */ @@ -228,10 +222,10 @@ EFI_STATUS /// /// When installed, the Driver Health Protocol produces a collection of services -/// that allow the health status for a controller to be retrieved. If a controller -/// is not in a usable state, status messages may be reported to the user, repair -/// operations can be invoked, and the user may be asked to make software and/or -/// hardware configuration changes. +/// that allow the health status for a controller to be retrieved. If a controller +/// is not in a usable state, status messages may be reported to the user, repair +/// operations can be invoked, and the user may be asked to make software and/or +/// hardware configuration changes. /// struct _EFI_DRIVER_HEALTH_PROTOCOL { EFI_DRIVER_HEALTH_GET_HEALTH_STATUS GetHealthStatus; diff --git a/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h b/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h index 2689ddd7f957..056ac3addfa4 100644 --- a/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h +++ b/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h @@ -4,14 +4,8 @@ required for EFI drivers that are on PCI and other plug-in cards. - Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -24,16 +18,16 @@ /// /// The EFI_DRIVER_SUPPORTED_EFI_VERSION_PROTOCOL provides a -/// mechanism for an EFI driver to publish the version of the EFI -/// specification it conforms to. This protocol must be placed on -/// the driver's image handle when the driver's entry point is +/// mechanism for an EFI driver to publish the version of the EFI +/// specification it conforms to. This protocol must be placed on +/// the driver's image handle when the driver's entry point is /// called. /// typedef struct _EFI_DRIVER_SUPPORTED_EFI_VERSION_PROTOCOL { /// - /// The size, in bytes, of the entire structure. Future versions of this + /// The size, in bytes, of the entire structure. Future versions of this /// specification may grow the size of the structure. - /// + /// UINT32 Length; /// /// The latest version of the UEFI specification that this driver conforms to. diff --git a/MdePkg/Include/Protocol/DxeMmReadyToLock.h b/MdePkg/Include/Protocol/DxeMmReadyToLock.h new file mode 100644 index 000000000000..d406aeefc38f --- /dev/null +++ b/MdePkg/Include/Protocol/DxeMmReadyToLock.h @@ -0,0 +1,19 @@ +/** @file + DXE MM Ready To Lock protocol introduced in the PI 1.5 specification. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _DXE_MM_READY_TO_LOCK_H_ +#define _DXE_MM_READY_TO_LOCK_H_ + +#define EFI_DXE_MM_READY_TO_LOCK_PROTOCOL_GUID \ + { \ + 0x60ff8964, 0xe906, 0x41d0, { 0xaf, 0xed, 0xf2, 0x41, 0xe9, 0x74, 0xe0, 0x8e } \ + } + +extern EFI_GUID gEfiDxeMmReadyToLockProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/DxeSmmReadyToLock.h b/MdePkg/Include/Protocol/DxeSmmReadyToLock.h index 540f4cf5e204..e4756dfc3055 100644 --- a/MdePkg/Include/Protocol/DxeSmmReadyToLock.h +++ b/MdePkg/Include/Protocol/DxeSmmReadyToLock.h @@ -17,24 +17,17 @@ platform code may choose to use notification handler to lock SMM by invoking EFI_SMM_ACCESS2_PROTOCOL.Lock() function. - Copyright (c) 2009 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef _DXE_SMM_READY_TO_LOCK_H_ #define _DXE_SMM_READY_TO_LOCK_H_ -#define EFI_DXE_SMM_READY_TO_LOCK_PROTOCOL_GUID \ - { \ - 0x60ff8964, 0xe906, 0x41d0, { 0xaf, 0xed, 0xf2, 0x41, 0xe9, 0x74, 0xe0, 0x8e } \ - } +#include <Protocol/DxeMmReadyToLock.h> + +#define EFI_DXE_SMM_READY_TO_LOCK_PROTOCOL_GUID EFI_DXE_MM_READY_TO_LOCK_PROTOCOL_GUID extern EFI_GUID gEfiDxeSmmReadyToLockProtocolGuid; diff --git a/MdePkg/Include/Protocol/Eap.h b/MdePkg/Include/Protocol/Eap.h index e91deb867006..3c2afa4cd4af 100644 --- a/MdePkg/Include/Protocol/Eap.h +++ b/MdePkg/Include/Protocol/Eap.h @@ -1,20 +1,14 @@ /** @file EFI EAP(Extended Authenticaton Protocol) Protocol Definition The EFI EAP Protocol is used to abstract the ability to configure and extend the - EAP framework. + EAP framework. The definitions in this file are defined in UEFI Specification 2.3.1B, which have not been verified by one implementation yet. - Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: + @par Revision Reference: This Protocol is introduced in UEFI Specification 2.2 **/ @@ -31,7 +25,7 @@ typedef struct _EFI_EAP_PROTOCOL EFI_EAP_PROTOCOL; /// -/// Type for the identification number assigned to the Port by the +/// Type for the identification number assigned to the Port by the /// System in which the Port resides. /// typedef VOID * EFI_PORT_HANDLE; @@ -61,7 +55,7 @@ typedef VOID * EFI_PORT_HANDLE; @param[in] RequestSize Packet size in bytes for the most recently received EAP-Request packet. @param[in] Buffer Pointer to the buffer to hold the built packet. - @param[in, out] BufferSize Pointer to the buffer size in bytes. + @param[in, out] BufferSize Pointer to the buffer size in bytes. On input, it is the buffer size provided by the caller. On output, it is the buffer size in fact needed to contain the packet. @@ -74,32 +68,32 @@ typedef EFI_STATUS (EFIAPI *EFI_EAP_BUILD_RESPONSE_PACKET)( IN EFI_PORT_HANDLE PortNumber, - IN UINT8 *RequestBuffer, - IN UINTN RequestSize, - IN UINT8 *Buffer, + IN UINT8 *RequestBuffer, + IN UINTN RequestSize, + IN UINT8 *Buffer, IN OUT UINTN *BufferSize ); /** Set the desired EAP authentication method for the Port. - The SetDesiredAuthMethod() function sets the desired EAP authentication method indicated + The SetDesiredAuthMethod() function sets the desired EAP authentication method indicated by EapAuthType for the Port. - - If EapAuthType is an invalid EAP authentication type, then EFI_INVALID_PARAMETER is + + If EapAuthType is an invalid EAP authentication type, then EFI_INVALID_PARAMETER is returned. If the EAP authentication method of EapAuthType is unsupported by the Ports, then it will return EFI_UNSUPPORTED. - The cryptographic strength of EFI_EAP_TYPE_TLS shall be at least of hash strength + The cryptographic strength of EFI_EAP_TYPE_TLS shall be at least of hash strength SHA-256 and RSA key length of at least 2048 bits. - - @param[in] This A pointer to the EFI_EAP_PROTOCOL instance that indicates + + @param[in] This A pointer to the EFI_EAP_PROTOCOL instance that indicates the calling context. - @param[in] EapAuthType The type of the EAP authentication method to register. It should + @param[in] EapAuthType The type of the EAP authentication method to register. It should be the type value defined by RFC. See RFC 2284 for details. @param[in] Handler The handler of the EAP authentication method to register. - @retval EFI_SUCCESS The EAP authentication method of EapAuthType is + @retval EFI_SUCCESS The EAP authentication method of EapAuthType is registered successfully. @retval EFI_INVALID_PARAMETER EapAuthType is an invalid EAP authentication type. @retval EFI_UNSUPPORTED The EAP authentication method of EapAuthType is @@ -109,28 +103,28 @@ EFI_STATUS typedef EFI_STATUS (EFIAPI *EFI_EAP_SET_DESIRED_AUTHENTICATION_METHOD)( - IN EFI_EAP_PROTOCOL *This, + IN EFI_EAP_PROTOCOL *This, IN UINT8 EapAuthType ); /** - Register an EAP authentication method. + Register an EAP authentication method. + + The RegisterAuthMethod() function registers the user provided EAP authentication method, + the type of which is EapAuthType and the handler of which is Handler. - The RegisterAuthMethod() function registers the user provided EAP authentication method, - the type of which is EapAuthType and the handler of which is Handler. - - If EapAuthType is an invalid EAP authentication type, then EFI_INVALID_PARAMETER is + If EapAuthType is an invalid EAP authentication type, then EFI_INVALID_PARAMETER is returned. - If there is not enough system memory to perform the registration, then + If there is not enough system memory to perform the registration, then EFI_OUT_OF_RESOURCES is returned. - @param[in] This A pointer to the EFI_EAP_PROTOCOL instance that indicates + @param[in] This A pointer to the EFI_EAP_PROTOCOL instance that indicates the calling context. - @param[in] EapAuthType The type of the EAP authentication method to register. It should + @param[in] EapAuthType The type of the EAP authentication method to register. It should be the type value defined by RFC. See RFC 2284 for details. @param[in] Handler The handler of the EAP authentication method to register. - @retval EFI_SUCCESS The EAP authentication method of EapAuthType is + @retval EFI_SUCCESS The EAP authentication method of EapAuthType is registered successfully. @retval EFI_INVALID_PARAMETER EapAuthType is an invalid EAP authentication type. @retval EFI_OUT_OF_RESOURCES There is not enough system memory to perform the registration. @@ -139,17 +133,17 @@ EFI_STATUS typedef EFI_STATUS (EFIAPI *EFI_EAP_REGISTER_AUTHENTICATION_METHOD)( - IN EFI_EAP_PROTOCOL *This, - IN UINT8 EapAuthType, + IN EFI_EAP_PROTOCOL *This, + IN UINT8 EapAuthType, IN EFI_EAP_BUILD_RESPONSE_PACKET Handler ); /// -/// EFI_EAP_PROTOCOL -/// is used to configure the desired EAP authentication method for the EAP +/// EFI_EAP_PROTOCOL +/// is used to configure the desired EAP authentication method for the EAP /// framework and extend the EAP framework by registering new EAP authentication /// method on a Port. The EAP framework is built on a per-Port basis. Herein, a -/// Port means a NIC. For the details of EAP protocol, please refer to RFC 2284. +/// Port means a NIC. For the details of EAP protocol, please refer to RFC 2284. /// struct _EFI_EAP_PROTOCOL { EFI_EAP_SET_DESIRED_AUTHENTICATION_METHOD SetDesiredAuthMethod; diff --git a/MdePkg/Include/Protocol/EapConfiguration.h b/MdePkg/Include/Protocol/EapConfiguration.h index dc30e62ad033..698d835410a2 100644 --- a/MdePkg/Include/Protocol/EapConfiguration.h +++ b/MdePkg/Include/Protocol/EapConfiguration.h @@ -1,14 +1,8 @@ /** @file This file defines the EFI EAP Configuration protocol. - Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.5 @@ -156,4 +150,4 @@ struct _EFI_EAP_CONFIGURATION_PROTOCOL { extern EFI_GUID gEfiEapConfigurationProtocolGuid; -#endif
\ No newline at end of file +#endif diff --git a/MdePkg/Include/Protocol/EapManagement.h b/MdePkg/Include/Protocol/EapManagement.h index 8fe4afb2a17d..c65bc1bdf032 100644 --- a/MdePkg/Include/Protocol/EapManagement.h +++ b/MdePkg/Include/Protocol/EapManagement.h @@ -1,21 +1,15 @@ /** @file EFI EAP Management Protocol Definition The EFI EAP Management Protocol is designed to provide ease of management and - ease of test for EAPOL state machine. It is intended for the supplicant side. - It conforms to IEEE 802.1x specification. + ease of test for EAPOL state machine. It is intended for the supplicant side. + It conforms to IEEE 802.1x specification. The definitions in this file are defined in UEFI Specification 2.2, which have not been verified by one implementation yet. - Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: + @par Revision Reference: This Protocol is introduced in UEFI Specification 2.2 **/ @@ -43,22 +37,22 @@ typedef struct _EFI_EAP_MANAGEMENT_PROTOCOL EFI_EAP_MANAGEMENT_PROTOCOL; /// /// EFI_EAPOL_PORT_INFO /// -typedef struct _EFI_EAPOL_PORT_INFO { - /// - /// The identification number assigned to the Port by the System in +typedef struct _EFI_EAPOL_PORT_INFO { + /// + /// The identification number assigned to the Port by the System in /// which the Port resides. - /// + /// EFI_PORT_HANDLE PortNumber; - /// - /// The protocol version number of the EAPOL implementation - /// supported by the Port. - /// + /// + /// The protocol version number of the EAPOL implementation + /// supported by the Port. + /// UINT8 ProtocolVersion; - /// - /// The capabilities of the PAE associated with the Port. This field - /// indicates whether Authenticator functionality, Supplicant + /// + /// The capabilities of the PAE associated with the Port. This field + /// indicates whether Authenticator functionality, Supplicant /// functionality, both, or neither, is supported by the Port's PAE. - /// + /// UINT8 PaeCapabilities; } EFI_EAPOL_PORT_INFO; @@ -77,7 +71,7 @@ typedef enum _EFI_EAPOL_SUPPLICANT_PAE_STATE { } EFI_EAPOL_SUPPLICANT_PAE_STATE; /// -/// Definitions for ValidFieldMask +/// Definitions for ValidFieldMask /// ///@{ #define AUTH_PERIOD_FIELD_VALID 0x01 @@ -90,27 +84,27 @@ typedef enum _EFI_EAPOL_SUPPLICANT_PAE_STATE { /// EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION /// typedef struct _EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION { - /// + /// /// Indicates which of the following fields are valid. - /// - UINT8 ValidFieldMask; + /// + UINT8 ValidFieldMask; /// /// The initial value for the authWhile timer. Its default value is 30s. /// - UINTN AuthPeriod; + UINTN AuthPeriod; + /// + /// The initial value for the heldWhile timer. Its default value is 60s. /// - /// The initial value for the heldWhile timer. Its default value is 60s. + UINTN HeldPeriod; /// - UINTN HeldPeriod; + /// The initial value for the startWhen timer. Its default value is 30s. /// - /// The initial value for the startWhen timer. Its default value is 30s. + UINTN StartPeriod; /// - UINTN StartPeriod; - /// - /// The maximum number of successive EAPOL-Start messages will - /// be sent before the Supplicant assumes that there is no + /// The maximum number of successive EAPOL-Start messages will + /// be sent before the Supplicant assumes that there is no /// Authenticator present. Its default value is 3. - /// + /// UINTN MaxStart; } EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION; @@ -120,17 +114,17 @@ typedef struct _EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION { typedef struct _EFI_EAPOL_SUPPLICANT_PAE_STATISTICS { /// /// The number of EAPOL frames of any type that have been received by this Supplican. - /// + /// UINTN EapolFramesReceived; /// - /// The number of EAPOL frames of any type that have been transmitted by this Supplicant. + /// The number of EAPOL frames of any type that have been transmitted by this Supplicant. /// UINTN EapolFramesTransmitted; - /// - /// The number of EAPOL Start frames that have been transmitted by this Supplicant. - /// + /// + /// The number of EAPOL Start frames that have been transmitted by this Supplicant. + /// UINTN EapolStartFramesTransmitted; - /// + /// /// The number of EAPOL Logoff frames that have been transmitted by this Supplicant. /// UINTN EapolLogoffFramesTransmitted; @@ -138,48 +132,48 @@ typedef struct _EFI_EAPOL_SUPPLICANT_PAE_STATISTICS { /// The number of EAP Resp/Id frames that have been transmitted by this Supplicant. /// UINTN EapRespIdFramesTransmitted; - /// - /// The number of valid EAP Response frames (other than Resp/Id frames) that have been + /// + /// The number of valid EAP Response frames (other than Resp/Id frames) that have been /// transmitted by this Supplicant. /// UINTN EapResponseFramesTransmitted; - /// + /// /// The number of EAP Req/Id frames that have been received by this Supplicant. - /// + /// UINTN EapReqIdFramesReceived; /// - /// The number of EAP Request frames (other than Rq/Id frames) that have been received + /// The number of EAP Request frames (other than Rq/Id frames) that have been received /// by this Supplicant. /// UINTN EapRequestFramesReceived; /// - /// The number of EAPOL frames that have been received by this Supplicant in which the + /// The number of EAPOL frames that have been received by this Supplicant in which the /// frame type is not recognized. /// UINTN InvalidEapolFramesReceived; - /// - /// The number of EAPOL frames that have been received by this Supplicant in which the + /// + /// The number of EAPOL frames that have been received by this Supplicant in which the /// Packet Body Length field (7.5.5) is invalid. - /// + /// UINTN EapLengthErrorFramesReceived; - /// + /// /// The protocol version number carried in the most recently received EAPOL frame. - /// + /// UINTN LastEapolFrameVersion; - /// + /// /// The source MAC address carried in the most recently received EAPOL frame. - /// + /// UINTN LastEapolFrameSource; } EFI_EAPOL_SUPPLICANT_PAE_STATISTICS; /** - Read the system configuration information associated with the Port. + Read the system configuration information associated with the Port. The GetSystemConfiguration() function reads the system configuration - information associated with the Port, including the value of the + information associated with the Port, including the value of the SystemAuthControl parameter of the System is returned in SystemAuthControl and the Port's information is returned in the buffer pointed to by PortInfo. - The Port's information is optional. + The Port's information is optional. If PortInfo is NULL, then reading the Port's information is ignored. If SystemAuthControl is NULL, then EFI_INVALID_PARAMETER is returned. @@ -187,7 +181,7 @@ typedef struct _EFI_EAPOL_SUPPLICANT_PAE_STATISTICS { @param[in] This A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL instance that indicates the calling context. @param[out] SystemAuthControl Returns the value of the SystemAuthControl - parameter of the System. + parameter of the System. TRUE means Enabled. FALSE means Disabled. @param[out] PortInfo Returns EFI_EAPOL_PORT_INFO structure to describe the Port's information. This parameter can be NULL @@ -202,21 +196,21 @@ typedef struct _EFI_EAPOL_SUPPLICANT_PAE_STATISTICS { typedef EFI_STATUS (EFIAPI *EFI_EAP_GET_SYSTEM_CONFIGURATION)( - IN EFI_EAP_MANAGEMENT_PROTOCOL *This, - OUT BOOLEAN *SystemAuthControl, + IN EFI_EAP_MANAGEMENT_PROTOCOL *This, + OUT BOOLEAN *SystemAuthControl, OUT EFI_EAPOL_PORT_INFO *PortInfo OPTIONAL ); /** - Set the system configuration information associated with the Port. + Set the system configuration information associated with the Port. - The SetSystemConfiguration() function sets the value of the SystemAuthControl + The SetSystemConfiguration() function sets the value of the SystemAuthControl parameter of the System to SystemAuthControl. @param[in] This A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL instance that indicates the calling context. - @param[in] SystemAuthControl The desired value of the SystemAuthControl - parameter of the System. + @param[in] SystemAuthControl The desired value of the SystemAuthControl + parameter of the System. TRUE means Enabled. FALSE means Disabled. @retval EFI_SUCCESS The system configuration information of the @@ -226,7 +220,7 @@ EFI_STATUS typedef EFI_STATUS (EFIAPI *EFI_EAP_SET_SYSTEM_CONFIGURATION)( - IN EFI_EAP_MANAGEMENT_PROTOCOL *This, + IN EFI_EAP_MANAGEMENT_PROTOCOL *This, IN BOOLEAN SystemAuthControl ); @@ -266,7 +260,7 @@ EFI_STATUS ); /** - Notify the EAPOL state machines for the Port that the user of the System has + Notify the EAPOL state machines for the Port that the user of the System has logged off. The UserLogoff() function notifies the EAPOL state machines for the Port. @@ -290,8 +284,8 @@ EFI_STATUS The GetSupplicantStatus() function reads the status of the Supplicant PAE state machine for the Port, including the current state CurrentState and the configuration of the operational parameters Configuration. The configuration of the operational - parameters is optional. If Configuration is NULL, then reading the configuration - is ignored. The operational parameters in Configuration to be read can also be + parameters is optional. If Configuration is NULL, then reading the configuration + is ignored. The operational parameters in Configuration to be read can also be specified by Configuration.ValidFieldMask. If CurrentState is NULL, then EFI_INVALID_PARAMETER is returned. @@ -303,11 +297,11 @@ EFI_STATUS @param[in, out] Configuration Returns the configuration of the operational parameters of the Supplicant PAE state machine for the Port as required. This parameter can be - NULL to ignore reading the configuration. - On input, Configuration.ValidFieldMask specifies the + NULL to ignore reading the configuration. + On input, Configuration.ValidFieldMask specifies the operational parameters to be read. On output, Configuration returns the configuration - of the required operational parameters. + of the required operational parameters. @retval EFI_SUCCESS The configuration of the operational parameter of the Supplicant PAE state machine for the Port @@ -318,16 +312,16 @@ EFI_STATUS typedef EFI_STATUS (EFIAPI *EFI_EAP_GET_SUPPLICANT_STATUS)( - IN EFI_EAP_MANAGEMENT_PROTOCOL *This, - OUT EFI_EAPOL_SUPPLICANT_PAE_STATE *CurrentState, + IN EFI_EAP_MANAGEMENT_PROTOCOL *This, + OUT EFI_EAPOL_SUPPLICANT_PAE_STATE *CurrentState, IN OUT EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION *Configuration OPTIONAL ); /** - Set the configuration of the operational parameter of the Supplicant PAE + Set the configuration of the operational parameter of the Supplicant PAE state machine for the Port. - The SetSupplicantConfiguration() function sets the configuration of the + The SetSupplicantConfiguration() function sets the configuration of the operational Parameter of the Supplicant PAE state machine for the Port to Configuration. The operational parameters in Configuration to be set can be specified by Configuration.ValidFieldMask. @@ -336,7 +330,7 @@ EFI_STATUS @param[in] This A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL instance that indicates the calling context. - @param[in] Configuration The desired configuration of the operational + @param[in] Configuration The desired configuration of the operational parameters of the Supplicant PAE state machine for the Port as required. @@ -349,23 +343,23 @@ EFI_STATUS typedef EFI_STATUS (EFIAPI *EFI_EAP_SET_SUPPLICANT_CONFIGURATION)( - IN EFI_EAP_MANAGEMENT_PROTOCOL *This, + IN EFI_EAP_MANAGEMENT_PROTOCOL *This, IN EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION *Configuration ); /** Read the statistical information regarding the operation of the Supplicant - associated with the Port. + associated with the Port. - The GetSupplicantStatistics() function reads the statistical information + The GetSupplicantStatistics() function reads the statistical information Statistics regarding the operation of the Supplicant associated with the Port. - + If Statistics is NULL, then EFI_INVALID_PARAMETER is returned. @param[in] This A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL instance that indicates the calling context. - @param[out] Statistics Returns the statistical information regarding the - operation of the Supplicant for the Port. + @param[out] Statistics Returns the statistical information regarding the + operation of the Supplicant for the Port. @retval EFI_SUCCESS The statistical information regarding the operation of the Supplicant for the Port is read successfully. @@ -375,15 +369,15 @@ EFI_STATUS typedef EFI_STATUS (EFIAPI *EFI_EAP_GET_SUPPLICANT_STATISTICS)( - IN EFI_EAP_MANAGEMENT_PROTOCOL *This, + IN EFI_EAP_MANAGEMENT_PROTOCOL *This, OUT EFI_EAPOL_SUPPLICANT_PAE_STATISTICS *Statistics ); /// -/// EFI_EAP_MANAGEMENT_PROTOCOL +/// EFI_EAP_MANAGEMENT_PROTOCOL /// is used to control, configure and monitor EAPOL state machine on /// a Port. EAPOL state machine is built on a per-Port basis. Herein, -/// a Port means a NIC. For the details of EAPOL, please refer to +/// a Port means a NIC. For the details of EAPOL, please refer to /// IEEE 802.1x specification. /// struct _EFI_EAP_MANAGEMENT_PROTOCOL { diff --git a/MdePkg/Include/Protocol/EapManagement2.h b/MdePkg/Include/Protocol/EapManagement2.h index d1e5981d0374..faae59116f5b 100644 --- a/MdePkg/Include/Protocol/EapManagement2.h +++ b/MdePkg/Include/Protocol/EapManagement2.h @@ -2,13 +2,7 @@ This file defines the EFI EAP Management2 protocol. Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.5 diff --git a/MdePkg/Include/Protocol/Ebc.h b/MdePkg/Include/Protocol/Ebc.h index dd6320d61cf4..ff28fcacb29c 100644 --- a/MdePkg/Include/Protocol/Ebc.h +++ b/MdePkg/Include/Protocol/Ebc.h @@ -1,14 +1,8 @@ /** @file Describes the protocol interface to the EBC interpreter. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -193,7 +187,7 @@ typedef struct _EFI_EBC_PROTOCOL EFI_EBC_PROTOCOL; /** Creates a thunk for an EBC entry point, returning the address of the thunk. - + A PE32+ EBC image, like any other PE32+ image, contains an optional header that specifies the entry point for image execution. However, for EBC images, this is the entry point of EBC instructions, so is not directly executable by the native processor. Therefore, when an EBC image is @@ -229,7 +223,7 @@ EFI_STATUS @param ImageHandle Image handle of the EBC image that is being unloaded from memory. @retval EFI_SUCCESS The function completed successfully. - @retval EFI_INVALID_PARAMETER Image handle is not recognized as belonging + @retval EFI_INVALID_PARAMETER Image handle is not recognized as belonging to an EBC image that has been executed. **/ typedef @@ -240,7 +234,7 @@ EFI_STATUS ); /** - This is the prototype for the Flush callback routine. A pointer to a routine + This is the prototype for the Flush callback routine. A pointer to a routine of this type is passed to the EBC EFI_EBC_REGISTER_ICACHE_FLUSH protocol service. @param Start The beginning physical address to flush from the processor's instruction cache. @@ -257,7 +251,7 @@ EFI_STATUS ); /** - Registers a callback function that the EBC interpreter calls to flush + Registers a callback function that the EBC interpreter calls to flush the processor instruction cache following creation of thunks. @param This A pointer to the EFI_EBC_PROTOCOL instance. @@ -279,7 +273,7 @@ EFI_STATUS This function is called to get the version of the loaded EBC interpreter. The value and format of the returned version is identical to that returned by the EBC BREAK 1 instruction. - @param This A pointer to the EFI_EBC_PROTOCOL instance. + @param This A pointer to the EFI_EBC_PROTOCOL instance. @param Version Pointer to where to store the returned version of the interpreter. @retval EFI_SUCCESS The function completed successfully. diff --git a/MdePkg/Include/Protocol/EdidActive.h b/MdePkg/Include/Protocol/EdidActive.h index 8e1ec8426288..531d077334ad 100644 --- a/MdePkg/Include/Protocol/EdidActive.h +++ b/MdePkg/Include/Protocol/EdidActive.h @@ -3,14 +3,8 @@ Placed on the video output device child handle that is actively displaying output. - Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Protocol/EdidDiscovered.h b/MdePkg/Include/Protocol/EdidDiscovered.h index ccaae1bbb353..4975564adc57 100644 --- a/MdePkg/Include/Protocol/EdidDiscovered.h +++ b/MdePkg/Include/Protocol/EdidDiscovered.h @@ -4,14 +4,8 @@ This protocol is placed on the video output device child handle. It represents the EDID information being used for the output device represented by the child handle. - Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -33,7 +27,7 @@ typedef struct { /// minimum of 128 bytes. /// UINT32 SizeOfEdid; - + /// /// A pointer to a read-only array of bytes that contains the EDID /// information for an active video output device. This pointer is @@ -41,7 +35,7 @@ typedef struct { /// device. The minimum size of a valid Edid buffer is 128 bytes. /// EDID information is defined in the E-EDID EEPROM /// specification published by VESA (www.vesa.org). - /// + /// UINT8 *Edid; } EFI_EDID_DISCOVERED_PROTOCOL; diff --git a/MdePkg/Include/Protocol/EdidOverride.h b/MdePkg/Include/Protocol/EdidOverride.h index cd847b666d75..6c7c082eab54 100644 --- a/MdePkg/Include/Protocol/EdidOverride.h +++ b/MdePkg/Include/Protocol/EdidOverride.h @@ -4,14 +4,8 @@ Allow platform to provide EDID information to the producer of the Graphics Output protocol. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -50,18 +44,18 @@ EFI_STATUS IN EFI_EDID_OVERRIDE_PROTOCOL *This, IN EFI_HANDLE *ChildHandle, OUT UINT32 *Attributes, - IN OUT UINTN *EdidSize, - IN OUT UINT8 **Edid + OUT UINTN *EdidSize, + OUT UINT8 **Edid ); /// -/// This protocol is produced by the platform to allow the platform to provide +/// This protocol is produced by the platform to allow the platform to provide /// EDID information to the producer of the Graphics Output protocol. /// struct _EFI_EDID_OVERRIDE_PROTOCOL { EFI_EDID_OVERRIDE_PROTOCOL_GET_EDID GetEdid; }; - + extern EFI_GUID gEfiEdidOverrideProtocolGuid; #endif diff --git a/MdePkg/Include/Protocol/EraseBlock.h b/MdePkg/Include/Protocol/EraseBlock.h index d136ccee24a8..bfedcf32c249 100644 --- a/MdePkg/Include/Protocol/EraseBlock.h +++ b/MdePkg/Include/Protocol/EraseBlock.h @@ -2,13 +2,7 @@ This file defines the EFI Erase Block Protocol. Copyright (c) 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.6 diff --git a/MdePkg/Include/Protocol/ExtendedSalBootService.h b/MdePkg/Include/Protocol/ExtendedSalBootService.h deleted file mode 100644 index 167201d85a95..000000000000 --- a/MdePkg/Include/Protocol/ExtendedSalBootService.h +++ /dev/null @@ -1,214 +0,0 @@ -/** @file - Definition of Extended SAL Boot Service Protocol - - The Extended SAL Boot Service Protocol provides a mechanisms for platform specific - drivers to update the SAL System Table and register Extended SAL Procedures that are - callable in physical or virtual mode using the SAL calling convention. - - Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -**/ - -#ifndef _EXTENDED_SAL_BOOT_SERVICE_PROTOCOL_H_ -#define _EXTENDED_SAL_BOOT_SERVICE_PROTOCOL_H_ - -#include <IndustryStandard/Sal.h> - -#define EXTENDED_SAL_BOOT_SERVICE_PROTOCOL_GUID \ - { 0xde0ee9a4, 0x3c7a, 0x44f2, {0xb7, 0x8b, 0xe3, 0xcc, 0xd6, 0x9c, 0x3a, 0xf7 } } - -typedef struct _EXTENDED_SAL_BOOT_SERVICE_PROTOCOL EXTENDED_SAL_BOOT_SERVICE_PROTOCOL; - -/** - Adds platform specific information to the to the header of the SAL System Table. - - @param This A pointer to the EXTENDED_SAL_BOOT_SERVICE_PROTOCOL instance. - @param SalAVersion Version of recovery SAL PEIM(s) in BCD format. Higher byte contains - the major revision and the lower byte contains the minor revision. - @param SalBVersion Version of DXE SAL Driver in BCD format. Higher byte contains - the major revision and the lower byte contains the minor revision. - @param OemId A pointer to a Null-terminated ASCII string that contains OEM unique string. - The string cannot be longer than 32 bytes in total length - @param ProductId A pointer to a Null-terminated ASCII string that uniquely identifies a family of - compatible products. The string cannot be longer than 32 bytes in total length. - - @retval EFI_SUCCESS The SAL System Table header was updated successfully. - @retval EFI_INVALID_PARAMETER OemId is NULL. - @retval EFI_INVALID_PARAMETER ProductId is NULL. - @retval EFI_INVALID_PARAMETER The length of OemId is greater than 32 characters. - @retval EFI_INVALID_PARAMETER The length of ProductId is greater than 32 characters. - -**/ -typedef -EFI_STATUS -(EFIAPI *EXTENDED_SAL_ADD_SST_INFO)( - IN EXTENDED_SAL_BOOT_SERVICE_PROTOCOL *This, - IN UINT16 SalAVersion, - IN UINT16 SalBVersion, - IN CHAR8 *OemId, - IN CHAR8 *ProductId - ); - -/** - Adds an entry to the SAL System Table. - - This function adds the SAL System Table Entry specified by TableEntry and EntrySize - to the SAL System Table. - - @param This A pointer to the EXTENDED_SAL_BOOT_SERVICE_PROTOCOL instance. - @param TableEntry Pointer to a buffer containing a SAL System Table entry that is EntrySize bytes - in length. The first byte of the TableEntry describes the type of entry. - @param EntrySize The size, in bytes, of TableEntry. - - @retval EFI_SUCCESSThe SAL System Table was updated successfully. - @retval EFI_INVALID_PARAMETER TableEntry is NULL. - @retval EFI_INVALID_PARAMETER TableEntry specifies an invalid entry type. - @retval EFI_INVALID_PARAMETER EntrySize is not valid for this type of entry. - -**/ -typedef -EFI_STATUS -(EFIAPI *EXTENDED_SAL_ADD_SST_ENTRY)( - IN EXTENDED_SAL_BOOT_SERVICE_PROTOCOL *This, - IN UINT8 *TableEntry, - IN UINTN EntrySize - ); - -/** - Internal ESAL procedures. - - This is prototype of internal Extended SAL procedures, which is registerd by - EXTENDED_SAL_REGISTER_INTERNAL_PROC service. - - @param FunctionId The Function ID associated with this Extended SAL Procedure. - @param Arg2 Second argument to the Extended SAL procedure. - @param Arg3 Third argument to the Extended SAL procedure. - @param Arg4 Fourth argument to the Extended SAL procedure. - @param Arg5 Fifth argument to the Extended SAL procedure. - @param Arg6 Sixth argument to the Extended SAL procedure. - @param Arg7 Seventh argument to the Extended SAL procedure. - @param Arg8 Eighth argument to the Extended SAL procedure. - @param VirtualMode TRUE if the Extended SAL Procedure is being invoked in virtual mode. - FALSE if the Extended SAL Procedure is being invoked in physical mode. - @param ModuleGlobal A pointer to the global context associated with this Extended SAL Procedure. - - @return The result returned from the specified Extended SAL Procedure - -**/ -typedef -SAL_RETURN_REGS -(EFIAPI *SAL_INTERNAL_EXTENDED_SAL_PROC)( - IN UINT64 FunctionId, - IN UINT64 Arg2, - IN UINT64 Arg3, - IN UINT64 Arg4, - IN UINT64 Arg5, - IN UINT64 Arg6, - IN UINT64 Arg7, - IN UINT64 Arg8, - IN BOOLEAN VirtualMode, - IN VOID *ModuleGlobal OPTIONAL - ); - -/** - Registers an Extended SAL Procedure. - - The Extended SAL Procedure specified by InternalSalProc and named by ClassGuidLo, - ClassGuidHi, and FunctionId is added to the set of available Extended SAL Procedures. - - @param This A pointer to the EXTENDED_SAL_BOOT_SERVICE_PROTOCOL instance. - @param ClassGuidLo The lower 64-bits of the class GUID for the Extended SAL Procedure being added. - Each class GUID contains one or more functions specified by a Function ID. - @param ClassGuidHi The upper 64-bits of the class GUID for the Extended SAL Procedure being added. - Each class GUID contains one or more functions specified by a Function ID. - @param FunctionId The Function ID for the Extended SAL Procedure that is being added. This Function - ID is a member of the Extended SAL Procedure class specified by ClassGuidLo - and ClassGuidHi. - @param InternalSalProc A pointer to the Extended SAL Procedure being added. - @param PhysicalModuleGlobal Pointer to a module global structure. This is a physical mode pointer. - This pointer is passed to the Extended SAL Procedure specified by ClassGuidLo, - ClassGuidHi, FunctionId, and InternalSalProc. If the system is in physical mode, - then this pointer is passed unmodified to InternalSalProc. If the system is in - virtual mode, then the virtual address associated with this pointer is passed to - InternalSalProc. - - @retval EFI_SUCCESS The Extended SAL Procedure was added. - @retval EFI_OUT_OF_RESOURCES There are not enough resources available to add the Extended SAL Procedure. - -**/ -typedef -EFI_STATUS -(EFIAPI *EXTENDED_SAL_REGISTER_INTERNAL_PROC)( - IN EXTENDED_SAL_BOOT_SERVICE_PROTOCOL *This, - IN UINT64 ClassGuidLo, - IN UINT64 ClassGuidHi, - IN UINT64 FunctionId, - IN SAL_INTERNAL_EXTENDED_SAL_PROC InternalSalProc, - IN VOID *PhysicalModuleGlobal OPTIONAL - ); - -/** - Calls a previously registered Extended SAL Procedure. - - This function calls the Extended SAL Procedure specified by ClassGuidLo, ClassGuidHi, - and FunctionId. The set of previously registered Extended SAL Procedures is searched for a - matching ClassGuidLo, ClassGuidHi, and FunctionId. If a match is not found, then - EFI_SAL_NOT_IMPLEMENTED is returned. - - @param ClassGuidLo The lower 64-bits of the class GUID for the Extended SAL Procedure - that is being called. - @param ClassGuidHi The upper 64-bits of the class GUID for the Extended SAL Procedure - that is being called. - @param FunctionId Function ID for the Extended SAL Procedure being called. - @param Arg2 Second argument to the Extended SAL procedure. - @param Arg3 Third argument to the Extended SAL procedure. - @param Arg4 Fourth argument to the Extended SAL procedure. - @param Arg5 Fifth argument to the Extended SAL procedure. - @param Arg6 Sixth argument to the Extended SAL procedure. - @param Arg7 Seventh argument to the Extended SAL procedure. - @param Arg8 Eighth argument to the Extended SAL procedure. - - @retval EFI_SAL_NOT_IMPLEMENTED The Extended SAL Procedure specified by ClassGuidLo, - ClassGuidHi, and FunctionId has not been registered. - @retval EFI_SAL_VIRTUAL_ADDRESS_ERROR This function was called in virtual mode before virtual mappings - for the specified Extended SAL Procedure are available. - @retval Other The result returned from the specified Extended SAL Procedure - -**/ -typedef -SAL_RETURN_REGS -(EFIAPI *EXTENDED_SAL_PROC)( - IN UINT64 ClassGuidLo, - IN UINT64 ClassGuidHi, - IN UINT64 FunctionId, - IN UINT64 Arg2, - IN UINT64 Arg3, - IN UINT64 Arg4, - IN UINT64 Arg5, - IN UINT64 Arg6, - IN UINT64 Arg7, - IN UINT64 Arg8 - ); - -/// -/// The EXTENDED_SAL_BOOT_SERVICE_PROTOCOL provides a mechanisms for platform specific -/// drivers to update the SAL System Table and register Extended SAL Procedures that are -/// callable in physical or virtual mode using the SAL calling convention. -/// -struct _EXTENDED_SAL_BOOT_SERVICE_PROTOCOL { - EXTENDED_SAL_ADD_SST_INFO AddSalSystemTableInfo; - EXTENDED_SAL_ADD_SST_ENTRY AddSalSystemTableEntry; - EXTENDED_SAL_REGISTER_INTERNAL_PROC RegisterExtendedSalProc; - EXTENDED_SAL_PROC ExtendedSalProc; -}; - -extern EFI_GUID gEfiExtendedSalBootServiceProtocolGuid; - -#endif diff --git a/MdePkg/Include/Protocol/ExtendedSalServiceClasses.h b/MdePkg/Include/Protocol/ExtendedSalServiceClasses.h deleted file mode 100644 index 126beedacf2e..000000000000 --- a/MdePkg/Include/Protocol/ExtendedSalServiceClasses.h +++ /dev/null @@ -1,275 +0,0 @@ -/** @file - The standard set of Extended SAL service classes. - - Copyright (c) 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -**/ - -#ifndef _EXTENDED_SAL_SERVICE_CLASSES_H_ -#define _EXTENDED_SAL_SERVICE_CLASSES_H_ - -/// -/// Extended SAL Base I/O Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_BASE_IO_SERVICES_PROTOCOL_GUID_LO 0x451531e15aea42b5 -#define EFI_EXTENDED_SAL_BASE_IO_SERVICES_PROTOCOL_GUID_HI 0xa6657525d5b831bc -#define EFI_EXTENDED_SAL_BASE_IO_SERVICES_PROTOCOL_GUID \ - { 0x5aea42b5, 0x31e1, 0x4515, {0xbc, 0x31, 0xb8, 0xd5, 0x25, 0x75, 0x65, 0xa6 } } - -typedef enum { - IoReadFunctionId, - IoWriteFunctionId, - MemReadFunctionId, - MemWriteFunctionId -} EFI_EXTENDED_SAL_BASE_IO_SERVICES_FUNC_ID; -///@} - -/// -/// Extended SAL Stall Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_STALL_SERVICES_PROTOCOL_GUID_LO 0x4d8cac2753a58d06 -#define EFI_EXTENDED_SAL_STALL_SERVICES_PROTOCOL_GUID_HI 0x704165808af0e9b5 -#define EFI_EXTENDED_SAL_STALL_SERVICES_PROTOCOL_GUID \ - { 0x53a58d06, 0xac27, 0x4d8c, {0xb5, 0xe9, 0xf0, 0x8a, 0x80, 0x65, 0x41, 0x70 } } - -typedef enum { - StallFunctionId -} EFI_EXTENDED_SAL_STALL_FUNC_ID; -///@} - -/// -/// Extended SAL Real Time Clock Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_RTC_SERVICES_PROTOCOL_GUID_LO 0x4d02efdb7e97a470 -#define EFI_EXTENDED_SAL_RTC_SERVICES_PROTOCOL_GUID_HI 0x96a27bd29061ce8f -#define EFI_EXTENDED_SAL_RTC_SERVICES_PROTOCOL_GUID \ - { 0x7e97a470, 0xefdb, 0x4d02, {0x8f, 0xce, 0x61, 0x90, 0xd2, 0x7b, 0xa2, 0x96 } } - -typedef enum { - GetTimeFunctionId, - SetTimeFunctionId, - GetWakeupTimeFunctionId, - SetWakeupTimeFunctionId, - GetRtcFreqFunctionId, - InitializeThresholdFunctionId, - BumpThresholdCountFunctionId, - GetThresholdCountFunctionId -} EFI_EXTENDED_SAL_RTC_SERVICES_FUNC_ID; -///@} - -/// -/// Extended SAL Variable Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_VARIABLE_SERVICES_PROTOCOL_GUID_LO 0x4370c6414ecb6c53 -#define EFI_EXTENDED_SAL_VARIABLE_SERVICES_PROTOCOL_GUID_HI 0x78836e490e3bb28c -#define EFI_EXTENDED_SAL_VARIABLE_SERVICES_PROTOCOL_GUID \ - { 0x4ecb6c53, 0xc641, 0x4370, {0x8c, 0xb2, 0x3b, 0x0e, 0x49, 0x6e, 0x83, 0x78 } } - -typedef enum { - EsalGetVariableFunctionId, - EsalGetNextVariableNameFunctionId, - EsalSetVariableFunctionId, - EsalQueryVariableInfoFunctionId -} EFI_EXTENDED_SAL_VARIABLE_SERVICES_FUNC_ID; -///@} - -/// -/// Extended SAL Monotonic Counter Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_MTC_SERVICES_PROTOCOL_GUID_LO 0x408b75e8899afd18 -#define EFI_EXTENDED_SAL_MTC_SERVICES_PROTOCOL_GUID_HI 0x54f4cd7e2e6e1aa4 -#define EFI_EXTENDED_SAL_MTC_SERVICES_PROTOCOL_GUID \ - { 0x899afd18, 0x75e8, 0x408b, {0xa4, 0x1a, 0x6e, 0x2e, 0x7e, 0xcd, 0xf4, 0x54 } } - -typedef enum { - GetNextHighMonotonicCountFunctionId -} EFI_EXTENDED_SAL_MTC_SERVICES_FUNC_ID; -///@} - -/// -/// Extended SAL Reset Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_RESET_SERVICES_PROTOCOL_GUID_LO 0x46f58ce17d019990 -#define EFI_EXTENDED_SAL_RESET_SERVICES_PROTOCOL_GUID_HI 0xa06a6798513c76a7 -#define EFI_EXTENDED_SAL_RESET_SERVICES_PROTOCOL_GUID \ - { 0x7d019990, 0x8ce1, 0x46f5, {0xa7, 0x76, 0x3c, 0x51, 0x98, 0x67, 0x6a, 0xa0 } } - -typedef enum { - ResetSystemFunctionId -} EFI_EXTENDED_SAL_RESET_SERVICES_FUNC_ID; -///@} - -/// -/// Extended SAL Status Code Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_STATUS_CODE_SERVICES_PROTOCOL_GUID_LO 0x420f55e9dbd91d -#define EFI_EXTENDED_SAL_STATUS_CODE_SERVICES_PROTOCOL_GUID_HI 0x4fb437849f5e3996 -#define EFI_EXTENDED_SAL_STATUS_CODE_SERVICES_PROTOCOL_GUID \ - { 0xdbd91d, 0x55e9, 0x420f, {0x96, 0x39, 0x5e, 0x9f, 0x84, 0x37, 0xb4, 0x4f } } - -typedef enum { - ReportStatusCodeServiceFunctionId -} EFI_EXTENDED_SAL_STATUS_CODE_SERVICES_FUNC_ID; -///@} - -/// -/// Extended SAL Firmware Volume Block Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_FV_BLOCK_SERVICES_PROTOCOL_GUID_LO 0x4f1dbcbba2271df1 -#define EFI_EXTENDED_SAL_FV_BLOCK_SERVICES_PROTOCOL_GUID_HI 0x1a072f17bc06a998 -#define EFI_EXTENDED_SAL_FV_BLOCK_SERVICES_PROTOCOL_GUID \ - { 0xa2271df1, 0xbcbb, 0x4f1d, {0x98, 0xa9, 0x06, 0xbc, 0x17, 0x2f, 0x07, 0x1a } } - -typedef enum { - ReadFunctionId, - WriteFunctionId, - EraseBlockFunctionId, - GetVolumeAttributesFunctionId, - SetVolumeAttributesFunctionId, - GetPhysicalAddressFunctionId, - GetBlockSizeFunctionId, -} EFI_EXTENDED_SAL_FV_BLOCK_SERVICES_FUNC_ID; -///@} - -/// -/// Extended SAL MP Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_MP_SERVICES_PROTOCOL_GUID_LO 0x4dc0cf18697d81a2 -#define EFI_EXTENDED_SAL_MP_SERVICES_PROTOCOL_GUID_HI 0x3f8a613b11060d9e -#define EFI_EXTENDED_SAL_MP_SERVICES_PROTOCOL_GUID \ - { 0x697d81a2, 0xcf18, 0x4dc0, {0x9e, 0x0d, 0x06, 0x11, 0x3b, 0x61, 0x8a, 0x3f } } - -typedef enum { - AddCpuDataFunctionId, - RemoveCpuDataFunctionId, - ModifyCpuDataFunctionId, - GetCpuDataByIDFunctionId, - GetCpuDataByIndexFunctionId, - SendIpiFunctionId, - CurrentProcInfoFunctionId, - NumProcessorsFunctionId, - SetMinStateFunctionId, - GetMinStateFunctionId -} EFI_EXTENDED_SAL_MP_SERVICES_FUNC_ID; -///@} - -/// -/// Extended SAL PAL Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_PAL_SERVICES_PROTOCOL_GUID_LO 0x438d0fc2e1cd9d21 -#define EFI_EXTENDED_SAL_PAL_SERVICES_PROTOCOL_GUID_HI 0x571e966de6040397 -#define EFI_EXTENDED_SAL_PAL_SERVICES_PROTOCOL_GUID \ - { 0xe1cd9d21, 0x0fc2, 0x438d, {0x97, 0x03, 0x04, 0xe6, 0x6d, 0x96, 0x1e, 0x57 } } - -typedef enum { - PalProcFunctionId, - SetNewPalEntryFunctionId, - GetNewPalEntryFunctionId, - EsalUpdatePalFunctionId -} EFI_EXTENDED_SAL_PAL_SERVICES_FUNC_ID; -///@} - -/// -/// Extended SAL Base Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_BASE_SERVICES_PROTOCOL_GUID_LO 0x41c30fe0d9e9fa06 -#define EFI_EXTENDED_SAL_BASE_SERVICES_PROTOCOL_GUID_HI 0xf894335a4283fb96 -#define EFI_EXTENDED_SAL_BASE_SERVICES_PROTOCOL_GUID \ - { 0xd9e9fa06, 0x0fe0, 0x41c3, {0x96, 0xfb, 0x83, 0x42, 0x5a, 0x33, 0x94, 0xf8 } } - -typedef enum { - SalSetVectorsFunctionId, - SalMcRendezFunctionId, - SalMcSetParamsFunctionId, - EsalGetVectorsFunctionId, - EsalMcGetParamsFunctionId, - EsalMcGetMcParamsFunctionId, - EsalGetMcCheckinFlagsFunctionId, - EsalGetPlatformBaseFreqFunctionId, - EsalPhysicalIdInfoFunctionId, - EsalRegisterPhysicalAddrFunctionId -} EFI_EXTENDED_SAL_BASE_SERVICES_FUNC_ID; -///@} - -/// -/// Extended SAL MCA Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_MCA_SERVICES_PROTOCOL_GUID_LO 0x42b16cc72a591128 -#define EFI_EXTENDED_SAL_MCA_SERVICES_PROTOCOL_GUID_HI 0xbb2d683b9358f08a -#define EFI_EXTENDED_SAL_MCA_SERVICES_PROTOCOL_GUID \ - { 0x2a591128, 0x6cc7, 0x42b1, {0x8a, 0xf0, 0x58, 0x93, 0x3b, 0x68, 0x2d, 0xbb } } - -typedef enum { - McaGetStateInfoFunctionId, - McaRegisterCpuFunctionId -} EFI_EXTENDED_SAL_MCA_SERVICES_FUNC_ID; -///@} - -/// -/// Extended SAL PCI Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_PCI_SERVICES_PROTOCOL_GUID_LO 0x4905ad66a46b1a31 -#define EFI_EXTENDED_SAL_PCI_SERVICES_PROTOCOL_GUID_HI 0x6330dc59462bf692 -#define EFI_EXTENDED_SAL_PCI_SERVICES_PROTOCOL_GUID \ - { 0xa46b1a31, 0xad66, 0x4905, {0x92, 0xf6, 0x2b, 0x46, 0x59, 0xdc, 0x30, 0x63 } } - -typedef enum { - SalPciConfigReadFunctionId, - SalPciConfigWriteFunctionId -} EFI_EXTENDED_SAL_PCI_SERVICES_FUNC_ID; -///@} - -/// -/// Extended SAL Cache Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_CACHE_SERVICES_PROTOCOL_GUID_LO 0x4ba52743edc9494 -#define EFI_EXTENDED_SAL_CACHE_SERVICES_PROTOCOL_GUID_HI 0x88f11352ef0a1888 -#define EFI_EXTENDED_SAL_CACHE_SERVICES_PROTOCOL_GUID \ - { 0xedc9494, 0x2743, 0x4ba5, { 0x88, 0x18, 0x0a, 0xef, 0x52, 0x13, 0xf1, 0x88 } } - -typedef enum { - SalCacheInitFunctionId, - SalCacheFlushFunctionId -} EFI_EXTENDED_SAL_CACHE_SERVICES_FUNC_ID; -///@} - -/// -/// Extended SAL MCA Log Services Class -/// -///@{ -#define EFI_EXTENDED_SAL_MCA_LOG_SERVICES_PROTOCOL_GUID_LO 0x4c0338a3cb3fd86e -#define EFI_EXTENDED_SAL_MCA_LOG_SERVICES_PROTOCOL_GUID_HI 0x7aaba2a3cf905c9a -#define EFI_EXTENDED_SAL_MCA_LOG_SERVICES_PROTOCOL_GUID \ - { 0xcb3fd86e, 0x38a3, 0x4c03, {0x9a, 0x5c, 0x90, 0xcf, 0xa3, 0xa2, 0xab, 0x7a } } - -typedef enum { - SalGetStateInfoFunctionId, - SalGetStateInfoSizeFunctionId, - SalClearStateInfoFunctionId, - EsalGetStateBufferFunctionId, - EsalSaveStateBufferFunctionId -} EFI_EXTENDED_SAL_MCA_LOG_SERVICES_FUNC_ID; -///@} - -#endif diff --git a/MdePkg/Include/Protocol/FirmwareManagement.h b/MdePkg/Include/Protocol/FirmwareManagement.h index e9a9e04ea0c3..d998b5738e4a 100644 --- a/MdePkg/Include/Protocol/FirmwareManagement.h +++ b/MdePkg/Include/Protocol/FirmwareManagement.h @@ -8,15 +8,9 @@ CheckImage(), GetPackageInfo(), and SetPackageInfo() shall return EFI_UNSUPPORTED if not supported by the driver. - Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.<BR> + Copyright (c) 2009 - 2020, Intel Corporation. All rights reserved.<BR> Copyright (c) 2013 - 2014, Hewlett-Packard Development Company, L.P.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.3 @@ -35,6 +29,31 @@ typedef struct _EFI_FIRMWARE_MANAGEMENT_PROTOCOL EFI_FIRMWARE_MANAGEMENT_PROTOCOL; /// +/// Dependency Expression Opcode +/// +#define EFI_FMP_DEP_PUSH_GUID 0x00 +#define EFI_FMP_DEP_PUSH_VERSION 0x01 +#define EFI_FMP_DEP_VERSION_STR 0x02 +#define EFI_FMP_DEP_AND 0x03 +#define EFI_FMP_DEP_OR 0x04 +#define EFI_FMP_DEP_NOT 0x05 +#define EFI_FMP_DEP_TRUE 0x06 +#define EFI_FMP_DEP_FALSE 0x07 +#define EFI_FMP_DEP_EQ 0x08 +#define EFI_FMP_DEP_GT 0x09 +#define EFI_FMP_DEP_GTE 0x0A +#define EFI_FMP_DEP_LT 0x0B +#define EFI_FMP_DEP_LTE 0x0C +#define EFI_FMP_DEP_END 0x0D + +/// +/// Image Attribute - Dependency +/// +typedef struct { + UINT8 Dependencies[1]; +} EFI_FIRMWARE_IMAGE_DEP; + +/// /// EFI_FIRMWARE_IMAGE_DESCRIPTOR /// typedef struct { @@ -117,6 +136,7 @@ typedef struct { /// present in version 3 or higher. /// UINT64 HardwareInstance; + EFI_FIRMWARE_IMAGE_DEP *Dependencies; } EFI_FIRMWARE_IMAGE_DESCRIPTOR; @@ -149,11 +169,17 @@ typedef struct { /// The attribute IMAGE_ATTRIBUTE_UEFI_IMAGE indicates that this image is an EFI compatible image. /// #define IMAGE_ATTRIBUTE_UEFI_IMAGE 0x0000000000000010 +/// +/// The attribute IMAGE_ATTRIBUTE_DEPENDENCY indicates that there is an EFI_FIRMWARE_IMAGE_DEP +/// section associated with the image. +/// +#define IMAGE_ATTRIBUTE_DEPENDENCY 0x0000000000000020 // // Image Compatibility Definitions // +/// /// Values from 0x0000000000000002 thru 0x000000000000FFFF are reserved for future assignments. /// Values from 0x0000000000010000 thru 0xFFFFFFFFFFFFFFFF are used by firmware vendor for /// compatibility check. @@ -163,11 +189,11 @@ typedef struct { /// /// Descriptor Version exposed by GetImageInfo() function /// -#define EFI_FIRMWARE_IMAGE_DESCRIPTOR_VERSION 3 +#define EFI_FIRMWARE_IMAGE_DESCRIPTOR_VERSION 4 /// -/// Image Attribute -Authentication Required +/// Image Attribute - Authentication Required /// typedef struct { /// @@ -316,11 +342,11 @@ EFI_STATUS This function allows a copy of the current firmware image to be created and saved. The saved copy could later been used, for example, in firmware image recovery or rollback. - @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance. - @param[in] ImageIndex A unique number identifying the firmware image(s) within the device. + @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance. + @param[in] ImageIndex A unique number identifying the firmware image(s) within the device. The number is between 1 and DescriptorCount. - @param[out] Image Points to the buffer where the current image is copied to. - @param[out] ImageSize On entry, points to the size of the buffer pointed to by Image, in bytes. + @param[out] Image Points to the buffer where the current image is copied to. + @param[in, out] ImageSize On entry, points to the size of the buffer pointed to by Image, in bytes. On return, points to the length of the image, in bytes. @retval EFI_SUCCESS The device was successfully updated with the new image. @@ -330,7 +356,7 @@ EFI_STATUS @retval EFI_INVALID_PARAMETER The Image was NULL. @retval EFI_NOT_FOUND The current image is not copied to the buffer. @retval EFI_UNSUPPORTED The operation is not supported. - @retval EFI_SECURITY_VIOLATIO The operation could not be performed due to an authentication failure. + @retval EFI_SECURITY_VIOLATION The operation could not be performed due to an authentication failure. **/ typedef @@ -338,7 +364,7 @@ EFI_STATUS (EFIAPI *EFI_FIRMWARE_MANAGEMENT_PROTOCOL_GET_IMAGE)( IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL *This, IN UINT8 ImageIndex, - IN OUT VOID *Image, + OUT VOID *Image, IN OUT UINTN *ImageSize ); @@ -385,7 +411,7 @@ EFI_STATUS @retval EFI_ABORTED The operation is aborted. @retval EFI_INVALID_PARAMETER The Image was NULL. @retval EFI_UNSUPPORTED The operation is not supported. - @retval EFI_SECURITY_VIOLATIO The operation could not be performed due to an authentication failure. + @retval EFI_SECURITY_VIOLATION The operation could not be performed due to an authentication failure. **/ typedef @@ -417,7 +443,7 @@ EFI_STATUS @retval EFI_SUCCESS The image was successfully checked. @retval EFI_INVALID_PARAMETER The Image was NULL. @retval EFI_UNSUPPORTED The operation is not supported. - @retval EFI_SECURITY_VIOLATIO The operation could not be performed due to an authentication failure. + @retval EFI_SECURITY_VIOLATION The operation could not be performed due to an authentication failure. **/ typedef @@ -501,7 +527,7 @@ EFI_STATUS @retval EFI_INVALID_PARAMETER The PackageVersionName length is longer than the value returned in PackageVersionNameMaxLen. @retval EFI_UNSUPPORTED The operation is not supported. - @retval EFI_SECURITY_VIOLATIO The operation could not be performed due to an authentication failure. + @retval EFI_SECURITY_VIOLATION The operation could not be performed due to an authentication failure. **/ typedef diff --git a/MdePkg/Include/Protocol/FirmwareVolume2.h b/MdePkg/Include/Protocol/FirmwareVolume2.h index 00523bf0837e..cc52ecc794e2 100644 --- a/MdePkg/Include/Protocol/FirmwareVolume2.h +++ b/MdePkg/Include/Protocol/FirmwareVolume2.h @@ -1,18 +1,12 @@ /** @file - The Firmware Volume Protocol provides file-level access to the firmware volume. - Each firmware volume driver must produce an instance of the + The Firmware Volume Protocol provides file-level access to the firmware volume. + Each firmware volume driver must produce an instance of the Firmware Volume Protocol if the firmware volume is to be visible to the system during the DXE phase. The Firmware Volume Protocol also provides mechanisms for determining and modifying some attributes of the firmware volume. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: PI Version 1.00. @@ -98,7 +92,7 @@ typedef UINT64 EFI_FV_ATTRIBUTES; undefined. @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. - + @param FvAttributes Pointer to an EFI_FV_ATTRIBUTES in which the attributes and current settings are returned. @@ -118,7 +112,7 @@ EFI_STATUS /** Modifies the current settings of the firmware volume according to the input parameter. - + The SetVolumeAttributes() function is used to set configurable firmware volume attributes. Only EFI_FV_READ_STATUS, EFI_FV_WRITE_STATUS, and EFI_FV_LOCK_STATUS may be modified, and @@ -136,7 +130,7 @@ EFI_STATUS TPL_NOTIFY is undefined. @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. - + @param FvAttributes On input, FvAttributes is a pointer to an EFI_FV_ATTRIBUTES containing the desired firmware volume settings. On @@ -145,7 +139,7 @@ EFI_STATUS unsuccessful return, FvAttributes is not modified and the firmware volume settings are not changed. - + @retval EFI_SUCCESS The requested firmware volume attributes were set and the resulting EFI_FV_ATTRIBUTES is returned in @@ -254,13 +248,13 @@ EFI_STATUS undefined. @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. - + @param NameGuid Pointer to an EFI_GUID, which is the file name. All firmware file names are EFI_GUIDs. A single firmware volume must not have two valid files with the same file name EFI_GUID. - + @param Buffer Pointer to a pointer to a buffer in which the file contents are returned, not including the file header. @@ -268,19 +262,19 @@ EFI_STATUS @param BufferSize Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by Buffer. - + @param FoundType Pointer to a caller-allocated EFI_FV_FILETYPE. - + @param FileAttributes Pointer to a caller-allocated EFI_FV_FILE_ATTRIBUTES. - + @param AuthenticationStatus Pointer to a caller-allocated UINT32 in which the authentication status is returned. - + @retval EFI_SUCCESS The call completed successfully. - + @retval EFI_WARN_BUFFER_TOO_SMALL The buffer is too small to contain the requested output. The buffer is @@ -342,56 +336,56 @@ EFI_STATUS undefined. @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. - + @param NameGuid Pointer to an EFI_GUID, which indicates the file name from which the requested section will be read. - + @param SectionType Indicates the section type to return. SectionType in conjunction with SectionInstance indicates which section to return. - + @param SectionInstance Indicates which instance of sections with a type of SectionType to return. SectionType in conjunction with SectionInstance indicates which section to return. SectionInstance is zero based. - + @param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not including the section header. - + @param BufferSize Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by Buffer. - + @param AuthenticationStatus Pointer to a caller-allocated UINT32 in which the authentication status is returned. - - + + @retval EFI_SUCCESS The call completed successfully. - + @retval EFI_WARN_BUFFER_TOO_SMALL The caller-allocated buffer is too small to contain the requested output. The buffer is filled and the output is truncated. - + @retval EFI_OUT_OF_RESOURCES An allocation failure occurred. - + @retval EFI_NOT_FOUND The requested file was not found in the firmware volume. EFI_NOT_FOUND The requested section was not found in the specified file. - + @retval EFI_DEVICE_ERROR A hardware error occurred when attempting to access the firmware volume. - + @retval EFI_ACCESS_DENIED The firmware volume is configured to disallow reads. EFI_PROTOCOL_ERROR The requested section was not found, @@ -472,7 +466,7 @@ typedef struct { Architectural Elements 84 August 21, 2006 Version 1.0 WriteFile() is callable only from TPL_NOTIFY and below. Behavior of WriteFile() at any EFI_TPL above TPL_NOTIFY is - undefined. + undefined. @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. @@ -482,31 +476,31 @@ typedef struct { write in the event of a power failure or other system failure during the write operation. - + @param FileData Pointer to an array of EFI_FV_WRITE_FILE_DATA. Each element of FileData[] represents a file to be written. @retval EFI_SUCCESS The write completed successfully. - + @retval EFI_OUT_OF_RESOURCES The firmware volume does not have enough free space to storefile(s). - + @retval EFI_DEVICE_ERROR A hardware error occurred when attempting to access the firmware volume. - + @retval EFI_WRITE_PROTECTED The firmware volume is configured to disallow writes. - + @retval EFI_NOT_FOUND A delete was requested, but the requested file was not found in the firmware volume. - + @retval EFI_INVALID_PARAMETER A delete was requested with a multiple file write. - + @retval EFI_INVALID_PARAMETER An unsupported WritePolicy was requested. @@ -515,10 +509,10 @@ typedef struct { @retval EFI_INVALID_PARAMETER A file system specific error has occurred. - + **/ typedef -EFI_STATUS +EFI_STATUS (EFIAPI * EFI_FV_WRITE_FILE)( IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, IN UINT32 NumberOfFiles, @@ -528,7 +522,7 @@ EFI_STATUS /** - Retrieves information about the next file in the firmware volume store + Retrieves information about the next file in the firmware volume store that matches the search criteria. GetNextFile() is the interface that is used to search a firmware @@ -547,7 +541,7 @@ EFI_STATUS implementation specific and no semantic content is implied. GetNextFile() is callable only from TPL_NOTIFY and below. Behavior of GetNextFile() at any EFI_TPL above TPL_NOTIFY is - undefined. + undefined. @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. @@ -600,7 +594,7 @@ EFI_STATUS @retval EFI_ACCESS_DENIED The firmware volume is configured to disallow reads. - + **/ typedef EFI_STATUS @@ -629,29 +623,29 @@ EFI_STATUS @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL instance that is the file handle the requested information is for. - + @param InformationType The type identifier for the information being requested. - + @param BufferSize On input, the size of Buffer. On output, the amount of data returned in Buffer. In both cases, the size is measured in bytes. - + @param Buffer A pointer to the data buffer to return. The buffer's type is indicated by InformationType. - - + + @retval EFI_SUCCESS The information was retrieved. - + @retval EFI_UNSUPPORTED The InformationType is not known. - + @retval EFI_NO_MEDIA The device has no medium. - + @retval EFI_DEVICE_ERROR The device reported an error. - + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. - + @retval EFI_BUFFER_TOO_SMALL The BufferSize is too small to read the current directory entry. BufferSize has been @@ -740,14 +734,14 @@ struct _EFI_FIRMWARE_VOLUME2_PROTOCOL { EFI_FV_READ_SECTION ReadSection; EFI_FV_WRITE_FILE WriteFile; EFI_FV_GET_NEXT_FILE GetNextFile; - + /// /// Data field that indicates the size in bytes /// of the Key input buffer for the - /// GetNextFile() API. + /// GetNextFile() API. /// UINT32 KeySize; - + /// /// Handle of the parent firmware volume. /// diff --git a/MdePkg/Include/Protocol/FirmwareVolumeBlock.h b/MdePkg/Include/Protocol/FirmwareVolumeBlock.h index 48c06e143906..3be86b003956 100644 --- a/MdePkg/Include/Protocol/FirmwareVolumeBlock.h +++ b/MdePkg/Include/Protocol/FirmwareVolumeBlock.h @@ -1,14 +1,8 @@ /** @file This file provides control over block-oriented firmware devices. -Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: PI Version 1.0 and 1.2. @@ -21,7 +15,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. // // EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL is defined in PI 1.0 spec and its GUID value // is later updated to be the same as that of EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL -// defined in PI 1.2 spec. +// defined in PI 1.2 spec. // #define EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \ { 0x8f644fa9, 0xe850, 0x4db1, {0x9c, 0xe2, 0xb, 0x44, 0x69, 0x8e, 0x8d, 0xa4 } } @@ -31,7 +25,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. typedef struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL; -typedef EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL; +typedef EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL; /** The GetAttributes() function retrieves the attributes and @@ -69,7 +63,7 @@ EFI_STATUS settings of the firmware volume. Type EFI_FVB_ATTRIBUTES_2 is defined in EFI_FIRMWARE_VOLUME_HEADER. - + @retval EFI_SUCCESS The firmware volume attributes were returned. @retval EFI_INVALID_PARAMETER The attributes requested are in @@ -92,14 +86,14 @@ EFI_STATUS only for memory-mapped firmware volumes. @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance. - + @param Address Pointer to a caller-allocated EFI_PHYSICAL_ADDRESS that, on successful return from GetPhysicalAddress(), contains the base address of the firmware volume. - + @retval EFI_SUCCESS The firmware volume base address was returned. - + @retval EFI_UNSUPPORTED The firmware volume is not memory mapped. **/ @@ -130,9 +124,9 @@ EFI_STATUS blocks in this range have a size of BlockSize. - + @retval EFI_SUCCESS The firmware volume base address was returned. - + @retval EFI_INVALID_PARAMETER The requested LBA is out of range. **/ @@ -163,7 +157,7 @@ EFI_STATUS aware that a read may be partially completed. @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance. - + @param Lba The starting logical block index from which to read. @@ -179,15 +173,15 @@ EFI_STATUS @retval EFI_SUCCESS The firmware volume was read successfully, and contents are in Buffer. - + @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA boundary. On output, NumBytes contains the total number of bytes returned in Buffer. - + @retval EFI_ACCESS_DENIED The firmware volume is in the ReadDisabled state. - + @retval EFI_DEVICE_ERROR The block device is not functioning correctly and could not be read. @@ -215,7 +209,7 @@ EFI_STATUS unpredictability arises because, for a sticky-write firmware volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY state but cannot flip it back again. Before calling the - Write() function, it is recommended for the caller to first call + Write() function, it is recommended for the caller to first call the EraseBlocks() function to erase the specified block to write. A block erase cycle will transition bits from the (NOT)EFI_FVB_ERASE_POLARITY state back to the @@ -234,29 +228,29 @@ EFI_STATUS returns. @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance. - + @param Lba The starting logical block index to write to. - + @param Offset Offset into the block at which to begin writing. - + @param NumBytes The pointer to a UINTN. At entry, *NumBytes contains the total size of the buffer. At exit, *NumBytes contains the total number of bytes actually written. - + @param Buffer The pointer to a caller-allocated buffer that contains the source for the write. - + @retval EFI_SUCCESS The firmware volume was written successfully. - + @retval EFI_BAD_BUFFER_SIZE The write was attempted across an LBA boundary. On output, NumBytes contains the total number of bytes actually written. - + @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state. - + @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not be written. @@ -317,7 +311,7 @@ EFI_STATUS @retval EFI_SUCCESS The erase request successfully completed. - + @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state. @retval EFI_DEVICE_ERROR The block device is not functioning @@ -326,7 +320,7 @@ EFI_STATUS partially erased. @retval EFI_INVALID_PARAMETER One or more of the LBAs listed in the variable argument list do - not exist in the firmware volume. + not exist in the firmware volume. **/ typedef @@ -355,7 +349,7 @@ struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL{ EFI_FVB_ERASE_BLOCKS EraseBlocks; /// /// The handle of the parent firmware volume. - /// + /// EFI_HANDLE ParentHandle; }; diff --git a/MdePkg/Include/Protocol/FormBrowser2.h b/MdePkg/Include/Protocol/FormBrowser2.h index de132f88c062..8bc26d6fda6d 100644 --- a/MdePkg/Include/Protocol/FormBrowser2.h +++ b/MdePkg/Include/Protocol/FormBrowser2.h @@ -1,17 +1,11 @@ /** @file This protocol is defined in UEFI spec. - - The EFI_FORM_BROWSER2_PROTOCOL is the interface to call for drivers to + + The EFI_FORM_BROWSER2_PROTOCOL is the interface to call for drivers to leverage the EFI configuration driver interface. - -Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -29,11 +23,11 @@ typedef struct _EFI_FORM_BROWSER2_PROTOCOL EFI_FORM_BROWSER2_PROTOCOL; /** - + @param LeftColumn The value that designates the text column where the browser window will begin from the left-hand side of the screen - + @param RightColumn The value that designates the text column where the browser window will end on the right-hand side of the screen. @@ -44,7 +38,7 @@ typedef struct _EFI_FORM_BROWSER2_PROTOCOL EFI_FORM_BROWSER2_PROTOCOL; @param BottomRow The value that designates the text row from the bottom of the screen where the browser - window will end. + window will end. **/ typedef struct { UINTN LeftColumn; @@ -69,14 +63,14 @@ typedef UINTN EFI_BROWSER_ACTION_REQUEST; /** Initialize the browser to display the specified configuration forms. - This function is the primary interface to the internal forms-based browser. - The forms browser will display forms associated with the specified Handles. - The browser will select all forms in packages which have the specified Type + This function is the primary interface to the internal forms-based browser. + The forms browser will display forms associated with the specified Handles. + The browser will select all forms in packages which have the specified Type and (for EFI_HII_PACKAGE_TYPE_GUID) the specified PackageGuid. @param This A pointer to the EFI_FORM_BROWSER2_PROTOCOL instance - @param Handles A pointer to an array of Handles. This value should correspond + @param Handles A pointer to an array of Handles. This value should correspond to the value of the HII form package that is required to be displayed. @param HandleCount The number of Handles specified in Handle. @@ -90,17 +84,17 @@ typedef UINTN EFI_BROWSER_ACTION_REQUEST; displayable page. If this field has a value of 0x0000, then the Forms Browser will render the first enabled form in the form set. - @param ScreenDimensions Points to recommended form dimensions, including any non-content area, in + @param ScreenDimensions Points to recommended form dimensions, including any non-content area, in characters. @param ActionRequest Points to the action recommended by the form. @retval EFI_SUCCESS The function completed successfully - + @retval EFI_NOT_FOUND The variable was not found. - + @retval EFI_INVALID_PARAMETER One of the parameters has an - invalid value. + invalid value. **/ typedef EFI_STATUS @@ -126,7 +120,7 @@ EFI_STATUS @param ResultsDataSize A pointer to the size of the buffer associated with ResultsData. On input, the size in - bytes of ResultsData. On output, the size of data + bytes of ResultsData. On output, the size of data returned in ResultsData. @param ResultsData A string returned from an IFR browser or @@ -148,7 +142,7 @@ EFI_STATUS @retval EFI_SUCCESS The results have been distributed or are awaiting distribution. - + @retval EFI_OUT_OF_RESOURCES The ResultsDataSize specified was too small to contain the results data. @@ -166,7 +160,7 @@ EFI_STATUS ); /// -/// This interface will allow the caller to direct the configuration +/// This interface will allow the caller to direct the configuration /// driver to use either the HII database or use the passed-in packet of data. /// struct _EFI_FORM_BROWSER2_PROTOCOL { diff --git a/MdePkg/Include/Protocol/Ftp4.h b/MdePkg/Include/Protocol/Ftp4.h index 939ea9e9c7a3..22b97ebda677 100644 --- a/MdePkg/Include/Protocol/Ftp4.h +++ b/MdePkg/Include/Protocol/Ftp4.h @@ -1,22 +1,16 @@ /** @file EFI FTPv4 (File Transfer Protocol version 4) Protocol Definition - The EFI FTPv4 Protocol is used to locate communication devices that are + The EFI FTPv4 Protocol is used to locate communication devices that are supported by an EFI FTPv4 Protocol driver and to create and destroy instances of the EFI FTPv4 Protocol child protocol driver that can use the underlying communication device. The definitions in this file are defined in UEFI Specification 2.3, which have not been verified by one implementation yet. - Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: + @par Revision Reference: This Protocol is introduced in UEFI Specification 2.2 **/ @@ -41,103 +35,103 @@ typedef struct _EFI_FTP4_PROTOCOL EFI_FTP4_PROTOCOL; /// EFI_FTP4_CONNECTION_TOKEN /// typedef struct { - /// - /// The Event to signal after the connection is established and Status field is updated - /// by the EFI FTP v4 Protocol driver. The type of Event must be - /// EVENT_NOTIFY_SIGNAL, and its Task Priority Level (TPL) must be lower than or - /// equal to TPL_CALLBACK. If it is set to NULL, this function will not return until the + /// + /// The Event to signal after the connection is established and Status field is updated + /// by the EFI FTP v4 Protocol driver. The type of Event must be + /// EVENT_NOTIFY_SIGNAL, and its Task Priority Level (TPL) must be lower than or + /// equal to TPL_CALLBACK. If it is set to NULL, this function will not return until the /// function completes. - /// - EFI_EVENT Event; + /// + EFI_EVENT Event; /// /// The variable to receive the result of the completed operation. /// EFI_SUCCESS: The FTP connection is established successfully - /// EFI_ACCESS_DENIED: The FTP server denied the access the user's request to access it. - /// EFI_CONNECTION_RESET: The connect fails because the connection is reset either by instance + /// EFI_ACCESS_DENIED: The FTP server denied the access the user's request to access it. + /// EFI_CONNECTION_RESET: The connect fails because the connection is reset either by instance /// itself or communication peer. - /// EFI_TIMEOUT: The connection establishment timer expired and no more specific + /// EFI_TIMEOUT: The connection establishment timer expired and no more specific /// information is available. - /// EFI_NETWORK_UNREACHABLE: The active open fails because an ICMP network unreachable error is - /// received. - /// EFI_HOST_UNREACHABLE: The active open fails because an ICMP host unreachable error is - /// received. - /// EFI_PROTOCOL_UNREACHABLE: The active open fails because an ICMP protocol unreachable error is + /// EFI_NETWORK_UNREACHABLE: The active open fails because an ICMP network unreachable error is + /// received. + /// EFI_HOST_UNREACHABLE: The active open fails because an ICMP host unreachable error is /// received. - /// EFI_PORT_UNREACHABLE: The connection establishment timer times out and an ICMP port + /// EFI_PROTOCOL_UNREACHABLE: The active open fails because an ICMP protocol unreachable error is + /// received. + /// EFI_PORT_UNREACHABLE: The connection establishment timer times out and an ICMP port /// unreachable error is received. - /// EFI_ICMP_ERROR: The connection establishment timer timeout and some other ICMP + /// EFI_ICMP_ERROR: The connection establishment timer timeout and some other ICMP /// error is received. /// EFI_DEVICE_ERROR: An unexpected system or network error occurred. - /// + /// EFI_STATUS Status; } EFI_FTP4_CONNECTION_TOKEN; /// -/// EFI_FTP4_CONFIG_DATA +/// EFI_FTP4_CONFIG_DATA /// typedef struct { - /// - /// Pointer to a ASCII string that contains user name. The caller is + /// + /// Pointer to a ASCII string that contains user name. The caller is /// responsible for freeing Username after GetModeData() is called. - /// + /// UINT8 *Username; - /// - /// Pointer to a ASCII string that contains password. The caller is + /// + /// Pointer to a ASCII string that contains password. The caller is /// responsible for freeing Password after GetModeData() is called. - /// + /// UINT8 *Password; - /// - /// Set it to TRUE to initiate an active data connection. Set it to + /// + /// Set it to TRUE to initiate an active data connection. Set it to /// FALSE to initiate a passive data connection. - /// + /// BOOLEAN Active; - /// + /// /// Boolean value indicating if default network settting used. - /// + /// BOOLEAN UseDefaultSetting; - /// + /// /// IP address of station if UseDefaultSetting is FALSE. - /// + /// EFI_IPv4_ADDRESS StationIp; - /// + /// /// Subnet mask of station if UseDefaultSetting is FALSE. - /// + /// EFI_IPv4_ADDRESS SubnetMask; - /// + /// /// IP address of gateway if UseDefaultSetting is FALSE. - /// + /// EFI_IPv4_ADDRESS GatewayIp; - /// + /// /// IP address of FTPv4 server. - /// + /// EFI_IPv4_ADDRESS ServerIp; - /// - /// FTPv4 server port number of control connection, and the default + /// + /// FTPv4 server port number of control connection, and the default /// value is 21 as convention. - /// + /// UINT16 ServerPort; - /// - /// FTPv4 server port number of data connection. If it is zero, use - /// (ServerPort - 1) by convention. - /// + /// + /// FTPv4 server port number of data connection. If it is zero, use + /// (ServerPort - 1) by convention. + /// UINT16 AltDataPort; - /// - /// A byte indicate the representation type. The right 4 bit is used for + /// + /// A byte indicate the representation type. The right 4 bit is used for /// first parameter, the left 4 bit is use for second parameter /// - For the first parameter, 0x0 = image, 0x1 = EBCDIC, 0x2 = ASCII, 0x3 = local - /// - For the second parameter, 0x0 = Non-print, 0x1 = Telnet format effectors, 0x2 = + /// - For the second parameter, 0x0 = Non-print, 0x1 = Telnet format effectors, 0x2 = /// Carriage Control. /// - If it is a local type, the second parameter is the local byte byte size. /// - If it is a image type, the second parameter is undefined. - /// + /// UINT8 RepType; - /// + /// /// Defines the file structure in FTP used. 0x00 = file, 0x01 = record, 0x02 = page. - /// + /// UINT8 FileStruct; - /// + /// /// Defines the transifer mode used in FTP. 0x00 = stream, 0x01 = Block, 0x02 = Compressed. - /// + /// UINT8 TransMode; } EFI_FTP4_CONFIG_DATA; @@ -149,9 +143,9 @@ typedef struct _EFI_FTP4_COMMAND_TOKEN EFI_FTP4_COMMAND_TOKEN; If it is receiving function that leads to inbound data, the callback function is called when data buffer is full. Then, old data in the data buffer should be flushed and new data is stored from the beginning of data buffer. - If it is a transmit function that lead to outbound data and the size of - Data in daata buffer has been transmitted, this callback function is called to - supply additional data to be transmitted. + If it is a transmit function that lead to outbound data and the size of + Data in daata buffer has been transmitted, this callback function is called to + supply additional data to be transmitted. @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. @param[in] Token Pointer to the token structure to provide the parameters that @@ -160,8 +154,8 @@ typedef struct _EFI_FTP4_COMMAND_TOKEN EFI_FTP4_COMMAND_TOKEN; **/ typedef -EFI_STATUS -(EFIAPI *EFI_FTP4_DATA_CALLBACK)( +EFI_STATUS +(EFIAPI *EFI_FTP4_DATA_CALLBACK)( IN EFI_FTP4_PROTOCOL *This, IN EFI_FTP4_COMMAND_TOKEN *Token ); @@ -170,57 +164,57 @@ EFI_STATUS /// EFI_FTP4_COMMAND_TOKEN /// struct _EFI_FTP4_COMMAND_TOKEN { - /// - /// The Event to signal after request is finished and Status field - /// is updated by the EFI FTP v4 Protocol driver. The type of Event - /// must be EVT_NOTIFY_SIGNAL, and its Task Priority Level - /// (TPL) must be lower than or equal to TPL_CALLBACK. If it is - /// set to NULL, related function must wait until the function + /// + /// The Event to signal after request is finished and Status field + /// is updated by the EFI FTP v4 Protocol driver. The type of Event + /// must be EVT_NOTIFY_SIGNAL, and its Task Priority Level + /// (TPL) must be lower than or equal to TPL_CALLBACK. If it is + /// set to NULL, related function must wait until the function /// completes. - /// - EFI_EVENT Event; - /// - /// Pointer to a null-terminated ASCII name string. - /// + /// + EFI_EVENT Event; + /// + /// Pointer to a null-terminated ASCII name string. + /// UINT8 *Pathname; - /// + /// /// The size of data buffer in bytes. - /// - UINT64 DataBufferSize; - /// - /// Pointer to the data buffer. Data downloaded from FTP server + /// + UINT64 DataBufferSize; + /// + /// Pointer to the data buffer. Data downloaded from FTP server /// through connection is downloaded here. - /// + /// VOID *DataBuffer; - /// - /// Pointer to a callback function. If it is receiving function that leads - /// to inbound data, the callback function is called when databuffer is - /// full. Then, old data in the data buffer should be flushed and new - /// data is stored from the beginning of data buffer. If it is a transmit - /// function that lead to outbound data and DataBufferSize of - /// Data in DataBuffer has been transmitted, this callback - /// function is called to supply additional data to be transmitted. The - /// size of additional data to be transmitted is indicated in - /// DataBufferSize, again. If there is no data remained, + /// + /// Pointer to a callback function. If it is receiving function that leads + /// to inbound data, the callback function is called when databuffer is + /// full. Then, old data in the data buffer should be flushed and new + /// data is stored from the beginning of data buffer. If it is a transmit + /// function that lead to outbound data and DataBufferSize of + /// Data in DataBuffer has been transmitted, this callback + /// function is called to supply additional data to be transmitted. The + /// size of additional data to be transmitted is indicated in + /// DataBufferSize, again. If there is no data remained, /// DataBufferSize should be set to 0. - /// - EFI_FTP4_DATA_CALLBACK *DataCallback; - /// + /// + EFI_FTP4_DATA_CALLBACK DataCallback; + /// /// Pointer to the parameter for DataCallback. - /// + /// VOID *Context; - /// + /// /// The variable to receive the result of the completed operation. /// EFI_SUCCESS: The FTP command is completed successfully. /// EFI_ACCESS_DENIED: The FTP server denied the access to the requested file. /// EFI_CONNECTION_RESET: The connect fails because the connection is reset either /// by instance itself or communication peer. - /// EFI_TIMEOUT: The connection establishment timer expired and no more + /// EFI_TIMEOUT: The connection establishment timer expired and no more /// specific information is available. /// EFI_NETWORK_UNREACHABLE: The active open fails because an ICMP network unreachable - /// error is received. + /// error is received. /// EFI_HOST_UNREACHABLE: The active open fails because an ICMP host unreachable - /// error is received. + /// error is received. /// EFI_PROTOCOL_UNREACHABLE: The active open fails because an ICMP protocol unreachable /// error is received. /// EFI_PORT_UNREACHABLE: The connection establishment timer times out and an ICMP port @@ -236,14 +230,14 @@ struct _EFI_FTP4_COMMAND_TOKEN { Gets the current operational settings. The GetModeData() function reads the current operational settings of this - EFI FTPv4 Protocol driver instance. EFI_FTP4_CONFIG_DATA is defined in the + EFI FTPv4 Protocol driver instance. EFI_FTP4_CONFIG_DATA is defined in the EFI_FTP4_PROTOCOL.Configure. @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. - @param[out] ModeData Pointer to storage for the EFI FTPv4 Protocol driver + @param[out] ModeData Pointer to storage for the EFI FTPv4 Protocol driver mode data. The string buffers for Username and Password in EFI_FTP4_CONFIG_DATA are allocated by the function, - and the caller should take the responsibility to free the + and the caller should take the responsibility to free the buffer later. @retval EFI_SUCCESS This function is called successfully. @@ -255,8 +249,8 @@ struct _EFI_FTP4_COMMAND_TOKEN { @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. **/ -typedef -EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_FTP4_GET_MODE_DATA)( IN EFI_FTP4_PROTOCOL *This, OUT EFI_FTP4_CONFIG_DATA *ModeData @@ -266,7 +260,7 @@ EFI_STATUS Disconnecting a FTP connection gracefully. The Connect() function will initiate a connection request to the remote FTP server - with the corresponding connection token. If this function returns EFI_SUCCESS, the + with the corresponding connection token. If this function returns EFI_SUCCESS, the connection sequence is initiated successfully. If the connection succeeds or faild due to any error, the Token->Event will be signaled and Token->Status will be updated accordingly. @@ -280,7 +274,7 @@ EFI_STATUS - Token is NULL. - Token->Event is NULL. @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started. - @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, + @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet. @retval EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation. @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. @@ -297,7 +291,7 @@ EFI_STATUS Disconnecting a FTP connection gracefully. The Close() function will initiate a close request to the remote FTP server with the - corresponding connection token. If this function returns EFI_SUCCESS, the control + corresponding connection token. If this function returns EFI_SUCCESS, the control connection with the remote FTP server is closed. @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. @@ -309,7 +303,7 @@ EFI_STATUS - Token is NULL. - Token->Event is NULL. @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started. - @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, + @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet. @retval EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation. @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. @@ -325,14 +319,14 @@ EFI_STATUS /** Sets or clears the operational parameters for the FTP child driver. - The Configure() function will configure the connected FTP session with the + The Configure() function will configure the connected FTP session with the configuration setting specified in FtpConfigData. The configuration data can be reset by calling Configure() with FtpConfigData set to NULL. @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. - @param[in] FtpConfigData Pointer to configuration data that will be assigned to + @param[in] FtpConfigData Pointer to configuration data that will be assigned to the FTP child driver instance. If NULL, the FTP child - driver instance is reset to startup defaults and all + driver instance is reset to startup defaults and all pending transmit and receive requests are flushed. @retval EFI_SUCCESS The FTPv4 driver was configured successfully. @@ -342,13 +336,13 @@ EFI_STATUS - FtpConfigData.FileStruct is invalid. - FtpConfigData.TransMode is invalid. - IP address in FtpConfigData is invalid. - @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, + @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet. @retval EFI_UNSUPPORTED One or more of the configuration parameters are not supported - by this implementation. - @retval EFI_OUT_OF_RESOURCES The EFI FTPv4 Protocol driver instance data could not be + by this implementation. + @retval EFI_OUT_OF_RESOURCES The EFI FTPv4 Protocol driver instance data could not be allocated. - @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI FTPv4 + @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI FTPv4 Protocol driver instance is not configured. **/ @@ -361,15 +355,15 @@ EFI_STATUS /** - Downloads a file from an FTPv4 server. + Downloads a file from an FTPv4 server. The ReadFile() function is used to initialize and start an FTPv4 download process and optionally wait for completion. When the download operation completes, whether - successfully or not, the Token.Status field is updated by the EFI FTPv4 Protocol + successfully or not, the Token.Status field is updated by the EFI FTPv4 Protocol driver and then Token.Event is signaled (if it is not NULL). Data will be downloaded from the FTPv4 server into Token.DataBuffer. If the file size - is larger than Token.DataBufferSize, Token.DataCallback will be called to allow for + is larger than Token.DataBufferSize, Token.DataCallback will be called to allow for processing data and then new data will be placed at the beginning of Token.DataBuffer. @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. @@ -384,29 +378,29 @@ EFI_STATUS - Token. DataBuffer is NULL. - Token. DataBufferSize is 0. @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started. - @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, + @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet. @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred. **/ -typedef -EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_FTP4_READ_FILE)( IN EFI_FTP4_PROTOCOL *This, IN EFI_FTP4_COMMAND_TOKEN *Token ); /** - Uploads a file from an FTPv4 server. + Uploads a file from an FTPv4 server. The WriteFile() function is used to initialize and start an FTPv4 upload process and optionally wait for completion. When the upload operation completes, whether successfully or not, the Token.Status field is updated by the EFI FTPv4 Protocol driver and then Token.Event is signaled (if it is not NULL). Data to be uploaded to server is stored - into Token.DataBuffer. Token.DataBufferSize is the number bytes to be transferred. + into Token.DataBuffer. Token.DataBufferSize is the number bytes to be transferred. If the file size is larger than Token.DataBufferSize, Token.DataCallback will be called - to allow for processing data and then new data will be placed at the beginning of + to allow for processing data and then new data will be placed at the beginning of Token.DataBuffer. Token.DataBufferSize is updated to reflect the actual number of bytes to be transferred. Token.DataBufferSize is set to 0 by the call back to indicate the completion of data transfer. @@ -424,30 +418,30 @@ EFI_STATUS - Token. DataBuffer is NULL. - Token. DataBufferSize is 0. @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started. - @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, + @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet. @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred. **/ -typedef -EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_FTP4_WRITE_FILE)( IN EFI_FTP4_PROTOCOL *This, IN EFI_FTP4_COMMAND_TOKEN *Token ); /** - Download a data file "directory" from a FTPv4 server. May be unsupported in some EFI + Download a data file "directory" from a FTPv4 server. May be unsupported in some EFI implementations. The ReadDirectory() function is used to return a list of files on the FTPv4 server that logically (or operationally) related to Token.Pathname, and optionally wait for completion. - When the download operation completes, whether successfully or not, the Token.Status field + When the download operation completes, whether successfully or not, the Token.Status field is updated by the EFI FTPv4 Protocol driver and then Token.Event is signaled (if it is not NULL). Data will be downloaded from the FTPv4 server into Token.DataBuffer. If the file size is larger than Token.DataBufferSize, Token.DataCallback will be called to allow for processing - data and then new data will be placed at the beginning of Token.DataBuffer. + data and then new data will be placed at the beginning of Token.DataBuffer. @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. @param[in] Token Pointer to the token structure to provide the parameters that @@ -461,7 +455,7 @@ EFI_STATUS - Token. DataBuffer is NULL. - Token. DataBufferSize is 0. @retval EFI_NOT_STARTED The EFI FTPv4 Protocol driver has not been started. - @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, + @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP, etc.) is not finished yet. @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred. @@ -475,15 +469,15 @@ EFI_STATUS ); /** - Polls for incoming data packets and processes outgoing data packets. + Polls for incoming data packets and processes outgoing data packets. The Poll() function can be used by network drivers and applications to increase the rate that data packets are moved between the communications device and the transmit and receive queues. In some systems, the periodic timer event in the managed network - driver may not poll the underlying communications device fast enough to transmit + driver may not poll the underlying communications device fast enough to transmit and/or receive all data packets without missing incoming packets or dropping outgoing packets. Drivers and applications that are experiencing packet loss should try calling - the Poll() function more often. + the Poll() function more often. @param[in] This Pointer to the EFI_FTP4_PROTOCOL instance. @@ -502,8 +496,8 @@ EFI_STATUS ); /// -/// EFI_FTP4_PROTOCOL -/// provides basic services for client-side FTP (File Transfer Protocol) +/// EFI_FTP4_PROTOCOL +/// provides basic services for client-side FTP (File Transfer Protocol) /// operations. /// struct _EFI_FTP4_PROTOCOL { diff --git a/MdePkg/Include/Protocol/GraphicsOutput.h b/MdePkg/Include/Protocol/GraphicsOutput.h index a3432ce1d6ef..9ba38c577a45 100644 --- a/MdePkg/Include/Protocol/GraphicsOutput.h +++ b/MdePkg/Include/Protocol/GraphicsOutput.h @@ -3,14 +3,8 @@ Abstraction of a very simple graphics device. - Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -33,18 +27,18 @@ typedef struct { typedef enum { /// - /// A pixel is 32-bits and byte zero represents red, byte one represents green, - /// byte two represents blue, and byte three is reserved. This is the definition - /// for the physical frame buffer. The byte values for the red, green, and blue - /// components represent the color intensity. This color intensity value range + /// A pixel is 32-bits and byte zero represents red, byte one represents green, + /// byte two represents blue, and byte three is reserved. This is the definition + /// for the physical frame buffer. The byte values for the red, green, and blue + /// components represent the color intensity. This color intensity value range /// from a minimum intensity of 0 to maximum intensity of 255. /// PixelRedGreenBlueReserved8BitPerColor, /// - /// A pixel is 32-bits and byte zero represents blue, byte one represents green, - /// byte two represents red, and byte three is reserved. This is the definition - /// for the physical frame buffer. The byte values for the red, green, and blue - /// components represent the color intensity. This color intensity value range + /// A pixel is 32-bits and byte zero represents blue, byte one represents green, + /// byte two represents red, and byte three is reserved. This is the definition + /// for the physical frame buffer. The byte values for the red, green, and blue + /// components represent the color intensity. This color intensity value range /// from a minimum intensity of 0 to maximum intensity of 255. /// PixelBlueGreenRedReserved8BitPerColor, @@ -64,7 +58,7 @@ typedef enum { typedef struct { /// - /// The version of this data structure. A value of zero represents the + /// The version of this data structure. A value of zero represents the /// EFI_GRAPHICS_OUTPUT_MODE_INFORMATION structure as defined in this specification. /// UINT32 Version; @@ -77,18 +71,18 @@ typedef struct { /// UINT32 VerticalResolution; /// - /// Enumeration that defines the physical format of the pixel. A value of PixelBltOnly + /// Enumeration that defines the physical format of the pixel. A value of PixelBltOnly /// implies that a linear frame buffer is not available for this mode. /// EFI_GRAPHICS_PIXEL_FORMAT PixelFormat; /// - /// This bit-mask is only valid if PixelFormat is set to PixelPixelBitMask. + /// This bit-mask is only valid if PixelFormat is set to PixelPixelBitMask. /// A bit being set defines what bits are used for what purpose such as Red, Green, Blue, or Reserved. /// EFI_PIXEL_BITMASK PixelInformation; /// /// Defines the number of pixel elements per video memory line. - /// + /// UINT32 PixelsPerScanLine; } EFI_GRAPHICS_OUTPUT_MODE_INFORMATION; @@ -116,7 +110,7 @@ EFI_STATUS ); /** - Set the video device into the specified mode and clears the visible portions of + Set the video device into the specified mode and clears the visible portions of the output display to black. @param This The EFI_GRAPHICS_OUTPUT_PROTOCOL instance. @@ -151,47 +145,47 @@ typedef union { /// typedef enum { /// - /// Write data from the BltBuffer pixel (0, 0) - /// directly to every pixel of the video display rectangle - /// (DestinationX, DestinationY) (DestinationX + Width, DestinationY + Height). - /// Only one pixel will be used from the BltBuffer. Delta is NOT used. + /// Write data from the BltBuffer pixel (0, 0) + /// directly to every pixel of the video display rectangle + /// (DestinationX, DestinationY) (DestinationX + Width, DestinationY + Height). + /// Only one pixel will be used from the BltBuffer. Delta is NOT used. /// EfiBltVideoFill, - + /// - /// Read data from the video display rectangle - /// (SourceX, SourceY) (SourceX + Width, SourceY + Height) and place it in - /// the BltBuffer rectangle (DestinationX, DestinationY ) - /// (DestinationX + Width, DestinationY + Height). If DestinationX or - /// DestinationY is not zero then Delta must be set to the length in bytes - /// of a row in the BltBuffer. + /// Read data from the video display rectangle + /// (SourceX, SourceY) (SourceX + Width, SourceY + Height) and place it in + /// the BltBuffer rectangle (DestinationX, DestinationY ) + /// (DestinationX + Width, DestinationY + Height). If DestinationX or + /// DestinationY is not zero then Delta must be set to the length in bytes + /// of a row in the BltBuffer. /// EfiBltVideoToBltBuffer, - + /// - /// Write data from the BltBuffer rectangle - /// (SourceX, SourceY) (SourceX + Width, SourceY + Height) directly to the - /// video display rectangle (DestinationX, DestinationY) - /// (DestinationX + Width, DestinationY + Height). If SourceX or SourceY is - /// not zero then Delta must be set to the length in bytes of a row in the + /// Write data from the BltBuffer rectangle + /// (SourceX, SourceY) (SourceX + Width, SourceY + Height) directly to the + /// video display rectangle (DestinationX, DestinationY) + /// (DestinationX + Width, DestinationY + Height). If SourceX or SourceY is + /// not zero then Delta must be set to the length in bytes of a row in the /// BltBuffer. /// - EfiBltBufferToVideo, - + EfiBltBufferToVideo, + /// /// Copy from the video display rectangle (SourceX, SourceY) - /// (SourceX + Width, SourceY + Height) to the video display rectangle - /// (DestinationX, DestinationY) (DestinationX + Width, DestinationY + Height). + /// (SourceX + Width, SourceY + Height) to the video display rectangle + /// (DestinationX, DestinationY) (DestinationX + Width, DestinationY + Height). /// The BltBuffer and Delta are not used in this mode. /// EfiBltVideoToVideo, - + EfiGraphicsOutputBltOperationMax } EFI_GRAPHICS_OUTPUT_BLT_OPERATION; /** Blt a rectangle of pixels on the graphics screen. Blt stands for BLock Transfer. - + @param This Protocol instance pointer. @param BltBuffer The data to transfer to the graphics screen. Size is at least Width*Height*sizeof(EFI_GRAPHICS_OUTPUT_BLT_PIXEL). @@ -250,15 +244,15 @@ typedef struct { /// EFI_PHYSICAL_ADDRESS FrameBufferBase; /// - /// Amount of frame buffer needed to support the active mode as defined by + /// Amount of frame buffer needed to support the active mode as defined by /// PixelsPerScanLine xVerticalResolution x PixelElementSize. /// UINTN FrameBufferSize; } EFI_GRAPHICS_OUTPUT_PROTOCOL_MODE; /// -/// Provides a basic abstraction to set video modes and copy pixels to and from -/// the graphics controller's frame buffer. The linear address of the hardware +/// Provides a basic abstraction to set video modes and copy pixels to and from +/// the graphics controller's frame buffer. The linear address of the hardware /// frame buffer is also exposed so software can write directly to the video hardware. /// struct _EFI_GRAPHICS_OUTPUT_PROTOCOL { diff --git a/MdePkg/Include/Protocol/GuidedSectionExtraction.h b/MdePkg/Include/Protocol/GuidedSectionExtraction.h index 8f35002cdd41..e44d639889ae 100644 --- a/MdePkg/Include/Protocol/GuidedSectionExtraction.h +++ b/MdePkg/Include/Protocol/GuidedSectionExtraction.h @@ -4,14 +4,8 @@ instance of the GUIDed Section Extraction Protocol to extract the section stream contained therein. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: PI Version 1.00. @@ -22,14 +16,14 @@ #define __GUID_SECTION_EXTRACTION_PROTOCOL_H__ // -// The protocol interface structures are identified by associating -// them with a GUID. Each instance of a protocol with a given -// GUID must have the same interface structure. While all instances -// of the GUIDed Section Extraction Protocol must have the same -// interface structure, they do not all have the same GUID. The -// GUID that is associated with an instance of the GUIDed Section -// Extraction Protocol is used to correlate it with the GUIDed -// section type that it is intended to process. +// The protocol interface structures are identified by associating +// them with a GUID. Each instance of a protocol with a given +// GUID must have the same interface structure. While all instances +// of the GUIDed Section Extraction Protocol must have the same +// interface structure, they do not all have the same GUID. The +// GUID that is associated with an instance of the GUIDed Section +// Extraction Protocol is used to correlate it with the GUIDed +// section type that it is intended to process. // typedef struct _EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL; @@ -61,9 +55,9 @@ typedef struct _EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL EFI_GUIDED_SECTION_EXTRAC EFI_TPL above TPL_NOTIFY is undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0 specification. - + @param This Indicates the EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL instance. - + @param InputSection Buffer containing the input GUIDed section to be processed. OutputBuffer OutputBuffer is allocated from boot services pool diff --git a/MdePkg/Include/Protocol/Hash.h b/MdePkg/Include/Protocol/Hash.h index 872dfb7abfd0..178926a1c42a 100644 --- a/MdePkg/Include/Protocol/Hash.h +++ b/MdePkg/Include/Protocol/Hash.h @@ -1,18 +1,12 @@ /** @file EFI_HASH_SERVICE_BINDING_PROTOCOL as defined in UEFI 2.0. EFI_HASH_PROTOCOL as defined in UEFI 2.0. - The EFI Hash Service Binding Protocol is used to locate hashing services support - provided by a driver and to create and destroy instances of the EFI Hash Protocol + The EFI Hash Service Binding Protocol is used to locate hashing services support + provided by a driver and to create and destroy instances of the EFI Hash Protocol so that a multiple drivers can use the underlying hashing services. -Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -23,7 +17,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. { \ 0x42881c98, 0xa4f3, 0x44b0, {0xa3, 0x9d, 0xdf, 0xa1, 0x86, 0x67, 0xd8, 0xcd } \ } - + #define EFI_HASH_PROTOCOL_GUID \ { \ 0xc5184932, 0xdba5, 0x46db, {0xa5, 0xba, 0xcc, 0x0b, 0xda, 0x9c, 0x14, 0x35 } \ @@ -37,17 +31,17 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define EFI_HASH_ALGORITHM_SHA224_GUID \ { \ 0x8df01a06, 0x9bd5, 0x4bf7, {0xb0, 0x21, 0xdb, 0x4f, 0xd9, 0xcc, 0xf4, 0x5b } \ - } + } #define EFI_HASH_ALGORITHM_SHA256_GUID \ { \ 0x51aa59de, 0xfdf2, 0x4ea3, {0xbc, 0x63, 0x87, 0x5f, 0xb7, 0x84, 0x2e, 0xe9 } \ - } + } #define EFI_HASH_ALGORITHM_SHA384_GUID \ { \ 0xefa96432, 0xde33, 0x4dd2, {0xae, 0xe6, 0x32, 0x8c, 0x33, 0xdf, 0x77, 0x7a } \ - } + } #define EFI_HASH_ALGORITHM_SHA512_GUID \ { \ @@ -106,7 +100,7 @@ typedef union { @retval EFI_SUCCESS Hash size returned successfully. @retval EFI_INVALID_PARAMETER HashSize is NULL or HashAlgorithm is NULL. - @retval EFI_UNSUPPORTED The algorithm specified by HashAlgorithm is not supported + @retval EFI_UNSUPPORTED The algorithm specified by HashAlgorithm is not supported by this driver. **/ @@ -116,7 +110,7 @@ EFI_STATUS IN CONST EFI_HASH_PROTOCOL *This, IN CONST EFI_GUID *HashAlgorithm, OUT UINTN *HashSize - ); + ); /** Creates a hash for the specified message text. @@ -127,13 +121,13 @@ EFI_STATUS existing hash (TRUE). @param[in] Message Points to the start of the message. @param[in] MessageSize The size of Message, in bytes. - @param[in,out] Hash On input, if Extend is TRUE, then this parameter holds a pointer - to a pointer to an array containing the hash to extend. If Extend - is FALSE, then this parameter holds a pointer to a pointer to a - caller-allocated array that will receive the result of the hash - computation. On output (regardless of the value of Extend), the + @param[in,out] Hash On input, if Extend is TRUE, then this parameter holds a pointer + to a pointer to an array containing the hash to extend. If Extend + is FALSE, then this parameter holds a pointer to a pointer to a + caller-allocated array that will receive the result of the hash + computation. On output (regardless of the value of Extend), the array will contain the result of the hash computation. - + @retval EFI_SUCCESS Hash returned successfully. @retval EFI_INVALID_PARAMETER Message or Hash, HashAlgorithm is NULL or MessageSize is 0. MessageSize is not an integer multiple of block size. @@ -150,10 +144,10 @@ EFI_STATUS IN CONST UINT8 *Message, IN UINT64 MessageSize, IN OUT EFI_HASH_OUTPUT *Hash - ); + ); /// -/// This protocol allows creating a hash of an arbitrary message digest +/// This protocol allows creating a hash of an arbitrary message digest /// using one or more hash algorithms. /// struct _EFI_HASH_PROTOCOL { diff --git a/MdePkg/Include/Protocol/Hash2.h b/MdePkg/Include/Protocol/Hash2.h index d049e8faffa2..9ad0e3023da3 100644 --- a/MdePkg/Include/Protocol/Hash2.h +++ b/MdePkg/Include/Protocol/Hash2.h @@ -8,13 +8,7 @@ message padding and finalization are performed by the supporting driver. Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Protocol/HiiConfigAccess.h b/MdePkg/Include/Protocol/HiiConfigAccess.h index 3b076511c6e2..21feba5fea56 100644 --- a/MdePkg/Include/Protocol/HiiConfigAccess.h +++ b/MdePkg/Include/Protocol/HiiConfigAccess.h @@ -1,18 +1,15 @@ /** @file - The EFI HII results processing protocol invokes this type of protocol - when it needs to forward results to a driver's configuration handler. - This protocol is published by drivers providing and requesting + The EFI HII results processing protocol invokes this type of protocol + when it needs to forward results to a driver's configuration handler. + This protocol is published by drivers providing and requesting configuration data from HII. It may only be invoked by HII. - -Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.1. **/ @@ -43,7 +40,7 @@ typedef UINTN EFI_BROWSER_ACTION; #define EFI_BROWSER_ACTION_DEFAULT_FIRMWARE 0x4000 /** - + This function allows the caller to request the current configuration for one or more named elements. The resulting string is in <ConfigAltResp> format. Any and all alternative @@ -64,12 +61,12 @@ typedef UINTN EFI_BROWSER_ACTION; includes the routing information as well as the configurable name / value pairs. It is invalid for this string to be in - <MultiConfigRequest> format. - If a NULL is passed in for the Request field, - all of the settings being abstracted by this function - will be returned in the Results field. In addition, - if a ConfigHdr is passed in with no request elements, - all of the settings being abstracted for that particular + <MultiConfigRequest> format. + If a NULL is passed in for the Request field, + all of the settings being abstracted by this function + will be returned in the Results field. In addition, + if a ConfigHdr is passed in with no request elements, + all of the settings being abstracted for that particular ConfigHdr reference will be returned in the Results Field. @param Progress On return, points to a character in the @@ -95,7 +92,7 @@ typedef UINTN EFI_BROWSER_ACTION; stored awaiting possible future protocols. - @retval EFI_NOT_FOUND A configuration element matching + @retval EFI_NOT_FOUND A configuration element matching the routing data is not found. Progress set to the first character in the routing header. @@ -121,7 +118,7 @@ EFI_STATUS /** - + This function applies changes in a driver's configuration. Input is a Configuration, which has the routing data for this driver followed by name / value configuration pairs. The driver @@ -134,8 +131,8 @@ EFI_STATUS @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL. @param Configuration A null-terminated Unicode string in - <ConfigString> format. - + <ConfigString> format. + @param Progress A pointer to a string filled in with the offset of the most recent '&' before the first failing name / value pair (or the @@ -146,16 +143,16 @@ EFI_STATUS @retval EFI_SUCCESS The results have been distributed or are awaiting distribution. - + @retval EFI_OUT_OF_RESOURCES Not enough memory to store the parts of the results that must be stored awaiting possible future protocols. - + @retval EFI_INVALID_PARAMETERS Passing in a NULL for the Results parameter would result in this type of error. - + @retval EFI_NOT_FOUND Target for the specified routing data was not found @@ -169,7 +166,7 @@ EFI_STATUS ); /** - + This function is called to provide results data to the driver. This data consists of a unique key that is used to identify which data is either being passed back or being asked for. @@ -178,7 +175,7 @@ EFI_STATUS @param Action Specifies the type of action taken by the browser. @param QuestionId A unique value which is sent to the original exporting driver so that it can identify the type - of data to expect. The format of the data tends to + of data to expect. The format of the data tends to vary based on the opcode that generated the callback. @param Type The type of value for the question. @param Value A pointer to the data being sent to the original @@ -204,7 +201,7 @@ EFI_STATUS OUT EFI_BROWSER_ACTION_REQUEST *ActionRequest ) ; - + /// /// This protocol provides a callable interface between the HII and /// drivers. Only drivers which provide IFR data to HII are required diff --git a/MdePkg/Include/Protocol/HiiConfigKeyword.h b/MdePkg/Include/Protocol/HiiConfigKeyword.h index 1c2d3c67dcac..5786fbc3693e 100644 --- a/MdePkg/Include/Protocol/HiiConfigKeyword.h +++ b/MdePkg/Include/Protocol/HiiConfigKeyword.h @@ -1,16 +1,14 @@ /** @file - The file provides the mechanism to set and get the values - associated with a keyword exposed through a x-UEFI- prefixed + The file provides the mechanism to set and get the values + associated with a keyword exposed through a x-UEFI- prefixed configuration language namespace. - -Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.5. + **/ @@ -40,18 +38,18 @@ typedef struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL EFI_CONFIG_KEYWORD_HANDLER_P This function accepts a <MultiKeywordResp> formatted string, finds the associated keyword owners, creates a <MultiConfigResp> string from it and forwards it to the EFI_HII_ROUTING_PROTOCOL.RouteConfig function. - - If there is an issue in resolving the contents of the KeywordString, then the - function returns an error and also sets the Progress and ProgressErr with the + + If there is an issue in resolving the contents of the KeywordString, then the + function returns an error and also sets the Progress and ProgressErr with the appropriate information about where the issue occurred and additional data about - the nature of the issue. - + the nature of the issue. + In the case when KeywordString containing multiple keywords, when an EFI_NOT_FOUND error is generated during processing the second or later keyword element, the system - storage associated with earlier keywords is not modified. All elements of the + storage associated with earlier keywords is not modified. All elements of the KeywordString must successfully pass all tests for format and access prior to making any modifications to storage. - + In the case when EFI_DEVICE_ERROR is returned from the processing of a KeywordString containing multiple keywords, the state of storage associated with earlier keywords is undefined. @@ -59,18 +57,18 @@ typedef struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL EFI_CONFIG_KEYWORD_HANDLER_P @param This Pointer to the EFI_KEYWORD_HANDLER _PROTOCOL instance. - @param KeywordString A null-terminated string in <MultiKeywordResp> format. + @param KeywordString A null-terminated string in <MultiKeywordResp> format. - @param Progress On return, points to a character in the KeywordString. - Points to the string's NULL terminator if the request - was successful. Points to the most recent '&' before + @param Progress On return, points to a character in the KeywordString. + Points to the string's NULL terminator if the request + was successful. Points to the most recent '&' before the first failing name / value pair (or the beginning of the string if the failure is in the first name / value pair) if the request was not successful. @param ProgressErr If during the processing of the KeywordString there was - a failure, this parameter gives additional information - about the possible source of the problem. The various + a failure, this parameter gives additional information + about the possible source of the problem. The various errors are defined in "Related Definitions" below. @@ -78,23 +76,23 @@ typedef struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL EFI_CONFIG_KEYWORD_HANDLER_P @retval EFI_INVALID_PARAMETER One or more of the following are TRUE: 1. KeywordString is NULL. - 2. Parsing of the KeywordString resulted in an + 2. Parsing of the KeywordString resulted in an error. See Progress and ProgressErr for more data. - @retval EFI_NOT_FOUND An element of the KeywordString was not found. + @retval EFI_NOT_FOUND An element of the KeywordString was not found. See ProgressErr for more data. - @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. + @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. See ProgressErr for more data. - - @retval EFI_ACCESS_DENIED The action violated system policy. See ProgressErr + + @retval EFI_ACCESS_DENIED The action violated system policy. See ProgressErr for more data. @retval EFI_DEVICE_ERROR An unexpected system error occurred. See ProgressErr for more data. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_CONFIG_KEYWORD_HANDLER_SET_DATA) ( IN EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL *This, @@ -106,56 +104,56 @@ EFI_STATUS /** - This function accepts a <MultiKeywordRequest> formatted string, finds the underlying + This function accepts a <MultiKeywordRequest> formatted string, finds the underlying keyword owners, creates a <MultiConfigRequest> string from it and forwards it to the EFI_HII_ROUTING_PROTOCOL.ExtractConfig function. - + If there is an issue in resolving the contents of the KeywordString, then the function returns an EFI_INVALID_PARAMETER and also set the Progress and ProgressErr with the appropriate information about where the issue occurred and additional data about the nature of the issue. - + In the case when KeywordString is NULL, or contains multiple keywords, or when EFI_NOT_FOUND is generated while processing the keyword elements, the Results string - contains values returned for all keywords processed prior to the keyword generating the + contains values returned for all keywords processed prior to the keyword generating the error but no values for the keyword with error or any following keywords. - + @param This Pointer to the EFI_KEYWORD_HANDLER _PROTOCOL instance. - + @param NameSpaceId A null-terminated string containing the platform configuration language to search through in the system. If a NULL is passed in, then it is assumed that any platform configuration language with the prefix of "x-UEFI-" are searched. - + @param KeywordString A null-terminated string in <MultiKeywordRequest> format. If a - NULL is passed in the KeywordString field, all of the known - keywords in the system for the NameSpaceId specified are + NULL is passed in the KeywordString field, all of the known + keywords in the system for the NameSpaceId specified are returned in the Results field. - + @param Progress On return, points to a character in the KeywordString. Points - to the string's NULL terminator if the request was successful. + to the string's NULL terminator if the request was successful. Points to the most recent '&' before the first failing name / value pair (or the beginning of the string if the failure is in the first name / value pair) if the request was not successful. - + @param ProgressErr If during the processing of the KeywordString there was a - failure, this parameter gives additional information about the + failure, this parameter gives additional information about the possible source of the problem. See the definitions in SetData() for valid value definitions. - + @param Results A null-terminated string in <MultiKeywordResp> format is returned - which has all the values filled in for the keywords in the + which has all the values filled in for the keywords in the KeywordString. This is a callee-allocated field, and must be freed - by the caller after being used. + by the caller after being used. @retval EFI_SUCCESS The specified action was completed successfully. - + @retval EFI_INVALID_PARAMETER One or more of the following are TRUE: 1.Progress, ProgressErr, or Results is NULL. 2.Parsing of the KeywordString resulted in an error. See Progress and ProgressErr for more data. - + @retval EFI_NOT_FOUND An element of the KeywordString was not found. See ProgressErr for more data. @@ -165,7 +163,7 @@ EFI_STATUS @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. See ProgressErr for more data. - + @retval EFI_ACCESS_DENIED The action violated system policy. See ProgressErr for more data. @@ -173,20 +171,20 @@ EFI_STATUS for more data. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_CONFIG_KEYWORD_HANDLER_GET_DATA) ( IN EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL *This, IN CONST EFI_STRING NameSpaceId, OPTIONAL IN CONST EFI_STRING KeywordString, OPTIONAL - OUT EFI_STRING *Progress, + OUT EFI_STRING *Progress, OUT UINT32 *ProgressErr, OUT EFI_STRING *Results ); /// -/// The EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL provides the mechanism -/// to set and get the values associated with a keyword exposed +/// The EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL provides the mechanism +/// to set and get the values associated with a keyword exposed /// through a x-UEFI- prefixed configuration language namespace /// diff --git a/MdePkg/Include/Protocol/HiiConfigRouting.h b/MdePkg/Include/Protocol/HiiConfigRouting.h index 89f3f9b2dbfd..88f98d19fdfd 100644 --- a/MdePkg/Include/Protocol/HiiConfigRouting.h +++ b/MdePkg/Include/Protocol/HiiConfigRouting.h @@ -4,15 +4,13 @@ It then serves as the single point to receive configuration information from configuration applications, routing the results to the appropriate drivers. - -Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.1. + **/ @@ -26,7 +24,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. typedef struct _EFI_HII_CONFIG_ROUTING_PROTOCOL EFI_HII_CONFIG_ROUTING_PROTOCOL; /** - + This function allows the caller to request the current configuration for one or more named elements from one or more drivers. The resulting string is in the standard HII @@ -84,8 +82,8 @@ typedef struct _EFI_HII_CONFIG_ROUTING_PROTOCOL EFI_HII_CONFIG_ROUTING_PROTOCOL; for the Request parameter would result in this type of error. The Progress parameter - is set to NULL. - + is set to NULL. + @retval EFI_NOT_FOUND Routing data doesn't match any known driver. Progress set to the "G" in "GUID" of the @@ -100,8 +98,8 @@ typedef struct _EFI_HII_CONFIG_ROUTING_PROTOCOL EFI_HII_CONFIG_ROUTING_PROTOCOL; error, or the beginning of the string. @retval EFI_INVALID_PARAMETER The ExtractConfig function of the - underlying HII Configuration - Access Protocol returned + underlying HII Configuration + Access Protocol returned EFI_INVALID_PARAMETER. Progress set to most recent & before the error or the beginning of the @@ -118,32 +116,32 @@ EFI_STATUS ); /** - This function allows the caller to request the current configuration + This function allows the caller to request the current configuration for the entirety of the current HII database and returns the data in a null-terminated string. This function allows the caller to request the current configuration for all of the current HII database. The results include both the current and alternate configurations as - described in ExtractConfig() above. - + described in ExtractConfig() above. + @param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. - + @param Results Null-terminated Unicode string in <MultiConfigAltResp> format which has all values - filled in for the entirety of the current HII - database. String to be allocated by the called + filled in for the entirety of the current HII + database. String to be allocated by the called function. De-allocation is up to the caller. - + @retval EFI_SUCCESS The Results string is filled with the values corresponding to all requested names. - + @retval EFI_OUT_OF_RESOURCES Not enough memory to store the parts of the results that must be stored awaiting possible future protocols. - + @retval EFI_INVALID_PARAMETERS For example, passing in a NULL for the Results parameter would result in this type of @@ -158,7 +156,7 @@ EFI_STATUS ); /** - + This function routes the results of processing forms to the appropriate targets. It scans for <ConfigHdr> within the string and passes the header and subsequent body to the driver whose @@ -182,16 +180,16 @@ EFI_STATUS @retval EFI_SUCCESS The results have been distributed or are awaiting distribution. - + @retval EFI_OUT_OF_RESOURCES Not enough memory to store the parts of the results that must be stored awaiting possible future protocols. - + @retval EFI_INVALID_PARAMETERS Passing in a NULL for the Results parameter would result in this type of error. - + @retval EFI_NOT_FOUND The target for the specified routing data was not found. @@ -206,7 +204,7 @@ EFI_STATUS /** - + This function extracts the current configuration from a block of bytes. To do so, it requires that the ConfigRequest string consists of a list of <BlockName> formatted names. It uses the @@ -228,7 +226,7 @@ EFI_STATUS @param Config The filled-in configuration string. String allocated by the function. Returned only if - call is successful. The null-terminated string + call is successful. The null-terminated string will be <ConfigResp> format. @param Progress A pointer to a string filled in with the @@ -256,7 +254,7 @@ EFI_STATUS @retval EFI_NOT_FOUND The target for the specified routing data was not found. Progress points to the 'G' in "GUID" of the errant routing - data. + data. @retval EFI_DEVICE_ERROR The block is not large enough. Progress undefined. @retval EFI_INVALID_PARAMETER Encountered non <BlockName> @@ -310,7 +308,7 @@ EFI_STATUS @param BlockSize The length of the Block in units of UINT8. On input, this is the size of the Block. On - output, if successful, contains the largest + output, if successful, contains the largest index of the modified byte in the Block, or the required buffer size if the Block is not large enough. @@ -339,7 +337,7 @@ EFI_STATUS @retval EFI_NOT_FOUND Target for the specified routing data was not found. Progress points to the "G" in "GUID" of the errant routing data. - @retval EFI_BUFFER_TOO_SMALL Block not large enough. Progress undefined. + @retval EFI_BUFFER_TOO_SMALL Block not large enough. Progress undefined. BlockSize is updated with the required buffer size. **/ @@ -354,48 +352,48 @@ EFI_STATUS ); /** - This helper function is to be called by drivers to extract portions of + This helper function is to be called by drivers to extract portions of a larger configuration string. - + @param This A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. @param ConfigResp A null-terminated string in <ConfigAltResp> format. - @param Guid A pointer to the GUID value to search for in the - routing portion of the ConfigResp string when retrieving - the requested data. If Guid is NULL, then all GUID + @param Guid A pointer to the GUID value to search for in the + routing portion of the ConfigResp string when retrieving + the requested data. If Guid is NULL, then all GUID + values will be searched for. + @param Name A pointer to the NAME value to search for in the + routing portion of the ConfigResp string when retrieving + the requested data. If Name is NULL, then all Name values will be searched for. - @param Name A pointer to the NAME value to search for in the - routing portion of the ConfigResp string when retrieving - the requested data. If Name is NULL, then all Name - values will be searched for. - @param DevicePath A pointer to the PATH value to search for in the - routing portion of the ConfigResp string when retrieving - the requested data. If DevicePath is NULL, then all - DevicePath values will be searched for. - @param AltCfgId A pointer to the ALTCFG value to search for in the - routing portion of the ConfigResp string when retrieving - the requested data. If this parameter is NULL, + @param DevicePath A pointer to the PATH value to search for in the + routing portion of the ConfigResp string when retrieving + the requested data. If DevicePath is NULL, then all + DevicePath values will be searched for. + @param AltCfgId A pointer to the ALTCFG value to search for in the + routing portion of the ConfigResp string when retrieving + the requested data. If this parameter is NULL, then the current setting will be retrieved. - @param AltCfgResp A pointer to a buffer which will be allocated by the - function which contains the retrieved string as requested. - This buffer is only allocated if the call was successful. + @param AltCfgResp A pointer to a buffer which will be allocated by the + function which contains the retrieved string as requested. + This buffer is only allocated if the call was successful. The null-terminated string will be <ConfigResp> format. - - @retval EFI_SUCCESS The request succeeded. The requested data was extracted + + @retval EFI_SUCCESS The request succeeded. The requested data was extracted and placed in the newly allocated AltCfgResp buffer. - @retval EFI_OUT_OF_RESOURCES Not enough memory to allocate AltCfgResp. + @retval EFI_OUT_OF_RESOURCES Not enough memory to allocate AltCfgResp. @retval EFI_INVALID_PARAMETER Any parameter is invalid. @retval EFI_NOT_FOUND The target for the specified routing data was not found. **/ typedef -EFI_STATUS +EFI_STATUS (EFIAPI * EFI_HII_GET_ALT_CFG)( - IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, - IN CONST EFI_STRING ConfigResp, - IN CONST EFI_GUID *Guid, - IN CONST EFI_STRING Name, - IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, + IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, + IN CONST EFI_STRING ConfigResp, + IN CONST EFI_GUID *Guid, + IN CONST EFI_STRING Name, + IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, IN CONST UINT16 *AltCfgId, - OUT EFI_STRING *AltCfgResp + OUT EFI_STRING *AltCfgResp ); /// diff --git a/MdePkg/Include/Protocol/HiiDatabase.h b/MdePkg/Include/Protocol/HiiDatabase.h index 435fe1be787a..8ea5b7d90996 100644 --- a/MdePkg/Include/Protocol/HiiDatabase.h +++ b/MdePkg/Include/Protocol/HiiDatabase.h @@ -1,15 +1,12 @@ /** @file The file provides Database manager for HII-related data structures. - -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.1. **/ @@ -25,7 +22,7 @@ typedef struct _EFI_HII_DATABASE_PROTOCOL EFI_HII_DATABASE_PROTOCOL; /// /// EFI_HII_DATABASE_NOTIFY_TYPE. -/// +/// typedef UINTN EFI_HII_DATABASE_NOTIFY_TYPE; #define EFI_HII_DATABASE_NOTIFY_NEW_PACK 0x00000001 @@ -33,7 +30,7 @@ typedef UINTN EFI_HII_DATABASE_NOTIFY_TYPE; #define EFI_HII_DATABASE_NOTIFY_EXPORT_PACK 0x00000004 #define EFI_HII_DATABASE_NOTIFY_ADD_PACK 0x00000008 /** - + Functions which are registered to receive notification of database events have this prototype. The actual event is encoded in NotifyType. The following table describes how PackageType, @@ -48,8 +45,8 @@ typedef UINTN EFI_HII_DATABASE_NOTIFY_TYPE; field of EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it must be NULL. - @param Package Points to the package referred to by the notification. - + @param Package Points to the package referred to by the notification. + @param Handle The handle of the package list which contains the specified package. @@ -80,7 +77,7 @@ EFI_STATUS be called. For each call to NewPackageList(), there should be a corresponding call to EFI_HII_DATABASE_PROTOCOL.RemovePackageList(). - + @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance. @param PackageList A pointer to an EFI_HII_PACKAGE_LIST_HEADER structure. @@ -88,7 +85,7 @@ EFI_STATUS @param DriverHandle Associate the package list with this EFI handle. If a NULL is specified, this data will not be associate with any drivers and cannot have a callback induced. - + @param Handle A pointer to the EFI_HII_HANDLE instance. @retval EFI_SUCCESS The package list associated with the @@ -121,10 +118,10 @@ EFI_STATUS be a corresponding call to RemovePackageList. @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance. - + @param Handle The handle that was registered to the data that is requested for removal. - + @retval EFI_SUCCESS The data associated with the Handle was removed from the HII database. @retval EFI_NOT_FOUND The specified Handle is not in database. @@ -139,7 +136,7 @@ EFI_STATUS /** - + This function updates the existing package list (which has the specified Handle) in the HII databases, using the new package list specified by PackageList. The update process has the @@ -162,18 +159,18 @@ EFI_STATUS ADD_PACK. @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance. - + @param Handle The handle that was registered to the data that is requested for removal. - + @param PackageList A pointer to an EFI_HII_PACKAGE_LIST package. - + @retval EFI_SUCCESS The HII database was successfully updated. - + @retval EFI_OUT_OF_RESOURCES Unable to allocate enough memory for the updated database. - + @retval EFI_INVALID_PARAMETER PackageList was NULL. @retval EFI_NOT_FOUND The specified Handle is not in database. @@ -188,25 +185,25 @@ EFI_STATUS /** - - This function returns a list of the package handles of the - specified type that are currently active in the database. The - pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package + + This function returns a list of the package handles of the + specified type that are currently active in the database. The + pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package handles to be listed. - + @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance. - + @param PackageType Specifies the package type of the packages to list or EFI_HII_PACKAGE_TYPE_ALL for all packages to be listed. - + @param PackageGuid If PackageType is EFI_HII_PACKAGE_TYPE_GUID, then this is the pointer to the GUID which must match the Guid field of EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it must be NULL. - + @param HandleBufferLength On input, a pointer to the length of the handle buffer. On output, the length of the handle buffer @@ -258,7 +255,7 @@ EFI_STATUS @param Handle An EFI_HII_HANDLE that corresponds to the desired package list in the HII database to export or NULL to indicate all package lists - should be exported. + should be exported. @param BufferSize On input, a pointer to the length of the buffer. On output, the length of the @@ -267,18 +264,18 @@ EFI_STATUS @param Buffer A pointer to a buffer that will contain the results of the export function. - - + + @retval EFI_SUCCESS Package exported. - + @retval EFI_OUT_OF_RESOURCES BufferSize is too small to hold the package. @retval EFI_NOT_FOUND The specified Handle could not be found in the current database. - + @retval EFI_INVALID_PARAMETER BufferSize was NULL. - - @retval EFI_INVALID_PARAMETER The value referenced by BufferSize was not zero + + @retval EFI_INVALID_PARAMETER The value referenced by BufferSize was not zero and Buffer was NULL. **/ typedef @@ -292,8 +289,8 @@ EFI_STATUS /** - - + + This function registers a function which will be called when specified actions related to packages of the specified type occur in the HII database. By registering a function, other @@ -302,12 +299,12 @@ EFI_STATUS or application which registers a notification should use EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() before exiting. - - + + @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance. @param PackageType The package type. See - EFI_HII_PACKAGE_TYPE_x in EFI_HII_PACKAGE_HEADER. + EFI_HII_PACKAGE_TYPE_x in EFI_HII_PACKAGE_HEADER. @param PackageGuid If PackageType is EFI_HII_PACKAGE_TYPE_GUID, then this is @@ -355,19 +352,19 @@ EFI_STATUS /** - + Removes the specified HII database package-related notification. - + @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance. @param NotificationHandle The handle of the notification function being unregistered. - - @retval EFI_SUCCESS Successsfully unregistered the notification. - - @retval EFI_NOT_FOUND The incoming notification handle does not exist + + @retval EFI_SUCCESS Successsfully unregistered the notification. + + @retval EFI_NOT_FOUND The incoming notification handle does not exist in the current hii database. - + **/ typedef EFI_STATUS @@ -378,7 +375,7 @@ EFI_STATUS /** - + This routine retrieves an array of GUID values for each keyboard layout that was previously registered in the system. @@ -388,13 +385,13 @@ EFI_STATUS of the keyboard GUID buffer. On output, the length of the handle buffer that is required for the - handles found. - + handles found. + @param KeyGuidBuffer An array of keyboard layout GUID instances returned. @retval EFI_SUCCESS KeyGuidBuffer was updated successfully. - + @retval EFI_BUFFER_TOO_SMALL The KeyGuidBufferLength parameter indicates that KeyGuidBuffer is too small to @@ -403,7 +400,7 @@ EFI_STATUS with a value that will enable the data to fit. @retval EFI_INVALID_PARAMETER The KeyGuidBufferLength is NULL. - @retval EFI_INVALID_PARAMETER The value referenced by + @retval EFI_INVALID_PARAMETER The value referenced by KeyGuidBufferLength is not zero and KeyGuidBuffer is NULL. @retval EFI_NOT_FOUND There was no keyboard layout. @@ -419,14 +416,14 @@ EFI_STATUS /** - + This routine retrieves the requested keyboard layout. The layout is a physical description of the keys on a keyboard, and the character(s) that are associated with a particular set of key strokes. @param This A pointer to the EFI_HII_PROTOCOL instance. - + @param KeyGuid A pointer to the unique ID associated with a given keyboard layout. If KeyGuid is NULL then the current layout will be retrieved. @@ -434,13 +431,13 @@ EFI_STATUS @param KeyboardLayoutLength On input, a pointer to the length of the KeyboardLayout buffer. On output, the length of the data placed into KeyboardLayout. - + @param KeyboardLayout A pointer to a buffer containing the retrieved keyboard layout. - + @retval EFI_SUCCESS The keyboard layout was retrieved successfully. - + @retval EFI_NOT_FOUND The requested keyboard layout was not found. **/ @@ -454,7 +451,7 @@ EFI_STATUS ); /** - + This routine sets the default keyboard layout to the one referenced by KeyGuid. When this routine is called, an event will be signaled of the EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID @@ -481,21 +478,21 @@ EFI_STATUS ); /** - + Return the EFI handle associated with a package list. - + @param This A pointer to the EFI_HII_PROTOCOL instance. - + @param PackageListHandle An EFI_HII_HANDLE that corresponds to the desired package list in the HIIdatabase. - + @param DriverHandle On return, contains the EFI_HANDLE which was registered with the package list in NewPackageList(). - + @retval EFI_SUCCESS The DriverHandle was returned successfully. - + @retval EFI_INVALID_PARAMETER The PackageListHandle was not valid. **/ diff --git a/MdePkg/Include/Protocol/HiiFont.h b/MdePkg/Include/Protocol/HiiFont.h index b94073449611..c229e394423d 100644 --- a/MdePkg/Include/Protocol/HiiFont.h +++ b/MdePkg/Include/Protocol/HiiFont.h @@ -1,14 +1,11 @@ /** @file The file provides services to retrieve font information. - -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.1. **/ @@ -27,7 +24,7 @@ typedef VOID *EFI_FONT_HANDLE; /// /// EFI_HII_OUT_FLAGS. -/// +/// typedef UINT32 EFI_HII_OUT_FLAGS; #define EFI_HII_OUT_FLAG_CLIP 0x00000001 @@ -49,12 +46,12 @@ typedef struct _EFI_HII_ROW_INFO { UINTN StartIndex; /// /// The index of the last character in the string which is displayed on the line. - /// If this is the same as StartIndex, then no characters are displayed. + /// If this is the same as StartIndex, then no characters are displayed. /// UINTN EndIndex; UINTN LineHeight; ///< The height of the line, in pixels. UINTN LineWidth; ///< The width of the text on the line, in pixels. - + /// /// The font baseline offset in pixels from the bottom of the row, or 0 if none. /// @@ -80,7 +77,7 @@ typedef UINT32 EFI_FONT_INFO_MASK; // // EFI_FONT_INFO -// +// typedef struct { EFI_HII_FONT_STYLE FontStyle; UINT16 FontSize; ///< character cell height in pixels @@ -103,7 +100,7 @@ typedef struct _EFI_FONT_DISPLAY_INFO { EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor; EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor; EFI_FONT_INFO_MASK FontInfoMask; - EFI_FONT_INFO FontInfo; + EFI_FONT_INFO FontInfo; } EFI_FONT_DISPLAY_INFO; /** @@ -155,7 +152,7 @@ typedef struct _EFI_FONT_DISPLAY_INFO { @param Flags Describes how the string is to be drawn. - @param String Points to the null-terminated string to be + @param String Points to the null-terminated string to be @param StringInfo Points to the string output information, including the color and font. If NULL, then @@ -203,9 +200,9 @@ typedef struct _EFI_FONT_DISPLAY_INFO { overlap. @retval EFI_SUCCESS The string was successfully updated. - + @retval EFI_OUT_OF_RESOURCES Unable to allocate an output buffer for RowInfoArray or Blt. - + @retval EFI_INVALID_PARAMETER The String or Blt was NULL. @retval EFI_INVALID_PARAMETER Flags were invalid combination. @@ -276,7 +273,7 @@ EFI_STATUS @param Flags Describes how the string is to be drawn. - @param PackageList + @param PackageList The package list in the HII database to search for the specified string. @@ -342,8 +339,8 @@ EFI_STATUS Width was NULL. @retval EFI_INVALID_PARAMETER The Blt or PackageList was NULL. @retval EFI_INVALID_PARAMETER Flags were invalid combination. - @retval EFI_NOT_FOUND The specified PackageList is not in the Database, - or the stringid is not in the specified PackageList. + @retval EFI_NOT_FOUND The specified PackageList is not in the Database, + or the stringid is not in the specified PackageList. **/ typedef @@ -424,26 +421,26 @@ EFI_STATUS to NULL if there are no more matching fonts. @param StringInfoIn Upon entry, points to the font to return - information about. If NULL, then the information + information about. If NULL, then the information about the system default font will be returned. @param StringInfoOut Upon return, contains the matching font's information. If NULL, then no information is returned. This buffer is allocated with a call to the Boot Service AllocatePool(). - It is the caller's responsibility to call the Boot + It is the caller's responsibility to call the Boot Service FreePool() when the caller no longer requires the contents of StringInfoOut. @param String Points to the string which will be tested to determine if all characters are available. If NULL, then any font is acceptable. - + @retval EFI_SUCCESS Matching font returned successfully. - + @retval EFI_NOT_FOUND No matching font was found. @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the request. - + **/ typedef EFI_STATUS diff --git a/MdePkg/Include/Protocol/HiiImage.h b/MdePkg/Include/Protocol/HiiImage.h index 3407532ea2c1..ef4559988e4f 100644 --- a/MdePkg/Include/Protocol/HiiImage.h +++ b/MdePkg/Include/Protocol/HiiImage.h @@ -1,14 +1,11 @@ /** @file The file provides services to access to images in the images database. - - Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.1. **/ @@ -25,18 +22,18 @@ typedef struct _EFI_HII_IMAGE_PROTOCOL EFI_HII_IMAGE_PROTOCOL; /// /// Flags in EFI_IMAGE_INPUT -/// +/// #define EFI_IMAGE_TRANSPARENT 0x00000001 /** - + Definition of EFI_IMAGE_INPUT. - + @param Flags Describe image characteristics. If EFI_IMAGE_TRANSPARENT is set, then the image was designed for transparent display. - @param Width Image width, in pixels. + @param Width Image width, in pixels. @param Height Image height, in pixels. @@ -44,7 +41,7 @@ typedef struct _EFI_HII_IMAGE_PROTOCOL EFI_HII_IMAGE_PROTOCOL; top-to-bottom. The size of the bitmap is Width*Height*sizeof(EFI_GRAPHICS_OUTPUT_BLT_PIXEL). - + **/ typedef struct _EFI_IMAGE_INPUT { UINT32 Flags; @@ -60,8 +57,8 @@ typedef struct _EFI_IMAGE_INPUT { owned by PackageList, and returns a new image identifier (ImageId). - @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. - + @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. + @param PackageList Handle of the package list where this image will be added. @param ImageId On return, contains the new image id, which is @@ -71,9 +68,9 @@ typedef struct _EFI_IMAGE_INPUT { @retval EFI_SUCCESS The new image was added successfully - + @retval EFI_OUT_OF_RESOURCES Could not add the image. - + @retval EFI_INVALID_PARAMETER Image is NULL or ImageId is NULL. @@ -100,21 +97,21 @@ EFI_STATUS updated to the size of buffer actually required to hold the image. - @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. - + @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. + @param PackageList The package list in the HII database to search for the specified image. - + @param ImageId The image's id, which is unique within PackageList. - + @param Image Points to the new image. - + @retval EFI_SUCCESS The image was returned successfully. @retval EFI_NOT_FOUND The image specified by ImageId is not available. Or The specified PackageList is not in the database. - + @retval EFI_INVALID_PARAMETER The Image or Langugae was NULL. @retval EFI_OUT_OF_RESOURCES The bitmap could not be retrieved because there was not enough memory. @@ -131,12 +128,12 @@ EFI_STATUS ); /** - + This function updates the image specified by ImageId in the specified PackageListHandle to the image specified by Image. - @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. + @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. @param PackageList The package list containing the images. @@ -145,10 +142,10 @@ EFI_STATUS @param Image Points to the image. @retval EFI_SUCCESS The image was successfully updated. - + @retval EFI_NOT_FOUND The image specified by ImageId is not in the database. - The specified PackageList is not in the database. - + The specified PackageList is not in the database. + @retval EFI_INVALID_PARAMETER The Image or Language was NULL. **/ @@ -176,9 +173,9 @@ typedef UINT32 EFI_HII_DRAW_FLAGS; #define EFI_HII_DIRECT_TO_SCREEN 0x00000080 /** - + Definition of EFI_IMAGE_OUTPUT. - + @param Width Width of the output image. @param Height Height of the output image. @@ -201,7 +198,7 @@ typedef struct _EFI_IMAGE_OUTPUT { /** - + This function renders an image to a bitmap or the screen using the specified color and options. It draws the image on an existing bitmap, allocates a new bitmap or uses the screen. The @@ -216,14 +213,14 @@ typedef struct _EFI_IMAGE_OUTPUT { specified by Bitmap. - @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. - + @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. + @param Flags Describes how the image is to be drawn. EFI_HII_DRAW_FLAGS is defined in Related Definitions, below. - - @param Image Points to the image to be displayed. - + + @param Image Points to the image to be displayed. + @param Blt If this points to a non-NULL on entry, this points to the image, which is Width pixels wide and Height pixels high. The image will be drawn onto @@ -259,7 +256,7 @@ EFI_STATUS ); /** - + This function renders an image as a bitmap or to the screen and can clip the image. The bitmap is either supplied by the caller or else is allocated by the function. The images can be drawn @@ -292,7 +289,7 @@ EFI_STATUS directly to the output device specified by Screen. Otherwise the image will be rendered to the bitmap specified by Bitmap. - @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. + @param This A pointer to the EFI_HII_IMAGE_PROTOCOL instance. @param Flags Describes how the image is to be drawn. @@ -315,14 +312,14 @@ EFI_STATUS pixel in the image. @retval EFI_SUCCESS The image was successfully updated. - + @retval EFI_OUT_OF_RESOURCES Unable to allocate an output buffer for RowInfoArray or Blt. - - @retval EFI_NOT_FOUND The image specified by ImageId is not in the database. - Or The specified PackageList is not in the database. - - @retval EFI_INVALID_PARAMETER The Blt was NULL. + + @retval EFI_NOT_FOUND The image specified by ImageId is not in the database. + Or The specified PackageList is not in the database. + + @retval EFI_INVALID_PARAMETER The Blt was NULL. **/ typedef diff --git a/MdePkg/Include/Protocol/HiiImageDecoder.h b/MdePkg/Include/Protocol/HiiImageDecoder.h index 6ee16c922243..965c59a9e0e0 100644 --- a/MdePkg/Include/Protocol/HiiImageDecoder.h +++ b/MdePkg/Include/Protocol/HiiImageDecoder.h @@ -2,15 +2,12 @@ This protocol provides generic image decoder interfaces to various image formats. (C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR> - Copyright (c) 2016, Intel Corporation. All rights reserved.<BR> + Copyright (c) 2016-2018, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. +SPDX-License-Identifier: BSD-2-Clause-Patent -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.6. **/ #ifndef __HII_IMAGE_DECODER_H__ @@ -18,15 +15,6 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #include <Protocol/HiiImage.h> - -// -// In UEFI 2.6 spec,this guid value is duplicate with -// EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID. Now update this guid value to -// avoid the duplicate guid issue. So its value is not consistent with -// UEFI spec definition now. We have proposed to update UEFI spec to -// use this new guid. After new spec released, we will remove this -// comments. -// #define EFI_HII_IMAGE_DECODER_PROTOCOL_GUID \ {0x9e66f251, 0x727c, 0x418c, { 0xbf, 0xd6, 0xc2, 0xb4, 0x25, 0x28, 0x18, 0xea }} diff --git a/MdePkg/Include/Protocol/HiiImageEx.h b/MdePkg/Include/Protocol/HiiImageEx.h index 5c4fd647e198..c0402b7bbb51 100644 --- a/MdePkg/Include/Protocol/HiiImageEx.h +++ b/MdePkg/Include/Protocol/HiiImageEx.h @@ -1,15 +1,12 @@ /** @file Protocol which allows access to the images in the images database. -(C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR> +(C) Copyright 2016-2018 Hewlett Packard Enterprise Development LP<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. +SPDX-License-Identifier: BSD-2-Clause-Patent -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.6. **/ @@ -28,8 +25,7 @@ typedef struct _EFI_HII_IMAGE_EX_PROTOCOL EFI_HII_IMAGE_EX_PROTOCOL; /** The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.NewImage(). - Same with EFI_HII_IMAGE_PROTOCOL.NewImage().This protocol invokes -EFI_HII_IMAGE_PROTOCOL.NewImage() implicitly. + This protocol invokes EFI_HII_IMAGE_PROTOCOL.NewImage() implicitly. @param This A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance. @param PackageList Handle of the package list where this image will @@ -57,22 +53,24 @@ EFI_STATUS /** Return the information about the image, associated with the package list. The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.GetImage(). - Same with EFI_HII_IMAGE_PROTOCOL.SetImage(),this protocol invokes EFI_HII_IMAGE_PROTOCOL.SetImage() implicitly. + + This function is similar to EFI_HII_IMAGE_PROTOCOL.GetImage().The difference is that + this function will locate all EFI_HII_IMAGE_DECODER_PROTOCOL instances installed in the + system if the decoder of the certain image type is not supported by the + EFI_HII_IMAGE_EX_PROTOCOL. The function will attempt to decode the image to the + EFI_IMAGE_INPUT using the first EFI_HII_IMAGE_DECODER_PROTOCOL instance that + supports the requested image type. @param This A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance. - @param PackageList Handle of the package list where this image will - be searched. - @param ImageId The image's id,, which is unique within - PackageList. + @param PackageList The package list in the HII database to search for the + specified image. + @param ImageId The image's id, which is unique within PackageList. @param Image Points to the image. @retval EFI_SUCCESS The new image was returned successfully. - @retval EFI_NOT_FOUND The image specified by ImageId is not in the - database. The specified PackageList is not in - the database. - @retval EFI_BUFFER_TOO_SMALL The buffer specified by ImageSize is too small to - hold the image. - @retval EFI_INVALID_PARAMETER The Image or ImageSize was NULL. + @retval EFI_NOT_FOUND The image specified by ImageId is not available. The specified + PackageList is not in the Database. + @retval EFI_INVALID_PARAMETER Image was NULL or ImageId was 0. @retval EFI_OUT_OF_RESOURCES The bitmap could not be retrieved because there was not enough memory. @@ -87,21 +85,22 @@ EFI_STATUS ); /** - Change the information about the image. The prototype of this extension - function is the same with EFI_HII_IMAGE_PROTOCOL.SetImage(). Same with - EFI_HII_IMAGE_PROTOCOL.DrawImageId(),this protocol invokes EFI_HII_IMAGE_PROTOCOL.DrawImageId() implicitly. + Change the information about the image. + + Same with EFI_HII_IMAGE_PROTOCOL.SetImage(),this protocol invokes + EFI_HII_IMAGE_PROTOCOL.SetImage()implicitly. @param This A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance. @param PackageList The package list containing the images. - @param ImageId The image's id,, which is unique within - PackageList. + @param ImageId The image's id, which is unique within PackageList. @param Image Points to the image. - @retval EFI_SUCCESS The new image was updated successfully. + @retval EFI_SUCCESS The new image was successfully updated. @retval EFI_NOT_FOUND The image specified by ImageId is not in the database. The specified PackageList is not in the database. - @retval EFI_INVALID_PARAMETER The Image was NULL. + @retval EFI_INVALID_PARAMETER The Image was NULL, the ImageId was 0 or + the Image->Bitmap was NULL. **/ typedef @@ -114,9 +113,11 @@ EFI_STATUS ); /** - Renders an image to a bitmap or to the display. The prototype of this extension - function is the same with EFI_HII_IMAGE_PROTOCOL.DrawImage(). - Same with EFI_HII_IMAGE_PROTOCOL.SetImage(),this protocol invokes EFI_HII_IMAGE_PROTOCOL.SetImage() implicitly. + Renders an image to a bitmap or to the display. + + The prototype of this extension function is the same with + EFI_HII_IMAGE_PROTOCOL.DrawImage(). This protocol invokes + EFI_HII_IMAGE_PROTOCOL.DrawImage() implicitly. @param This A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance. @param Flags Describes how the image is to be drawn. @@ -125,19 +126,18 @@ EFI_STATUS to the image, which is Width pixels wide and Height pixels high. The image will be drawn onto this image and EFI_HII_DRAW_FLAG_CLIP is implied. - If this points to a NULL on entry, then a buffer - will be allocated to hold the generated image and + If this points to a NULL on entry, then a buffer + will be allocated to hold the generated image and the pointer updated on exit. It is the caller's responsibility to free this buffer. @param BltX Specifies the offset from the left and top edge of - the output image of the first pixel in the image. + the output image of the first pixel in the image. @param BltY Specifies the offset from the left and top edge of - the output image of the first pixel in the image. + the output image of the first pixel in the image. @retval EFI_SUCCESS The image was successfully drawn. @retval EFI_OUT_OF_RESOURCES Unable to allocate an output buffer for Blt. @retval EFI_INVALID_PARAMETER The Image or Blt was NULL. - Any combination of Flags is invalid. **/ typedef @@ -153,17 +153,20 @@ EFI_STATUS /** Renders an image to a bitmap or the screen containing the contents of the specified - image. The prototype of this extension function is the same with E - FI_HII_IMAGE_PROTOCOL.DrawImageId(). - Same with EFI_HII_IMAGE_PROTOCOL.DrawImageId(),this protocol invokes -EFI_HII_IMAGE_PROTOCOL.DrawImageId() implicitly. + image. + + This function is similar to EFI_HII_IMAGE_PROTOCOL.DrawImageId(). The difference is that + this function will locate all EFI_HII_IMAGE_DECODER_PROTOCOL instances installed in the + system if the decoder of the certain image type is not supported by the + EFI_HII_IMAGE_EX_PROTOCOL. The function will attempt to decode the image to the + EFI_IMAGE_INPUT using the first EFI_HII_IMAGE_DECODER_PROTOCOL instance that + supports the requested image type. @param This A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance. @param Flags Describes how the image is to be drawn. @param PackageList The package list in the HII database to search for the specified image. - @param ImageId The image's id, which is unique within - PackageList. + @param ImageId The image's id, which is unique within PackageList. @param Blt If this points to a non-NULL on entry, this points to the image, which is Width pixels wide and Height pixels high. The image will be drawn onto @@ -179,7 +182,7 @@ EFI_HII_IMAGE_PROTOCOL.DrawImageId() implicitly. @retval EFI_SUCCESS The image was successfully drawn. @retval EFI_OUT_OF_RESOURCES Unable to allocate an output buffer for Blt. - @retval EFI_INVALID_PARAMETER The Blt was NULL. + @retval EFI_INVALID_PARAMETER The Blt was NULL or ImageId was 0. @retval EFI_NOT_FOUND The image specified by ImageId is not in the database. The specified PackageList is not in the database. @@ -206,7 +209,7 @@ EFI_STATUS @param This A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance. @param PackageList Handle of the package list where this image will be searched. - @param ImageId The image's id,, which is unique within PackageList. + @param ImageId The image's id, which is unique within PackageList. @param Image Points to the image. @retval EFI_SUCCESS The new image was returned successfully. @@ -214,7 +217,7 @@ EFI_STATUS database. The specified PackageList is not in the database. @retval EFI_BUFFER_TOO_SMALL The buffer specified by ImageSize is too small to hold the image. - @retval EFI_INVALID_PARAMETER The Image or ImageSize was NULL. + @retval EFI_INVALID_PARAMETER The Image was NULL or the ImageId was 0. @retval EFI_OUT_OF_RESOURCES The bitmap could not be retrieved because there was not enough memory. diff --git a/MdePkg/Include/Protocol/HiiPackageList.h b/MdePkg/Include/Protocol/HiiPackageList.h index 3842973281ec..a161edfa592a 100644 --- a/MdePkg/Include/Protocol/HiiPackageList.h +++ b/MdePkg/Include/Protocol/HiiPackageList.h @@ -4,15 +4,9 @@ if the image contains a custom PE/COFF resource with the type 'HII'. The protocol's interface pointer points to the HII package list, which is contained in the resource's data. - - Copyright (c) 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Protocol/HiiPopup.h b/MdePkg/Include/Protocol/HiiPopup.h new file mode 100644 index 000000000000..8924a3a5704c --- /dev/null +++ b/MdePkg/Include/Protocol/HiiPopup.h @@ -0,0 +1,78 @@ +/** @file + This protocol provides services to display a popup window. + The protocol is typically produced by the forms browser and consumed by a driver callback handler. + + Copyright (c) 2017-2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.7. + +**/ + +#ifndef __HII_POPUP_H__ +#define __HII_POPUP_H__ + +#define EFI_HII_POPUP_PROTOCOL_GUID \ + {0x4311edc0, 0x6054, 0x46d4, {0x9e, 0x40, 0x89, 0x3e, 0xa9, 0x52, 0xfc, 0xcc}} + +#define EFI_HII_POPUP_PROTOCOL_REVISION 1 + +typedef struct _EFI_HII_POPUP_PROTOCOL EFI_HII_POPUP_PROTOCOL; + +typedef enum { + EfiHiiPopupStyleInfo, + EfiHiiPopupStyleWarning, + EfiHiiPopupStyleError +} EFI_HII_POPUP_STYLE; + +typedef enum { + EfiHiiPopupTypeOk, + EfiHiiPopupTypeOkCancel, + EfiHiiPopupTypeYesNo, + EfiHiiPopupTypeYesNoCancel +} EFI_HII_POPUP_TYPE; + +typedef enum { + EfiHiiPopupSelectionOk, + EfiHiiPopupSelectionCancel, + EfiHiiPopupSelectionYes, + EfiHiiPopupSelectionNo +} EFI_HII_POPUP_SELECTION; + +/** + Displays a popup window. + + @param This A pointer to the EFI_HII_POPUP_PROTOCOL instance. + @param PopupStyle Popup style to use. + @param PopupType Type of the popup to display. + @param HiiHandle HII handle of the string pack containing Message + @param Message A message to display in the popup box. + @param UserSelection User selection. + + @retval EFI_SUCCESS The popup box was successfully displayed. + @retval EFI_INVALID_PARAMETER HiiHandle and Message do not define a valid HII string. + @retval EFI_INVALID_PARAMETER PopupType is not one of the values defined by this specification. + @retval EFI_OUT_OF_RESOURCES There are not enough resources available to display the popup box. + +**/ +typedef +EFI_STATUS +(EFIAPI * EFI_HII_CREATE_POPUP) ( + IN EFI_HII_POPUP_PROTOCOL *This, + IN EFI_HII_POPUP_STYLE PopupStyle, + IN EFI_HII_POPUP_TYPE PopupType, + IN EFI_HII_HANDLE HiiHandle, + IN EFI_STRING_ID Message, + OUT EFI_HII_POPUP_SELECTION *UserSelection OPTIONAL +); + +typedef struct _EFI_HII_POPUP_PROTOCOL { + UINT64 Revision; + EFI_HII_CREATE_POPUP CreatePopup; +} EFI_HII_POPUP_PROTOCOL; + +extern EFI_GUID gEfiHiiPopupProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/HiiString.h b/MdePkg/Include/Protocol/HiiString.h index 9e9f7ff50753..989d181f5aa8 100644 --- a/MdePkg/Include/Protocol/HiiString.h +++ b/MdePkg/Include/Protocol/HiiString.h @@ -1,14 +1,11 @@ /** @file The file provides services to manipulate string data. - -Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.1. **/ @@ -25,8 +22,8 @@ typedef struct _EFI_HII_STRING_PROTOCOL EFI_HII_STRING_PROTOCOL; /** This function adds the string String to the group of strings owned by PackageList, with the specified font information StringFontInfo, and returns a new string id. - The new string identifier is guaranteed to be unique within the package list. - That new string identifier is reserved for all languages in the package list. + The new string identifier is guaranteed to be unique within the package list. + That new string identifier is reserved for all languages in the package list. @param This A pointer to the EFI_HII_STRING_PROTOCOL instance. @param PackageList The handle of the package list where this string will @@ -61,7 +58,7 @@ EFI_STATUS IN EFI_HII_HANDLE PackageList, OUT EFI_STRING_ID *StringId, IN CONST CHAR8 *Language, - IN CONST CHAR16 *LanguageName, OPTIONAL + IN CONST CHAR16 *LanguageName, OPTIONAL IN CONST EFI_STRING String, IN CONST EFI_FONT_INFO *StringFontInfo OPTIONAL ); @@ -89,7 +86,7 @@ EFI_STATUS @retval EFI_SUCCESS The string was returned successfully. @retval EFI_NOT_FOUND The string specified by StringId is not available. The specified PackageList is not in the database. - @retval EFI_INVALID_LANGUAGE The string specified by StringId is available but + @retval EFI_INVALID_LANGUAGE The string specified by StringId is available but not in the specified language. @retval EFI_BUFFER_TOO_SMALL The buffer specified by StringSize is too small to hold the string. diff --git a/MdePkg/Include/Protocol/Http.h b/MdePkg/Include/Protocol/Http.h index bdfe76db80d4..30a691bd2def 100644 --- a/MdePkg/Include/Protocol/Http.h +++ b/MdePkg/Include/Protocol/Http.h @@ -4,15 +4,9 @@ HTTP Service Binding Protocol (HTTPSB) HTTP Protocol (HTTP) - Copyright (c) 2016, Intel Corporation. All rights reserved.<BR> - (C) Copyright 2015 Hewlett Packard Enterprise Development LP<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2016 - 2018, Intel Corporation. All rights reserved.<BR> + (C) Copyright 2015-2017 Hewlett Packard Enterprise Development LP<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.5 @@ -73,7 +67,7 @@ typedef enum { HTTP_STATUS_204_NO_CONTENT, HTTP_STATUS_205_RESET_CONTENT, HTTP_STATUS_206_PARTIAL_CONTENT, - HTTP_STATUS_300_MULTIPLE_CHIOCES, + HTTP_STATUS_300_MULTIPLE_CHOICES, HTTP_STATUS_301_MOVED_PERMANENTLY, HTTP_STATUS_302_FOUND, HTTP_STATUS_303_SEE_OTHER, @@ -103,7 +97,8 @@ typedef enum { HTTP_STATUS_502_BAD_GATEWAY, HTTP_STATUS_503_SERVICE_UNAVAILABLE, HTTP_STATUS_504_GATEWAY_TIME_OUT, - HTTP_STATUS_505_HTTP_VERSION_NOT_SUPPORTED + HTTP_STATUS_505_HTTP_VERSION_NOT_SUPPORTED, + HTTP_STATUS_308_PERMANENT_REDIRECT } EFI_HTTP_STATUS_CODE; /// @@ -304,20 +299,22 @@ typedef struct { @param[in] This Pointer to EFI_HTTP_PROTOCOL instance. @param[out] HttpConfigData Point to buffer for operational parameters of this - HTTP instance. + HTTP instance. It is the responsibility of the caller + to allocate the memory for HttpConfigData and + HttpConfigData->AccessPoint.IPv6Node/IPv4Node. In fact, + it is recommended to allocate sufficient memory to record + IPv6Node since it is big enough for all possibilities. @retval EFI_SUCCESS Operation succeeded. @retval EFI_INVALID_PARAMETER This is NULL. HttpConfigData is NULL. - HttpInstance->LocalAddressIsIPv6 is FALSE and - HttpConfigData->IPv4Node is NULL. - HttpInstance->LocalAddressIsIPv6 is TRUE and - HttpConfigData->IPv6Node is NULL. + HttpConfigData->AccessPoint.IPv4Node or + HttpConfigData->AccessPoint.IPv6Node is NULL. @retval EFI_NOT_STARTED This EFI HTTP Protocol instance has not been started. **/ typedef EFI_STATUS -(EFIAPI * EFI_HTTP_GET_MODE_DATA)( +(EFIAPI *EFI_HTTP_GET_MODE_DATA)( IN EFI_HTTP_PROTOCOL *This, OUT EFI_HTTP_CONFIG_DATA *HttpConfigData ); @@ -342,9 +339,9 @@ EFI_STATUS @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: This is NULL. HttpConfigData->LocalAddressIsIPv6 is FALSE and - HttpConfigData->IPv4Node is NULL. + HttpConfigData->AccessPoint.IPv4Node is NULL. HttpConfigData->LocalAddressIsIPv6 is TRUE and - HttpConfigData->IPv6Node is NULL. + HttpConfigData->AccessPoint.IPv6Node is NULL. @retval EFI_ALREADY_STARTED Reinitialize this HTTP instance without calling Configure() with NULL to reset it. @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. @@ -355,13 +352,13 @@ EFI_STATUS **/ typedef EFI_STATUS -(EFIAPI * EFI_HTTP_CONFIGURE)( +(EFIAPI *EFI_HTTP_CONFIGURE)( IN EFI_HTTP_PROTOCOL *This, - IN EFI_HTTP_CONFIG_DATA *HttpConfigData + IN EFI_HTTP_CONFIG_DATA *HttpConfigData OPTIONAL ); /** - The Request() function queues an HTTP request to this HTTP instance, + The Request() function queues an HTTP request to this HTTP instance, similar to Transmit() function in the EFI TCP driver. When the HTTP request is sent successfully, or if there is an error, Status in token will be updated and Event will be signaled. diff --git a/MdePkg/Include/Protocol/HttpBootCallback.h b/MdePkg/Include/Protocol/HttpBootCallback.h new file mode 100644 index 000000000000..2381c9dbc791 --- /dev/null +++ b/MdePkg/Include/Protocol/HttpBootCallback.h @@ -0,0 +1,94 @@ +/** @file + This file defines the EFI HTTP Boot Callback Protocol interface. + + Copyright (c) 2017 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol is introduced in UEFI Specification 2.7 + +**/ + +#ifndef __EFI_HTTP_BOOT_CALLBACK_H__ +#define __EFI_HTTP_BOOT_CALLBACK_H__ + +#define EFI_HTTP_BOOT_CALLBACK_PROTOCOL_GUID \ + { \ + 0xba23b311, 0x343d, 0x11e6, {0x91, 0x85, 0x58, 0x20, 0xb1, 0xd6, 0x52, 0x99} \ + } + +typedef struct _EFI_HTTP_BOOT_CALLBACK_PROTOCOL EFI_HTTP_BOOT_CALLBACK_PROTOCOL; + +/// +/// EFI_HTTP_BOOT_CALLBACK_DATA_TYPE +/// +typedef enum { + /// + /// Data points to a DHCP4 packet which is about to transmit or has received. + /// + HttpBootDhcp4, + /// + /// Data points to a DHCP6 packet which is about to be transmit or has received. + /// + HttpBootDhcp6, + /// + /// Data points to an EFI_HTTP_MESSAGE structure, whichcontians a HTTP request message + /// to be transmitted. + /// + HttpBootHttpRequest, + /// + /// Data points to an EFI_HTTP_MESSAGE structure, which contians a received HTTP + /// response message. + /// + HttpBootHttpResponse, + /// + /// Part of the entity body has been received from the HTTP server. Data points to the + /// buffer of the entity body data. + /// + HttpBootHttpEntityBody, + HttpBootTypeMax +} EFI_HTTP_BOOT_CALLBACK_DATA_TYPE; + +/** + Callback function that is invoked when the HTTP Boot driver is about to transmit or has received a + packet. + + This function is invoked when the HTTP Boot driver is about to transmit or has received packet. + Parameters DataType and Received specify the type of event and the format of the buffer pointed + to by Data. Due to the polling nature of UEFI device drivers, this callback function should not + execute for more than 5 ms. + The returned status code determines the behavior of the HTTP Boot driver. + + @param[in] This Pointer to the EFI_HTTP_BOOT_CALLBACK_PROTOCOL instance. + @param[in] DataType The event that occurs in the current state. + @param[in] Received TRUE if the callback is being invoked due to a receive event. + FALSE if the callback is being invoked due to a transmit event. + @param[in] DataLength The length in bytes of the buffer pointed to by Data. + @param[in] Data A pointer to the buffer of data, the data type is specified by + DataType. + + @retval EFI_SUCCESS Tells the HTTP Boot driver to continue the HTTP Boot process. + @retval EFI_ABORTED Tells the HTTP Boot driver to abort the current HTTP Boot process. +**/ +typedef +EFI_STATUS +(EFIAPI * EFI_HTTP_BOOT_CALLBACK) ( + IN EFI_HTTP_BOOT_CALLBACK_PROTOCOL *This, + IN EFI_HTTP_BOOT_CALLBACK_DATA_TYPE DataType, + IN BOOLEAN Received, + IN UINT32 DataLength, + IN VOID *Data OPTIONAL + ); + +/// +/// EFI HTTP Boot Callback Protocol is invoked when the HTTP Boot driver is about to transmit or +/// has received a packet. The EFI HTTP Boot Callback Protocol must be installed on the same handle +/// as the Load File Protocol for the HTTP Boot. +/// +struct _EFI_HTTP_BOOT_CALLBACK_PROTOCOL { + EFI_HTTP_BOOT_CALLBACK Callback; +}; + +extern EFI_GUID gEfiHttpBootCallbackProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/HttpUtilities.h b/MdePkg/Include/Protocol/HttpUtilities.h index 59c1ea2f7853..b54666295b66 100644 --- a/MdePkg/Include/Protocol/HttpUtilities.h +++ b/MdePkg/Include/Protocol/HttpUtilities.h @@ -3,13 +3,7 @@ message comprehension. Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.5 diff --git a/MdePkg/Include/Protocol/I2cBusConfigurationManagement.h b/MdePkg/Include/Protocol/I2cBusConfigurationManagement.h index b29333e0009e..848e141567a3 100644 --- a/MdePkg/Include/Protocol/I2cBusConfigurationManagement.h +++ b/MdePkg/Include/Protocol/I2cBusConfigurationManagement.h @@ -1,19 +1,13 @@ /** @file I2C Bus Configuration Management Protocol as defined in the PI 1.3 specification. - The EFI I2C bus configuration management protocol provides platform specific - services that allow the I2C host protocol to reconfigure the switches and multiplexers - and set the clock frequency for the I2C bus. This protocol also enables the I2C host protocol + The EFI I2C bus configuration management protocol provides platform specific + services that allow the I2C host protocol to reconfigure the switches and multiplexers + and set the clock frequency for the I2C bus. This protocol also enables the I2C host protocol to reset an I2C device which may be locking up the I2C bus by holding the clock or data line low. - Copyright (c) 2013, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This protocol is from PI Version 1.3. diff --git a/MdePkg/Include/Protocol/I2cEnumerate.h b/MdePkg/Include/Protocol/I2cEnumerate.h index 00f80d0b68e4..d7bcb15ea8a7 100644 --- a/MdePkg/Include/Protocol/I2cEnumerate.h +++ b/MdePkg/Include/Protocol/I2cEnumerate.h @@ -3,14 +3,8 @@ This protocol supports the enumerations of device on the I2C bus. - Copyright (c) 2013, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This protocol is from PI Version 1.3. diff --git a/MdePkg/Include/Protocol/I2cHost.h b/MdePkg/Include/Protocol/I2cHost.h index fcd82de6b96e..27373a0784a3 100644 --- a/MdePkg/Include/Protocol/I2cHost.h +++ b/MdePkg/Include/Protocol/I2cHost.h @@ -1,17 +1,11 @@ /** @file I2C Host Protocol as defined in the PI 1.3 specification. - This protocol provides callers with the ability to do I/O transactions + This protocol provides callers with the ability to do I/O transactions to all of the devices on the I2C bus. - Copyright (c) 2013 - 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This protocol is from PI Version 1.3. @@ -50,7 +44,7 @@ typedef struct _EFI_I2C_HOST_PROTOCOL EFI_I2C_HOST_PROTOCOL; This routine must be called at or below TPL_NOTIFY. For synchronous requests this routine must be called at or below TPL_CALLBACK. - + The I2C host protocol uses the concept of I2C bus configurations to describe the I2C bus. An I2C bus configuration is defined as a unique setting of the multiplexers and switches in the I2C bus diff --git a/MdePkg/Include/Protocol/I2cIo.h b/MdePkg/Include/Protocol/I2cIo.h index 4e4267d83855..282308ecd4bb 100644 --- a/MdePkg/Include/Protocol/I2cIo.h +++ b/MdePkg/Include/Protocol/I2cIo.h @@ -1,17 +1,11 @@ /** @file I2C I/O Protocol as defined in the PI 1.3 specification. - The EFI I2C I/O protocol enables the user to manipulate a single + The EFI I2C I/O protocol enables the user to manipulate a single I2C device independent of the host controller and I2C design. - Copyright (c) 2013 - 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This protocol is from PI Version 1.3. @@ -66,7 +60,7 @@ typedef struct _EFI_I2C_IO_PROTOCOL EFI_I2C_IO_PROTOCOL; The upper layer driver writer provides the following to the platform vendor: - + 1. Vendor specific GUID for the I2C part 2. Guidance on proper construction of the slave address array when the I2C device uses more than one slave address. The I2C bus protocol diff --git a/MdePkg/Include/Protocol/I2cMaster.h b/MdePkg/Include/Protocol/I2cMaster.h index 26f689788c36..e3053ffa75f9 100644 --- a/MdePkg/Include/Protocol/I2cMaster.h +++ b/MdePkg/Include/Protocol/I2cMaster.h @@ -1,17 +1,11 @@ /** @file I2C Master Protocol as defined in the PI 1.3 specification. - This protocol manipulates the I2C host controller to perform transactions as a master + This protocol manipulates the I2C host controller to perform transactions as a master on the I2C bus using the current state of any switches or multiplexers in the I2C bus. - Copyright (c) 2013, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This protocol is from PI Version 1.3. @@ -72,7 +66,7 @@ EFI_STATUS @retval EFI_SUCCESS The reset completed successfully. @retval EFI_ALREADY_STARTED The controller is busy with another transaction. @retval EFI_DEVICE_ERROR The reset operation failed. - + **/ typedef EFI_STATUS diff --git a/MdePkg/Include/Protocol/IScsiInitiatorName.h b/MdePkg/Include/Protocol/IScsiInitiatorName.h index 5dffaeedf96c..d8f9e885a202 100644 --- a/MdePkg/Include/Protocol/IScsiInitiatorName.h +++ b/MdePkg/Include/Protocol/IScsiInitiatorName.h @@ -1,15 +1,9 @@ /** @file EFI_ISCSI_INITIATOR_NAME_PROTOCOL as defined in UEFI 2.0. - It provides the ability to get and set the iSCSI Initiator Name. + It provides the ability to get and set the iSCSI Initiator Name. - Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -39,7 +33,7 @@ typedef struct _EFI_ISCSI_INITIATOR_NAME_PROTOCOL EFI_ISCSI_INITIATOR_NAME_PROTO @retval EFI_DEVICE_ERROR The iSCSI initiator name could not be retrieved due to a hardware error. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_ISCSI_INITIATOR_NAME_GET)( IN EFI_ISCSI_INITIATOR_NAME_PROTOCOL *This, @@ -47,7 +41,7 @@ EFI_STATUS OUT VOID *Buffer ); - + /** Sets the iSCSI Initiator Name. @@ -71,10 +65,10 @@ typedef EFI_STATUS IN EFI_ISCSI_INITIATOR_NAME_PROTOCOL *This, IN OUT UINTN *BufferSize, IN VOID *Buffer - ); + ); /// -/// iSCSI Initiator Name Protocol for setting and obtaining the iSCSI Initiator Name. +/// iSCSI Initiator Name Protocol for setting and obtaining the iSCSI Initiator Name. /// struct _EFI_ISCSI_INITIATOR_NAME_PROTOCOL { EFI_ISCSI_INITIATOR_NAME_GET Get; diff --git a/MdePkg/Include/Protocol/IdeControllerInit.h b/MdePkg/Include/Protocol/IdeControllerInit.h index c099af308435..9b5b7894500e 100644 --- a/MdePkg/Include/Protocol/IdeControllerInit.h +++ b/MdePkg/Include/Protocol/IdeControllerInit.h @@ -1,31 +1,25 @@ /** @file This file declares EFI IDE Controller Init Protocol - + The EFI_IDE_CONTROLLER_INIT_PROTOCOL provides the chipset-specific information to the driver entity. This protocol is mandatory for IDE controllers if the IDE devices behind the controller are to be enumerated by a driver entity. - + There can only be one instance of EFI_IDE_CONTROLLER_INIT_PROTOCOL for each IDE controller in a system. It is installed on the handle that corresponds to the IDE controller. A driver entity that wishes to manage an IDE bus and possibly IDE devices in a system will have to retrieve the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance that is associated with the controller to be managed. - + A device handle for an IDE controller must contain an EFI_DEVICE_PATH_PROTOCOL. -Copyright (c) 2007 - 2011, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: - This Protocol is defined in UEFI Platform Initialization Specification 1.2 + This Protocol is defined in UEFI Platform Initialization Specification 1.2 Volume 5: Standards. - + **/ #ifndef _EFI_IDE_CONTROLLER_INIT_PROTOCOL_H_ @@ -71,7 +65,7 @@ typedef enum { /// /// The driver entity has completed resetting the devices behind /// the specified channel. This notification can be used to perform - /// any chipset-specific programming. + /// any chipset-specific programming. /// EfiIdeAfterChannelReset, /// @@ -84,13 +78,13 @@ typedef enum { /// /// The driver entity is done with detecting the presence of /// devices behind the specified channel. This notification can be - /// used to perform any chipset-specific programming. + /// used to perform any chipset-specific programming. /// EfiIdeBusAfterDevicePresenceDetection, /// /// The IDE bus is requesting the IDE controller driver to /// reprogram the IDE controller hardware and thereby reset all - /// the mode and timing settings to default settings. + /// the mode and timing settings to default settings. /// EfiIdeResetMode, EfiIdeBusPhaseMaximum @@ -135,11 +129,11 @@ typedef struct { typedef struct { /// /// An enumeration defining various transfer protocols other than the protocols - /// that exist at the time this specification was developed (i.e., PIO, single - /// word DMA, multiword DMA, and UDMA). Each transfer protocol is associated - /// with a mode. The various transfer protocols are defined by the ATA/ATAPI - /// specification. This enumeration makes the interface extensible because we - /// can support new transport protocols beyond UDMA. Type EFI_ATA_EXT_TRANSFER_PROTOCOL + /// that exist at the time this specification was developed (i.e., PIO, single + /// word DMA, multiword DMA, and UDMA). Each transfer protocol is associated + /// with a mode. The various transfer protocols are defined by the ATA/ATAPI + /// specification. This enumeration makes the interface extensible because we + /// can support new transport protocols beyond UDMA. Type EFI_ATA_EXT_TRANSFER_PROTOCOL /// is defined below. /// EFI_ATA_EXT_TRANSFER_PROTOCOL TransferProtocol; @@ -155,7 +149,7 @@ typedef struct { typedef struct { /// /// This field specifies the PIO mode. PIO modes are defined in the ATA/ATAPI - /// specification. The ATA/ATAPI specification defines the enumeration. In + /// specification. The ATA/ATAPI specification defines the enumeration. In /// other words, a value of 1 in this field means PIO mode 1. The actual meaning /// of PIO mode 1 is governed by the ATA/ATAPI specification. Type EFI_ATA_MODE /// is defined below. @@ -168,26 +162,26 @@ typedef struct { /// controllers will not support this transfer mode. The ATA/ATAPI specification defines /// the enumeration. In other words, a value of 1 in this field means single word DMA /// mode 1. The actual meaning of single word DMA mode 1 is governed by the ATA/ - /// ATAPI specification. + /// ATAPI specification. /// EFI_ATA_MODE SingleWordDmaMode; /// /// This field specifies the multiword DMA mode. Various multiword DMA modes are /// defined in the ATA/ATAPI specification. A value of 1 in this field means multiword /// DMA mode 1. The actual meaning of multiword DMA mode 1 is governed by the - /// ATA/ATAPI specification. + /// ATA/ATAPI specification. /// EFI_ATA_MODE MultiWordDmaMode; /// /// This field specifies the ultra DMA (UDMA) mode. UDMA modes are defined in the /// ATA/ATAPI specification. A value of 1 in this field means UDMA mode 1. The - /// actual meaning of UDMA mode 1 is governed by the ATA/ATAPI specification. + /// actual meaning of UDMA mode 1 is governed by the ATA/ATAPI specification. /// EFI_ATA_MODE UdmaMode; /// /// The number of extended-mode bitmap entries. Extended modes describe transfer /// protocols beyond PIO, single word DMA, multiword DMA, and UDMA. This field - /// can be zero and provides extensibility. + /// can be zero and provides extensibility. /// UINT32 ExtModeCount; /// @@ -195,7 +189,7 @@ typedef struct { /// than the ones defined above (i.e., PIO, single word DMA, multiword DMA, and /// UDMA). This field is defined for extensibility. At this time, only one extended /// transfer protocol is defined to cover SATA transfers. Type - /// EFI_ATA_EXTENDED_MODE is defined below. + /// EFI_ATA_EXTENDED_MODE is defined below. /// EFI_ATA_EXTENDED_MODE ExtMode[1]; } EFI_ATA_COLLECTIVE_MODE; @@ -206,16 +200,16 @@ typedef struct { /// The definition of these two structures is not part of the protocol /// definition because the ATA/ATAPI Specification controls the definition /// of all the fields. The ATA/ATAPI Specification can obsolete old fields -/// or redefine existing fields. +/// or redefine existing fields. typedef ATA_IDENTIFY_DATA EFI_ATA_IDENTIFY_DATA; typedef ATAPI_IDENTIFY_DATA EFI_ATAPI_IDENTIFY_DATA; /// /// This flag indicates whether the IDENTIFY data is a response from an ATA device -/// (EFI_ATA_IDENTIFY_DATA) or response from an ATAPI device +/// (EFI_ATA_IDENTIFY_DATA) or response from an ATAPI device /// (EFI_ATAPI_IDENTIFY_DATA). According to the ATA/ATAPI specification, -/// EFI_IDENTIFY_DATA is for an ATA device if bit 15 of the Config field is zero. -/// The Config field is common to both EFI_ATA_IDENTIFY_DATA and +/// EFI_IDENTIFY_DATA is for an ATA device if bit 15 of the Config field is zero. +/// The Config field is common to both EFI_ATA_IDENTIFY_DATA and /// EFI_ATAPI_IDENTIFY_DATA. /// #define EFI_ATAPI_DEVICE_IDENTIFY_DATA 0x8000 @@ -225,8 +219,8 @@ typedef ATAPI_IDENTIFY_DATA EFI_ATAPI_IDENTIFY_DATA; /// typedef union { /// - /// The data that is returned by an ATA device upon successful completion - /// of the ATA IDENTIFY_DEVICE command. + /// The data that is returned by an ATA device upon successful completion + /// of the ATA IDENTIFY_DEVICE command. /// EFI_ATA_IDENTIFY_DATA AtaData; /// @@ -238,34 +232,34 @@ typedef union { /** Returns the information about the specified IDE channel. - + This function can be used to obtain information about a particular IDE channel. - The driver entity uses this information during the enumeration process. - - If Enabled is set to FALSE, the driver entity will not scan the channel. Note + The driver entity uses this information during the enumeration process. + + If Enabled is set to FALSE, the driver entity will not scan the channel. Note that it will not prevent an operating system driver from scanning the channel. - - For most of today's controllers, MaxDevices will either be 1 or 2. For SATA - controllers, this value will always be 1. SATA configurations can contain SATA + + For most of today's controllers, MaxDevices will either be 1 or 2. For SATA + controllers, this value will always be 1. SATA configurations can contain SATA port multipliers. SATA port multipliers behave like SATA bridges and can support - up to 16 devices on the other side. If a SATA port out of the IDE controller - is connected to a port multiplier, MaxDevices will be set to the number of SATA - devices that the port multiplier supports. Because today's port multipliers - support up to fifteen SATA devices, this number can be as large as fifteen. The IDE - bus driver is required to scan for the presence of port multipliers behind an SATA - controller and enumerate up to MaxDevices number of devices behind the port - multiplier. - - In this context, the devices behind a port multiplier constitute a channel. - + up to 16 devices on the other side. If a SATA port out of the IDE controller + is connected to a port multiplier, MaxDevices will be set to the number of SATA + devices that the port multiplier supports. Because today's port multipliers + support up to fifteen SATA devices, this number can be as large as fifteen. The IDE + bus driver is required to scan for the presence of port multipliers behind an SATA + controller and enumerate up to MaxDevices number of devices behind the port + multiplier. + + In this context, the devices behind a port multiplier constitute a channel. + @param[in] This The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance. @param[in] Channel Zero-based channel number. - @param[out] Enabled TRUE if this channel is enabled. Disabled channels + @param[out] Enabled TRUE if this channel is enabled. Disabled channels are not scanned to see if any devices are present. @param[out] MaxDevices The maximum number of IDE devices that the bus driver - can expect on this channel. For the ATA/ATAPI - specification, version 6, this number will either be - one or two. For Serial ATA (SATA) configurations with a + can expect on this channel. For the ATA/ATAPI + specification, version 6, this number will either be + one or two. For Serial ATA (SATA) configurations with a port multiplier, this number can be as large as fifteen. @retval EFI_SUCCESS Information was returned without any errors. @@ -284,13 +278,13 @@ EFI_STATUS /** The notifications from the driver entity that it is about to enter a certain phase of the IDE channel enumeration process. - - This function can be used to notify the IDE controller driver to perform - specific actions, including any chipset-specific initialization, so that the - chipset is ready to enter the next phase. Seven notification points are defined - at this time. - - More synchronization points may be added as required in the future. + + This function can be used to notify the IDE controller driver to perform + specific actions, including any chipset-specific initialization, so that the + chipset is ready to enter the next phase. Seven notification points are defined + at this time. + + More synchronization points may be added as required in the future. @param[in] This The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance. @param[in] Phase The phase during enumeration. @@ -299,9 +293,9 @@ EFI_STATUS @retval EFI_SUCCESS The notification was accepted without any errors. @retval EFI_UNSUPPORTED Phase is not supported. @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount). - @retval EFI_NOT_READY This phase cannot be entered at this time; for - example, an attempt was made to enter a Phase - without having entered one or more previous + @retval EFI_NOT_READY This phase cannot be entered at this time; for + example, an attempt was made to enter a Phase + without having entered one or more previous Phase. **/ @@ -316,32 +310,32 @@ EFI_STATUS /** Submits the device information to the IDE controller driver. - This function is used by the driver entity to pass detailed information about - a particular device to the IDE controller driver. The driver entity obtains + This function is used by the driver entity to pass detailed information about + a particular device to the IDE controller driver. The driver entity obtains this information by issuing an ATA or ATAPI IDENTIFY_DEVICE command. IdentifyData - is the pointer to the response data buffer. The IdentifyData buffer is owned - by the driver entity, and the IDE controller driver must make a local copy - of the entire buffer or parts of the buffer as needed. The original IdentifyData + is the pointer to the response data buffer. The IdentifyData buffer is owned + by the driver entity, and the IDE controller driver must make a local copy + of the entire buffer or parts of the buffer as needed. The original IdentifyData buffer pointer may not be valid when - + - EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() or - EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() is called at a later point. - - The IDE controller driver may consult various fields of EFI_IDENTIFY_DATA to - compute the optimum mode for the device. These fields are not limited to the - timing information. For example, an implementation of the IDE controller driver - may examine the vendor and type/mode field to match known bad drives. - - The driver entity may submit drive information in any order, as long as it - submits information for all the devices belonging to the enumeration group + + The IDE controller driver may consult various fields of EFI_IDENTIFY_DATA to + compute the optimum mode for the device. These fields are not limited to the + timing information. For example, an implementation of the IDE controller driver + may examine the vendor and type/mode field to match known bad drives. + + The driver entity may submit drive information in any order, as long as it + submits information for all the devices belonging to the enumeration group before EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() is called for any device in that enumeration group. If a device is absent, EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() - should be called with IdentifyData set to NULL. The IDE controller driver may - not have any other mechanism to know whether a device is present or not. Therefore, - setting IdentifyData to NULL does not constitute an error condition. - EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() can be called only once for a - given (Channel, Device) pair. - + should be called with IdentifyData set to NULL. The IDE controller driver may + not have any other mechanism to know whether a device is present or not. Therefore, + setting IdentifyData to NULL does not constitute an error condition. + EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() can be called only once for a + given (Channel, Device) pair. + @param[in] This A pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance. @param[in] Channel Zero-based channel number. @param[in] Device Zero-based device number on the Channel. @@ -364,31 +358,31 @@ EFI_STATUS /** Disqualifies specific modes for an IDE device. - This function allows the driver entity or other drivers (such as platform + This function allows the driver entity or other drivers (such as platform drivers) to reject certain timing modes and request the IDE controller driver - to recalculate modes. This function allows the driver entity and the IDE - controller driver to negotiate the timings on a per-device basis. This function - is useful in the case of drives that lie about their capabilities. An example - is when the IDE device fails to accept the timing modes that are calculated + to recalculate modes. This function allows the driver entity and the IDE + controller driver to negotiate the timings on a per-device basis. This function + is useful in the case of drives that lie about their capabilities. An example + is when the IDE device fails to accept the timing modes that are calculated by the IDE controller driver based on the response to the Identify Drive command. - If the driver entity does not want to limit the ATA timing modes and leave that - decision to the IDE controller driver, it can either not call this function for - the given device or call this function and set the Valid flag to FALSE for all + If the driver entity does not want to limit the ATA timing modes and leave that + decision to the IDE controller driver, it can either not call this function for + the given device or call this function and set the Valid flag to FALSE for all modes that are listed in EFI_ATA_COLLECTIVE_MODE. - - The driver entity may disqualify modes for a device in any order and any number + + The driver entity may disqualify modes for a device in any order and any number of times. - - This function can be called multiple times to invalidate multiple modes of the - same type (e.g., Programmed Input/Output [PIO] modes 3 and 4). See the ATA/ATAPI - specification for more information on PIO modes. - + + This function can be called multiple times to invalidate multiple modes of the + same type (e.g., Programmed Input/Output [PIO] modes 3 and 4). See the ATA/ATAPI + specification for more information on PIO modes. + For Serial ATA (SATA) controllers, this member function can be used to disqualify a higher transfer rate mode on a given channel. For example, a platform driver - may inform the IDE controller driver to not use second-generation (Gen2) speeds + may inform the IDE controller driver to not use second-generation (Gen2) speeds for a certain SATA drive. - + @param[in] This The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance. @param[in] Channel The zero-based channel number. @param[in] Device The zero-based device number on the Channel. @@ -399,7 +393,7 @@ EFI_STATUS @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount). @retval EFI_INVALID_PARAMETER Device is invalid. @retval EFI_INVALID_PARAMETER IdentifyData is NULL. - + **/ typedef EFI_STATUS @@ -414,39 +408,39 @@ EFI_STATUS Returns the information about the optimum modes for the specified IDE device. This function is used by the driver entity to obtain the optimum ATA modes for - a specific device. The IDE controller driver takes into account the following + a specific device. The IDE controller driver takes into account the following while calculating the mode: - The IdentifyData inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() - The BadModes inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() - The driver entity is required to call EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() - for all the devices that belong to an enumeration group before calling - EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() for any device in the same group. - - The IDE controller driver will use controller- and possibly platform-specific - algorithms to arrive at SupportedModes. The IDE controller may base its - decision on user preferences and other considerations as well. This function - may be called multiple times because the driver entity may renegotiate the mode + The driver entity is required to call EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() + for all the devices that belong to an enumeration group before calling + EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() for any device in the same group. + + The IDE controller driver will use controller- and possibly platform-specific + algorithms to arrive at SupportedModes. The IDE controller may base its + decision on user preferences and other considerations as well. This function + may be called multiple times because the driver entity may renegotiate the mode with the IDE controller driver using EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode(). - - The driver entity may collect timing information for various devices in any + + The driver entity may collect timing information for various devices in any order. The driver entity is responsible for making sure that all the dependencies - are satisfied. For example, the SupportedModes information for device A that - was previously returned may become stale after a call to + are satisfied. For example, the SupportedModes information for device A that + was previously returned may become stale after a call to EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() for device B. - - The buffer SupportedModes is allocated by the callee because the caller does - not necessarily know the size of the buffer. The type EFI_ATA_COLLECTIVE_MODE - is defined in a way that allows for future extensibility and can be of variable - length. This memory pool should be deallocated by the caller when it is no - longer necessary. - - The IDE controller driver for a Serial ATA (SATA) controller can use this - member function to force a lower speed (first-generation [Gen1] speeds on a - second-generation [Gen2]-capable hardware). The IDE controller driver can - also allow the driver entity to stay with the speed that has been negotiated + + The buffer SupportedModes is allocated by the callee because the caller does + not necessarily know the size of the buffer. The type EFI_ATA_COLLECTIVE_MODE + is defined in a way that allows for future extensibility and can be of variable + length. This memory pool should be deallocated by the caller when it is no + longer necessary. + + The IDE controller driver for a Serial ATA (SATA) controller can use this + member function to force a lower speed (first-generation [Gen1] speeds on a + second-generation [Gen2]-capable hardware). The IDE controller driver can + also allow the driver entity to stay with the speed that has been negotiated by the physical layer. - + @param[in] This The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance. @param[in] Channel A zero-based channel number. @param[in] Device A zero-based device number on the Channel. @@ -454,13 +448,13 @@ EFI_STATUS @retval EFI_SUCCESS SupportedModes was returned. @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount). - @retval EFI_INVALID_PARAMETER Device is invalid. + @retval EFI_INVALID_PARAMETER Device is invalid. @retval EFI_INVALID_PARAMETER SupportedModes is NULL. - @retval EFI_NOT_READY Modes cannot be calculated due to a lack of - data. This error may happen if - EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() - and EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyData() - were not called for at least one drive in the + @retval EFI_NOT_READY Modes cannot be calculated due to a lack of + data. This error may happen if + EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() + and EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyData() + were not called for at least one drive in the same enumeration group. **/ @@ -477,9 +471,9 @@ EFI_STATUS Commands the IDE controller driver to program the IDE controller hardware so that the specified device can operate at the specified mode. - This function is used by the driver entity to instruct the IDE controller - driver to program the IDE controller hardware to the specified modes. This - function can be called only once for a particular device. For a Serial ATA + This function is used by the driver entity to instruct the IDE controller + driver to program the IDE controller hardware to the specified modes. This + function can be called only once for a particular device. For a Serial ATA (SATA) Advanced Host Controller Interface (AHCI) controller, no controller- specific programming may be required. @@ -513,48 +507,48 @@ struct _EFI_IDE_CONTROLLER_INIT_PROTOCOL { /// Returns the information about a specific channel. /// EFI_IDE_CONTROLLER_GET_CHANNEL_INFO GetChannelInfo; - + /// /// The notification that the driver entity is about to enter the - /// specified phase during the enumeration process. + /// specified phase during the enumeration process. /// EFI_IDE_CONTROLLER_NOTIFY_PHASE NotifyPhase; - + /// /// Submits the Drive Identify data that was returned by the device. /// EFI_IDE_CONTROLLER_SUBMIT_DATA SubmitData; - + /// - /// Submits information about modes that should be disqualified. The specified - /// IDE device does not support these modes and these modes should not be + /// Submits information about modes that should be disqualified. The specified + /// IDE device does not support these modes and these modes should not be /// returned by EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() /// EFI_IDE_CONTROLLER_DISQUALIFY_MODE DisqualifyMode; - + /// /// Calculates and returns the optimum mode for a particular IDE device. /// EFI_IDE_CONTROLLER_CALCULATE_MODE CalculateMode; - + /// /// Programs the IDE controller hardware to the default timing or per the modes - /// that were returned by the last call to EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode(). + /// that were returned by the last call to EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode(). /// EFI_IDE_CONTROLLER_SET_TIMING SetTiming; - + /// /// Set to TRUE if the enumeration group includes all the channels that are /// produced by this controller. Set to FALSE if an enumeration group consists of - /// only one channel. + /// only one channel. /// BOOLEAN EnumAll; - + /// /// The number of channels that are produced by this controller. Parallel ATA - /// (PATA) controllers can support up to two channels. Advanced Host Controller + /// (PATA) controllers can support up to two channels. Advanced Host Controller /// Interface (AHCI) Serial ATA (SATA) controllers can support up to 32 channels, - /// each of which can have up to one device. In the presence of a multiplier, + /// each of which can have up to one device. In the presence of a multiplier, /// each channel can have fifteen devices. /// UINT8 ChannelCount; diff --git a/MdePkg/Include/Protocol/IncompatiblePciDeviceSupport.h b/MdePkg/Include/Protocol/IncompatiblePciDeviceSupport.h index 9a924d4a6725..d963cb43f4ca 100644 --- a/MdePkg/Include/Protocol/IncompatiblePciDeviceSupport.h +++ b/MdePkg/Include/Protocol/IncompatiblePciDeviceSupport.h @@ -1,74 +1,68 @@ /** @file This file declares Incompatible PCI Device Support Protocol - - Allows the PCI bus driver to support resource allocation for some PCI devices + + Allows the PCI bus driver to support resource allocation for some PCI devices that do not comply with the PCI Specification. - - @par Note: - This protocol is optional. Only those platforms that implement this protocol - will have the capability to support incompatible PCI devices. The absence of - this protocol can cause the PCI bus driver to configure these incompatible - PCI devices incorrectly. As a result, these devices may not work properly. - + + @par Note: + This protocol is optional. Only those platforms that implement this protocol + will have the capability to support incompatible PCI devices. The absence of + this protocol can cause the PCI bus driver to configure these incompatible + PCI devices incorrectly. As a result, these devices may not work properly. + The EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL is used by the PCI bus driver - to support resource allocation for some PCI devices that do not comply with the - PCI Specification. This protocol can find some incompatible PCI devices and - report their special resource requirements to the PCI bus driver. The generic - PCI bus driver does not have prior knowledge of any incompatible PCI devices. - It interfaces with the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL to find out - if a device is incompatible and to obtain the special configuration requirements + to support resource allocation for some PCI devices that do not comply with the + PCI Specification. This protocol can find some incompatible PCI devices and + report their special resource requirements to the PCI bus driver. The generic + PCI bus driver does not have prior knowledge of any incompatible PCI devices. + It interfaces with the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL to find out + if a device is incompatible and to obtain the special configuration requirements for a specific incompatible PCI device. This protocol is optional, and only one instance of this protocol can be present - in the system. If a platform supports this protocol, this protocol is produced - by a Driver Execution Environment (DXE) driver and must be made available before - the Boot Device Selection (BDS) phase. The PCI bus driver will look for the - presence of this protocol before it begins PCI enumeration. If this protocol + in the system. If a platform supports this protocol, this protocol is produced + by a Driver Execution Environment (DXE) driver and must be made available before + the Boot Device Selection (BDS) phase. The PCI bus driver will look for the + presence of this protocol before it begins PCI enumeration. If this protocol exists in a platform, it indicates that the platform has the capability to support - those incompatible PCI devices. However, final support for incompatible PCI - devices still depends on the implementation of the PCI bus driver. The PCI bus - driver may fully, partially, or not even support these incompatible devices. - - During PCI bus enumeration, the PCI bus driver will probe the PCI Base Address - Registers (BARs) for each PCI device regardless of whether the PCI device is - incompatible or not to determine the resource requirements so that the PCI bus - driver can invoke the proper PCI resources for them. Generally, this resource + those incompatible PCI devices. However, final support for incompatible PCI + devices still depends on the implementation of the PCI bus driver. The PCI bus + driver may fully, partially, or not even support these incompatible devices. + + During PCI bus enumeration, the PCI bus driver will probe the PCI Base Address + Registers (BARs) for each PCI device regardless of whether the PCI device is + incompatible or not to determine the resource requirements so that the PCI bus + driver can invoke the proper PCI resources for them. Generally, this resource information includes the following: - Resource type - Resource length - Alignment - + However, some incompatible PCI devices may have special requirements. As a result, - the length or the alignment that is derived through BAR probing may not be exactly - the same as the actual resource requirement of the device. For example, there + the length or the alignment that is derived through BAR probing may not be exactly + the same as the actual resource requirement of the device. For example, there are some devices that request I/O resources at a length of 0x100 from their I/O - BAR, but these incompatible devices will never work correctly if an odd I/O base - address, such as 0x100, 0x300, or 0x500, is assigned to the BAR. Instead, these - devices request an even base address, such as 0x200 or 0x400. The Incompatible - PCI Device Support Protocol can then be used to obtain these special resource - requirements for these incompatible PCI devices. In this way, the PCI bus driver - will take special consideration for these devices during PCI resource allocation + BAR, but these incompatible devices will never work correctly if an odd I/O base + address, such as 0x100, 0x300, or 0x500, is assigned to the BAR. Instead, these + devices request an even base address, such as 0x200 or 0x400. The Incompatible + PCI Device Support Protocol can then be used to obtain these special resource + requirements for these incompatible PCI devices. In this way, the PCI bus driver + will take special consideration for these devices during PCI resource allocation to ensure that they can work correctly. - + This protocol may support the following incompatible PCI BAR types: - I/O or memory length that is different from what the BAR reports - I/O or memory alignment that is different from what the BAR reports - Fixed I/O or memory base address - - See the Conventional PCI Specification 3.0 for the details of how a PCI BAR - reports the resource length and the alignment that it requires. - Copyright (c) 2007 - 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + See the Conventional PCI Specification 3.0 for the details of how a PCI BAR + reports the resource length and the alignment that it requires. - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: - This Protocol is defined in UEFI Platform Initialization Specification 1.2 + This Protocol is defined in UEFI Platform Initialization Specification 1.2 Volume 5: Standards **/ @@ -92,51 +86,51 @@ typedef struct _EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL EFI_INCOMPATIBLE_PC /** Returns a list of ACPI resource descriptors that detail the special resource configuration requirements for an incompatible PCI device. - - This function returns a list of ACPI resource descriptors that detail the - special resource configuration requirements for an incompatible PCI device. - + + This function returns a list of ACPI resource descriptors that detail the + special resource configuration requirements for an incompatible PCI device. + Prior to bus enumeration, the PCI bus driver will look for the presence of the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL. Only one instance of this - protocol can be present in the system. For each PCI device that the PCI bus + protocol can be present in the system. For each PCI device that the PCI bus driver discovers, the PCI bus driver calls this function with the device's vendor ID, device ID, revision ID, subsystem vendor ID, and subsystem device ID. If the VendorId, DeviceId, RevisionId, SubsystemVendorId, or SubsystemDeviceId value is set to (UINTN)-1, that field will be ignored. The ID values that are not (UINTN)-1 - will be used to identify the current device. - - This function will only return EFI_SUCCESS. However, if the device is an - incompatible PCI device, a list of ACPI resource descriptors will be returned - in Configuration. Otherwise, NULL will be returned in Configuration instead. - The PCI bus driver does not need to allocate memory for Configuration. However, - it is the PCI bus driver's responsibility to free it. The PCI bus driver then - can configure this device with the information that is derived from this list + will be used to identify the current device. + + This function will only return EFI_SUCCESS. However, if the device is an + incompatible PCI device, a list of ACPI resource descriptors will be returned + in Configuration. Otherwise, NULL will be returned in Configuration instead. + The PCI bus driver does not need to allocate memory for Configuration. However, + it is the PCI bus driver's responsibility to free it. The PCI bus driver then + can configure this device with the information that is derived from this list of resource nodes, rather than the result of BAR probing. - Only the following two resource descriptor types from the ACPI Specification + Only the following two resource descriptor types from the ACPI Specification may be used to describe the incompatible PCI device resource requirements: - QWORD Address Space Descriptor (ACPI 2.0, section 6.4.3.5.1; also ACPI 3.0) - End Tag (ACPI 2.0, section 6.4.2.8; also ACPI 3.0) - The QWORD Address Space Descriptor can describe memory, I/O, and bus number - ranges for dynamic or fixed resources. The configuration of a PCI root bridge - is described with one or more QWORD Address Space Descriptors, followed by an + The QWORD Address Space Descriptor can describe memory, I/O, and bus number + ranges for dynamic or fixed resources. The configuration of a PCI root bridge + is described with one or more QWORD Address Space Descriptors, followed by an End Tag. See the ACPI Specification for details on the field values. - - @param[in] This Pointer to the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL + + @param[in] This Pointer to the EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL instance. - @param[in] VendorId A unique ID to identify the manufacturer of + @param[in] VendorId A unique ID to identify the manufacturer of the PCI device. See the Conventional PCI Specification 3.0 for details. - @param[in] DeviceId A unique ID to identify the particular PCI - device. See the Conventional PCI Specification + @param[in] DeviceId A unique ID to identify the particular PCI + device. See the Conventional PCI Specification 3.0 for details. - @param[in] RevisionId A PCI device-specific revision identifier. + @param[in] RevisionId A PCI device-specific revision identifier. See the Conventional PCI Specification 3.0 for details. - @param[in] SubsystemVendorId Specifies the subsystem vendor ID. See the + @param[in] SubsystemVendorId Specifies the subsystem vendor ID. See the Conventional PCI Specification 3.0 for details. - @param[in] SubsystemDeviceId Specifies the subsystem device ID. See the + @param[in] SubsystemDeviceId Specifies the subsystem device ID. See the Conventional PCI Specification 3.0 for details. @param[out] Configuration A list of ACPI resource descriptors that detail the configuration requirement. diff --git a/MdePkg/Include/Protocol/Ip4.h b/MdePkg/Include/Protocol/Ip4.h index e36f38d8f5d2..519c80d62916 100644 --- a/MdePkg/Include/Protocol/Ip4.h +++ b/MdePkg/Include/Protocol/Ip4.h @@ -6,21 +6,15 @@ - EFI IPv4 Variable (deprecated in UEFI 2.4B) - EFI IPv4 Protocol. The EFI IPv4 Protocol provides basic network IPv4 packet I/O services, - which includes support foR a subset of the Internet Control Message + which includes support foR a subset of the Internet Control Message Protocol (ICMP) and may include support for the Internet Group Management Protocol (IGMP). - -Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: - This Protocol is introduced in UEFI Specification 2.0. + +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol is introduced in UEFI Specification 2.0. **/ @@ -49,7 +43,7 @@ typedef struct { EFI_HANDLE InstanceHandle; EFI_IPv4_ADDRESS Ip4Address; EFI_IPv4_ADDRESS SubnetMask; -} EFI_IP4_ADDRESS_PAIR; +} EFI_IP4_ADDRESS_PAIR; /// /// EFI_IP4_VARIABLE_DATA is deprecated in the UEFI 2.4B and should not be used any more. @@ -271,7 +265,7 @@ typedef struct { /** Gets the current operational settings for this instance of the EFI IPv4 Protocol driver. - + The GetModeData() function returns the current operational mode data for this driver instance. The data fields in EFI_IP4_MODE_DATA are read only. This function is used optionally to retrieve the operational mode data of underlying @@ -294,11 +288,11 @@ EFI_STATUS OUT EFI_IP4_MODE_DATA *Ip4ModeData OPTIONAL, OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL, OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL - ); + ); /** Assigns an IPv4 address and subnet mask to this EFI IPv4 Protocol driver instance. - + The Configure() function is used to set, change, or reset the operational parameters and filter settings for this EFI IPv4 Protocol instance. Until these parameters have been set, no network traffic can be sent or received by this @@ -307,14 +301,14 @@ EFI_STATUS parameters have been set again. Each EFI IPv4 Protocol instance can be started and stopped independently of each other by enabling or disabling their receive filter settings with the Configure() function. - + When IpConfigData.UseDefaultAddress is set to FALSE, the new station address will be appended as an alias address into the addresses list in the EFI IPv4 Protocol driver. While set to TRUE, Configure() will trigger the EFI_IP4_CONFIG_PROTOCOL to retrieve the default IPv4 address if it is not available yet. Clients could frequently call GetModeData() to check the status to ensure that the default IPv4 address is ready. - + If operational parameters are reset or changed, any pending transmit and receive requests will be cancelled. Their completion token status will be set to EFI_ABORTED and their events will be signaled. @@ -328,7 +322,7 @@ EFI_STATUS @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: This is NULL. IpConfigData.StationAddress is not a unicast IPv4 address. - IpConfigData.SubnetMask is not a valid IPv4 subnet + IpConfigData.SubnetMask is not a valid IPv4 subnet @retval EFI_UNSUPPORTED One or more of the following conditions is TRUE: A configuration protocol (DHCP, BOOTP, RARP, etc.) could not be located when clients choose to use the default IPv4 @@ -342,20 +336,20 @@ EFI_STATUS Protocol driver instance is not opened. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_IP4_CONFIGURE)( IN EFI_IP4_PROTOCOL *This, IN EFI_IP4_CONFIG_DATA *IpConfigData OPTIONAL - ); + ); /** Joins and leaves multicast groups. - + The Groups() function is used to join and leave multicast group sessions. Joining a group will enable reception of matching multicast packets. Leaving a group will disable the multicast packet reception. - + If JoinFlag is FALSE and GroupAddress is NULL, all joined groups will be left. @param This The pointer to the EFI_IP4_PROTOCOL instance. @@ -379,32 +373,32 @@ EFI_STATUS @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_IP4_GROUPS)( IN EFI_IP4_PROTOCOL *This, IN BOOLEAN JoinFlag, IN EFI_IPv4_ADDRESS *GroupAddress OPTIONAL - ); + ); /** Adds and deletes routing table entries. The Routes() function adds a route to or deletes a route from the routing table. - + Routes are determined by comparing the SubnetAddress with the destination IPv4 address arithmetically AND-ed with the SubnetMask. The gateway address must be on the same subnet as the configured station address. - + The default route is added with SubnetAddress and SubnetMask both set to 0.0.0.0. The default route matches all destination IPv4 addresses that do not match any other routes. - + A GatewayAddress that is zero is a nonroute. Packets are sent to the destination IP address if it can be found in the ARP cache or on the local subnet. One automatic nonroute entry will be inserted into the routing table for outgoing packets that are addressed to a local subnet (gateway address of 0.0.0.0). - + Each EFI IPv4 Protocol instance has its own independent routing table. Those EFI IPv4 Protocol instances that use the default IPv4 address will also have copies of the routing table that was provided by the EFI_IP4_CONFIG_PROTOCOL, and these @@ -435,17 +429,17 @@ EFI_STATUS @retval EFI_NOT_FOUND This route is not in the routing table (when DeleteRoute is TRUE). @retval EFI_ACCESS_DENIED The route is already defined in the routing table (when DeleteRoute is FALSE). - + **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_IP4_ROUTES)( IN EFI_IP4_PROTOCOL *This, IN BOOLEAN DeleteRoute, IN EFI_IPv4_ADDRESS *SubnetAddress, IN EFI_IPv4_ADDRESS *SubnetMask, - IN EFI_IPv4_ADDRESS *GatewayAddress - ); + IN EFI_IPv4_ADDRESS *GatewayAddress + ); /** Places outgoing data packets into the transmit queue. @@ -465,7 +459,7 @@ EFI_STATUS @retval EFI_ACCESS_DENIED The transmit completion token with the same Token.Event was already in the transmit queue. @retval EFI_NOT_READY The completion token could not be queued because the transmit - queue is full. + queue is full. @retval EFI_NOT_FOUND Not route is found to destination address. @retval EFI_OUT_OF_RESOURCES Could not queue the transmit data. @retval EFI_BUFFER_TOO_SMALL Token.Packet.TxData.TotalDataLength is too @@ -476,19 +470,19 @@ EFI_STATUS DoNotFragment is TRUE.) **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_IP4_TRANSMIT)( IN EFI_IP4_PROTOCOL *This, IN EFI_IP4_COMPLETION_TOKEN *Token - ); + ); /** Places a receiving request into the receiving queue. - + The Receive() function places a completion token into the receive packet queue. This function is always asynchronous. - + The Token.Event field in the completion token must be filled in by the caller and cannot be NULL. When the receive operation completes, the EFI IPv4 Protocol driver updates the Token.Status and Token.Packet.RxData fields and the Token.Event @@ -515,16 +509,16 @@ EFI_STATUS @retval EFI_ICMP_ERROR An ICMP error packet was received. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_IP4_RECEIVE)( IN EFI_IP4_PROTOCOL *This, IN EFI_IP4_COMPLETION_TOKEN *Token - ); + ); /** Abort an asynchronous transmit or receive request. - + The Cancel() function is used to abort a pending transmit or receive request. If the token is in the transmit or receive request queues, after calling this function, Token->Status will be set to EFI_ABORTED and then Token->Event will @@ -556,16 +550,16 @@ EFI_STATUS (EFIAPI *EFI_IP4_CANCEL)( IN EFI_IP4_PROTOCOL *This, IN EFI_IP4_COMPLETION_TOKEN *Token OPTIONAL - ); - + ); + /** Polls for incoming data packets and processes outgoing data packets. - + The Poll() function polls for incoming data packets and processes outgoing data packets. Network drivers and applications can call the EFI_IP4_PROTOCOL.Poll() function to increase the rate that data packets are moved between the communications device and the transmit and receive queues. - + In some systems the periodic timer event may not poll the underlying communications device fast enough to transmit and/or receive all data packets without missing incoming packets or dropping outgoing packets. Drivers and applications that are @@ -585,14 +579,14 @@ EFI_STATUS Consider increasing the polling rate. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_IP4_POLL)( IN EFI_IP4_PROTOCOL *This - ); + ); /// -/// The EFI IPv4 Protocol implements a simple packet-oriented interface that can be +/// The EFI IPv4 Protocol implements a simple packet-oriented interface that can be /// used by drivers, daemons, and applications to transmit and receive network packets. /// struct _EFI_IP4_PROTOCOL { diff --git a/MdePkg/Include/Protocol/Ip4Config.h b/MdePkg/Include/Protocol/Ip4Config.h index ece7efb6688c..6f991feb3491 100644 --- a/MdePkg/Include/Protocol/Ip4Config.h +++ b/MdePkg/Include/Protocol/Ip4Config.h @@ -2,16 +2,10 @@ This file provides a definition of the EFI IPv4 Configuration Protocol. -Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: This Protocol is introduced in UEFI Specification 2.0. **/ @@ -31,11 +25,11 @@ typedef struct _EFI_IP4_CONFIG_PROTOCOL EFI_IP4_CONFIG_PROTOCOL; (EFI_VARIABLE_NON_VOLATILE | EFI_VARIABLE_BOOTSERVICE_ACCESS) /// -/// EFI_IP4_IPCONFIG_DATA contains the minimum IPv4 configuration data -/// that is needed to start basic network communication. The StationAddress +/// EFI_IP4_IPCONFIG_DATA contains the minimum IPv4 configuration data +/// that is needed to start basic network communication. The StationAddress /// and SubnetMask must be a valid unicast IP address and subnet mask. -/// If RouteTableSize is not zero, then RouteTable contains a properly -/// formatted routing table for the StationAddress/SubnetMask, with the +/// If RouteTableSize is not zero, then RouteTable contains a properly +/// formatted routing table for the StationAddress/SubnetMask, with the /// last entry in the table being the default route. /// typedef struct { @@ -61,47 +55,47 @@ typedef struct { /** Starts running the configuration policy for the EFI IPv4 Protocol driver. - - The Start() function is called to determine and to begin the platform - configuration policy by the EFI IPv4 Protocol driver. This determination may - be as simple as returning EFI_UNSUPPORTED if there is no EFI IPv4 Protocol - driver configuration policy. It may be as involved as loading some defaults - from nonvolatile storage, downloading dynamic data from a DHCP server, and + + The Start() function is called to determine and to begin the platform + configuration policy by the EFI IPv4 Protocol driver. This determination may + be as simple as returning EFI_UNSUPPORTED if there is no EFI IPv4 Protocol + driver configuration policy. It may be as involved as loading some defaults + from nonvolatile storage, downloading dynamic data from a DHCP server, and checking permissions with a site policy server. - Starting the configuration policy is just the beginning. It may finish almost - instantly or it may take several minutes before it fails to retrieve configuration - information from one or more servers. Once the policy is started, drivers - should use the DoneEvent parameter to determine when the configuration policy - has completed. EFI_IP4_CONFIG_PROTOCOL.GetData() must then be called to + Starting the configuration policy is just the beginning. It may finish almost + instantly or it may take several minutes before it fails to retrieve configuration + information from one or more servers. Once the policy is started, drivers + should use the DoneEvent parameter to determine when the configuration policy + has completed. EFI_IP4_CONFIG_PROTOCOL.GetData() must then be called to determine if the configuration succeeded or failed. - Until the configuration completes successfully, EFI IPv4 Protocol driver instances + Until the configuration completes successfully, EFI IPv4 Protocol driver instances that are attempting to use default configurations must return EFI_NO_MAPPING. - Once the configuration is complete, the EFI IPv4 Configuration Protocol driver - signals DoneEvent. The configuration may need to be updated in the future. - Note that in this case the EFI IPv4 Configuration Protocol driver must signal - ReconfigEvent, and all EFI IPv4 Protocol driver instances that are using default - configurations must return EFI_NO_MAPPING until the configuration policy has + Once the configuration is complete, the EFI IPv4 Configuration Protocol driver + signals DoneEvent. The configuration may need to be updated in the future. + Note that in this case the EFI IPv4 Configuration Protocol driver must signal + ReconfigEvent, and all EFI IPv4 Protocol driver instances that are using default + configurations must return EFI_NO_MAPPING until the configuration policy has been rerun. @param This The pointer to the EFI_IP4_CONFIG_PROTOCOL instance. - @param DoneEvent Event that will be signaled when the EFI IPv4 - Protocol driver configuration policy completes + @param DoneEvent Event that will be signaled when the EFI IPv4 + Protocol driver configuration policy completes execution. This event must be of type EVT_NOTIFY_SIGNAL. - @param ReconfigEvent Event that will be signaled when the EFI IPv4 - Protocol driver configuration needs to be updated. + @param ReconfigEvent Event that will be signaled when the EFI IPv4 + Protocol driver configuration needs to be updated. This event must be of type EVT_NOTIFY_SIGNAL. - - @retval EFI_SUCCESS The configuration policy for the EFI IPv4 Protocol + + @retval EFI_SUCCESS The configuration policy for the EFI IPv4 Protocol driver is now running. @retval EFI_INVALID_PARAMETER One or more of the following parameters is NULL: This DoneEvent ReconfigEvent @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. - @retval EFI_ALREADY_STARTED The configuration policy for the EFI IPv4 Protocol + @retval EFI_ALREADY_STARTED The configuration policy for the EFI IPv4 Protocol driver was already started. @retval EFI_DEVICE_ERROR An unexpected system error or network error occurred. - @retval EFI_UNSUPPORTED This interface does not support the EFI IPv4 Protocol + @retval EFI_UNSUPPORTED This interface does not support the EFI IPv4 Protocol driver configuration. **/ @@ -115,18 +109,18 @@ EFI_STATUS /** Stops running the configuration policy for the EFI IPv4 Protocol driver. - - The Stop() function stops the configuration policy for the EFI IPv4 Protocol driver. + + The Stop() function stops the configuration policy for the EFI IPv4 Protocol driver. All configuration data will be lost after calling Stop(). @param This The pointer to the EFI_IP4_CONFIG_PROTOCOL instance. - @retval EFI_SUCCESS The configuration policy for the EFI IPv4 Protocol + @retval EFI_SUCCESS The configuration policy for the EFI IPv4 Protocol driver has been stopped. @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_NOT_STARTED The configuration policy for the EFI IPv4 Protocol + @retval EFI_NOT_STARTED The configuration policy for the EFI IPv4 Protocol driver was not started. - + **/ typedef EFI_STATUS @@ -137,25 +131,25 @@ EFI_STATUS /** Returns the default configuration data (if any) for the EFI IPv4 Protocol driver. - The GetData() function returns the current configuration data for the EFI IPv4 + The GetData() function returns the current configuration data for the EFI IPv4 Protocol driver after the configuration policy has completed. - + @param This The pointer to the EFI_IP4_CONFIG_PROTOCOL instance. - @param IpConfigDataSize On input, the size of the IpConfigData buffer. - On output, the count of bytes that were written + @param IpConfigDataSize On input, the size of the IpConfigData buffer. + On output, the count of bytes that were written into the IpConfigData buffer. - @param IpConfigData The pointer to the EFI IPv4 Configuration Protocol - driver configuration data structure. - Type EFI_IP4_IPCONFIG_DATA is defined in + @param IpConfigData The pointer to the EFI IPv4 Configuration Protocol + driver configuration data structure. + Type EFI_IP4_IPCONFIG_DATA is defined in "Related Definitions" below. @retval EFI_SUCCESS The EFI IPv4 Protocol driver configuration has been returned. @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_NOT_STARTED The configuration policy for the EFI IPv4 Protocol + @retval EFI_NOT_STARTED The configuration policy for the EFI IPv4 Protocol driver is not running. @retval EFI_NOT_READY EFI IPv4 Protocol driver configuration is still running. @retval EFI_ABORTED EFI IPv4 Protocol driver configuration could not complete. - @retval EFI_BUFFER_TOO_SMALL *IpConfigDataSize is smaller than the configuration + @retval EFI_BUFFER_TOO_SMALL *IpConfigDataSize is smaller than the configuration data buffer or IpConfigData is NULL. **/ @@ -168,8 +162,8 @@ EFI_STATUS ); /// -/// The EFI_IP4_CONFIG_PROTOCOL driver performs platform-dependent and policy-dependent -/// configurations for the EFI IPv4 Protocol driver. +/// The EFI_IP4_CONFIG_PROTOCOL driver performs platform-dependent and policy-dependent +/// configurations for the EFI IPv4 Protocol driver. /// struct _EFI_IP4_CONFIG_PROTOCOL { EFI_IP4_CONFIG_START Start; diff --git a/MdePkg/Include/Protocol/Ip4Config2.h b/MdePkg/Include/Protocol/Ip4Config2.h index 5eed0cbc1342..e1c4a7e3ff63 100644 --- a/MdePkg/Include/Protocol/Ip4Config2.h +++ b/MdePkg/Include/Protocol/Ip4Config2.h @@ -2,14 +2,8 @@ This file provides a definition of the EFI IPv4 Configuration II Protocol. -Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at<BR> -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.5 @@ -33,43 +27,49 @@ typedef struct _EFI_IP4_CONFIG2_PROTOCOL EFI_IP4_CONFIG2_PROTOCOL; /// typedef enum { /// - /// The interface information of the communication device this EFI - /// IPv4 Configuration II Protocol instance manages. This type of - /// data is read only. The corresponding Data is of type + /// The interface information of the communication device this EFI + /// IPv4 Configuration II Protocol instance manages. This type of + /// data is read only. The corresponding Data is of type /// EFI_IP4_CONFIG2_INTERFACE_INFO. /// Ip4Config2DataTypeInterfaceInfo, /// - /// The general configuration policy for the EFI IPv4 network stack - /// running on the communication device this EFI IPv4 - /// Configuration II Protocol instance manages. The policy will - /// affect other configuration settings. The corresponding Data is of + /// The general configuration policy for the EFI IPv4 network stack + /// running on the communication device this EFI IPv4 + /// Configuration II Protocol instance manages. The policy will + /// affect other configuration settings. The corresponding Data is of /// type EFI_IP4_CONFIG2_POLICY. /// Ip4Config2DataTypePolicy, /// - /// The station addresses set manually for the EFI IPv4 network - /// stack. It is only configurable when the policy is - /// Ip4Config2PolicyStatic. The corresponding Data is of - /// type EFI_IP4_CONFIG2_MANUAL_ADDRESS. + /// The station addresses set manually for the EFI IPv4 network + /// stack. It is only configurable when the policy is + /// Ip4Config2PolicyStatic. The corresponding Data is of + /// type EFI_IP4_CONFIG2_MANUAL_ADDRESS. When DataSize + /// is 0 and Data is NULL, the existing configuration is cleared + /// from the EFI IPv4 Configuration II Protocol instance. /// Ip4Config2DataTypeManualAddress, /// - /// The gateway addresses set manually for the EFI IPv4 network - /// stack running on the communication device this EFI IPv4 - /// Configuration II Protocol manages. It is not configurable when - /// the policy is Ip4Config2PolicyDhcp. The gateway - /// addresses must be unicast IPv4 addresses. The corresponding + /// The gateway addresses set manually for the EFI IPv4 network + /// stack running on the communication device this EFI IPv4 + /// Configuration II Protocol manages. It is not configurable when + /// the policy is Ip4Config2PolicyDhcp. The gateway + /// addresses must be unicast IPv4 addresses. The corresponding /// Data is a pointer to an array of EFI_IPv4_ADDRESS instances. + /// When DataSize is 0 and Data is NULL, the existing configuration + /// is cleared from the EFI IPv4 Configuration II Protocol instance. /// Ip4Config2DataTypeGateway, /// - /// The DNS server list for the EFI IPv4 network stack running on - /// the communication device this EFI IPv4 Configuration II - /// Protocol manages. It is not configurable when the policy is - /// Ip4Config2PolicyDhcp. The DNS server addresses must be - /// unicast IPv4 addresses. The corresponding Data is a pointer to - /// an array of EFI_IPv4_ADDRESS instances. + /// The DNS server list for the EFI IPv4 network stack running on + /// the communication device this EFI IPv4 Configuration II + /// Protocol manages. It is not configurable when the policy is + /// Ip4Config2PolicyDhcp. The DNS server addresses must be + /// unicast IPv4 addresses. The corresponding Data is a pointer to + /// an array of EFI_IPv4_ADDRESS instances. When DataSize + /// is 0 and Data is NULL, the existing configuration is cleared + /// from the EFI IPv4 Configuration II Protocol instance. /// Ip4Config2DataTypeDnsServer, Ip4Config2DataTypeMaximum @@ -89,7 +89,7 @@ typedef struct { /// CHAR16 Name[EFI_IP4_CONFIG2_INTERFACE_INFO_NAME_SIZE]; /// - /// The interface type of the network interface. See RFC 1700, + /// The interface type of the network interface. See RFC 1700, /// section "Number Hardware Type". /// UINT8 IfType; @@ -114,8 +114,8 @@ typedef struct { /// UINT32 RouteTableSize; /// - /// The route table of the IPv4 network stack runs on this interface. - /// Set to NULL if RouteTableSize is zero. Type EFI_IP4_ROUTE_TABLE is defined in + /// The route table of the IPv4 network stack runs on this interface. + /// Set to NULL if RouteTableSize is zero. Type EFI_IP4_ROUTE_TABLE is defined in /// EFI_IP4_PROTOCOL.GetModeData(). /// EFI_IP4_ROUTE_TABLE *RouteTable OPTIONAL; @@ -126,17 +126,17 @@ typedef struct { /// typedef enum { /// - /// Under this policy, the Ip4Config2DataTypeManualAddress, - /// Ip4Config2DataTypeGateway and Ip4Config2DataTypeDnsServer configuration - /// data are required to be set manually. The EFI IPv4 Protocol will get all - /// required configuration such as IPv4 address, subnet mask and + /// Under this policy, the Ip4Config2DataTypeManualAddress, + /// Ip4Config2DataTypeGateway and Ip4Config2DataTypeDnsServer configuration + /// data are required to be set manually. The EFI IPv4 Protocol will get all + /// required configuration such as IPv4 address, subnet mask and /// gateway settings from the EFI IPv4 Configuration II protocol. /// Ip4Config2PolicyStatic, /// - /// Under this policy, the Ip4Config2DataTypeManualAddress, - /// Ip4Config2DataTypeGateway and Ip4Config2DataTypeDnsServer configuration data are - /// not allowed to set via SetData(). All of these configurations are retrieved from DHCP + /// Under this policy, the Ip4Config2DataTypeManualAddress, + /// Ip4Config2DataTypeGateway and Ip4Config2DataTypeDnsServer configuration data are + /// not allowed to set via SetData(). All of these configurations are retrieved from DHCP /// server or other auto-configuration mechanism. /// Ip4Config2PolicyDhcp, @@ -147,59 +147,58 @@ typedef enum { /// EFI_IP4_CONFIG2_MANUAL_ADDRESS /// typedef struct { - /// + /// /// The IPv4 unicast address. /// EFI_IPv4_ADDRESS Address; /// - /// The subnet mask. + /// The subnet mask. /// EFI_IPv4_ADDRESS SubnetMask; } EFI_IP4_CONFIG2_MANUAL_ADDRESS; /** - Set the configuration for the EFI IPv4 network stack running on the communication device this EFI + Set the configuration for the EFI IPv4 network stack running on the communication device this EFI IPv4 Configuration II Protocol instance manages. - This function is used to set the configuration data of type DataType for the EFI IPv4 network stack + This function is used to set the configuration data of type DataType for the EFI IPv4 network stack running on the communication device this EFI IPv4 Configuration II Protocol instance manages. The successfully configured data is valid after system reset or power-off. - The DataSize is used to calculate the count of structure instances in the Data for some + The DataSize is used to calculate the count of structure instances in the Data for some DataType that multiple structure instances are allowed. - This function is always non-blocking. When setting some typeof configuration data, an - asynchronous process is invoked to check the correctness of the data, such as doing address conflict - detection on the manually set local IPv4 address. EFI_NOT_READY is returned immediately to - indicate that such an asynchronous process is invoked and the process is not finished yet. The caller + This function is always non-blocking. When setting some typeof configuration data, an + asynchronous process is invoked to check the correctness of the data, such as doing address conflict + detection on the manually set local IPv4 address. EFI_NOT_READY is returned immediately to + indicate that such an asynchronous process is invoked and the process is not finished yet. The caller willing to get the result of the asynchronous process is required to call RegisterDataNotify() - to register an event on the specified configuration data. Once the event is signaled, the caller can call - GetData()to get back the configuration data in order to know the result. For other types of - configuration data that do not require an asynchronous configuration process, the result of the - operation is immediately returned. + to register an event on the specified configuration data. Once the event is signaled, the caller can call + GetData()to get back the configuration data in order to know the result. For other types of + configuration data that do not require an asynchronous configuration process, the result of the + operation is immediately returned. - @param[in] This Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance. + @param[in] This Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance. @param[in] DataType The type of data to set. @param[in] DataSize Size of the buffer pointed to by Data in bytes. - @param[in] Data The data buffer to set. The type ofthe data buffer is associated - with the DataType. + @param[in] Data The data buffer to set. The type ofthe data buffer is associated + with the DataType. - @retval EFI_SUCCESS The specified configuration data for the EFI IPv4 network stack is set + @retval EFI_SUCCESS The specified configuration data for the EFI IPv4 network stack is set successfully. @retval EFI_INVALID_PARAMETER One or more of the following are TRUE: This is NULL. - Data is NULL. - One or more fields in Data do not match the requirement of the data type - indicated by DataType. - @retval EFI_WRITE_PROTECTED The specified configuration data is read-only or the specified configuration + One or more fields in Data and DataSize do not match the + requirement of the data type indicated by DataType. + @retval EFI_WRITE_PROTECTED The specified configuration data is read-only or the specified configuration data can not be set under the current policy. @retval EFI_ACCESS_DENIED Another set operation on the specified configuration data is already in process. - @retval EFI_NOT_READY An asynchronous process is invoked to set the specified configuration data and + @retval EFI_NOT_READY An asynchronous process is invoked to set the specified configuration data and the process is not finished yet. - @retval EFI_BAD_BUFFER_SIZE The DataSize does not match the size of the type indicated by DataType. + @retval EFI_BAD_BUFFER_SIZE The DataSize does not match the size of the type indicated by DataType. @retval EFI_UNSUPPORTED This DataType is not supported. @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. @retval EFI_DEVICE_ERROR An unexpected system error or network error occurred. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_IP4_CONFIG2_SET_DATA) ( IN EFI_IP4_CONFIG2_PROTOCOL *This, @@ -209,35 +208,35 @@ EFI_STATUS ); /** - Get the configuration data for the EFI IPv4 network stack running on the communication device this + Get the configuration data for the EFI IPv4 network stack running on the communication device this EFI IPv4 Configuration II Protocol instance manages. - This function returns the configuration data of type DataType for the EFI IPv4 network stack + This function returns the configuration data of type DataType for the EFI IPv4 network stack running on the communication device this EFI IPv4 Configuration II Protocol instance manages. - The caller is responsible for allocating the buffer usedto return the specified configuration data and + The caller is responsible for allocating the buffer usedto return the specified configuration data and the required size will be returned to the caller if the size of the buffer is too small. - EFI_NOT_READY is returned if the specified configuration data is not ready due to an already in - progress asynchronous configuration process. The caller can call RegisterDataNotify() to - register an event on the specified configuration data. Once the asynchronous configuration process is - finished, the event will be signaled and a subsequent GetData() call will return the specified + EFI_NOT_READY is returned if the specified configuration data is not ready due to an already in + progress asynchronous configuration process. The caller can call RegisterDataNotify() to + register an event on the specified configuration data. Once the asynchronous configuration process is + finished, the event will be signaled and a subsequent GetData() call will return the specified configuration data. - @param[in] This Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance. + @param[in] This Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance. @param[in] DataType The type of data to get. - @param[out] DataSize On input, in bytes, the size of Data. On output, in bytes, the size - of buffer required to store the specified configuration data. - @param[in] Data The data buffer in which the configuration data is returned. The - type of the data buffer is associated with the DataType. Ignored - if DataSize is 0. + @param[out] DataSize On input, in bytes, the size of Data. On output, in bytes, the size + of buffer required to store the specified configuration data. + @param[in] Data The data buffer in which the configuration data is returned. The + type of the data buffer is associated with the DataType. Ignored + if DataSize is 0. @retval EFI_SUCCESS The specified configuration data is got successfully. @retval EFI_INVALID_PARAMETER One or more of the followings are TRUE: This is NULL. DataSize is NULL. Data is NULL if *DataSizeis not zero. - @retval EFI_BUFFER_TOO_SMALL The size of Data is too small for the specified configuration data + @retval EFI_BUFFER_TOO_SMALL The size of Data is too small for the specified configuration data and the required size is returned in DataSize. - @retval EFI_NOT_READY The specified configuration data is not ready due to an already in + @retval EFI_NOT_READY The specified configuration data is not ready due to an already in progress asynchronous configuration process. @retval EFI_NOT_FOUND The specified configuration data is not found. **/ @@ -251,19 +250,19 @@ EFI_STATUS ); /** - Register an event that is to be signaled whenever a configuration process on the specified + Register an event that is to be signaled whenever a configuration process on the specified configuration data is done. - This function registers an event that is to be signaled whenever a configuration process on the + This function registers an event that is to be signaled whenever a configuration process on the specified configuration data is done. An event can be registered for different DataType - simultaneously and the caller is responsible for determining which type of configuration data causes + simultaneously and the caller is responsible for determining which type of configuration data causes the signaling of the event in such case. - @param[in] This Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance. + @param[in] This Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance. @param[in] DataType The type of data to unregister the event for. @param[in] Event The event to register. - @retval EFI_SUCCESS The notification event for the specified configuration data is + @retval EFI_SUCCESS The notification event for the specified configuration data is registered. @retval EFI_INVALID_PARAMETER This is NULL or Event is NULL. @retval EFI_UNSUPPORTED The configuration data type specified by DataType is not supported. @@ -283,7 +282,7 @@ EFI_STATUS This function removes a previously registeredevent for the specified configuration data. - @param[in] This Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance. + @param[in] This Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance. @param[in] DataType The type of data to remove the previously registered event for. @param[in] Event The event to unregister. @@ -300,9 +299,9 @@ EFI_STATUS ); /// -/// The EFI_IP4_CONFIG2_PROTOCOL is designed to be the central repository for the common +/// The EFI_IP4_CONFIG2_PROTOCOL is designed to be the central repository for the common /// configurations and the administrator configurable settings for the EFI IPv4 network stack. -/// An EFI IPv4 Configuration II Protocol instance will be installed on each communication device that +/// An EFI IPv4 Configuration II Protocol instance will be installed on each communication device that /// the EFI IPv4 network stack runs on. /// struct _EFI_IP4_CONFIG2_PROTOCOL { diff --git a/MdePkg/Include/Protocol/Ip6.h b/MdePkg/Include/Protocol/Ip6.h index 1598f8250a87..c82f36501d22 100644 --- a/MdePkg/Include/Protocol/Ip6.h +++ b/MdePkg/Include/Protocol/Ip6.h @@ -11,13 +11,7 @@ Message Protocol (ICMPv6). Copyright (c) 2008 - 2014, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.2 diff --git a/MdePkg/Include/Protocol/Ip6Config.h b/MdePkg/Include/Protocol/Ip6Config.h index dd4facb897c5..fe93ba24e8bc 100644 --- a/MdePkg/Include/Protocol/Ip6Config.h +++ b/MdePkg/Include/Protocol/Ip6Config.h @@ -2,14 +2,8 @@ This file provides a definition of the EFI IPv6 Configuration Protocol. -Copyright (c) 2008 - 2011, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at<BR> -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2008 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef __EFI_IP6CONFIG_PROTOCOL_H__ @@ -27,65 +21,71 @@ typedef struct _EFI_IP6_CONFIG_PROTOCOL EFI_IP6_CONFIG_PROTOCOL; /// /// EFI_IP6_CONFIG_DATA_TYPE /// -typedef enum { - /// - /// The interface information of the communication - /// device this EFI IPv6 Configuration Protocol instance manages. - /// This type of data is read only.The corresponding Data is of type +typedef enum { + /// + /// The interface information of the communication + /// device this EFI IPv6 Configuration Protocol instance manages. + /// This type of data is read only.The corresponding Data is of type /// EFI_IP6_CONFIG_INTERFACE_INFO. - /// + /// Ip6ConfigDataTypeInterfaceInfo, - /// - /// The alternative interface ID for the - /// communication device this EFI IPv6 Configuration Protocol - /// instance manages if the link local IPv6 address generated from - /// the interfaced ID based on the default source the EFI IPv6 - /// Protocol uses is a duplicate address. The length of the interface - /// ID is 64 bit. The corresponding Data is of type + /// + /// The alternative interface ID for the + /// communication device this EFI IPv6 Configuration Protocol + /// instance manages if the link local IPv6 address generated from + /// the interfaced ID based on the default source the EFI IPv6 + /// Protocol uses is a duplicate address. The length of the interface + /// ID is 64 bit. The corresponding Data is of type /// EFI_IP6_CONFIG_INTERFACE_ID. - /// + /// Ip6ConfigDataTypeAltInterfaceId, - /// - /// The general configuration policy for the EFI IPv6 network - /// stack running on the communication device this EFI IPv6 - /// Configuration Protocol instance manages. The policy will affect - /// other configuration settings. The corresponding Data is of type + /// + /// The general configuration policy for the EFI IPv6 network + /// stack running on the communication device this EFI IPv6 + /// Configuration Protocol instance manages. The policy will affect + /// other configuration settings. The corresponding Data is of type /// EFI_IP6_CONFIG_POLICY. /// Ip6ConfigDataTypePolicy, - /// - /// The number of consecutive - /// Neighbor Solicitation messages sent while performing Duplicate - /// Address Detection on a tentative address. A value of zero - /// indicates that Duplicate Address Detection will not be performed - /// on tentative addresses. The corresponding Data is of type + /// + /// The number of consecutive + /// Neighbor Solicitation messages sent while performing Duplicate + /// Address Detection on a tentative address. A value of zero + /// indicates that Duplicate Address Detection will not be performed + /// on tentative addresses. The corresponding Data is of type /// EFI_IP6_CONFIG_DUP_ADDR_DETECT_TRANSMITS. - /// + /// Ip6ConfigDataTypeDupAddrDetectTransmits, - /// - /// The station addresses set manually for the EFI - /// IPv6 network stack. It is only configurable when the policy is - /// Ip6ConfigPolicyManual. The corresponding Data is a - /// pointer to an array of EFI_IPv6_ADDRESS instances. - /// + /// + /// The station addresses set manually for the EFI + /// IPv6 network stack. It is only configurable when the policy is + /// Ip6ConfigPolicyManual. The corresponding Data is a + /// pointer to an array of EFI_IPv6_ADDRESS instances. When + /// DataSize is 0 and Data is NULL, the existing configuration + /// is cleared from the EFI IPv6 Configuration Protocol instance. + /// Ip6ConfigDataTypeManualAddress, - /// - /// The gateway addresses set manually for the EFI IPv6 - /// network stack running on the communication device this EFI - /// IPv6 Configuration Protocol manages. It is not configurable when - /// the policy is Ip6ConfigPolicyAutomatic. The gateway - /// addresses must be unicast IPv6 addresses. The corresponding + /// + /// The gateway addresses set manually for the EFI IPv6 + /// network stack running on the communication device this EFI + /// IPv6 Configuration Protocol manages. It is not configurable when + /// the policy is Ip6ConfigPolicyAutomatic. The gateway + /// addresses must be unicast IPv6 addresses. The corresponding /// Data is a pointer to an array of EFI_IPv6_ADDRESS instances. - /// + /// When DataSize is 0 and Data is NULL, the existing configuration + /// is cleared from the EFI IPv6 Configuration Protocol instance. + /// Ip6ConfigDataTypeGateway, - /// - /// The DNS server list for the EFI IPv6 network stack - /// running on the communication device this EFI IPv6 - /// Configuration Protocol manages. It is not configurable when the - /// policy is Ip6ConfigPolicyAutomatic.The DNS server - /// addresses must be unicast IPv6 addresses. The corresponding + /// + /// The DNS server list for the EFI IPv6 network stack + /// running on the communication device this EFI IPv6 + /// Configuration Protocol manages. It is not configurable when the + /// policy is Ip6ConfigPolicyAutomatic.The DNS server + /// addresses must be unicast IPv6 addresses. The corresponding /// Data is a pointer to an array of EFI_IPv6_ADDRESS instances. - /// + /// When DataSize is 0 and Data is NULL, the existing configuration + /// is cleared from the EFI IPv6 Configuration Protocol instance. + /// Ip6ConfigDataTypeDnsServer, /// /// The number of this enumeration memebers. @@ -95,7 +95,7 @@ typedef enum { /// /// EFI_IP6_CONFIG_INTERFACE_INFO -/// describes the operational state of the interface this +/// describes the operational state of the interface this /// EFI IPv6 Configuration Protocol instance manages. /// typedef struct { @@ -103,37 +103,37 @@ typedef struct { /// The name of the interface. It is a NULL-terminated string. /// CHAR16 Name[32]; - /// + /// /// The interface type of the network interface. - /// + /// UINT8 IfType; - /// + /// /// The size, in bytes, of the network interface's hardware address. - /// + /// UINT32 HwAddressSize; - /// + /// /// The hardware address for the network interface. - /// + /// EFI_MAC_ADDRESS HwAddress; - /// + /// /// Number of EFI_IP6_ADDRESS_INFO structures pointed to by AddressInfo. - /// + /// UINT32 AddressInfoCount; - /// - /// Pointer to an array of EFI_IP6_ADDRESS_INFO instances - /// which contain the local IPv6 addresses and the corresponding - /// prefix length information. Set to NULL if AddressInfoCount + /// + /// Pointer to an array of EFI_IP6_ADDRESS_INFO instances + /// which contain the local IPv6 addresses and the corresponding + /// prefix length information. Set to NULL if AddressInfoCount /// is zero. - /// + /// EFI_IP6_ADDRESS_INFO *AddressInfo; - /// + /// /// Number of route table entries in the following RouteTable. - /// + /// UINT32 RouteCount; - /// - /// The route table of the IPv6 network stack runs on this interface. - /// Set to NULL if RouteCount is zero. - /// + /// + /// The route table of the IPv6 network stack runs on this interface. + /// Set to NULL if RouteCount is zero. + /// EFI_IP6_ROUTE_TABLE *RouteTable; } EFI_IP6_CONFIG_INTERFACE_INFO; @@ -147,42 +147,42 @@ typedef struct { /// /// EFI_IP6_CONFIG_POLICY -/// defines the general configuration policy the EFI IPv6 +/// defines the general configuration policy the EFI IPv6 /// Configuration Protocol supports. /// typedef enum { /// - /// Under this policy, the IpI6ConfigDataTypeManualAddress, + /// Under this policy, the IpI6ConfigDataTypeManualAddress, /// Ip6ConfigDataTypeGateway and Ip6ConfigDataTypeDnsServer - /// configuration data are required to be set manually. + /// configuration data are required to be set manually. /// The EFI IPv6 Protocol will get all required configuration /// such as address, prefix and gateway settings from the EFI /// IPv6 Configuration protocol. /// - Ip6ConfigPolicyManual, - /// - /// Under this policy, the IpI6ConfigDataTypeManualAddress, + Ip6ConfigPolicyManual, + /// + /// Under this policy, the IpI6ConfigDataTypeManualAddress, /// Ip6ConfigDataTypeGateway and Ip6ConfigDataTypeDnsServer /// configuration data are not allowed to set via SetData(). /// All of these configurations are retrieved from some auto - /// configuration mechanism. - /// The EFI IPv6 Protocol will use the IPv6 stateless address - /// autoconfiguration mechanism and/or the IPv6 stateful address - /// autoconfiguration mechanism described in the related RFCs to + /// configuration mechanism. + /// The EFI IPv6 Protocol will use the IPv6 stateless address + /// autoconfiguration mechanism and/or the IPv6 stateful address + /// autoconfiguration mechanism described in the related RFCs to /// get address and other configuration information - /// + /// Ip6ConfigPolicyAutomatic } EFI_IP6_CONFIG_POLICY; /// /// EFI_IP6_CONFIG_DUP_ADDR_DETECT_TRANSMITS /// describes the number of consecutive Neighbor Solicitation messages sent -/// while performing Duplicate Address Detection on a tentative address. +/// while performing Duplicate Address Detection on a tentative address. /// The default value for a newly detected communication device is 1. /// typedef struct { UINT32 DupAddrDetectTransmits; ///< The number of consecutive Neighbor Solicitation messages sent. -} EFI_IP6_CONFIG_DUP_ADDR_DETECT_TRANSMITS; +} EFI_IP6_CONFIG_DUP_ADDR_DETECT_TRANSMITS; /// /// EFI_IP6_CONFIG_MANUAL_ADDRESS @@ -199,50 +199,49 @@ typedef struct { /** Set the configuration for the EFI IPv6 network stack running on the communication device this EFI IPv6 Configuration Protocol instance manages. - - This function is used to set the configuration data of type DataType for the EFI + + This function is used to set the configuration data of type DataType for the EFI IPv6 network stack running on the communication device this EFI IPv6 Configuration Protocol instance manages. - The DataSize is used to calculate the count of structure instances in the Data for + The DataSize is used to calculate the count of structure instances in the Data for some DataType that multiple structure instances are allowed. - + This function is always non-blocking. When setting some type of configuration data, - an asynchronous process is invoked to check the correctness of the data, such as - doing Duplicate Address Detection on the manually set local IPv6 addresses. + an asynchronous process is invoked to check the correctness of the data, such as + doing Duplicate Address Detection on the manually set local IPv6 addresses. EFI_NOT_READY is returned immediately to indicate that such an asynchronous process is invoked and the process is not finished yet. The caller willing to get the result of the asynchronous process is required to call RegisterDataNotify() to register an - event on the specified configuration data. Once the event is signaled, the caller + event on the specified configuration data. Once the event is signaled, the caller can call GetData() to get back the configuration data in order to know the result. - For other types of configuration data that do not require an asynchronous configuration + For other types of configuration data that do not require an asynchronous configuration process, the result of the operation is immediately returned. @param[in] This Pointer to the EFI_IP6_CONFIG_PROTOCOL instance. - @param[in] DataType The type of data to set. + @param[in] DataType The type of data to set. @param[in] DataSize Size of the buffer pointed to by Data in bytes. @param[in] Data The data buffer to set. The type of the data buffer is associated with the DataType. - - @retval EFI_SUCCESS The specified configuration data for the EFI IPv6 + + @retval EFI_SUCCESS The specified configuration data for the EFI IPv6 network stack is set successfully. @retval EFI_INVALID_PARAMETER One or more of the following are TRUE: - This is NULL. - - Data is NULL. - - One or more fields in Data do not match the requirement of the - data type indicated by DataType. - @retval EFI_WRITE_PROTECTED The specified configuration data is read-only or the specified + - One or more fields in Data and DataSize do not match the + requirement of the data type indicated by DataType. + @retval EFI_WRITE_PROTECTED The specified configuration data is read-only or the specified configuration data can not be set under the current policy - @retval EFI_ACCESS_DENIED Another set operation on the specified configuration + @retval EFI_ACCESS_DENIED Another set operation on the specified configuration data is already in process. @retval EFI_NOT_READY An asynchronous process is invoked to set the specified configuration data and the process is not finished yet. - @retval EFI_BAD_BUFFER_SIZE The DataSize does not match the size of the type + @retval EFI_BAD_BUFFER_SIZE The DataSize does not match the size of the type indicated by DataType. @retval EFI_UNSUPPORTED This DataType is not supported. @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. @retval EFI_DEVICE_ERROR An unexpected system error or network error occurred. - + **/ typedef EFI_STATUS @@ -256,39 +255,39 @@ EFI_STATUS /** Get the configuration data for the EFI IPv6 network stack running on the communication device this EFI IPv6 Configuration Protocol instance manages. - + This function returns the configuration data of type DataType for the EFI IPv6 network stack running on the communication device this EFI IPv6 Configuration Protocol instance manages. The caller is responsible for allocating the buffer used to return the specified configuration data and the required size will be returned to the caller if the size of - the buffer is too small. - - EFI_NOT_READY is returned if the specified configuration data is not ready due to an + the buffer is too small. + + EFI_NOT_READY is returned if the specified configuration data is not ready due to an already in progress asynchronous configuration process. The caller can call RegisterDataNotify() to register an event on the specified configuration data. Once the asynchronous configuration - process is finished, the event will be signaled and a subsequent GetData() call will return + process is finished, the event will be signaled and a subsequent GetData() call will return the specified configuration data. @param[in] This Pointer to the EFI_IP6_CONFIG_PROTOCOL instance. - @param[in] DataType The type of data to get. - @param[in,out] DataSize On input, in bytes, the size of Data. On output, in bytes, the + @param[in] DataType The type of data to get. + @param[in,out] DataSize On input, in bytes, the size of Data. On output, in bytes, the size of buffer required to store the specified configuration data. - @param[in] Data The data buffer in which the configuration data is returned. The + @param[in] Data The data buffer in which the configuration data is returned. The type of the data buffer is associated with the DataType. - + @retval EFI_SUCCESS The specified configuration data is got successfully. @retval EFI_INVALID_PARAMETER One or more of the followings are TRUE: - This is NULL. - DataSize is NULL. - Data is NULL if *DataSize is not zero. - @retval EFI_BUFFER_TOO_SMALL The size of Data is too small for the specified configuration data + @retval EFI_BUFFER_TOO_SMALL The size of Data is too small for the specified configuration data and the required size is returned in DataSize. - @retval EFI_NOT_READY The specified configuration data is not ready due to an already in + @retval EFI_NOT_READY The specified configuration data is not ready due to an already in progress asynchronous configuration process. @retval EFI_NOT_FOUND The specified configuration data is not found. - + **/ typedef EFI_STATUS @@ -302,24 +301,24 @@ EFI_STATUS /** Register an event that is to be signaled whenever a configuration process on the specified configuration data is done. - + This function registers an event that is to be signaled whenever a configuration process on the specified configuration data is done. An event can be registered for different DataType simultaneously and the caller is responsible for determining which type of configuration data causes the signaling of the event in such case. @param[in] This Pointer to the EFI_IP6_CONFIG_PROTOCOL instance. - @param[in] DataType The type of data to unregister the event for. - @param[in] Event The event to register. - - @retval EFI_SUCCESS The notification event for the specified configuration data is + @param[in] DataType The type of data to unregister the event for. + @param[in] Event The event to register. + + @retval EFI_SUCCESS The notification event for the specified configuration data is registered. @retval EFI_INVALID_PARAMETER This is NULL or Event is NULL. - @retval EFI_UNSUPPORTED The configuration data type specified by DataType is not + @retval EFI_UNSUPPORTED The configuration data type specified by DataType is not supported. @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. @retval EFI_ACCESS_DENIED The Event is already registered for the DataType. - + **/ typedef EFI_STATUS @@ -331,18 +330,18 @@ EFI_STATUS /** Remove a previously registered event for the specified configuration data. - + This function removes a previously registered event for the specified configuration data. @param[in] This Pointer to the EFI_IP6_CONFIG_PROTOCOL instance. - @param[in] DataType The type of data to remove the previously registered event for. + @param[in] DataType The type of data to remove the previously registered event for. @param[in] Event The event to unregister. - + @retval EFI_SUCCESS The event registered for the specified configuration data is removed. @retval EFI_INVALID_PARAMETER This is NULL or Event is NULL. - @retval EFI_NOT_FOUND The Event has not been registered for the specified + @retval EFI_NOT_FOUND The Event has not been registered for the specified DataType. - + **/ typedef EFI_STATUS diff --git a/MdePkg/Include/Protocol/IpSec.h b/MdePkg/Include/Protocol/IpSec.h index a22326309ca0..b51936c49068 100644 --- a/MdePkg/Include/Protocol/IpSec.h +++ b/MdePkg/Include/Protocol/IpSec.h @@ -1,25 +1,19 @@ /** @file EFI IPSEC Protocol Definition The EFI_IPSEC_PROTOCOL is used to abstract the ability to deal with the individual - packets sent and received by the host and provide packet-level security for IP + packets sent and received by the host and provide packet-level security for IP datagram. The EFI_IPSEC2_PROTOCOL is used to abstract the ability to deal with the individual - packets sent and received by the host and provide packet-level security for IP - datagram. In addition, it supports the Option (extension header) processing in - IPsec which doesn't support in EFI_IPSEC_PROTOCOL. It is also recommended to - use EFI_IPSEC2_PROTOCOL instead of EFI_IPSEC_PROTOCOL especially for IPsec Tunnel + packets sent and received by the host and provide packet-level security for IP + datagram. In addition, it supports the Option (extension header) processing in + IPsec which doesn't support in EFI_IPSEC_PROTOCOL. It is also recommended to + use EFI_IPSEC2_PROTOCOL instead of EFI_IPSEC_PROTOCOL especially for IPsec Tunnel Mode. - Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: + @par Revision Reference: The EFI_IPSEC2_PROTOCOL is introduced in UEFI Specification 2.3D. **/ @@ -43,34 +37,34 @@ typedef struct _EFI_IPSEC_PROTOCOL EFI_IPSEC_PROTOCOL; typedef struct _EFI_IPSEC2_PROTOCOL EFI_IPSEC2_PROTOCOL; /// -/// EFI_IPSEC_FRAGMENT_DATA +/// EFI_IPSEC_FRAGMENT_DATA /// defines the instances of packet fragments. /// -typedef struct _EFI_IPSEC_FRAGMENT_DATA { +typedef struct _EFI_IPSEC_FRAGMENT_DATA { UINT32 FragmentLength; VOID *FragmentBuffer; -} EFI_IPSEC_FRAGMENT_DATA; +} EFI_IPSEC_FRAGMENT_DATA; /** - Handles IPsec packet processing for inbound and outbound IP packets. + Handles IPsec packet processing for inbound and outbound IP packets. The EFI_IPSEC_PROCESS process routine handles each inbound or outbound packet. - The behavior is that it can perform one of the following actions: - bypass the packet, discard the packet, or protect the packet. + The behavior is that it can perform one of the following actions: + bypass the packet, discard the packet, or protect the packet. @param[in] This Pointer to the EFI_IPSEC_PROTOCOL instance. @param[in] NicHandle Instance of the network interface. @param[in] IpVer IPV4 or IPV6. @param[in, out] IpHead Pointer to the IP Header. @param[in] LastHead The protocol of the next layer to be processed by IPsec. - @param[in] OptionsBuffer Pointer to the options buffer. + @param[in] OptionsBuffer Pointer to the options buffer. @param[in] OptionsLength Length of the options buffer. - @param[in, out] FragmentTable Pointer to a list of fragments. + @param[in, out] FragmentTable Pointer to a list of fragments. @param[in] FragmentCount Number of fragments. @param[in] TrafficDirection Traffic direction. @param[out] RecycleSignal Event for recycling of resources. - + @retval EFI_SUCCESS The packet was bypassed and all buffers remain the same. @retval EFI_SUCCESS The packet was protected. @retval EFI_ACCESS_DENIED The packet was discarded. @@ -93,9 +87,9 @@ EFI_STATUS ); /// -/// EFI_IPSEC_PROTOCOL +/// EFI_IPSEC_PROTOCOL /// provides the ability for securing IP communications by authenticating -/// and/or encrypting each IP packet in a data stream. +/// and/or encrypting each IP packet in a data stream. // EFI_IPSEC_PROTOCOL can be consumed by both the IPv4 and IPv6 stack. // A user can employ this protocol for IPsec package handling in both IPv4 // and IPv6 environment. @@ -107,72 +101,72 @@ struct _EFI_IPSEC_PROTOCOL { }; /** - Handles IPsec processing for both inbound and outbound IP packets. Compare with - Process() in EFI_IPSEC_PROTOCOL, this interface has the capability to process - Option(Extension Header). + Handles IPsec processing for both inbound and outbound IP packets. Compare with + Process() in EFI_IPSEC_PROTOCOL, this interface has the capability to process + Option(Extension Header). The EFI_IPSEC2_PROCESS process routine handles each inbound or outbound packet. - The behavior is that it can perform one of the following actions: - bypass the packet, discard the packet, or protect the packet. + The behavior is that it can perform one of the following actions: + bypass the packet, discard the packet, or protect the packet. @param[in] This Pointer to the EFI_IPSEC2_PROTOCOL instance. - @param[in] NicHandle Instance of the network interface. + @param[in] NicHandle Instance of the network interface. @param[in] IpVer IP version.IPv4 or IPv6. - @param[in, out] IpHead Pointer to the IP Header it is either + @param[in, out] IpHead Pointer to the IP Header it is either the EFI_IP4_HEADER or EFI_IP6_HEADER. - On input, it contains the IP header. - On output, 1) in tunnel mode and the - traffic direction is inbound, the buffer - will be reset to zero by IPsec; 2) in - tunnel mode and the traffic direction - is outbound, the buffer will reset to - be the tunnel IP header.3) in transport - mode, the related fielders (like payload - length, Next header) in IP header will + On input, it contains the IP header. + On output, 1) in tunnel mode and the + traffic direction is inbound, the buffer + will be reset to zero by IPsec; 2) in + tunnel mode and the traffic direction + is outbound, the buffer will reset to + be the tunnel IP header.3) in transport + mode, the related fielders (like payload + length, Next header) in IP header will be modified according to the condition. @param[in, out] LastHead For IP4, it is the next protocol in IP - header. For IP6 it is the Next Header + header. For IP6 it is the Next Header of the last extension header. - @param[in, out] OptionsBuffer On input, it contains the options - (extensions header) to be processed by + @param[in, out] OptionsBuffer On input, it contains the options + (extensions header) to be processed by IPsec. On output, 1) in tunnel mode and - the traffic direction is outbound, it - will be set to NULL, and that means this - contents was wrapped after inner header - and should not be concatenated after - tunnel header again; 2) in transport - mode and the traffic direction is inbound, - if there are IP options (extension headers) - protected by IPsec, IPsec will concatenate - the those options after the input options - (extension headers); 3) on other situations, - the output of contents of OptionsBuffer - might be same with input's. The caller - should take the responsibility to free + the traffic direction is outbound, it + will be set to NULL, and that means this + contents was wrapped after inner header + and should not be concatenated after + tunnel header again; 2) in transport + mode and the traffic direction is inbound, + if there are IP options (extension headers) + protected by IPsec, IPsec will concatenate + the those options after the input options + (extension headers); 3) on other situations, + the output of contents of OptionsBuffer + might be same with input's. The caller + should take the responsibility to free the buffer both on input and on output. - @param[in, out] OptionsLength On input, the input length of the options - buffer. On output, the output length of + @param[in, out] OptionsLength On input, the input length of the options + buffer. On output, the output length of the options buffer. - @param[in, out] FragmentTable Pointer to a list of fragments. On input, - these fragments contain the IP payload. - On output, 1) in tunnel mode and the traffic - direction is inbound, the fragments contain - the whole IP payload which is from the - IP inner header to the last byte of the - packet; 2) in tunnel mode and the traffic - direction is the outbound, the fragments - contains the whole encapsulated payload - which encapsulates the whole IP payload - between the encapsulated header and - encapsulated trailer fields. 3) in transport - mode and the traffic direction is inbound, - the fragments contains the IP payload - which is from the next layer protocol to - the last byte of the packet; 4) in transport - mode and the traffic direction is outbound, - the fragments contains the whole encapsulated - payload which encapsulates the next layer - protocol information between the encapsulated + @param[in, out] FragmentTable Pointer to a list of fragments. On input, + these fragments contain the IP payload. + On output, 1) in tunnel mode and the traffic + direction is inbound, the fragments contain + the whole IP payload which is from the + IP inner header to the last byte of the + packet; 2) in tunnel mode and the traffic + direction is the outbound, the fragments + contains the whole encapsulated payload + which encapsulates the whole IP payload + between the encapsulated header and + encapsulated trailer fields. 3) in transport + mode and the traffic direction is inbound, + the fragments contains the IP payload + which is from the next layer protocol to + the last byte of the packet; 4) in transport + mode and the traffic direction is outbound, + the fragments contains the whole encapsulated + payload which encapsulates the next layer + protocol information between the encapsulated header and encapsulated trailer fields. @param[in, out] FragmentCount Number of fragments. @param[in] TrafficDirection Traffic direction. @@ -180,7 +174,7 @@ struct _EFI_IPSEC_PROTOCOL { @retval EFI_SUCCESS The packet was processed by IPsec successfully. @retval EFI_ACCESS_DENIED The packet was discarded. - @retval EFI_NOT_READY The IKE negotiation is invoked and the packet + @retval EFI_NOT_READY The IKE negotiation is invoked and the packet was discarded. @retval EFI_INVALID_PARAMETER One or more of following are TRUE: If OptionsBuffer is NULL; @@ -189,23 +183,23 @@ struct _EFI_IPSEC_PROTOCOL { If FragmentCount is NULL. **/ -typedef +typedef EFI_STATUS -(EFIAPI *EFI_IPSEC_PROCESSEXT) ( - IN EFI_IPSEC2_PROTOCOL *This, - IN EFI_HANDLE NicHandle, - IN UINT8 IpVer, - IN OUT VOID *IpHead, - IN OUT UINT8 *LastHead, - IN OUT VOID **OptionsBuffer, - IN OUT UINT32 *OptionsLength, - IN OUT EFI_IPSEC_FRAGMENT_DATA **FragmentTable, - IN OUT UINT32 *FragmentCount, - IN EFI_IPSEC_TRAFFIC_DIR TrafficDirection, +(EFIAPI *EFI_IPSEC_PROCESSEXT) ( + IN EFI_IPSEC2_PROTOCOL *This, + IN EFI_HANDLE NicHandle, + IN UINT8 IpVer, + IN OUT VOID *IpHead, + IN OUT UINT8 *LastHead, + IN OUT VOID **OptionsBuffer, + IN OUT UINT32 *OptionsLength, + IN OUT EFI_IPSEC_FRAGMENT_DATA **FragmentTable, + IN OUT UINT32 *FragmentCount, + IN EFI_IPSEC_TRAFFIC_DIR TrafficDirection, OUT EFI_EVENT *RecycleSignal ); -/// +/// /// EFI_IPSEC2_PROTOCOL /// supports the Option (extension header) processing in IPsec which doesn't support /// in EFI_IPSEC_PROTOCOL. It is also recommended to use EFI_IPSEC2_PROTOCOL instead @@ -213,10 +207,10 @@ EFI_STATUS /// provides the ability for securing IP communications by authenticating and/or /// encrypting each IP packet in a data stream. /// -struct _EFI_IPSEC2_PROTOCOL { +struct _EFI_IPSEC2_PROTOCOL { EFI_IPSEC_PROCESSEXT ProcessExt; -EFI_EVENT DisabledEvent; -BOOLEAN DisabledFlag; +EFI_EVENT DisabledEvent; +BOOLEAN DisabledFlag; }; extern EFI_GUID gEfiIpSecProtocolGuid; diff --git a/MdePkg/Include/Protocol/IpSecConfig.h b/MdePkg/Include/Protocol/IpSecConfig.h index 4efc2e3d747a..78a201d4a47b 100644 --- a/MdePkg/Include/Protocol/IpSecConfig.h +++ b/MdePkg/Include/Protocol/IpSecConfig.h @@ -1,18 +1,12 @@ /** @file EFI IPsec Configuration Protocol Definition - The EFI_IPSEC_CONFIG_PROTOCOL provides the mechanism to set and retrieve security and + The EFI_IPSEC_CONFIG_PROTOCOL provides the mechanism to set and retrieve security and policy related information for the EFI IPsec protocol driver. - Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: + @par Revision Reference: This Protocol is introduced in UEFI Specification 2.2 **/ @@ -32,34 +26,34 @@ typedef struct _EFI_IPSEC_CONFIG_PROTOCOL EFI_IPSEC_CONFIG_PROTOCOL; /// EFI_IPSEC_CONFIG_DATA_TYPE /// typedef enum { - /// - /// The IPsec Security Policy Database (aka SPD) setting. In IPsec, - /// an essential element of Security Association (SA) processing is - /// underlying SPD that specifies what services are to be offered to - /// IP datagram and in what fashion. The SPD must be consulted - /// during the processing of all traffic (inbound and outbound), - /// including traffic not protected by IPsec, that traverses the IPsec - /// boundary. With this DataType, SetData() function is to set - /// the SPD entry information, which may add one new entry, delete - /// one existed entry or flush the whole database according to the - /// parameter values. The corresponding Data is of type + /// + /// The IPsec Security Policy Database (aka SPD) setting. In IPsec, + /// an essential element of Security Association (SA) processing is + /// underlying SPD that specifies what services are to be offered to + /// IP datagram and in what fashion. The SPD must be consulted + /// during the processing of all traffic (inbound and outbound), + /// including traffic not protected by IPsec, that traverses the IPsec + /// boundary. With this DataType, SetData() function is to set + /// the SPD entry information, which may add one new entry, delete + /// one existed entry or flush the whole database according to the + /// parameter values. The corresponding Data is of type /// EFI_IPSEC_SPD_DATA - /// + /// IPsecConfigDataTypeSpd, - /// - /// The IPsec Security Association Database (aka SAD) setting. A - /// SA is a simplex connection that affords security services to the - /// traffic carried by it. Security services are afforded to an SA by the - /// use of AH, or ESP, but not both. The corresponding Data is of + /// + /// The IPsec Security Association Database (aka SAD) setting. A + /// SA is a simplex connection that affords security services to the + /// traffic carried by it. Security services are afforded to an SA by the + /// use of AH, or ESP, but not both. The corresponding Data is of /// type EFI_IPSEC_SAD_DATA. - /// + /// IPsecConfigDataTypeSad, - /// - /// The IPsec Peer Authorization Database (aka PAD) setting, which - /// provides the link between the SPD and a security association - /// management protocol. The PAD entry specifies the - /// authentication protocol (e.g. IKEv1, IKEv2) method used and the - /// authentication data. The corresponding Data is of type + /// + /// The IPsec Peer Authorization Database (aka PAD) setting, which + /// provides the link between the SPD and a security association + /// management protocol. The PAD entry specifies the + /// authentication protocol (e.g. IKEv1, IKEv2) method used and the + /// authentication data. The corresponding Data is of type /// EFI_IPSEC_PAD_DATA. /// IPsecConfigDataTypePad, @@ -79,70 +73,70 @@ typedef struct _EFI_IP_ADDRESS_INFO { /// EFI_IPSEC_SPD_SELECTOR /// typedef struct _EFI_IPSEC_SPD_SELECTOR { - /// + /// /// Specifies the actual number of entries in LocalAddress. - /// + /// UINT32 LocalAddressCount; - /// - /// A list of ranges of IPv4 or IPv6 addresses, which refers to the + /// + /// A list of ranges of IPv4 or IPv6 addresses, which refers to the /// addresses being protected by IPsec policy. - /// + /// EFI_IP_ADDRESS_INFO *LocalAddress; - /// + /// /// Specifies the actual number of entries in RemoteAddress. - /// + /// UINT32 RemoteAddressCount; - /// - /// A list of ranges of IPv4 or IPv6 addresses, which are peer entities - /// to LocalAddress. - /// + /// + /// A list of ranges of IPv4 or IPv6 addresses, which are peer entities + /// to LocalAddress. + /// EFI_IP_ADDRESS_INFO *RemoteAddress; - /// - /// Next layer protocol. Obtained from the IPv4 Protocol or the IPv6 - /// Next Header fields. The next layer protocol is whatever comes - /// after any IP extension headers that are present. A zero value is a + /// + /// Next layer protocol. Obtained from the IPv4 Protocol or the IPv6 + /// Next Header fields. The next layer protocol is whatever comes + /// after any IP extension headers that are present. A zero value is a /// wildcard that matches any value in NextLayerProtocol field. - /// - UINT16 NextLayerProtocol; - /// - /// Local Port if the Next Layer Protocol uses two ports (as do TCP, - /// UDP, and others). A zero value is a wildcard that matches any + /// + UINT16 NextLayerProtocol; + /// + /// Local Port if the Next Layer Protocol uses two ports (as do TCP, + /// UDP, and others). A zero value is a wildcard that matches any /// value in LocalPort field. - /// + /// UINT16 LocalPort; - /// - /// A designed port range size. The start port is LocalPort, and - /// the total number of ports is described by LocalPortRange. - /// This field is ignored if NextLayerProtocol does not use - /// ports. - /// + /// + /// A designed port range size. The start port is LocalPort, and + /// the total number of ports is described by LocalPortRange. + /// This field is ignored if NextLayerProtocol does not use + /// ports. + /// UINT16 LocalPortRange; - /// - /// Remote Port if the Next Layer Protocol uses two ports. A zero + /// + /// Remote Port if the Next Layer Protocol uses two ports. A zero /// value is a wildcard that matches any value in RemotePort field. - /// + /// UINT16 RemotePort; - /// - /// A designed port range size. The start port is RemotePort, and - /// the total number of ports is described by RemotePortRange. + /// + /// A designed port range size. The start port is RemotePort, and + /// the total number of ports is described by RemotePortRange. /// This field is ignored if NextLayerProtocol does not use ports. - /// + /// UINT16 RemotePortRange; } EFI_IPSEC_SPD_SELECTOR; - + /// /// EFI_IPSEC_TRAFFIC_DIR /// represents the directionality in an SPD entry. /// typedef enum { /// - /// The EfiIPsecInBound refers to traffic entering an IPsec implementation via + /// The EfiIPsecInBound refers to traffic entering an IPsec implementation via /// the unprotected interface or emitted by the implementation on the unprotected - /// side of the boundary and directed towards the protected interface. + /// side of the boundary and directed towards the protected interface. /// EfiIPsecInBound, /// - /// The EfiIPsecOutBound refers to traffic entering the implementation via + /// The EfiIPsecOutBound refers to traffic entering the implementation via /// the protected interface, or emitted by the implementation on the protected side /// of the boundary and directed toward the unprotected interface. /// @@ -154,54 +148,54 @@ typedef enum { /// represents three possible processing choices. /// typedef enum { - /// + /// /// Refers to traffic that is not allowed to traverse the IPsec boundary. - /// + /// EfiIPsecActionDiscard, - /// - /// Refers to traffic that is allowed to cross the IPsec boundary + /// + /// Refers to traffic that is allowed to cross the IPsec boundary /// without protection. - /// + /// EfiIPsecActionBypass, - /// - /// Refers to traffic that is afforded IPsec protection, and for such - /// traffic the SPD must specify the security protocols to be - /// employed, their mode, security service options, and the - /// cryptographic algorithms to be used. + /// + /// Refers to traffic that is afforded IPsec protection, and for such + /// traffic the SPD must specify the security protocols to be + /// employed, their mode, security service options, and the + /// cryptographic algorithms to be used. /// EfiIPsecActionProtect } EFI_IPSEC_ACTION; /// /// EFI_IPSEC_SA_LIFETIME -/// defines the lifetime of an SA, which represents when a SA must be -/// replaced or terminated. A value of all 0 for each field removes +/// defines the lifetime of an SA, which represents when a SA must be +/// replaced or terminated. A value of all 0 for each field removes /// the limitation of a SA lifetime. /// typedef struct _EFI_IPSEC_SA_LIFETIME { - /// + /// /// The number of bytes to which the IPsec cryptographic algorithm /// can be applied. For ESP, this is the encryption algorithm and for - /// AH, this is the authentication algorithm. The ByteCount + /// AH, this is the authentication algorithm. The ByteCount /// includes pad bytes for cryptographic operations. - /// + /// UINT64 ByteCount; - /// - /// A time interval in second that warns the implementation to + /// + /// A time interval in second that warns the implementation to /// initiate action such as setting up a replacement SA. - /// + /// UINT64 SoftLifetime; - /// - /// A time interval in second when the current SA ends and is + /// + /// A time interval in second when the current SA ends and is /// destroyed. - /// + /// UINT64 HardLifetime; } EFI_IPSEC_SA_LIFETIME; /// /// EFI_IPSEC_MODE -/// There are two modes of IPsec operation: transport mode and tunnel mode. In -/// EfiIPsecTransport mode, AH and ESP provide protection primarily for next layer protocols; +/// There are two modes of IPsec operation: transport mode and tunnel mode. In +/// EfiIPsecTransport mode, AH and ESP provide protection primarily for next layer protocols; /// In EfiIPsecTunnel mode, AH and ESP are applied to tunneled IP packets. /// typedef enum { @@ -226,19 +220,19 @@ typedef enum { /// EFI_IPSEC_TUNNEL_OPTION /// typedef struct _EFI_IPSEC_TUNNEL_OPTION { - /// + /// /// Local tunnel address when IPsec mode is EfiIPsecTunnel. - /// + /// EFI_IP_ADDRESS LocalTunnelAddress; - /// + /// /// Remote tunnel address when IPsec mode is EfiIPsecTunnel. - /// + /// EFI_IP_ADDRESS RemoteTunnelAddress; - /// + /// /// The option of copying the DF bit from an outbound package - /// to the tunnel mode header that it emits, when traffic is - /// carried via a tunnel mode SA. - /// + /// to the tunnel mode header that it emits, when traffic is + /// carried via a tunnel mode SA. + /// EFI_IPSEC_TUNNEL_DF_OPTION DF; } EFI_IPSEC_TUNNEL_OPTION; @@ -247,7 +241,7 @@ typedef struct _EFI_IPSEC_TUNNEL_OPTION { /// typedef enum { EfiIPsecAH, ///< IP Authentication Header protocol which is specified in RFC 4302. - EfiIPsecESP ///< IP Encapsulating Security Payload which is specified in RFC 4303. + EfiIPsecESP ///< IP Encapsulating Security Payload which is specified in RFC 4303. } EFI_IPSEC_PROTOCOL_TYPE; /// @@ -255,48 +249,48 @@ typedef enum { /// describes a policy list for traffic processing. /// typedef struct _EFI_IPSEC_PROCESS_POLICY { - /// - /// Extended Sequence Number. Is this SA using extended sequence + /// + /// Extended Sequence Number. Is this SA using extended sequence /// numbers. 64 bit counter is used if TRUE. - /// + /// BOOLEAN ExtSeqNum; - /// - /// A flag indicating whether overflow of the sequence number - /// counter should generate an auditable event and prevent - /// transmission of additional packets on the SA, or whether rollover + /// + /// A flag indicating whether overflow of the sequence number + /// counter should generate an auditable event and prevent + /// transmission of additional packets on the SA, or whether rollover /// is permitted. - /// + /// BOOLEAN SeqOverflow; - /// - /// Is this SA using stateful fragment checking. TRUE represents + /// + /// Is this SA using stateful fragment checking. TRUE represents /// stateful fragment checking. - /// + /// BOOLEAN FragCheck; - /// - /// A time interval after which a SA must be replaced with a new SA - /// (and new SPI) or terminated. - /// + /// + /// A time interval after which a SA must be replaced with a new SA + /// (and new SPI) or terminated. + /// EFI_IPSEC_SA_LIFETIME SaLifetime; - /// + /// /// IPsec mode: tunnel or transport. - /// + /// EFI_IPSEC_MODE Mode; - /// + /// /// Tunnel Option. TunnelOption is ignored if Mode is EfiIPsecTransport. - /// + /// EFI_IPSEC_TUNNEL_OPTION *TunnelOption; - /// + /// /// IPsec protocol: AH or ESP - /// + /// EFI_IPSEC_PROTOCOL_TYPE Proto; - /// + /// /// Cryptographic algorithm type used for authentication. - /// + /// UINT8 AuthAlgoId; - /// - /// Cryptographic algorithm type used for encryption. EncAlgo is - /// NULL when IPsec protocol is AH. For ESP protocol, EncAlgo - /// can also be used to describe the algorithm if a combined mode + /// + /// Cryptographic algorithm type used for encryption. EncAlgo is + /// NULL when IPsec protocol is AH. For ESP protocol, EncAlgo + /// can also be used to describe the algorithm if a combined mode /// algorithm is used. /// UINT8 EncAlgoId; @@ -307,19 +301,19 @@ typedef struct _EFI_IPSEC_PROCESS_POLICY { /// A triplet to identify an SA, consisting of the following members. /// typedef struct _EFI_IPSEC_SA_ID { - /// - /// Security Parameter Index (aka SPI). An arbitrary 32-bit value - /// that is used by a receiver to identity the SA to which an incoming + /// + /// Security Parameter Index (aka SPI). An arbitrary 32-bit value + /// that is used by a receiver to identity the SA to which an incoming /// package should be bound. - /// + /// UINT32 Spi; - /// + /// /// IPsec protocol: AH or ESP - /// + /// EFI_IPSEC_PROTOCOL_TYPE Proto; - /// - /// Destination IP address. - /// + /// + /// Destination IP address. + /// EFI_IP_ADDRESS DestAddress; } EFI_IPSEC_SA_ID; @@ -330,48 +324,48 @@ typedef struct _EFI_IPSEC_SA_ID { /// EFI_IPSEC_SPD_DATA /// typedef struct _EFI_IPSEC_SPD_DATA { - /// - /// A null-terminated ASCII name string which is used as a symbolic + /// + /// A null-terminated ASCII name string which is used as a symbolic /// identifier for an IPsec Local or Remote address. - /// + /// UINT8 Name[MAX_PEERID_LEN]; - /// - /// Bit-mapped list describing Populate from Packet flags. When - /// creating a SA, if PackageFlag bit is set to TRUE, instantiate - /// the selector from the corresponding field in the package that - /// triggered the creation of the SA, else from the value(s) in the - /// corresponding SPD entry. The PackageFlag bit setting for + /// + /// Bit-mapped list describing Populate from Packet flags. When + /// creating a SA, if PackageFlag bit is set to TRUE, instantiate + /// the selector from the corresponding field in the package that + /// triggered the creation of the SA, else from the value(s) in the + /// corresponding SPD entry. The PackageFlag bit setting for /// corresponding selector field of EFI_IPSEC_SPD_SELECTOR: - /// Bit 0: EFI_IPSEC_SPD_SELECTOR.LocalAddress - /// Bit 1: EFI_IPSEC_SPD_SELECTOR.RemoteAddress - /// Bit 2: - /// EFI_IPSEC_SPD_SELECTOR.NextLayerProtocol - /// Bit 3: EFI_IPSEC_SPD_SELECTOR.LocalPort - /// Bit 4: EFI_IPSEC_SPD_SELECTOR.RemotePort + /// Bit 0: EFI_IPSEC_SPD_SELECTOR.LocalAddress + /// Bit 1: EFI_IPSEC_SPD_SELECTOR.RemoteAddress + /// Bit 2: + /// EFI_IPSEC_SPD_SELECTOR.NextLayerProtocol + /// Bit 3: EFI_IPSEC_SPD_SELECTOR.LocalPort + /// Bit 4: EFI_IPSEC_SPD_SELECTOR.RemotePort /// Others: Reserved. /// UINT32 PackageFlag; - /// + /// /// The traffic direction of data gram. - /// + /// EFI_IPSEC_TRAFFIC_DIR TrafficDirection; - /// - /// Processing choices to indicate which action is required by this - /// policy. - /// + /// + /// Processing choices to indicate which action is required by this + /// policy. + /// EFI_IPSEC_ACTION Action; - /// + /// /// The policy and rule information for a SPD entry. - /// + /// EFI_IPSEC_PROCESS_POLICY *ProcessingPolicy; - /// + /// /// Specifies the actual number of entries in SaId list. - /// + /// UINTN SaIdCount; - /// - /// The SAD entry used for the traffic processing. The + /// + /// The SAD entry used for the traffic processing. The /// existed SAD entry links indicate this is the manual key case. - /// + /// EFI_IPSEC_SA_ID SaId[1]; } EFI_IPSEC_SPD_DATA; @@ -389,9 +383,9 @@ typedef struct _EFI_IPSEC_AH_ALGO_INFO { /// /// EFI_IPSEC_ESP_ALGO_INFO /// The security algorithm selection for IPsec ESP encryption and authentication. -/// The required authentication algorithm is specified in RFC 4305. -/// EncAlgoId fields can also specify an ESP combined mode algorithm -/// (e.g. AES with CCM mode, specified in RFC 4309), which provides both +/// The required authentication algorithm is specified in RFC 4305. +/// EncAlgoId fields can also specify an ESP combined mode algorithm +/// (e.g. AES with CCM mode, specified in RFC 4309), which provides both /// confidentiality and authentication services. /// typedef struct _EFI_IPSEC_ESP_ALGO_INFO { @@ -415,40 +409,40 @@ typedef union { /// EFI_IPSEC_SA_DATA /// typedef struct _EFI_IPSEC_SA_DATA { - /// + /// /// IPsec mode: tunnel or transport. - /// + /// EFI_IPSEC_MODE Mode; - /// - /// Sequence Number Counter. A 64-bit counter used to generate the + /// + /// Sequence Number Counter. A 64-bit counter used to generate the /// sequence number field in AH or ESP headers. - /// + /// UINT64 SNCount; - /// - /// Anti-Replay Window. A 64-bit counter and a bit-map used to + /// + /// Anti-Replay Window. A 64-bit counter and a bit-map used to /// determine whether an inbound AH or ESP packet is a replay. - /// + /// UINT8 AntiReplayWindows; - /// - /// AH/ESP cryptographic algorithm, key and parameters. - /// + /// + /// AH/ESP cryptographic algorithm, key and parameters. + /// EFI_IPSEC_ALGO_INFO AlgoInfo; - /// - /// Lifetime of this SA. - /// + /// + /// Lifetime of this SA. + /// EFI_IPSEC_SA_LIFETIME SaLifetime; - /// - /// Any observed path MTU and aging variables. The Path MTU + /// + /// Any observed path MTU and aging variables. The Path MTU /// processing is defined in section 8 of RFC 4301. - /// + /// UINT32 PathMTU; - /// + /// /// Link to one SPD entry. - /// + /// EFI_IPSEC_SPD_SELECTOR *SpdSelector; - /// - /// Indication of whether it's manually set or negotiated automatically. - /// If ManualSet is FALSE, the corresponding SA entry is inserted through + /// + /// Indication of whether it's manually set or negotiated automatically. + /// If ManualSet is FALSE, the corresponding SA entry is inserted through /// IKE protocol negotiation. /// BOOLEAN ManualSet; @@ -457,41 +451,41 @@ typedef struct _EFI_IPSEC_SA_DATA { /// /// EFI_IPSEC_SA_DATA2 /// -typedef struct _EFI_IPSEC_SA_DATA2 { +typedef struct _EFI_IPSEC_SA_DATA2 { /// /// IPsec mode: tunnel or transport /// - EFI_IPSEC_MODE Mode; + EFI_IPSEC_MODE Mode; /// - /// Sequence Number Counter. A 64-bit counter used to generate the sequence - /// number field in AH or ESP headers. + /// Sequence Number Counter. A 64-bit counter used to generate the sequence + /// number field in AH or ESP headers. /// - UINT64 SNCount; + UINT64 SNCount; /// - /// Anti-Replay Window. A 64-bit counter and a bit-map used to determine + /// Anti-Replay Window. A 64-bit counter and a bit-map used to determine /// whether an inbound AH or ESP packet is a replay. /// - UINT8 AntiReplayWindows; + UINT8 AntiReplayWindows; /// /// AH/ESP cryptographic algorithm, key and parameters. /// - EFI_IPSEC_ALGO_INFO AlgoInfo; + EFI_IPSEC_ALGO_INFO AlgoInfo; /// /// Lifetime of this SA. /// - EFI_IPSEC_SA_LIFETIME SaLifetime; + EFI_IPSEC_SA_LIFETIME SaLifetime; /// - /// Any observed path MTU and aging variables. The Path MTU processing is + /// Any observed path MTU and aging variables. The Path MTU processing is /// defined in section 8 of RFC 4301. /// - UINT32 PathMTU; + UINT32 PathMTU; /// /// Link to one SPD entry /// - EFI_IPSEC_SPD_SELECTOR *SpdSelector; + EFI_IPSEC_SPD_SELECTOR *SpdSelector; /// - /// Indication of whether it's manually set or negotiated automatically. - /// If ManualSet is FALSE, the corresponding SA entry is inserted through IKE + /// Indication of whether it's manually set or negotiated automatically. + /// If ManualSet is FALSE, the corresponding SA entry is inserted through IKE /// protocol negotiation /// BOOLEAN ManualSet; @@ -503,7 +497,7 @@ typedef struct _EFI_IPSEC_SA_DATA2 { /// The tunnel header IP destination address. /// EFI_IP_ADDRESS TunnelDestinationAddress; -} EFI_IPSEC_SA_DATA2; +} EFI_IPSEC_SA_DATA2; /// @@ -514,8 +508,8 @@ typedef struct _EFI_IPSEC_SA_DATA2 { typedef struct _EFI_IPSEC_PAD_ID { /// /// Flag to identify which type of PAD Id is used. - /// - BOOLEAN PeerIdValid; + /// + BOOLEAN PeerIdValid; union { /// /// Pointer to the IPv4 or IPv6 address range. @@ -523,8 +517,8 @@ typedef struct _EFI_IPSEC_PAD_ID { EFI_IP_ADDRESS_INFO IpAddress; /// /// Pointer to a null terminated ASCII string - /// representing the symbolic names. A PeerId can be a DNS - /// name, Distinguished Name, RFC 822 email address or Key ID + /// representing the symbolic names. A PeerId can be a DNS + /// name, Distinguished Name, RFC 822 email address or Key ID /// (specified in section 4.4.3.1 of RFC 4301) /// UINT8 PeerId[MAX_PEERID_LEN]; @@ -533,7 +527,7 @@ typedef struct _EFI_IPSEC_PAD_ID { /// /// EFI_IPSEC_CONFIG_SELECTOR -/// describes the expected IPsec configuration data selector +/// describes the expected IPsec configuration data selector /// of type EFI_IPSEC_CONFIG_DATA_TYPE. /// typedef union { @@ -544,7 +538,7 @@ typedef union { /// /// EFI_IPSEC_AUTH_PROTOCOL_TYPE -/// defines the possible authentication protocol for IPsec +/// defines the possible authentication protocol for IPsec /// security association management. /// typedef enum { @@ -572,64 +566,64 @@ typedef enum { /// EFI_IPSEC_PAD_DATA /// typedef struct _EFI_IPSEC_PAD_DATA { - /// + /// /// Authentication Protocol for IPsec security association management. - /// + /// EFI_IPSEC_AUTH_PROTOCOL_TYPE AuthProtocol; - /// + /// /// Authentication method used. - /// + /// EFI_IPSEC_AUTH_METHOD AuthMethod; - /// - /// The IKE ID payload will be used as a symbolic name for SPD - /// lookup if IkeIdFlag is TRUE. Otherwise, the remote IP + /// + /// The IKE ID payload will be used as a symbolic name for SPD + /// lookup if IkeIdFlag is TRUE. Otherwise, the remote IP /// address provided in traffic selector playloads will be used. - /// + /// BOOLEAN IkeIdFlag; - /// + /// /// The size of Authentication data buffer, in bytes. - /// + /// UINTN AuthDataSize; - /// - /// Buffer for Authentication data, (e.g., the pre-shared secret or the - /// trust anchor relative to which the peer's certificate will be + /// + /// Buffer for Authentication data, (e.g., the pre-shared secret or the + /// trust anchor relative to which the peer's certificate will be /// validated). - /// + /// VOID *AuthData; - /// + /// /// The size of RevocationData, in bytes - /// + /// UINTN RevocationDataSize; - /// - /// Pointer to CRL or OCSP data, if certificates are used for + /// + /// Pointer to CRL or OCSP data, if certificates are used for /// authentication method. - /// + /// VOID *RevocationData; } EFI_IPSEC_PAD_DATA; /** Set the security association, security policy and peer authorization configuration - information for the EFI IPsec driver. + information for the EFI IPsec driver. This function is used to set the IPsec configuration information of type DataType for the EFI IPsec driver. The IPsec configuration data has a unique selector/identifier separately to identify a data entry. The selector structure depends on DataType's definition. Using SetData() with a Data of NULL causes the IPsec configuration data entry identified - by DataType and Selector to be deleted. + by DataType and Selector to be deleted. @param[in] This Pointer to the EFI_IPSEC_CONFIG_PROTOCOL instance. @param[in] DataType The type of data to be set. - @param[in] Selector Pointer to an entry selector on operated configuration data - specified by DataType. A NULL Selector causes the entire + @param[in] Selector Pointer to an entry selector on operated configuration data + specified by DataType. A NULL Selector causes the entire specified-type configuration information to be flushed. - @param[in] Data The data buffer to be set. The structure of the data buffer is + @param[in] Data The data buffer to be set. The structure of the data buffer is associated with the DataType. @param[in] InsertBefore Pointer to one entry selector which describes the expected position the new data entry will be added. If InsertBefore is NULL, the new entry will be appended the end of database. - + @retval EFI_SUCCESS The specified configuration entry data is set successfully. @retval EFI_INVALID_PARAMETER One or more of the following are TRUE: - This is NULL. @@ -648,20 +642,20 @@ EFI_STATUS ); /** - Return the configuration value for the EFI IPsec driver. + Return the configuration value for the EFI IPsec driver. This function lookup the data entry from IPsec database or IKEv2 configuration information. The expected data type and unique identification are described in - DataType and Selector parameters. + DataType and Selector parameters. @param[in] This Pointer to the EFI_IPSEC_CONFIG_PROTOCOL instance. @param[in] DataType The type of data to retrieve. - @param[in] Selector Pointer to an entry selector which is an identifier of the IPsec + @param[in] Selector Pointer to an entry selector which is an identifier of the IPsec configuration data entry. @param[in, out] DataSize On output the size of data returned in Data. - @param[out] Data The buffer to return the contents of the IPsec configuration data. - The type of the data buffer is associated with the DataType. - + @param[out] Data The buffer to return the contents of the IPsec configuration data. + The type of the data buffer is associated with the DataType. + @retval EFI_SUCCESS The specified configuration data is got successfully. @retval EFI_INVALID_PARAMETER One or more of the followings are TRUE: - This is NULL. @@ -685,30 +679,30 @@ EFI_STATUS ); /** - Enumerates the current selector for IPsec configuration data entry. + Enumerates the current selector for IPsec configuration data entry. This function is called multiple times to retrieve the entry Selector in IPsec - configuration database. On each call to GetNextSelector(), the next entry + configuration database. On each call to GetNextSelector(), the next entry Selector are retrieved into the output interface. - - If the entire IPsec configuration database has been iterated, the error + + If the entire IPsec configuration database has been iterated, the error EFI_NOT_FOUND is returned. - If the Selector buffer is too small for the next Selector copy, an - EFI_BUFFER_TOO_SMALL error is returned, and SelectorSize is updated to reflect + If the Selector buffer is too small for the next Selector copy, an + EFI_BUFFER_TOO_SMALL error is returned, and SelectorSize is updated to reflect the size of buffer needed. On the initial call to GetNextSelector() to start the IPsec configuration database - search, a pointer to the buffer with all zero value is passed in Selector. Calls - to SetData() between calls to GetNextSelector may produce unpredictable results. + search, a pointer to the buffer with all zero value is passed in Selector. Calls + to SetData() between calls to GetNextSelector may produce unpredictable results. @param[in] This Pointer to the EFI_IPSEC_CONFIG_PROTOCOL instance. @param[in] DataType The type of IPsec configuration data to retrieve. @param[in, out] SelectorSize The size of the Selector buffer. - @param[in, out] Selector On input, supplies the pointer to last Selector that was + @param[in, out] Selector On input, supplies the pointer to last Selector that was returned by GetNextSelector(). On output, returns one copy of the current entry Selector - of a given DataType. - + of a given DataType. + @retval EFI_SUCCESS The specified configuration data is got successfully. @retval EFI_INVALID_PARAMETER One or more of the followings are TRUE: - This is NULL. @@ -717,7 +711,7 @@ EFI_STATUS @retval EFI_NOT_FOUND The next configuration data entry was not found. @retval EFI_UNSUPPORTED The specified DataType is not supported. @retval EFI_BUFFER_TOO_SMALL The SelectorSize is too small for the result. This parameter - has been updated with the size needed to complete the search + has been updated with the size needed to complete the search request. **/ @@ -732,18 +726,18 @@ EFI_STATUS /** Register an event that is to be signaled whenever a configuration process on the - specified IPsec configuration information is done. + specified IPsec configuration information is done. This function registers an event that is to be signaled whenever a configuration - process on the specified IPsec configuration data is done (e.g. IPsec security + process on the specified IPsec configuration data is done (e.g. IPsec security policy database configuration is ready). An event can be registered for different - DataType simultaneously and the caller is responsible for determining which type - of configuration data causes the signaling of the event in such case. + DataType simultaneously and the caller is responsible for determining which type + of configuration data causes the signaling of the event in such case. @param[in] This Pointer to the EFI_IPSEC_CONFIG_PROTOCOL instance. @param[in] DataType The type of data to be registered the event for. @param[in] Event The event to be registered. - + @retval EFI_SUCCESS The event is registered successfully. @retval EFI_INVALID_PARAMETER This is NULL or Event is NULL. @retval EFI_ACCESS_DENIED The Event is already registered for the DataType. @@ -761,16 +755,16 @@ EFI_STATUS /** Remove the specified event that is previously registered on the specified IPsec - configuration data. + configuration data. - This function removes a previously registered event for the specified configuration data. + This function removes a previously registered event for the specified configuration data. @param[in] This Pointer to the EFI_IPSEC_CONFIG_PROTOCOL instance. @param[in] DataType The configuration data type to remove the registered event for. @param[in] Event The event to be unregistered. - + @retval EFI_SUCCESS The event is removed successfully. - @retval EFI_NOT_FOUND The Event specified by DataType could not be found in the + @retval EFI_NOT_FOUND The Event specified by DataType could not be found in the database. @retval EFI_INVALID_PARAMETER This is NULL or Event is NULL. @retval EFI_UNSUPPORTED The notify registration unsupported or the specified @@ -788,12 +782,12 @@ EFI_STATUS /// /// EFI_IPSEC_CONFIG_PROTOCOL /// provides the ability to set and lookup the IPsec SAD (Security Association Database), -/// SPD (Security Policy Database) data entry and configure the security association -/// management protocol such as IKEv2. This protocol is used as the central +/// SPD (Security Policy Database) data entry and configure the security association +/// management protocol such as IKEv2. This protocol is used as the central /// repository of any policy-specific configuration for EFI IPsec driver. -/// EFI_IPSEC_CONFIG_PROTOCOL can be bound to both IPv4 and IPv6 stack. User can use this +/// EFI_IPSEC_CONFIG_PROTOCOL can be bound to both IPv4 and IPv6 stack. User can use this /// protocol for IPsec configuration in both IPv4 and IPv6 environment. -/// +/// struct _EFI_IPSEC_CONFIG_PROTOCOL { EFI_IPSEC_CONFIG_SET_DATA SetData; EFI_IPSEC_CONFIG_GET_DATA GetData; diff --git a/MdePkg/Include/Protocol/IsaHc.h b/MdePkg/Include/Protocol/IsaHc.h index bc92675d12ca..66f19a755bf2 100644 --- a/MdePkg/Include/Protocol/IsaHc.h +++ b/MdePkg/Include/Protocol/IsaHc.h @@ -5,14 +5,8 @@ subtractive-decode ISA bus. It allows devices to be registered and also handles opening and closing the apertures which are positively-decoded. - Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This protocol is from PI Version 1.2.1. @@ -76,7 +70,7 @@ EFI_STATUS hardware aperture (via CloseIoAperture()) until there are no more references to it. @param This A pointer to this instance of the EFI_ISA_HC_PROTOCOL. - @param IoApertureHandle The I/O aperture handle previously returned from a + @param IoApertureHandle The I/O aperture handle previously returned from a call to OpenIoAperture(). @retval EFI_SUCCESS The IO aperture was closed successfully. diff --git a/MdePkg/Include/Protocol/Kms.h b/MdePkg/Include/Protocol/Kms.h index a8e58bc89b49..0b261a25892b 100644 --- a/MdePkg/Include/Protocol/Kms.h +++ b/MdePkg/Include/Protocol/Kms.h @@ -8,14 +8,8 @@ server over the network, or to a Hardware Security Module (HSM) attached to the system it runs on, or anything else that is capable of providing the key management service. - Copyright (c) 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials are licensed and made available under - the terms and conditions of the BSD License that accompanies this distribution. - The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php. - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -80,6 +74,10 @@ typedef struct _EFI_KMS_PROTOCOL EFI_KMS_PROTOCOL; { \ 0xb9237513, 0x6c44, 0x4411, {0xa9, 0x90, 0x21, 0xe5, 0x56, 0xe0, 0x5a, 0xde } \ } +#define EFI_KMS_FORMAT_GENERIC_DYNAMIC_GUID \ + { \ + 0x2156e996, 0x66de, 0x4b27, {0x9c, 0xc9, 0xb0, 0x9f, 0xac, 0x4d, 0x2, 0xbe } \ + } ///@} /// @@ -177,6 +175,17 @@ typedef struct _EFI_KMS_PROTOCOL EFI_KMS_PROTOCOL; typedef struct { /// + /// Length in bytes of the KeyData. + /// + UINT32 KeySize; + /// + /// The data of the key. + /// + UINT8 KeyData[1]; +} EFI_KMS_FORMAT_GENERIC_DYNAMIC; + +typedef struct { + /// /// The size in bytes for the client identifier. /// UINT16 ClientIdSize; @@ -358,7 +367,7 @@ EFI_STATUS @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. - @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of data specified by the ClientData parameter. This parameter may be NULL, in which case the ClientData parameter will be ignored and no data will be @@ -373,11 +382,11 @@ EFI_STATUS which will be zero if no data is returned from the KMS. @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of *ClientDataSize that is to be passed directly to the - KMS if it supports the use of client data. This - parameter may be NULL if and only if the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the ClientDataSize parameter is also NULL. Upon return to - the caller, *ClientData points to a block of data of - *ClientDataSize that was returned from the KMS. + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. If the returned value for *ClientDataSize is zero, then the returned value for *ClientData must be NULL and should be ignored by the caller. The KMS protocol @@ -403,7 +412,7 @@ EFI_STATUS IN EFI_KMS_CLIENT_INFO *Client, IN OUT UINTN *ClientDataSize OPTIONAL, IN OUT VOID **ClientData OPTIONAL - ); + ); /** Request that the KMS generate one or more new keys and associate them with key identifiers. @@ -439,7 +448,7 @@ EFI_STATUS type and must be freed by the caller when it is no longer needed. Also, the KeyStatus field must reflect the result of the request relative to that key. - @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of data specified by the ClientData parameter. This parameter may be NULL, in which case the ClientData parameter will be ignored and no data will be @@ -454,11 +463,11 @@ EFI_STATUS which will be zero if no data is returned from the KMS. @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of *ClientDataSize that is to be passed directly to the - KMS if it supports the use of client data. This - parameter may be NULL if and only if the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the ClientDataSize parameter is also NULL. Upon return to - the caller, *ClientData points to a block of data of - *ClientDataSize that was returned from the KMS. + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. If the returned value for *ClientDataSize is zero, then the returned value for *ClientData must be NULL and should be ignored by the caller. The KMS protocol @@ -520,12 +529,12 @@ EFI_STATUS On output, the KeyIdentifierSize and KeyIdentifier fields will be unchanged, while the KeyFormat and KeyValue fields will be updated values associated with this key - identifier. Memory for the KeyValue field will be + identifier. Memory for the KeyValue field will be allocated with the BOOT_SERVICES_DATA type and must be freed by the caller when it is no longer needed. Also, the KeyStatus field will reflect the result of the request relative to the individual key descriptor. - @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of data specified by the ClientData parameter. This parameter may be NULL, in which case the ClientData parameter will be ignored and no data will be @@ -540,11 +549,11 @@ EFI_STATUS which will be zero if no data is returned from the KMS. @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of *ClientDataSize that is to be passed directly to the - KMS if it supports the use of client data. This - parameter may be NULL if and only if the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the ClientDataSize parameter is also NULL. Upon return to - the caller, *ClientData points to a block of data of - *ClientDataSize that was returned from the KMS. + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. If the returned value for *ClientDataSize is zero, then the returned value for *ClientData must be NULL and should be ignored by the caller. The KMS protocol @@ -611,7 +620,7 @@ EFI_STATUS consistent values to be associated with the given KeyId. On return, the KeyStatus field will reflect the result of the operation for each key request. - @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of data specified by the ClientData parameter. This parameter may be NULL, in which case the ClientData parameter will be ignored and no data will be @@ -626,11 +635,11 @@ EFI_STATUS which will be zero if no data is returned from the KMS. @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of *ClientDataSize that is to be passed directly to the - KMS if it supports the use of client data. This - parameter may be NULL if and only if the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the ClientDataSize parameter is also NULL. Upon return to - the caller, *ClientData points to a block of data of - *ClientDataSize that was returned from the KMS. + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. If the returned value for *ClientDataSize is zero, then the returned value for *ClientData must be NULL and should be ignored by the caller. The KMS protocol @@ -696,7 +705,7 @@ EFI_STATUS KeyValue fields are ignored, but should be 0. On return, the KeyStatus field will reflect the result of the operation for each key request. - @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of data specified by the ClientData parameter. This parameter may be NULL, in which case the ClientData parameter will be ignored and no data will be @@ -711,11 +720,11 @@ EFI_STATUS which will be zero if no data is returned from the KMS. @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of *ClientDataSize that is to be passed directly to the - KMS if it supports the use of client data. This - parameter may be NULL if and only if the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the ClientDataSize parameter is also NULL. Upon return to - the caller, *ClientData points to a block of data of - *ClientDataSize that was returned from the KMS. + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. If the returned value for *ClientDataSize is zero, then the returned value for *ClientData must be NULL and should be ignored by the caller. The KMS protocol @@ -774,7 +783,7 @@ EFI_STATUS On input, the fields in the structure should be NULL. On output, the attribute fields will have updated values for attributes associated with this key identifier. - @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of data specified by the ClientData parameter. This parameter may be NULL, in which case the ClientData parameter will be ignored and no data will be @@ -789,11 +798,11 @@ EFI_STATUS which will be zero if no data is returned from the KMS. @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of *ClientDataSize that is to be passed directly to the - KMS if it supports the use of client data. This - parameter may be NULL if and only if the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the ClientDataSize parameter is also NULL. Upon return to - the caller, *ClientData points to a block of data of - *ClientDataSize that was returned from the KMS. + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. If the returned value for *ClientDataSize is zero, then the returned value for *ClientData must be NULL and should be ignored by the caller. The KMS protocol @@ -861,7 +870,7 @@ EFI_STATUS are completely filled in. On return the KeyAttributeStatus field will reflect the result of the operation for each key attribute request. - @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of data specified by the ClientData parameter. This parameter may be NULL, in which case the ClientData parameter will be ignored and no data will be @@ -876,11 +885,11 @@ EFI_STATUS which will be zero if no data is returned from the KMS. @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of *ClientDataSize that is to be passed directly to the - KMS if it supports the use of client data. This - parameter may be NULL if and only if the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the ClientDataSize parameter is also NULL. Upon return to - the caller, *ClientData points to a block of data of - *ClientDataSize that was returned from the KMS. + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. If the returned value for *ClientDataSize is zero, then the returned value for *ClientData must be NULL and should be ignored by the caller. The KMS protocol @@ -952,7 +961,7 @@ EFI_STATUS are completely filled in. On return the KeyAttributeStatus field will reflect the result of the operation for each key attribute request. - @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of data specified by the ClientData parameter. This parameter may be NULL, in which case the ClientData parameter will be ignored and no data will be @@ -967,11 +976,11 @@ EFI_STATUS which will be zero if no data is returned from the KMS. @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of *ClientDataSize that is to be passed directly to the - KMS if it supports the use of client data. This - parameter may be NULL if and only if the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the ClientDataSize parameter is also NULL. Upon return to - the caller, *ClientData points to a block of data of - *ClientDataSize that was returned from the KMS. + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. If the returned value for *ClientDataSize is zero, then the returned value for *ClientData must be NULL and should be ignored by the caller. The KMS protocol @@ -1049,7 +1058,7 @@ EFI_STATUS caller when it is no longer needed. Also, the KeyStatus field of each descriptor will reflect the result of the request relative to that key descriptor. - @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of data specified by the ClientData parameter. This parameter may be NULL, in which case the ClientData parameter will be ignored and no data will be @@ -1064,11 +1073,11 @@ EFI_STATUS which will be zero if no data is returned from the KMS. @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of *ClientDataSize that is to be passed directly to the - KMS if it supports the use of client data. This - parameter may be NULL if and only if the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the ClientDataSize parameter is also NULL. Upon return to - the caller, *ClientData points to a block of data of - *ClientDataSize that was returned from the KMS. + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. If the returned value for *ClientDataSize is zero, then the returned value for *ClientData must be NULL and should be ignored by the caller. The KMS protocol diff --git a/MdePkg/Include/Protocol/LegacyRegion2.h b/MdePkg/Include/Protocol/LegacyRegion2.h index 6f553bd7ad25..4a21784ce361 100644 --- a/MdePkg/Include/Protocol/LegacyRegion2.h +++ b/MdePkg/Include/Protocol/LegacyRegion2.h @@ -2,17 +2,11 @@ The Legacy Region Protocol controls the read, write and boot-lock attributes for the region 0xC0000 to 0xFFFFF. - Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: - This Protocol is defined in UEFI Platform Initialization Specification 1.2 + This Protocol is defined in UEFI Platform Initialization Specification 1.2 Volume 5: Standards **/ @@ -31,9 +25,9 @@ typedef struct _EFI_LEGACY_REGION2_PROTOCOL EFI_LEGACY_REGION2_PROTOCOL; /** Modify the hardware to allow (decode) or disallow (not decode) memory reads in a region. - If the On parameter evaluates to TRUE, this function enables memory reads in the address range + If the On parameter evaluates to TRUE, this function enables memory reads in the address range Start to (Start + Length - 1). - If the On parameter evaluates to FALSE, this function disables memory reads in the address range + If the On parameter evaluates to FALSE, this function disables memory reads in the address range Start to (Start + Length - 1). @param This[in] Indicates the EFI_LEGACY_REGION2_PROTOCOL instance. @@ -96,7 +90,7 @@ EFI_STATUS /** Modify the hardware to disallow memory attribute changes in a region. - This function makes the attributes of a region read only. Once a region is boot-locked with this + This function makes the attributes of a region read only. Once a region is boot-locked with this function, the read and write attributes of that region cannot be changed until a power cycle has reset the boot-lock attribute. Calls to Decode(), Lock() and Unlock() will have no effect. @@ -131,7 +125,7 @@ EFI_STATUS /** Modify the hardware to allow memory writes in a region. - This function changes the attributes of a memory range to allow writes. + This function changes the attributes of a memory range to allow writes. @param This[in] Indicates the EFI_LEGACY_REGION2_PROTOCOL instance. @param Start[in] The beginning of the physical address of the region whose @@ -195,9 +189,9 @@ typedef struct { /** Get region information for the attributes of the Legacy Region. - This function is used to discover the granularity of the attributes for the memory in the legacy + This function is used to discover the granularity of the attributes for the memory in the legacy region. Each attribute may have a different granularity and the granularity may not be the same - for all memory ranges in the legacy region. + for all memory ranges in the legacy region. @param This[in] Indicates the EFI_LEGACY_REGION2_PROTOCOL instance. @param DescriptorCount[out] The number of region descriptor entries returned in the Descriptor @@ -220,8 +214,8 @@ EFI_STATUS ); -/// -/// The EFI_LEGACY_REGION2_PROTOCOL is used to abstract the hardware control of the memory +/// +/// The EFI_LEGACY_REGION2_PROTOCOL is used to abstract the hardware control of the memory /// attributes of the Option ROM shadowing region, 0xC0000 to 0xFFFFF. /// There are three memory attributes that can be modified through this protocol: read, write and /// boot-lock. These protocols may be set in any combination. diff --git a/MdePkg/Include/Protocol/LegacySpiController.h b/MdePkg/Include/Protocol/LegacySpiController.h new file mode 100644 index 000000000000..d08741d5ed81 --- /dev/null +++ b/MdePkg/Include/Protocol/LegacySpiController.h @@ -0,0 +1,259 @@ +/** @file + This file defines the Legacy SPI Controller Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI PI Specification 1.6. + +**/ + +#ifndef __LEGACY_SPI_CONTROLLER_PROTOCOL_H__ +#define __LEGACY_SPI_CONTROLLER_PROTOCOL_H__ + +/// +/// Note: The UEFI PI 1.6 specification uses the character 'l' in the GUID +/// definition. This definition assumes it was supposed to be '1'. +/// +/// Global ID for the Legacy SPI Controller Protocol +/// +#define EFI_LEGACY_SPI_CONTROLLER_GUID \ + { 0x39136fc7, 0x1a11, 0x49de, \ + { 0xbf, 0x35, 0x0e, 0x78, 0xdd, 0xb5, 0x24, 0xfc }} + +typedef +struct _EFI_LEGACY_SPI_CONTROLLER_PROTOCOL +EFI_LEGACY_SPI_CONTROLLER_PROTOCOL; + +/** + Set the erase block opcode. + + This routine must be called at or below TPL_NOTIFY. + The menu table contains SPI transaction opcodes which are accessible after + the legacy SPI flash controller's configuration is locked. The board layer + specifies the erase block size for the SPI NOR flash part. The SPI NOR flash + peripheral driver selects the erase block opcode which matches the erase + block size and uses this API to load the opcode into the opcode menu table. + + @param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL + structure. + @param[in] EraseBlockOpcode Erase block opcode to be placed into the opcode + menu table. + + @retval EFI_SUCCESS The opcode menu table was updated + @retval EFI_ACCESS_ERROR The SPI controller is locked + +**/ +typedef EFI_STATUS +(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_ERASE_BLOCK_OPCODE) ( + IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This, + IN UINT8 EraseBlockOpcode + ); + +/** + Set the write status prefix opcode. + + This routine must be called at or below TPL_NOTIFY. + The prefix table contains SPI transaction write prefix opcodes which are + accessible after the legacy SPI flash controller's configuration is locked. + The board layer specifies the write status prefix opcode for the SPI NOR + flash part. The SPI NOR flash peripheral driver uses this API to load the + opcode into the prefix table. + + @param[in] This Pointer to an + EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structure. + @param[in] WriteStatusPrefix Prefix opcode for the write status command. + + @retval EFI_SUCCESS The prefix table was updated + @retval EFI_ACCESS_ERROR The SPI controller is locked + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_WRITE_STATUS_PREFIX) ( + IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This, + IN UINT8 WriteStatusPrefix + ); + +/** + Set the BIOS base address. + + This routine must be called at or below TPL_NOTIFY. + The BIOS base address works with the protect range registers to protect + portions of the SPI NOR flash from erase and write operat ions. The BIOS + calls this API prior to passing control to the OS loader. + + @param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL + structure. + @param[in] BiosBaseAddress The BIOS base address. + + @retval EFI_SUCCESS The BIOS base address was properly set + @retval EFI_ACCESS_ERROR The SPI controller is locked + @retval EFI_INVALID_PARAMETER The BIOS base address is greater than + This->Maxi.mumOffset + @retval EFI_UNSUPPORTED The BIOS base address was already set + +**/ +typedef EFI_STATUS +(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_BIOS_BASE_ADDRESS) ( + IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This, + IN UINT32 BiosBaseAddress + ); + +/** + Clear the SPI protect range registers. + + This routine must be called at or below TPL_NOTIFY. + The BIOS uses this routine to set an initial condition on the SPI protect + range registers. + + @param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structure. + + @retval EFI_SUCCESS The registers were successfully cleared + @retval EFI_ACCESS_ERROR The SPI controller is locked + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_CLEAR_SPI_PROTECT) ( + IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This + ); + +/** + Determine if the SPI range is protected. + + This routine must be called at or below TPL_NOTIFY. + The BIOS uses this routine to verify a range in the SPI is protected. + + @param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL + structure. + @param[in] BiosAddress Address within a 4 KiB block to start protecting. + @param[in] BytesToProtect The number of 4 KiB blocks to protect. + + @retval TRUE The range is protected + @retval FALSE The range is not protected + +**/ +typedef +BOOLEAN +(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_IS_RANGE_PROTECTED) ( + IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This, + IN UINT32 BiosAddress, + IN UINT32 BlocksToProtect + ); + +/** + Set the next protect range register. + + This routine must be called at or below TPL_NOTIFY. + The BIOS sets the protect range register to prevent write and erase + operations to a portion of the SPI NOR flash device. + + @param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL + structure. + @param[in] BiosAddress Address within a 4 KiB block to start protecting. + @param[in] BlocksToProtect The number of 4 KiB blocks to protect. + + @retval EFI_SUCCESS The register was successfully updated + @retval EFI_ACCESS_ERROR The SPI controller is locked + @retval EFI_INVALID_PARAMETER BiosAddress < This->BiosBaseAddress, or + BlocksToProtect * 4 KiB + > This->MaximumRangeBytes, or + BiosAddress - This->BiosBaseAddress + + (BlocksToProtect * 4 KiB) + > This->MaximumRangeBytes + @retval EFI_OUT_OF_RESOURCES No protect range register available + @retval EFI_UNSUPPORTED Call This->SetBaseAddress because the BIOS base + address is not set + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_PROTECT_NEXT_RANGE) ( + IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This, + IN UINT32 BiosAddress, + IN UINT32 BlocksToProtect + ); + +/** + Lock the SPI controller configuration. + + This routine must be called at or below TPL_NOTIFY. + This routine locks the SPI controller's configuration so that the software + is no longer able to update: + * Prefix table + * Opcode menu + * Opcode type table + * BIOS base address + * Protect range registers + + @param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structure. + + @retval EFI_SUCCESS The SPI controller was successfully locked + @retval EFI_ALREADY_STARTED The SPI controller was already locked + +**/ +typedef EFI_STATUS +(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_LOCK_CONTROLLER) ( + IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This + ); + +/// +/// Support the extra features of the legacy SPI flash controller. +/// +struct _EFI_LEGACY_SPI_CONTROLLER_PROTOCOL { + /// + /// Maximum offset from the BIOS base address that is able to be protected. + /// + UINT32 MaximumOffset; + + /// + /// Maximum number of bytes that can be protected by one range register. + /// + UINT32 MaximumRangeBytes; + + /// + /// The number of registers available for protecting the BIOS. + /// + UINT32 RangeRegisterCount; + + /// + /// Set the erase block opcode. + /// + EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_ERASE_BLOCK_OPCODE EraseBlockOpcode; + + /// + /// Set the write status prefix opcode. + /// + EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_WRITE_STATUS_PREFIX WriteStatusPrefix; + + /// + /// Set the BIOS base address. + /// + EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_BIOS_BASE_ADDRESS BiosBaseAddress; + + /// + /// Clear the SPI protect range registers. + /// + EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_CLEAR_SPI_PROTECT ClearSpiProtect; + + /// + /// Determine if the SPI range is protected. + /// + EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_IS_RANGE_PROTECTED IsRangeProtected; + + /// + /// Set the next protect range register. + /// + EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_PROTECT_NEXT_RANGE ProtectNextRange; + + /// + /// Lock the SPI controller configuration. + /// + EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_LOCK_CONTROLLER LockController; +}; + +extern EFI_GUID gEfiLegacySpiControllerProtocolGuid; + +#endif // __LEGACY_SPI_CONTROLLER_PROTOCOL_H__ diff --git a/MdePkg/Include/Protocol/LegacySpiFlash.h b/MdePkg/Include/Protocol/LegacySpiFlash.h new file mode 100644 index 000000000000..539ecedb2676 --- /dev/null +++ b/MdePkg/Include/Protocol/LegacySpiFlash.h @@ -0,0 +1,195 @@ +/** @file + This file defines the Legacy SPI Flash Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI PI Specification 1.6. + +**/ + +#ifndef __LEGACY_SPI_FLASH_PROTOCOL_H__ +#define __LEGACY_SPI_FLASH_PROTOCOL_H__ + +#include <Protocol/SpiNorFlash.h> + +/// +/// Global ID for the Legacy SPI Flash Protocol +/// +#define EFI_LEGACY_SPI_FLASH_PROTOCOL_GUID \ + { 0xf01bed57, 0x04bc, 0x4f3f, \ + { 0x96, 0x60, 0xd6, 0xf2, 0xea, 0x22, 0x82, 0x59 }} + +typedef struct _EFI_LEGACY_SPI_FLASH_PROTOCOL EFI_LEGACY_SPI_FLASH_PROTOCOL; + +/** + Set the BIOS base address. + + This routine must be called at or below TPL_NOTIFY. + The BIOS base address works with the protect range registers to protect + portions of the SPI NOR flash from erase and write operat ions. + The BIOS calls this API prior to passing control to the OS loader. + + @param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data + structure. + @param[in] BiosBaseAddress The BIOS base address. + + @retval EFI_SUCCESS The BIOS base address was properly set + @retval EFI_ACCESS_ERROR The SPI controller is locked + @retval EFI_INVALID_PARAMETER BiosBaseAddress > This->MaximumOffset + @retval EFI_UNSUPPORTED The BIOS base address was already set or not a + legacy SPI host controller + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_BIOS_BASE_ADDRESS) ( + IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL *This, + IN UINT32 BiosBaseAddress + ); + +/** + Clear the SPI protect range registers. + + This routine must be called at or below TPL_NOTIFY. + The BIOS uses this routine to set an initial condition on the SPI protect + range registers. + + @param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data structure. + + @retval EFI_SUCCESS The registers were successfully cleared + @retval EFI_ACCESS_ERROR The SPI controller is locked + @retval EFI_UNSUPPORTED Not a legacy SPI host controller + +**/ +typedef EFI_STATUS +(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_CLEAR_SPI_PROTECT) ( + IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL *This + ); + +/** + Determine if the SPI range is protected. + + This routine must be called at or below TPL_NOTIFY. + The BIOS uses this routine to verify a range in the SPI is protected. + + @param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data + structure. + @param[in] BiosAddress Address within a 4 KiB block to start protecting. + @param[in] BlocksToProtect The number of 4 KiB blocks to protect. + + @retval TRUE The range is protected + @retval FALSE The range is not protected + +**/ +typedef +BOOLEAN +(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_IS_RANGE_PROTECTED) ( + IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL *This, + IN UINT32 BiosAddress, + IN UINT32 BlocksToProtect + ); + +/** + Set the next protect range register. + + This routine must be called at or below TPL_NOTIFY. + The BIOS sets the protect range register to prevent write and erase + operations to a portion of the SPI NOR flash device. + + @param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data + structure. + @param[in] BiosAddress Address within a 4 KiB block to start protecting. + @param[in] BlocksToProtect The number of 4 KiB blocks to protect. + + @retval EFI_SUCCESS The register was successfully updated + @retval EFI_ACCESS_ERROR The SPI controller is locked + @retval EFI_INVALID_PARAMETER BiosAddress < This->BiosBaseAddress, or + @retval EFI_INVALID_PARAMETER BlocksToProtect * 4 KiB + > This->MaximumRangeBytes, or + BiosAddress - This->BiosBaseAddress + + (BlocksToProtect * 4 KiB) + > This->MaximumRangeBytes + @retval EFI_OUT_OF_RESOURCES No protect range register available + @retval EFI_UNSUPPORTED Call This->SetBaseAddress because the BIOS + base address is not set Not a legacy SPI host + controller + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_PROTECT_NEXT_RANGE) ( + IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL *This, + IN UINT32 BiosAddress, + IN UINT32 BlocksToProtect + ); + +/** + Lock the SPI controller configuration. + + This routine must be called at or below TPL_NOTIFY. + This routine locks the SPI controller's configuration so that the software is + no longer able to update: + * Prefix table + * Opcode menu + * Opcode type table + * BIOS base address + * Protect range registers + + @param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data structure. + + @retval EFI_SUCCESS The SPI controller was successfully locked + @retval EFI_ALREADY_STARTED The SPI controller was already locked + @retval EFI_UNSUPPORTED Not a legacy SPI host controller +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_LOCK_CONTROLLER) ( + IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL *This + ); + +/// +/// The EFI_LEGACY_SPI_FLASH_PROTOCOL extends the EFI_SPI_NOR_FLASH_PROTOCOL +/// with APls to support the legacy SPI flash controller. +/// +struct _EFI_LEGACY_SPI_FLASH_PROTOCOL { + /// + /// This protocol manipulates the SPI NOR flash parts using a common set of + /// commands. + /// + EFI_SPI_NOR_FLASH_PROTOCOL FlashProtocol; + + // + // Legacy flash (SPI host) controller support + // + + /// + /// Set the BIOS base address. + /// + EFI_LEGACY_SPI_FLASH_PROTOCOL_BIOS_BASE_ADDRESS BiosBaseAddress; + + /// + /// Clear the SPI protect range registers. + /// + EFI_LEGACY_SPI_FLASH_PROTOCOL_CLEAR_SPI_PROTECT ClearSpiProtect; + + /// + /// Determine if the SPI range is protected. + /// + EFI_LEGACY_SPI_FLASH_PROTOCOL_IS_RANGE_PROTECTED IsRangeProtected; + + /// + /// Set the next protect range register. + /// + EFI_LEGACY_SPI_FLASH_PROTOCOL_PROTECT_NEXT_RANGE ProtectNextRange; + + /// + /// Lock the SPI controller configuration. + /// + EFI_LEGACY_SPI_FLASH_PROTOCOL_LOCK_CONTROLLER LockController; +}; + +extern EFI_GUID gEfiLegacySpiFlashProtocolGuid; + +#endif // __LEGACY_SPI_FLASH_PROTOCOL_H__ diff --git a/MdePkg/Include/Protocol/LegacySpiSmmController.h b/MdePkg/Include/Protocol/LegacySpiSmmController.h new file mode 100644 index 000000000000..e4fa7d967284 --- /dev/null +++ b/MdePkg/Include/Protocol/LegacySpiSmmController.h @@ -0,0 +1,30 @@ +/** @file + This file defines the Legacy SPI SMM Controler Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI PI Specification 1.6. + +**/ + +#ifndef __LEGACY_SPI_SMM_CONTROLLER_PROTOCOL_H__ +#define __LEGACY_SPI_SMM_CONTROLLER_PROTOCOL_H__ + +#include <Protocol/LegacySpiController.h> + +/// +/// Global ID for the Legacy SPI SMM Controller Protocol +/// +#define EFI_LEGACY_SPI_SMM_CONTROLLER_PROTOCOL_GUID \ + { 0x62331b78, 0xd8d0, 0x4c8c, \ + { 0x8c, 0xcb, 0xd2, 0x7d, 0xfe, 0x32, 0xdb, 0x9b }} + +typedef +struct _EFI_LEGACY_SPI_CONTROLLER_PROTOCOL +EFI_LEGACY_SPI_SMM_CONTROLLER_PROTOCOL; + +extern EFI_GUID gEfiLegacySpiSmmControllerProtocolGuid; + +#endif // __LEGACY_SPI_SMM_CONTROLLER_PROTOCOL_H__ diff --git a/MdePkg/Include/Protocol/LegacySpiSmmFlash.h b/MdePkg/Include/Protocol/LegacySpiSmmFlash.h new file mode 100644 index 000000000000..6e3f234065ab --- /dev/null +++ b/MdePkg/Include/Protocol/LegacySpiSmmFlash.h @@ -0,0 +1,30 @@ +/** @file + This file defines the Legacy SPI SMM Flash Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI PI Specification 1.6. + +**/ + +#ifndef __LEGACY_SPI_SMM_FLASH_PROTOCOL_H__ +#define __LEGACY_SPI_SMM_FLASH_PROTOCOL_H__ + +#include <Protocol/LegacySpiFlash.h> + +/// +/// Global ID for the Legacy SPI SMM Flash Protocol +/// +#define EFI_LEGACY_SPI_SMM_FLASH_PROTOCOL_GUID \ + { 0x5e3848d4, 0x0db5, 0x4fc0, \ + { 0x97, 0x29, 0x3f, 0x35, 0x3d, 0x4f, 0x87, 0x9f }} + +typedef +struct _EFI_LEGACY_SPI_FLASH_PROTOCOL +EFI_LEGACY_SPI_SMM_FLASH_PROTOCOL; + +extern EFI_GUID gEfiLegacySpiSmmFlashProtocolGuid; + +#endif // __SPI_SMM_FLASH_PROTOCOL_H__ diff --git a/MdePkg/Include/Protocol/LoadFile.h b/MdePkg/Include/Protocol/LoadFile.h index 430ddb843dc9..1c2890feae47 100644 --- a/MdePkg/Include/Protocol/LoadFile.h +++ b/MdePkg/Include/Protocol/LoadFile.h @@ -1,20 +1,14 @@ /** @file Load File protocol as defined in the UEFI 2.0 specification. - The load file protocol exists to supports the addition of new boot devices, - and to support booting from devices that do not map well to file system. + The load file protocol exists to supports the addition of new boot devices, + and to support booting from devices that do not map well to file system. Network boot is done via a LoadFile protocol. UEFI 2.0 can boot from any device that produces a LoadFile protocol. -Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -35,7 +29,7 @@ typedef struct _EFI_LOAD_FILE_PROTOCOL EFI_LOAD_FILE_PROTOCOL; /// /// Backward-compatible with EFI1.1 -/// +/// typedef EFI_LOAD_FILE_PROTOCOL EFI_LOAD_FILE_INTERFACE; /** diff --git a/MdePkg/Include/Protocol/LoadFile2.h b/MdePkg/Include/Protocol/LoadFile2.h index cb977fbf3ec6..52105a1bfbd7 100644 --- a/MdePkg/Include/Protocol/LoadFile2.h +++ b/MdePkg/Include/Protocol/LoadFile2.h @@ -1,20 +1,14 @@ /** @file Load File protocol as defined in the UEFI 2.0 specification. - Load file protocol exists to supports the addition of new boot devices, - and to support booting from devices that do not map well to file system. + Load file protocol exists to supports the addition of new boot devices, + and to support booting from devices that do not map well to file system. Network boot is done via a LoadFile protocol. UEFI 2.0 can boot from any device that produces a LoadFile protocol. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -57,7 +51,7 @@ typedef struct _EFI_LOAD_FILE2_PROTOCOL EFI_LOAD_FILE2_PROTOCOL; @retval EFI_NO_RESPONSE The remote system did not respond. @retval EFI_NOT_FOUND The file was not found @retval EFI_ABORTED The file load process was manually canceled. - @retval EFI_BUFFER_TOO_SMALL The BufferSize is too small to read the current + @retval EFI_BUFFER_TOO_SMALL The BufferSize is too small to read the current directory entry. BufferSize has been updated with the size needed to complete the request. diff --git a/MdePkg/Include/Protocol/LoadedImage.h b/MdePkg/Include/Protocol/LoadedImage.h index 53971bc91868..6b4aee651a45 100644 --- a/MdePkg/Include/Protocol/LoadedImage.h +++ b/MdePkg/Include/Protocol/LoadedImage.h @@ -4,14 +4,8 @@ Every EFI driver and application is passed an image handle when it is loaded. This image handle will contain a Loaded Image Protocol. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -30,7 +24,7 @@ /// /// Protocol GUID defined in EFI1.1. -/// +/// #define LOADED_IMAGE_PROTOCOL EFI_LOADED_IMAGE_PROTOCOL_GUID /// @@ -40,25 +34,25 @@ /// /// Revision defined in EFI1.1. -/// +/// #define EFI_LOADED_IMAGE_INFORMATION_REVISION EFI_LOADED_IMAGE_PROTOCOL_REVISION /// /// Can be used on any image handle to obtain information about the loaded image. /// typedef struct { - UINT32 Revision; ///< Defines the revision of the EFI_LOADED_IMAGE_PROTOCOL structure. + UINT32 Revision; ///< Defines the revision of the EFI_LOADED_IMAGE_PROTOCOL structure. ///< All future revisions will be backward compatible to the current revision. - EFI_HANDLE ParentHandle; ///< Parent image's image handle. NULL if the image is loaded directly from - ///< the firmware's boot manager. + EFI_HANDLE ParentHandle; ///< Parent image's image handle. NULL if the image is loaded directly from + ///< the firmware's boot manager. EFI_SYSTEM_TABLE *SystemTable; ///< the image's EFI system table pointer. // // Source location of image // - EFI_HANDLE DeviceHandle; ///< The device handle that the EFI Image was loaded from. - EFI_DEVICE_PATH_PROTOCOL *FilePath; ///< A pointer to the file path portion specific to DeviceHandle - ///< that the EFI Image was loaded from. + EFI_HANDLE DeviceHandle; ///< The device handle that the EFI Image was loaded from. + EFI_DEVICE_PATH_PROTOCOL *FilePath; ///< A pointer to the file path portion specific to DeviceHandle + ///< that the EFI Image was loaded from. VOID *Reserved; ///< Reserved. DO NOT USE. // @@ -79,7 +73,7 @@ typedef struct { // // For backward-compatible with EFI1.1. -// +// typedef EFI_LOADED_IMAGE_PROTOCOL EFI_LOADED_IMAGE; extern EFI_GUID gEfiLoadedImageProtocolGuid; diff --git a/MdePkg/Include/Protocol/ManagedNetwork.h b/MdePkg/Include/Protocol/ManagedNetwork.h index 2ac001c4f95c..4617afbc188a 100644 --- a/MdePkg/Include/Protocol/ManagedNetwork.h +++ b/MdePkg/Include/Protocol/ManagedNetwork.h @@ -2,16 +2,10 @@ EFI_MANAGED_NETWORK_SERVICE_BINDING_PROTOCOL as defined in UEFI 2.0. EFI_MANAGED_NETWORK_PROTOCOL as defined in UEFI 2.0. -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: This Protocol is introduced in UEFI Specification 2.0 **/ @@ -352,7 +346,7 @@ EFI_STATUS ); /// -/// The MNP is used by network applications (and drivers) to +/// The MNP is used by network applications (and drivers) to /// perform raw (unformatted) asynchronous network packet I/O. /// struct _EFI_MANAGED_NETWORK_PROTOCOL { diff --git a/MdePkg/Include/Protocol/McaInitPmi.h b/MdePkg/Include/Protocol/McaInitPmi.h deleted file mode 100644 index c0c66147eab8..000000000000 --- a/MdePkg/Include/Protocol/McaInitPmi.h +++ /dev/null @@ -1,207 +0,0 @@ -/** @file - MCA/PMI/INIT Protocol as defined in PI Specification VOLUME 4. - - This protocol provides services to handle Machine Checks (MCA), - Initialization (INIT) events, and Platform Management Interrupt (PMI) events - on an Intel Itanium Processor Family based system. - - Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -**/ - -#ifndef __MCA_INIT_PMI_PROTOCOL_H__ -#define __MCA_INIT_PMI_PROTOCOL_H__ - -/// -/// Global ID for the MCA/PMI/INIT Protocol. -/// -#define EFI_SAL_MCA_INIT_PMI_PROTOCOL_GUID \ - { 0xb60dc6e8, 0x3b6f, 0x11d5, {0xaf, 0x9, 0x0, 0xa0, 0xc9, 0x44, 0xa0, 0x5b} } - - -/// -/// Declare forward reference for the Timer Architectural Protocol -/// -typedef struct _EFI_SAL_MCA_INIT_PMI_PROTOCOL EFI_SAL_MCA_INIT_PMI_PROTOCOL; - -#pragma pack(1) -/// -/// MCA Records Structure -/// -typedef struct { - UINT64 First : 1; - UINT64 Last : 1; - UINT64 EntryCount : 16; - UINT64 DispatchedCount : 16; - UINT64 Reserved : 30; -} SAL_MCA_COUNT_STRUCTURE; - -#pragma pack() - -/** - Prototype of MCA handler. - - @param ModuleGlobal The context of MCA Handler - @param ProcessorStateParameters The processor state parameters (PSP) - @param MinstateBase Base address of the min-state - @param RendezvouseStateInformation Rendezvous state information to be passed to - the OS on OS MCA entry - @param CpuIndex Index of the logical processor - @param McaCountStructure Pointer to the MCA records structure - @param CorrectedMachineCheck This flag is set to TRUE is the MCA has been - corrected by the handler or by a previous handler - - @retval EFI_SUCCESS Handler successfully returned - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SAL_MCA_HANDLER)( - IN VOID *ModuleGlobal, - IN UINT64 ProcessorStateParameters, - IN EFI_PHYSICAL_ADDRESS MinstateBase, - IN UINT64 RendezvouseStateInformation, - IN UINT64 CpuIndex, - IN SAL_MCA_COUNT_STRUCTURE *McaCountStructure, - OUT BOOLEAN *CorrectedMachineCheck - ); - -/** - Prototype of INIT handler. - - @param ModuleGlobal The context of INIT Handler - @param ProcessorStateParameters The processor state parameters (PSP) - @param MinstateBase Base address of the min-state - @param McaInProgress This flag indicates if an MCA is in progress - @param CpuIndex Index of the logical processor - @param McaCountStructure Pointer to the MCA records structure - @param DumpSwitchPressed This flag indicates the crash dump switch has been pressed - - @retval EFI_SUCCESS Handler successfully returned - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SAL_INIT_HANDLER)( - IN VOID *ModuleGlobal, - IN UINT64 ProcessorStateParameters, - IN EFI_PHYSICAL_ADDRESS MinstateBase, - IN BOOLEAN McaInProgress, - IN UINT64 CpuIndex, - IN SAL_MCA_COUNT_STRUCTURE *McaCountStructure, - OUT BOOLEAN *DumpSwitchPressed - ); - -/** - Prototype of PMI handler - - @param ModuleGlobal The context of PMI Handler - @param CpuIndex Index of the logical processor - @param PmiVector The PMI vector number as received from the PALE_PMI exit state (GR24) - - @retval EFI_SUCCESS Handler successfully returned - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SAL_PMI_HANDLER)( - IN VOID *ModuleGlobal, - IN UINT64 CpuIndex, - IN UINT64 PmiVector - ); - -/** - Register a MCA handler with the MCA dispatcher. - - @param This The EFI_SAL_MCA_INIT_PMI_PROTOCOL instance - @param McaHandler The MCA handler to register - @param ModuleGlobal The context of MCA Handler - @param MakeFirst This flag specifies the handler should be made first in the list - @param MakeLast This flag specifies the handler should be made last in the list - - @retval EFI_SUCCESS MCA Handle was registered - @retval EFI_OUT_OF_RESOURCES No more resources to register an MCA handler - @retval EFI_INVALID_PARAMETER Invalid parameters were passed - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SAL_REGISTER_MCA_HANDLER)( - IN EFI_SAL_MCA_INIT_PMI_PROTOCOL *This, - IN EFI_SAL_MCA_HANDLER McaHandler, - IN VOID *ModuleGlobal, - IN BOOLEAN MakeFirst, - IN BOOLEAN MakeLast - ); - -/** - Register an INIT handler with the INIT dispatcher. - - @param This The EFI_SAL_MCA_INIT_PMI_PROTOCOL instance - @param InitHandler The INIT handler to register - @param ModuleGlobal The context of INIT Handler - @param MakeFirst This flag specifies the handler should be made first in the list - @param MakeLast This flag specifies the handler should be made last in the list - - @retval EFI_SUCCESS INIT Handle was registered - @retval EFI_OUT_OF_RESOURCES No more resources to register an INIT handler - @retval EFI_INVALID_PARAMETER Invalid parameters were passed - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SAL_REGISTER_INIT_HANDLER)( - IN EFI_SAL_MCA_INIT_PMI_PROTOCOL *This, - IN EFI_SAL_INIT_HANDLER InitHandler, - IN VOID *ModuleGlobal, - IN BOOLEAN MakeFirst, - IN BOOLEAN MakeLast - ); - -/** - Register a PMI handler with the PMI dispatcher. - - @param This The EFI_SAL_MCA_INIT_PMI_PROTOCOL instance - @param PmiHandler The PMI handler to register - @param ModuleGlobal The context of PMI Handler - @param MakeFirst This flag specifies the handler should be made first in the list - @param MakeLast This flag specifies the handler should be made last in the list - - @retval EFI_SUCCESS PMI Handle was registered - @retval EFI_OUT_OF_RESOURCES No more resources to register an PMI handler - @retval EFI_INVALID_PARAMETER Invalid parameters were passed - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SAL_REGISTER_PMI_HANDLER)( - IN EFI_SAL_MCA_INIT_PMI_PROTOCOL *This, - IN EFI_SAL_PMI_HANDLER PmiHandler, - IN VOID *ModuleGlobal, - IN BOOLEAN MakeFirst, - IN BOOLEAN MakeLast - ); - -/// -/// This protocol is used to register MCA, INIT and PMI handlers with their respective dispatcher -/// -struct _EFI_SAL_MCA_INIT_PMI_PROTOCOL { - EFI_SAL_REGISTER_MCA_HANDLER RegisterMcaHandler; - EFI_SAL_REGISTER_INIT_HANDLER RegisterInitHandler; - EFI_SAL_REGISTER_PMI_HANDLER RegisterPmiHandler; - BOOLEAN McaInProgress; ///< Whether MCA handler is in progress - BOOLEAN InitInProgress; ///< Whether Init handler is in progress - BOOLEAN PmiInProgress; ///< Whether Pmi handler is in progress -}; - -extern EFI_GUID gEfiSalMcaInitPmiProtocolGuid; - -#endif - diff --git a/MdePkg/Include/Protocol/Metronome.h b/MdePkg/Include/Protocol/Metronome.h index 358d94b722ce..624c387c58a9 100644 --- a/MdePkg/Include/Protocol/Metronome.h +++ b/MdePkg/Include/Protocol/Metronome.h @@ -3,14 +3,8 @@ This code abstracts the DXE core to provide delay services. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -29,17 +23,17 @@ typedef struct _EFI_METRONOME_ARCH_PROTOCOL EFI_METRONOME_ARCH_PROTOCOL; /** - The WaitForTick() function waits for the number of ticks specified by - TickNumber from a known time source in the platform. If TickNumber of - ticks are detected, then EFI_SUCCESS is returned. The actual time passed - between entry of this function and the first tick is between 0 and - TickPeriod 100 nS units. If you want to guarantee that at least TickPeriod - time has elapsed, wait for two ticks. This function waits for a hardware - event to determine when a tick occurs. It is possible for interrupt - processing, or exception processing to interrupt the execution of the - WaitForTick() function. Depending on the hardware source for the ticks, it - is possible for a tick to be missed. This function cannot guarantee that - ticks will not be missed. If a timeout occurs waiting for the specified + The WaitForTick() function waits for the number of ticks specified by + TickNumber from a known time source in the platform. If TickNumber of + ticks are detected, then EFI_SUCCESS is returned. The actual time passed + between entry of this function and the first tick is between 0 and + TickPeriod 100 nS units. If you want to guarantee that at least TickPeriod + time has elapsed, wait for two ticks. This function waits for a hardware + event to determine when a tick occurs. It is possible for interrupt + processing, or exception processing to interrupt the execution of the + WaitForTick() function. Depending on the hardware source for the ticks, it + is possible for a tick to be missed. This function cannot guarantee that + ticks will not be missed. If a timeout occurs waiting for the specified number of ticks, then EFI_TIMEOUT is returned. @param This The EFI_METRONOME_ARCH_PROTOCOL instance. @@ -50,7 +44,7 @@ typedef struct _EFI_METRONOME_ARCH_PROTOCOL EFI_METRONOME_ARCH_PROTOCOL; @retval EFI_TIMEOUT A timeout occurred waiting for the specified number of ticks. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_METRONOME_WAIT_FOR_TICK)( IN EFI_METRONOME_ARCH_PROTOCOL *This, @@ -59,18 +53,18 @@ EFI_STATUS /// /// This protocol provides access to a known time source in the platform to the -/// core. The core uses this known time source to produce core services that -/// require calibrated delays. +/// core. The core uses this known time source to produce core services that +/// require calibrated delays. /// struct _EFI_METRONOME_ARCH_PROTOCOL { EFI_METRONOME_WAIT_FOR_TICK WaitForTick; - + /// - /// The period of platform's known time source in 100 nS units. - /// This value on any platform must be at least 10 uS, and must not - /// exceed 200 uS. The value in this field is a constant that must - /// not be modified after the Metronome architectural protocol is - /// installed. All consumers must treat this as a read-only field. + /// The period of platform's known time source in 100 nS units. + /// This value on any platform must be at least 10 uS, and must not + /// exceed 200 uS. The value in this field is a constant that must + /// not be modified after the Metronome architectural protocol is + /// installed. All consumers must treat this as a read-only field. /// UINT32 TickPeriod; }; diff --git a/MdePkg/Include/Protocol/MmAccess.h b/MdePkg/Include/Protocol/MmAccess.h new file mode 100644 index 000000000000..39c379560362 --- /dev/null +++ b/MdePkg/Include/Protocol/MmAccess.h @@ -0,0 +1,127 @@ +/** @file + EFI MM Access Protocol as defined in the PI 1.5 specification. + + This protocol is used to control the visibility of the MMRAM on the platform. + It abstracts the location and characteristics of MMRAM. The expectation is + that the north bridge or memory controller would publish this protocol. + + The principal functionality found in the memory controller includes the following: + - Exposing the MMRAM to all non-MM agents, or the "open" state + - Shrouding the MMRAM to all but the MM agents, or the "closed" state + - Preserving the system integrity, or "locking" the MMRAM, such that the settings cannot be + perturbed by either boot service or runtime agents + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_ACCESS_H_ +#define _MM_ACCESS_H_ + +#define EFI_MM_ACCESS_PROTOCOL_GUID \ + { \ + 0xc2702b74, 0x800c, 0x4131, {0x87, 0x46, 0x8f, 0xb5, 0xb8, 0x9c, 0xe4, 0xac } \ + } + + +typedef struct _EFI_MM_ACCESS_PROTOCOL EFI_MM_ACCESS_PROTOCOL; + +/** + Opens the MMRAM area to be accessible by a boot-service driver. + + This function "opens" MMRAM so that it is visible while not inside of MM. The function should + return EFI_UNSUPPORTED if the hardware does not support hiding of MMRAM. The function + should return EFI_DEVICE_ERROR if the MMRAM configuration is locked. + + @param[in] This The EFI_MM_ACCESS_PROTOCOL instance. + + @retval EFI_SUCCESS The operation was successful. + @retval EFI_UNSUPPORTED The system does not support opening and closing of MMRAM. + @retval EFI_DEVICE_ERROR MMRAM cannot be opened, perhaps because it is locked. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_OPEN)( + IN EFI_MM_ACCESS_PROTOCOL *This + ); + +/** + Inhibits access to the MMRAM. + + This function "closes" MMRAM so that it is not visible while outside of MM. The function should + return EFI_UNSUPPORTED if the hardware does not support hiding of MMRAM. + + @param[in] This The EFI_MM_ACCESS_PROTOCOL instance. + + @retval EFI_SUCCESS The operation was successful. + @retval EFI_UNSUPPORTED The system does not support opening and closing of MMRAM. + @retval EFI_DEVICE_ERROR MMRAM cannot be closed. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_CLOSE)( + IN EFI_MM_ACCESS_PROTOCOL *This + ); + +/** + Inhibits access to the MMRAM. + + This function prohibits access to the MMRAM region. This function is usually implemented such + that it is a write-once operation. + + @param[in] This The EFI_MM_ACCESS_PROTOCOL instance. + + @retval EFI_SUCCESS The device was successfully locked. + @retval EFI_UNSUPPORTED The system does not support locking of MMRAM. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_LOCK)( + IN EFI_MM_ACCESS_PROTOCOL *This + ); + +/** + Queries the memory controller for the possible regions that will support MMRAM. + + @param[in] This The EFI_MM_ACCESS_PROTOCOL instance. + @param[in,out] MmramMapSize A pointer to the size, in bytes, of the MmramMemoryMap buffer. + @param[in,out] MmramMap A pointer to the buffer in which firmware places the current memory map. + + @retval EFI_SUCCESS The chipset supported the given resource. + @retval EFI_BUFFER_TOO_SMALL The MmramMap parameter was too small. The current buffer size + needed to hold the memory map is returned in MmramMapSize. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_CAPABILITIES)( + IN CONST EFI_MM_ACCESS_PROTOCOL *This, + IN OUT UINTN *MmramMapSize, + IN OUT EFI_MMRAM_DESCRIPTOR *MmramMap + ); + +/// +/// EFI MM Access Protocol is used to control the visibility of the MMRAM on the platform. +/// It abstracts the location and characteristics of MMRAM. The platform should report all +/// MMRAM via EFI_MM_ACCESS_PROTOCOL. The expectation is that the north bridge or memory +/// controller would publish this protocol. +/// +struct _EFI_MM_ACCESS_PROTOCOL { + EFI_MM_OPEN Open; + EFI_MM_CLOSE Close; + EFI_MM_LOCK Lock; + EFI_MM_CAPABILITIES GetCapabilities; + /// + /// Indicates the current state of the MMRAM. Set to TRUE if MMRAM is locked. + /// + BOOLEAN LockState; + /// + /// Indicates the current state of the MMRAM. Set to TRUE if MMRAM is open. + /// + BOOLEAN OpenState; +}; + +extern EFI_GUID gEfiMmAccessProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MmBase.h b/MdePkg/Include/Protocol/MmBase.h new file mode 100644 index 000000000000..3a8f3e69bb19 --- /dev/null +++ b/MdePkg/Include/Protocol/MmBase.h @@ -0,0 +1,81 @@ +/** @file + EFI MM Base Protocol as defined in the PI 1.5 specification. + + This protocol is utilized by all MM drivers to locate the MM infrastructure services and determine + whether the driver is being invoked inside MMRAM or outside of MMRAM. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_BASE_H_ +#define _MM_BASE_H_ + +#include <Pi/PiMmCis.h> + +#define EFI_MM_BASE_PROTOCOL_GUID \ + { \ + 0xf4ccbfb7, 0xf6e0, 0x47fd, {0x9d, 0xd4, 0x10, 0xa8, 0xf1, 0x50, 0xc1, 0x91 } \ + } + +typedef struct _EFI_MM_BASE_PROTOCOL EFI_MM_BASE_PROTOCOL; + +/** + Service to indicate whether the driver is currently executing in the MM Initialization phase. + + This service is used to indicate whether the driver is currently executing in the MM Initialization + phase. For MM drivers, this will return TRUE in InMmram while inside the driver's entry point and + otherwise FALSE. For combination MM/DXE drivers, this will return FALSE in the DXE launch. For the + MM launch, it behaves as an MM driver. + + @param[in] This The EFI_MM_BASE_PROTOCOL instance. + @param[out] InMmram Pointer to a Boolean which, on return, indicates that the driver is + currently executing inside of MMRAM (TRUE) or outside of MMRAM (FALSE). + + @retval EFI_SUCCESS The call returned successfully. + @retval EFI_INVALID_PARAMETER InMmram was NULL. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_INSIDE_OUT)( + IN CONST EFI_MM_BASE_PROTOCOL *This, + OUT BOOLEAN *InMmram + ) +; + +/** + Returns the location of the Management Mode Service Table (MMST). + + This function returns the location of the Management Mode Service Table (MMST). The use of the + API is such that a driver can discover the location of the MMST in its entry point and then cache it in + some driver global variable so that the MMST can be invoked in subsequent handlers. + + @param[in] This The EFI_MM_BASE_PROTOCOL instance. + @param[in,out] Mmst On return, points to a pointer to the Management Mode Service Table (MMST). + + @retval EFI_SUCCESS The operation was successful. + @retval EFI_INVALID_PARAMETER Mmst was invalid. + @retval EFI_UNSUPPORTED Not in MM. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_GET_MMST_LOCATION)( + IN CONST EFI_MM_BASE_PROTOCOL *This, + IN OUT EFI_MM_SYSTEM_TABLE **Mmst + ) +; + +/// +/// EFI MM Base Protocol is utilized by all MM drivers to locate the MM infrastructure +/// services and determine whether the driver is being invoked inside MMRAM or outside of MMRAM. +/// +struct _EFI_MM_BASE_PROTOCOL { + EFI_MM_INSIDE_OUT InMm; + EFI_MM_GET_MMST_LOCATION GetMmstLocation; +}; + +extern EFI_GUID gEfiMmBaseProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MmCommunication.h b/MdePkg/Include/Protocol/MmCommunication.h new file mode 100644 index 000000000000..f6e2a6f43ffe --- /dev/null +++ b/MdePkg/Include/Protocol/MmCommunication.h @@ -0,0 +1,87 @@ +/** @file + EFI MM Communication Protocol as defined in the PI 1.5 specification. + + This protocol provides a means of communicating between drivers outside of MM and MMI + handlers inside of MM. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_COMMUNICATION_H_ +#define _MM_COMMUNICATION_H_ + +#pragma pack(1) + +/// +/// To avoid confusion in interpreting frames, the communication buffer should always +/// begin with EFI_MM_COMMUNICATE_HEADER +/// +typedef struct { + /// + /// Allows for disambiguation of the message format. + /// + EFI_GUID HeaderGuid; + /// + /// Describes the size of Data (in bytes) and does not include the size of the header. + /// + UINTN MessageLength; + /// + /// Designates an array of bytes that is MessageLength in size. + /// + UINT8 Data[1]; +} EFI_MM_COMMUNICATE_HEADER; + +#pragma pack() + +#define EFI_MM_COMMUNICATION_PROTOCOL_GUID \ + { \ + 0xc68ed8e2, 0x9dc6, 0x4cbd, { 0x9d, 0x94, 0xdb, 0x65, 0xac, 0xc5, 0xc3, 0x32 } \ + } + +typedef struct _EFI_MM_COMMUNICATION_PROTOCOL EFI_MM_COMMUNICATION_PROTOCOL; + +/** + Communicates with a registered handler. + + This function provides a service to send and receive messages from a registered UEFI service. + + @param[in] This The EFI_MM_COMMUNICATION_PROTOCOL instance. + @param[in] CommBuffer A pointer to the buffer to convey into MMRAM. + @param[in] CommSize The size of the data buffer being passed in. On exit, the size of data + being returned. Zero if the handler does not wish to reply with any data. + This parameter is optional and may be NULL. + + @retval EFI_SUCCESS The message was successfully posted. + @retval EFI_INVALID_PARAMETER The CommBuffer was NULL. + @retval EFI_BAD_BUFFER_SIZE The buffer is too large for the MM implementation. + If this error is returned, the MessageLength field + in the CommBuffer header or the integer pointed by + CommSize, are updated to reflect the maximum payload + size the implementation can accommodate. + @retval EFI_ACCESS_DENIED The CommunicateBuffer parameter or CommSize parameter, + if not omitted, are in address range that cannot be + accessed by the MM environment. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_COMMUNICATE)( + IN CONST EFI_MM_COMMUNICATION_PROTOCOL *This, + IN OUT VOID *CommBuffer, + IN OUT UINTN *CommSize OPTIONAL + ); + +/// +/// EFI MM Communication Protocol provides runtime services for communicating +/// between DXE drivers and a registered MMI handler. +/// +struct _EFI_MM_COMMUNICATION_PROTOCOL { + EFI_MM_COMMUNICATE Communicate; +}; + +extern EFI_GUID gEfiMmCommunicationProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MmCommunication2.h b/MdePkg/Include/Protocol/MmCommunication2.h new file mode 100644 index 000000000000..2e02dbc452a4 --- /dev/null +++ b/MdePkg/Include/Protocol/MmCommunication2.h @@ -0,0 +1,69 @@ +/** @file + EFI MM Communication Protocol 2 as defined in the PI 1.7 errata A specification. + + This protocol provides a means of communicating between drivers outside of MM and MMI + handlers inside of MM. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + Copyright (c) 2019, Arm Limited. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_COMMUNICATION2_H_ +#define _MM_COMMUNICATION2_H_ + +#include <Protocol/MmCommunication.h> + +#define EFI_MM_COMMUNICATION2_PROTOCOL_GUID \ + { \ + 0x378daedc, 0xf06b, 0x4446, { 0x83, 0x14, 0x40, 0xab, 0x93, 0x3c, 0x87, 0xa3 } \ + } + +typedef struct _EFI_MM_COMMUNICATION2_PROTOCOL EFI_MM_COMMUNICATION2_PROTOCOL; + +/** + Communicates with a registered handler. + + This function provides a service to send and receive messages from a registered UEFI service. + + @param[in] This The EFI_MM_COMMUNICATION_PROTOCOL instance. + @param[in] CommBufferPhysical Physical address of the MM communication buffer + @param[in] CommBufferVirtual Virtual address of the MM communication buffer + @param[in] CommSize The size of the data buffer being passed in. On exit, the size of data + being returned. Zero if the handler does not wish to reply with any data. + This parameter is optional and may be NULL. + + @retval EFI_SUCCESS The message was successfully posted. + @retval EFI_INVALID_PARAMETER CommBufferPhysical was NULL or CommBufferVirtual was NULL. + @retval EFI_BAD_BUFFER_SIZE The buffer is too large for the MM implementation. + If this error is returned, the MessageLength field + in the CommBuffer header or the integer pointed by + CommSize, are updated to reflect the maximum payload + size the implementation can accommodate. + @retval EFI_ACCESS_DENIED The CommunicateBuffer parameter or CommSize parameter, + if not omitted, are in address range that cannot be + accessed by the MM environment. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_COMMUNICATE2)( + IN CONST EFI_MM_COMMUNICATION2_PROTOCOL *This, + IN OUT VOID *CommBufferPhysical, + IN OUT VOID *CommBufferVirtual, + IN OUT UINTN *CommSize OPTIONAL + ); + +/// +/// EFI MM Communication Protocol provides runtime services for communicating +/// between DXE drivers and a registered MMI handler. +/// +struct _EFI_MM_COMMUNICATION2_PROTOCOL { + EFI_MM_COMMUNICATE2 Communicate; +}; + +extern EFI_GUID gEfiMmCommunication2ProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MmConfiguration.h b/MdePkg/Include/Protocol/MmConfiguration.h new file mode 100644 index 000000000000..bca926621358 --- /dev/null +++ b/MdePkg/Include/Protocol/MmConfiguration.h @@ -0,0 +1,80 @@ +/** @file + EFI MM Configuration Protocol as defined in the PI 1.5 specification. + + This protocol is used to: + 1) report the portions of MMRAM regions which cannot be used for the MMRAM heap. + 2) register the MM Foundation entry point with the processor code. The entry + point will be invoked by the MM processor entry code. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_CONFIGURATION_H_ +#define _MM_CONFIGURATION_H_ + +#include <Pi/PiMmCis.h> + +#define EFI_MM_CONFIGURATION_PROTOCOL_GUID \ + { \ + 0x26eeb3de, 0xb689, 0x492e, {0x80, 0xf0, 0xbe, 0x8b, 0xd7, 0xda, 0x4b, 0xa7 } \ + } + +/// +/// Structure describing a MMRAM region which cannot be used for the MMRAM heap. +/// +typedef struct _EFI_MM_RESERVED_MMRAM_REGION { + /// + /// Starting address of the reserved MMRAM area, as it appears while MMRAM is open. + /// Ignored if MmramReservedSize is 0. + /// + EFI_PHYSICAL_ADDRESS MmramReservedStart; + /// + /// Number of bytes occupied by the reserved MMRAM area. A size of zero indicates the + /// last MMRAM area. + /// + UINT64 MmramReservedSize; +} EFI_MM_RESERVED_MMRAM_REGION; + +typedef struct _EFI_MM_CONFIGURATION_PROTOCOL EFI_MM_CONFIGURATION_PROTOCOL; + +/** + Register the MM Foundation entry point. + + This function registers the MM Foundation entry point with the processor code. This entry point + will be invoked by the MM Processor entry code. + + @param[in] This The EFI_MM_CONFIGURATION_PROTOCOL instance. + @param[in] MmEntryPoint MM Foundation entry point. + + @retval EFI_SUCCESS Success to register MM Entry Point. + @retval EFI_INVALID_PARAMETER MmEntryPoint is NULL. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_REGISTER_MM_ENTRY)( + IN CONST EFI_MM_CONFIGURATION_PROTOCOL *This, + IN EFI_MM_ENTRY_POINT MmEntryPoint + ); + +/// +/// The EFI MM Configuration Protocol is a mandatory protocol published by a DXE CPU driver to +/// indicate which areas within MMRAM are reserved for use by the CPU for any purpose, +/// such as stack, save state or MM entry point. +/// +/// The RegistermmEntry() function allows the MM IPL DXE driver to register the MM +/// Foundation entry point with the MM entry vector code. +/// +struct _EFI_MM_CONFIGURATION_PROTOCOL { + /// + /// A pointer to an array MMRAM ranges used by the initial MM entry code. + /// + EFI_MM_RESERVED_MMRAM_REGION *MmramReservedRegions; + EFI_MM_REGISTER_MM_ENTRY RegisterMmEntry; +}; + +extern EFI_GUID gEfiMmConfigurationProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MmControl.h b/MdePkg/Include/Protocol/MmControl.h new file mode 100644 index 000000000000..92a5b10efb3d --- /dev/null +++ b/MdePkg/Include/Protocol/MmControl.h @@ -0,0 +1,100 @@ +/** @file + EFI MM Control Protocol as defined in the PI 1.5 specification. + + This protocol is used initiate synchronous MMI activations. This protocol could be published by a + processor driver to abstract the MMI IPI or a driver which abstracts the ASIC that is supporting the + APM port. Because of the possibility of performing MMI IPI transactions, the ability to generate this + event from a platform chipset agent is an optional capability for both IA-32 and x64-based systems. + + The EFI_MM_CONTROL_PROTOCOL is produced by a runtime driver. It provides an + abstraction of the platform hardware that generates an MMI. There are often I/O ports that, when + accessed, will generate the MMI. Also, the hardware optionally supports the periodic generation of + these signals. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_CONTROL_H_ +#define _MM_CONTROL_H_ + +#include <PiDxe.h> + +#define EFI_MM_CONTROL_PROTOCOL_GUID \ + { \ + 0x843dc720, 0xab1e, 0x42cb, {0x93, 0x57, 0x8a, 0x0, 0x78, 0xf3, 0x56, 0x1b} \ + } + +typedef struct _EFI_MM_CONTROL_PROTOCOL EFI_MM_CONTROL_PROTOCOL; +typedef UINTN EFI_MM_PERIOD; + +/** + Invokes MMI activation from either the preboot or runtime environment. + + This function generates an MMI. + + @param[in] This The EFI_MM_CONTROL_PROTOCOL instance. + @param[in,out] CommandPort The value written to the command port. + @param[in,out] DataPort The value written to the data port. + @param[in] Periodic Optional mechanism to engender a periodic stream. + @param[in] ActivationInterval Optional parameter to repeat at this period one + time or, if the Periodic Boolean is set, periodically. + + @retval EFI_SUCCESS The MMI/PMI has been engendered. + @retval EFI_DEVICE_ERROR The timing is unsupported. + @retval EFI_INVALID_PARAMETER The activation period is unsupported. + @retval EFI_INVALID_PARAMETER The last periodic activation has not been cleared. + @retval EFI_NOT_STARTED The MM base service has not been initialized. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_ACTIVATE)( + IN CONST EFI_MM_CONTROL_PROTOCOL *This, + IN OUT UINT8 *CommandPort OPTIONAL, + IN OUT UINT8 *DataPort OPTIONAL, + IN BOOLEAN Periodic OPTIONAL, + IN UINTN ActivationInterval OPTIONAL + ); + +/** + Clears any system state that was created in response to the Trigger() call. + + This function acknowledges and causes the deassertion of the MMI activation source. + + @param[in] This The EFI_MM_CONTROL_PROTOCOL instance. + @param[in] Periodic Optional parameter to repeat at this period one time + + @retval EFI_SUCCESS The MMI/PMI has been engendered. + @retval EFI_DEVICE_ERROR The source could not be cleared. + @retval EFI_INVALID_PARAMETER The service did not support the Periodic input argument. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_DEACTIVATE)( + IN CONST EFI_MM_CONTROL_PROTOCOL *This, + IN BOOLEAN Periodic OPTIONAL + ); + +/// +/// The EFI_MM_CONTROL_PROTOCOL is produced by a runtime driver. It provides an +/// abstraction of the platform hardware that generates an MMI. There are often I/O ports that, when +/// accessed, will generate the MMI. Also, the hardware optionally supports the periodic generation of +/// these signals. +/// +struct _EFI_MM_CONTROL_PROTOCOL { + EFI_MM_ACTIVATE Trigger; + EFI_MM_DEACTIVATE Clear; + /// + /// Minimum interval at which the platform can set the period. A maximum is not + /// specified in that the MM infrastructure code can emulate a maximum interval that is + /// greater than the hardware capabilities by using software emulation in the MM + /// infrastructure code. + /// + EFI_MM_PERIOD MinimumTriggerPeriod; +}; + +extern EFI_GUID gEfiMmControlProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MmCpu.h b/MdePkg/Include/Protocol/MmCpu.h new file mode 100644 index 000000000000..37df7a5fb758 --- /dev/null +++ b/MdePkg/Include/Protocol/MmCpu.h @@ -0,0 +1,241 @@ +/** @file + EFI MM CPU Protocol as defined in the PI 1.5 specification. + + This protocol allows MM drivers to access architecture-standard registers from any of the CPU + save state areas. In some cases, difference processors provide the same information in the save state, + but not in the same format. These so-called pseudo-registers provide this information in a standard + format. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_CPU_H_ +#define _MM_CPU_H_ + +#define EFI_MM_CPU_PROTOCOL_GUID \ + { \ + 0xeb346b97, 0x975f, 0x4a9f, { 0x8b, 0x22, 0xf8, 0xe9, 0x2b, 0xb3, 0xd5, 0x69 } \ + } + +/// +/// Save State register index +/// +typedef enum { + /// + /// x86/X64 standard registers + /// + EFI_MM_SAVE_STATE_REGISTER_GDTBASE = 4, + EFI_MM_SAVE_STATE_REGISTER_IDTBASE = 5, + EFI_MM_SAVE_STATE_REGISTER_LDTBASE = 6, + EFI_MM_SAVE_STATE_REGISTER_GDTLIMIT = 7, + EFI_MM_SAVE_STATE_REGISTER_IDTLIMIT = 8, + EFI_MM_SAVE_STATE_REGISTER_LDTLIMIT = 9, + EFI_MM_SAVE_STATE_REGISTER_LDTINFO = 10, + EFI_MM_SAVE_STATE_REGISTER_ES = 20, + EFI_MM_SAVE_STATE_REGISTER_CS = 21, + EFI_MM_SAVE_STATE_REGISTER_SS = 22, + EFI_MM_SAVE_STATE_REGISTER_DS = 23, + EFI_MM_SAVE_STATE_REGISTER_FS = 24, + EFI_MM_SAVE_STATE_REGISTER_GS = 25, + EFI_MM_SAVE_STATE_REGISTER_LDTR_SEL = 26, + EFI_MM_SAVE_STATE_REGISTER_TR_SEL = 27, + EFI_MM_SAVE_STATE_REGISTER_DR7 = 28, + EFI_MM_SAVE_STATE_REGISTER_DR6 = 29, + EFI_MM_SAVE_STATE_REGISTER_R8 = 30, + EFI_MM_SAVE_STATE_REGISTER_R9 = 31, + EFI_MM_SAVE_STATE_REGISTER_R10 = 32, + EFI_MM_SAVE_STATE_REGISTER_R11 = 33, + EFI_MM_SAVE_STATE_REGISTER_R12 = 34, + EFI_MM_SAVE_STATE_REGISTER_R13 = 35, + EFI_MM_SAVE_STATE_REGISTER_R14 = 36, + EFI_MM_SAVE_STATE_REGISTER_R15 = 37, + EFI_MM_SAVE_STATE_REGISTER_RAX = 38, + EFI_MM_SAVE_STATE_REGISTER_RBX = 39, + EFI_MM_SAVE_STATE_REGISTER_RCX = 40, + EFI_MM_SAVE_STATE_REGISTER_RDX = 41, + EFI_MM_SAVE_STATE_REGISTER_RSP = 42, + EFI_MM_SAVE_STATE_REGISTER_RBP = 43, + EFI_MM_SAVE_STATE_REGISTER_RSI = 44, + EFI_MM_SAVE_STATE_REGISTER_RDI = 45, + EFI_MM_SAVE_STATE_REGISTER_RIP = 46, + EFI_MM_SAVE_STATE_REGISTER_RFLAGS = 51, + EFI_MM_SAVE_STATE_REGISTER_CR0 = 52, + EFI_MM_SAVE_STATE_REGISTER_CR3 = 53, + EFI_MM_SAVE_STATE_REGISTER_CR4 = 54, + EFI_MM_SAVE_STATE_REGISTER_FCW = 256, + EFI_MM_SAVE_STATE_REGISTER_FSW = 257, + EFI_MM_SAVE_STATE_REGISTER_FTW = 258, + EFI_MM_SAVE_STATE_REGISTER_OPCODE = 259, + EFI_MM_SAVE_STATE_REGISTER_FP_EIP = 260, + EFI_MM_SAVE_STATE_REGISTER_FP_CS = 261, + EFI_MM_SAVE_STATE_REGISTER_DATAOFFSET = 262, + EFI_MM_SAVE_STATE_REGISTER_FP_DS = 263, + EFI_MM_SAVE_STATE_REGISTER_MM0 = 264, + EFI_MM_SAVE_STATE_REGISTER_MM1 = 265, + EFI_MM_SAVE_STATE_REGISTER_MM2 = 266, + EFI_MM_SAVE_STATE_REGISTER_MM3 = 267, + EFI_MM_SAVE_STATE_REGISTER_MM4 = 268, + EFI_MM_SAVE_STATE_REGISTER_MM5 = 269, + EFI_MM_SAVE_STATE_REGISTER_MM6 = 270, + EFI_MM_SAVE_STATE_REGISTER_MM7 = 271, + EFI_MM_SAVE_STATE_REGISTER_XMM0 = 272, + EFI_MM_SAVE_STATE_REGISTER_XMM1 = 273, + EFI_MM_SAVE_STATE_REGISTER_XMM2 = 274, + EFI_MM_SAVE_STATE_REGISTER_XMM3 = 275, + EFI_MM_SAVE_STATE_REGISTER_XMM4 = 276, + EFI_MM_SAVE_STATE_REGISTER_XMM5 = 277, + EFI_MM_SAVE_STATE_REGISTER_XMM6 = 278, + EFI_MM_SAVE_STATE_REGISTER_XMM7 = 279, + EFI_MM_SAVE_STATE_REGISTER_XMM8 = 280, + EFI_MM_SAVE_STATE_REGISTER_XMM9 = 281, + EFI_MM_SAVE_STATE_REGISTER_XMM10 = 282, + EFI_MM_SAVE_STATE_REGISTER_XMM11 = 283, + EFI_MM_SAVE_STATE_REGISTER_XMM12 = 284, + EFI_MM_SAVE_STATE_REGISTER_XMM13 = 285, + EFI_MM_SAVE_STATE_REGISTER_XMM14 = 286, + EFI_MM_SAVE_STATE_REGISTER_XMM15 = 287, + /// + /// Pseudo-Registers + /// + EFI_MM_SAVE_STATE_REGISTER_IO = 512, + EFI_MM_SAVE_STATE_REGISTER_LMA = 513, + EFI_MM_SAVE_STATE_REGISTER_PROCESSOR_ID = 514 +} EFI_MM_SAVE_STATE_REGISTER; + +/// +/// The EFI_MM_SAVE_STATE_REGISTER_LMA pseudo-register values +/// If the processor acts in 32-bit mode at the time the MMI occurred, the pseudo register value +/// EFI_MM_SAVE_STATE_REGISTER_LMA_32BIT is returned in Buffer. Otherwise, +/// EFI_MM_SAVE_STATE_REGISTER_LMA_64BIT is returned in Buffer. +/// +#define EFI_MM_SAVE_STATE_REGISTER_LMA_32BIT 32 +#define EFI_MM_SAVE_STATE_REGISTER_LMA_64BIT 64 + +/// +/// Size width of I/O instruction +/// +typedef enum { + EFI_MM_SAVE_STATE_IO_WIDTH_UINT8 = 0, + EFI_MM_SAVE_STATE_IO_WIDTH_UINT16 = 1, + EFI_MM_SAVE_STATE_IO_WIDTH_UINT32 = 2, + EFI_MM_SAVE_STATE_IO_WIDTH_UINT64 = 3 +} EFI_MM_SAVE_STATE_IO_WIDTH; + +/// +/// Types of I/O instruction +/// +typedef enum { + EFI_MM_SAVE_STATE_IO_TYPE_INPUT = 1, + EFI_MM_SAVE_STATE_IO_TYPE_OUTPUT = 2, + EFI_MM_SAVE_STATE_IO_TYPE_STRING = 4, + EFI_MM_SAVE_STATE_IO_TYPE_REP_PREFIX = 8 +} EFI_MM_SAVE_STATE_IO_TYPE; + +/// +/// Structure of the data which is returned when ReadSaveState() is called with +/// EFI_MM_SAVE_STATE_REGISTER_IO. If there was no I/O then ReadSaveState() will +/// return EFI_NOT_FOUND. +/// +/// This structure describes the I/O operation which was in process when the MMI was generated. +/// +typedef struct _EFI_MM_SAVE_STATE_IO_INFO { + /// + /// For input instruction (IN, INS), this is data read before the MMI occurred. For output + /// instructions (OUT, OUTS) this is data that was written before the MMI occurred. The + /// width of the data is specified by IoWidth. + /// + UINT64 IoData; + /// + /// The I/O port that was being accessed when the MMI was triggered. + /// + UINT16 IoPort; + /// + /// Defines the size width (UINT8, UINT16, UINT32, UINT64) for IoData. + /// + EFI_MM_SAVE_STATE_IO_WIDTH IoWidth; + /// + /// Defines type of I/O instruction. + /// + EFI_MM_SAVE_STATE_IO_TYPE IoType; +} EFI_MM_SAVE_STATE_IO_INFO; + +typedef struct _EFI_MM_CPU_PROTOCOL EFI_MM_CPU_PROTOCOL; + +/** + Read data from the CPU save state. + + This function is used to read the specified number of bytes of the specified register from the CPU + save state of the specified CPU and place the value into the buffer. If the CPU does not support the + specified register Register, then EFI_NOT_FOUND should be returned. If the CPU does not + support the specified register width Width, then EFI_INVALID_PARAMETER is returned. + + @param[in] This The EFI_MM_CPU_PROTOCOL instance. + @param[in] Width The number of bytes to read from the CPU save state. + @param[in] Register Specifies the CPU register to read form the save state. + @param[in] CpuIndex Specifies the zero-based index of the CPU save state. + @param[out] Buffer Upon return, this holds the CPU register value read from the save state. + + @retval EFI_SUCCESS The register was read from Save State. + @retval EFI_NOT_FOUND The register is not defined for the Save State of Processor. + @retval EFI_INVALID_PARAMETER Input parameters are not valid, for example, Processor No or register width + is not correct.This or Buffer is NULL. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_READ_SAVE_STATE)( + IN CONST EFI_MM_CPU_PROTOCOL *This, + IN UINTN Width, + IN EFI_MM_SAVE_STATE_REGISTER Register, + IN UINTN CpuIndex, + OUT VOID *Buffer + ); + + +/** + Write data to the CPU save state. + + This function is used to write the specified number of bytes of the specified register to the CPU save + state of the specified CPU and place the value into the buffer. If the CPU does not support the + specified register Register, then EFI_UNSUPPORTED should be returned. If the CPU does not + support the specified register width Width, then EFI_INVALID_PARAMETER is returned. + + @param[in] This The EFI_MM_CPU_PROTOCOL instance. + @param[in] Width The number of bytes to write to the CPU save state. + @param[in] Register Specifies the CPU register to write to the save state. + @param[in] CpuIndex Specifies the zero-based index of the CPU save state. + @param[in] Buffer Upon entry, this holds the new CPU register value. + + @retval EFI_SUCCESS The register was written to Save State. + @retval EFI_NOT_FOUND The register is not defined for the Save State of Processor. + @retval EFI_INVALID_PARAMETER Input parameters are not valid. For example: + ProcessorIndex or Width is not correct. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_WRITE_SAVE_STATE)( + IN CONST EFI_MM_CPU_PROTOCOL *This, + IN UINTN Width, + IN EFI_MM_SAVE_STATE_REGISTER Register, + IN UINTN CpuIndex, + IN CONST VOID *Buffer + ); + +/// +/// EFI MM CPU Protocol provides access to CPU-related information while in MM. +/// +/// This protocol allows MM drivers to access architecture-standard registers from any of the CPU +/// save state areas. In some cases, difference processors provide the same information in the save state, +/// but not in the same format. These so-called pseudo-registers provide this information in a standard +/// format. +/// +struct _EFI_MM_CPU_PROTOCOL { + EFI_MM_READ_SAVE_STATE ReadSaveState; + EFI_MM_WRITE_SAVE_STATE WriteSaveState; +}; + +extern EFI_GUID gEfiMmCpuProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MmCpuIo.h b/MdePkg/Include/Protocol/MmCpuIo.h new file mode 100644 index 000000000000..f0e7ec6e877b --- /dev/null +++ b/MdePkg/Include/Protocol/MmCpuIo.h @@ -0,0 +1,90 @@ +/** @file + MM CPU I/O 2 protocol as defined in the PI 1.5 specification. + + This protocol provides CPU I/O and memory access within MM. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_CPU_IO_H_ +#define _MM_CPU_IO_H_ + +#define EFI_MM_CPU_IO_PROTOCOL_GUID \ + { \ + 0x3242A9D8, 0xCE70, 0x4AA0, { 0x95, 0x5D, 0x5E, 0x7B, 0x14, 0x0D, 0xE4, 0xD2 } \ + } + +typedef struct _EFI_MM_CPU_IO_PROTOCOL EFI_MM_CPU_IO_PROTOCOL; + +/// +/// Width of the MM CPU I/O operations +/// +typedef enum { + MM_IO_UINT8 = 0, + MM_IO_UINT16 = 1, + MM_IO_UINT32 = 2, + MM_IO_UINT64 = 3 +} EFI_MM_IO_WIDTH; + +/** + Provides the basic memory and I/O interfaces used toabstract accesses to devices. + + The I/O operations are carried out exactly as requested. The caller is + responsible for any alignment and I/O width issues that the bus, device, + platform, or type of I/O might require. + + @param[in] This The EFI_MM_CPU_IO_PROTOCOL instance. + @param[in] Width Signifies the width of the I/O operations. + @param[in] Address The base address of the I/O operations. The caller is + responsible for aligning the Address if required. + @param[in] Count The number of I/O operations to perform. + @param[in,out] Buffer For read operations, the destination buffer to store + the results. For write operations, the source buffer + from which to write data. + + @retval EFI_SUCCESS The data was read from or written to the device. + @retval EFI_UNSUPPORTED The Address is not valid for this system. + @retval EFI_INVALID_PARAMETER Width or Count, or both, were invalid. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack + of resources. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_CPU_IO)( + IN CONST EFI_MM_CPU_IO_PROTOCOL *This, + IN EFI_MM_IO_WIDTH Width, + IN UINT64 Address, + IN UINTN Count, + IN OUT VOID *Buffer + ); + +typedef struct { + /// + /// This service provides the various modalities of memory and I/O read. + /// + EFI_MM_CPU_IO Read; + /// + /// This service provides the various modalities of memory and I/O write. + /// + EFI_MM_CPU_IO Write; +} EFI_MM_IO_ACCESS; + +/// +/// MM CPU I/O Protocol provides CPU I/O and memory access within MM. +/// +struct _EFI_MM_CPU_IO_PROTOCOL { + /// + /// Allows reads and writes to memory-mapped I/O space. + /// + EFI_MM_IO_ACCESS Mem; + /// + /// Allows reads and writes to I/O space. + /// + EFI_MM_IO_ACCESS Io; +}; + +extern EFI_GUID gEfiMmCpuIoProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/MmEndOfDxe.h b/MdePkg/Include/Protocol/MmEndOfDxe.h new file mode 100644 index 000000000000..74f8427efe85 --- /dev/null +++ b/MdePkg/Include/Protocol/MmEndOfDxe.h @@ -0,0 +1,24 @@ +/** @file + MM End Of Dxe protocol introduced in the PI 1.5 specification. + + This protocol is a mandatory protocol published by MM Foundation code. + This protocol is an MM counterpart of the End of DXE Event. + This protocol prorogates End of DXE notification into MM environment. + This protocol is installed prior to installation of the MM Ready to Lock Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_END_OF_DXE_H_ +#define _MM_END_OF_DXE_H_ + +#define EFI_MM_END_OF_DXE_PROTOCOL_GUID \ + { \ + 0x24e70042, 0xd5c5, 0x4260, { 0x8c, 0x39, 0xa, 0xd3, 0xaa, 0x32, 0xe9, 0x3d } \ + } + +extern EFI_GUID gEfiMmEndOfDxeProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/MmGpiDispatch.h b/MdePkg/Include/Protocol/MmGpiDispatch.h new file mode 100644 index 000000000000..877c0e2a2400 --- /dev/null +++ b/MdePkg/Include/Protocol/MmGpiDispatch.h @@ -0,0 +1,119 @@ +/** @file + MM General Purpose Input (GPI) Dispatch Protocol as defined in PI 1.5 Specification + Volume 4 Management Mode Core Interface. + + This protocol provides the parent dispatch service for the General Purpose Input + (GPI) MMI source generator. + + The EFI_MM_GPI_DISPATCH_PROTOCOL provides the ability to install child handlers for the + given event types. Several inputs can be enabled. This purpose of this interface is to generate an + MMI in response to any of these inputs having a true value provided. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This protocol is from PI Version 1.5. + +**/ + +#ifndef _MM_GPI_DISPATCH_H_ +#define _MM_GPI_DISPATCH_H_ + +#include <Pi/PiMmCis.h> + +#define EFI_MM_GPI_DISPATCH_PROTOCOL_GUID \ + { \ + 0x25566b03, 0xb577, 0x4cbf, {0x95, 0x8c, 0xed, 0x66, 0x3e, 0xa2, 0x43, 0x80 } \ + } + +/// +/// The dispatch function's context. +/// +typedef struct { + /// + /// A number from one of 2^64 possible GPIs that can generate an MMI. A + /// 0 corresponds to logical GPI[0]; 1 corresponds to logical GPI[1]; and + /// GpiNum of N corresponds to GPI[N], where N can span from 0 to 2^64-1. + /// + UINT64 GpiNum; +} EFI_MM_GPI_REGISTER_CONTEXT; + +typedef struct _EFI_MM_GPI_DISPATCH_PROTOCOL EFI_MM_GPI_DISPATCH_PROTOCOL; + +/** + Registers a child MMI source dispatch function with a parent MM driver. + + This service registers a function (DispatchFunction) which will be called when an MMI is + generated because of one or more of the GPIs specified by RegisterContext. On return, + DispatchHandle contains a unique handle which may be used later to unregister the function + using UnRegister(). + The DispatchFunction will be called with Context set to the same value as was passed into + this function in RegisterContext and with CommBuffer pointing to another instance of + EFI_MM_GPI_REGISTER_CONTEXT describing the GPIs which actually caused the MMI and + CommBufferSize pointing to the size of the structure. + + @param[in] This Pointer to the EFI_MM_GPI_DISPATCH_PROTOCOL instance. + @param[in] DispatchFunction Function to register for handler when the specified GPI causes an MMI. + @param[in] RegisterContext Pointer to the dispatch function's context. + The caller fills this context in before calling + the register function to indicate to the register + function the GPI(s) for which the dispatch function + should be invoked. + @param[out] DispatchHandle Handle generated by the dispatcher to track the + function instance. + + @retval EFI_SUCCESS The dispatch function has been successfully + registered and the MMI source has been enabled. + @retval EFI_DEVICE_ERROR The driver was unable to enable the MMI source. + @retval EFI_INVALID_PARAMETER RegisterContext is invalid. The GPI input value + is not within valid range. + @retval EFI_OUT_OF_RESOURCES There is not enough memory (system or MM) to manage this child. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_GPI_REGISTER)( + IN CONST EFI_MM_GPI_DISPATCH_PROTOCOL *This, + IN EFI_MM_HANDLER_ENTRY_POINT DispatchFunction, + IN CONST EFI_MM_GPI_REGISTER_CONTEXT *RegisterContext, + OUT EFI_HANDLE *DispatchHandle + ); + +/** + Unregisters a General Purpose Input (GPI) service. + + This service removes the handler associated with DispatchHandle so that it will no longer be + called when the GPI triggers an MMI. + + @param[in] This Pointer to the EFI_MM_GPI_DISPATCH_PROTOCOL instance. + @param[in] DispatchHandle Handle of the service to remove. + + @retval EFI_SUCCESS Handle of the service to remove. + @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_GPI_UNREGISTER)( + IN CONST EFI_MM_GPI_DISPATCH_PROTOCOL *This, + IN EFI_HANDLE DispatchHandle + ); + +/// +/// Interface structure for the MM GPI MMI Dispatch Protocol +/// +/// The MM GPI MMI Dispatch Protocol provides the parent dispatch service +/// for the General Purpose Input (GPI) MMI source generator. +/// +struct _EFI_MM_GPI_DISPATCH_PROTOCOL { + EFI_MM_GPI_REGISTER Register; + EFI_MM_GPI_UNREGISTER UnRegister; + /// + /// Denotes the maximum value of inputs that can have handlers attached. + /// + UINTN NumSupportedGpis; +}; + +extern EFI_GUID gEfiMmGpiDispatchProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MmIoTrapDispatch.h b/MdePkg/Include/Protocol/MmIoTrapDispatch.h new file mode 100644 index 000000000000..4434645035e3 --- /dev/null +++ b/MdePkg/Include/Protocol/MmIoTrapDispatch.h @@ -0,0 +1,130 @@ +/** @file + MM IO Trap Dispatch Protocol as defined in PI 1.5 Specification + Volume 4 Management Mode Core Interface. + + This protocol provides a parent dispatch service for IO trap MMI sources. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This protocol is from PI Version 1.5. + +**/ + +#ifndef _MM_IO_TRAP_DISPATCH_H_ +#define _MM_IO_TRAP_DISPATCH_H_ + +#include <Pi/PiMmCis.h> + +#define EFI_MM_IO_TRAP_DISPATCH_PROTOCOL_GUID \ + { \ + 0x58dc368d, 0x7bfa, 0x4e77, {0xab, 0xbc, 0xe, 0x29, 0x41, 0x8d, 0xf9, 0x30 } \ + } + +/// +/// IO Trap valid types +/// +typedef enum { + WriteTrap, + ReadTrap, + ReadWriteTrap, + IoTrapTypeMaximum +} EFI_MM_IO_TRAP_DISPATCH_TYPE; + +/// +/// IO Trap context structure containing information about the +/// IO trap event that should invoke the handler +/// +typedef struct { + UINT16 Address; + UINT16 Length; + EFI_MM_IO_TRAP_DISPATCH_TYPE Type; +} EFI_MM_IO_TRAP_REGISTER_CONTEXT; + +/// +/// IO Trap context structure containing information about the IO trap that occurred +/// +typedef struct { + UINT32 WriteData; +} EFI_MM_IO_TRAP_CONTEXT; + +typedef struct _EFI_MM_IO_TRAP_DISPATCH_PROTOCOL EFI_MM_IO_TRAP_DISPATCH_PROTOCOL; + +/** + Register an IO trap MMI child handler for a specified MMI. + + This service registers a function (DispatchFunction) which will be called when an MMI is + generated because of an access to an I/O port specified by RegisterContext. On return, + DispatchHandle contains a unique handle which may be used later to unregister the function + using UnRegister(). If the base of the I/O range specified is zero, then an I/O range with the + specified length and characteristics will be allocated and the Address field in RegisterContext + updated. If no range could be allocated, then EFI_OUT_OF_RESOURCES will be returned. + + The service will not perform GCD allocation if the base address is non-zero or + EFI_MM_READY_TO_LOCK has been installed. In this case, the caller is responsible for the + existence and allocation of the specific IO range. + An error may be returned if some or all of the requested resources conflict with an existing IO trap + child handler. + + It is not required that implementations will allow multiple children for a single IO trap MMI source. + Some implementations may support multiple children. + The DispatchFunction will be called with Context updated to contain information + concerning the I/O action that actually happened and is passed in RegisterContext, with + CommBuffer pointing to the data actually written and CommBufferSize pointing to the size of + the data in CommBuffer. + + @param[in] This Pointer to the EFI_MM_IO_TRAP_DISPATCH_PROTOCOL instance. + @param[in] DispatchFunction Function to register for handler when I/O trap location is accessed. + @param[in] RegisterContext Pointer to the dispatch function's context. The caller fills this + context in before calling the register function to indicate to the register + function the IO trap MMI source for which the dispatch function should be invoked. + @param[out] DispatchHandle Handle of the dispatch function, for when interfacing with the parent MM driver. + + @retval EFI_SUCCESS The dispatch function has been successfully registered. + @retval EFI_DEVICE_ERROR The driver was unable to complete due to hardware error. + @retval EFI_OUT_OF_RESOURCES Insufficient resources are available to fulfill the IO trap range request. + @retval EFI_INVALID_PARAMETER RegisterContext is invalid. The input value is not within a valid range. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_IO_TRAP_DISPATCH_REGISTER)( + IN CONST EFI_MM_IO_TRAP_DISPATCH_PROTOCOL *This, + IN EFI_MM_HANDLER_ENTRY_POINT DispatchFunction, + IN OUT EFI_MM_IO_TRAP_REGISTER_CONTEXT *RegisterContext, + OUT EFI_HANDLE *DispatchHandle + ); + +/** + Unregister a child MMI source dispatch function with a parent MM driver. + + This service removes a previously installed child dispatch handler. This does not guarantee that the + system resources will be freed from the GCD. + + @param[in] This Pointer to the EFI_MM_IO_TRAP_DISPATCH_PROTOCOL instance. + @param[in] DispatchHandle Handle of the child service to remove. + + @retval EFI_SUCCESS The dispatch function has been successfully unregistered. + @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_IO_TRAP_DISPATCH_UNREGISTER)( + IN CONST EFI_MM_IO_TRAP_DISPATCH_PROTOCOL *This, + IN EFI_HANDLE DispatchHandle + ); + +/// +/// Interface structure for the MM IO Trap Dispatch Protocol. +/// +/// This protocol provides a parent dispatch service for IO trap MMI sources. +/// +struct _EFI_MM_IO_TRAP_DISPATCH_PROTOCOL { + EFI_MM_IO_TRAP_DISPATCH_REGISTER Register; + EFI_MM_IO_TRAP_DISPATCH_UNREGISTER UnRegister; +}; + +extern EFI_GUID gEfiMmIoTrapDispatchProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MmMp.h b/MdePkg/Include/Protocol/MmMp.h new file mode 100644 index 000000000000..4f67ffcf3011 --- /dev/null +++ b/MdePkg/Include/Protocol/MmMp.h @@ -0,0 +1,333 @@ +/** @file + EFI MM MP Protocol is defined in the PI 1.5 specification. + + The MM MP protocol provides a set of functions to allow execution of procedures on processors that + have entered MM. This protocol has the following properties: + 1. The caller can only invoke execution of a procedure on a processor, other than the caller, that + has also entered MM. + 2. It is possible to invoke a procedure on multiple processors. Supports blocking and non-blocking + modes of operation. + + Copyright (c) 2019, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_MP_H_ +#define _MM_MP_H_ + +#include <Pi/PiMmCis.h> + +#define EFI_MM_MP_PROTOCOL_GUID \ + { \ + 0x5d5450d7, 0x990c, 0x4180, {0xa8, 0x3, 0x8e, 0x63, 0xf0, 0x60, 0x83, 0x7 } \ + } + +// +// Revision definition. +// +#define EFI_MM_MP_PROTOCOL_REVISION 0x00 + +// +// Attribute flags +// +#define EFI_MM_MP_TIMEOUT_SUPPORTED 0x01 + +// +// Completion token +// +typedef VOID* MM_COMPLETION; + +typedef struct { + MM_COMPLETION Completion; + EFI_STATUS Status; +} MM_DISPATCH_COMPLETION_TOKEN; + +typedef struct _EFI_MM_MP_PROTOCOL EFI_MM_MP_PROTOCOL; + +/** + Service to retrieves the number of logical processor in the platform. + + @param[in] This The EFI_MM_MP_PROTOCOL instance. + @param[out] NumberOfProcessors Pointer to the total number of logical processors in the system, + including the BSP and all APs. + + @retval EFI_SUCCESS The number of processors was retrieved successfully + @retval EFI_INVALID_PARAMETER NumberOfProcessors is NULL +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_GET_NUMBER_OF_PROCESSORS) ( + IN CONST EFI_MM_MP_PROTOCOL *This, + OUT UINTN *NumberOfProcessors +); + + +/** + This service allows the caller to invoke a procedure one of the application processors (AP). This + function uses an optional token parameter to support blocking and non-blocking modes. If the token + is passed into the call, the function will operate in a non-blocking fashion and the caller can + check for completion with CheckOnProcedure or WaitForProcedure. + + @param[in] This The EFI_MM_MP_PROTOCOL instance. + @param[in] Procedure A pointer to the procedure to be run on the designated target + AP of the system. Type EFI_AP_PROCEDURE2 is defined below in + related definitions. + @param[in] CpuNumber The zero-based index of the processor number of the target + AP, on which the code stream is supposed to run. If the number + points to the calling processor then it will not run the + supplied code. + @param[in] TimeoutInMicroseconds Indicates the time limit in microseconds for this AP to + finish execution of Procedure, either for blocking or + non-blocking mode. Zero means infinity. If the timeout + expires before this AP returns from Procedure, then Procedure + on the AP is terminated. If the timeout expires in blocking + mode, the call returns EFI_TIMEOUT. If the timeout expires + in non-blocking mode, the timeout determined can be through + CheckOnProcedure or WaitForProcedure. + Note that timeout support is optional. Whether an + implementation supports this feature, can be determined via + the Attributes data member. + @param[in,out] ProcedureArguments Allows the caller to pass a list of parameters to the code + that is run by the AP. It is an optional common mailbox + between APs and the caller to share information. + @param[in,out] Token This is parameter is broken into two components: + 1.Token->Completion is an optional parameter that allows the + caller to execute the procedure in a blocking or non-blocking + fashion. If it is NULL the call is blocking, and the call will + not return until the AP has completed the procedure. If the + token is not NULL, the call will return immediately. The caller + can check whether the procedure has completed with + CheckOnProcedure or WaitForProcedure. + 2.Token->Status The implementation updates the address pointed + at by this variable with the status code returned by Procedure + when it completes execution on the target AP, or with EFI_TIMEOUT + if the Procedure fails to complete within the optional timeout. + The implementation will update this variable with EFI_NOT_READY + prior to starting Procedure on the target AP. + @param[in,out] CPUStatus This optional pointer may be used to get the status code returned + by Procedure when it completes execution on the target AP, or with + EFI_TIMEOUT if the Procedure fails to complete within the optional + timeout. The implementation will update this variable with + EFI_NOT_READY prior to starting Procedure on the target AP. + + @retval EFI_SUCCESS In the blocking case, this indicates that Procedure has completed + execution on the target AP. + In the non-blocking case this indicates that the procedure has + been successfully scheduled for execution on the target AP. + @retval EFI_INVALID_PARAMETER The input arguments are out of range. Either the target AP is the + caller of the function, or the Procedure or Token is NULL + @retval EFI_NOT_READY If the target AP is busy executing another procedure + @retval EFI_ALREADY_STARTED Token is already in use for another procedure + @retval EFI_TIMEOUT In blocking mode, the timeout expired before the specified AP + has finished +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_DISPATCH_PROCEDURE) ( + IN CONST EFI_MM_MP_PROTOCOL *This, + IN EFI_AP_PROCEDURE2 Procedure, + IN UINTN CpuNumber, + IN UINTN TimeoutInMicroseconds, + IN OUT VOID *ProcedureArguments OPTIONAL, + IN OUT MM_COMPLETION *Token, + IN OUT EFI_STATUS *CPUStatus +); + +/** + This service allows the caller to invoke a procedure on all running application processors (AP) + except the caller. This function uses an optional token parameter to support blocking and + nonblocking modes. If the token is passed into the call, the function will operate in a non-blocking + fashion and the caller can check for completion with CheckOnProcedure or WaitForProcedure. + + It is not necessary for the implementation to run the procedure on every processor on the platform. + Processors that are powered down in such a way that they cannot respond to interrupts, may be + excluded from the broadcast. + + + @param[in] This The EFI_MM_MP_PROTOCOL instance. + @param[in] Procedure A pointer to the code stream to be run on the APs that have + entered MM. Type EFI_AP_PROCEDURE is defined below in related + definitions. + @param[in] TimeoutInMicroseconds Indicates the time limit in microseconds for the APs to finish + execution of Procedure, either for blocking or non-blocking mode. + Zero means infinity. If the timeout expires before all APs return + from Procedure, then Procedure on the failed APs is terminated. If + the timeout expires in blocking mode, the call returns EFI_TIMEOUT. + If the timeout expires in non-blocking mode, the timeout determined + can be through CheckOnProcedure or WaitForProcedure. + Note that timeout support is optional. Whether an implementation + supports this feature can be determined via the Attributes data + member. + @param[in,out] ProcedureArguments Allows the caller to pass a list of parameters to the code + that is run by the AP. It is an optional common mailbox + between APs and the caller to share information. + @param[in,out] Token This is parameter is broken into two components: + 1.Token->Completion is an optional parameter that allows the + caller to execute the procedure in a blocking or non-blocking + fashion. If it is NULL the call is blocking, and the call will + not return until the AP has completed the procedure. If the + token is not NULL, the call will return immediately. The caller + can check whether the procedure has completed with + CheckOnProcedure or WaitForProcedure. + 2.Token->Status The implementation updates the address pointed + at by this variable with the status code returned by Procedure + when it completes execution on the target AP, or with EFI_TIMEOUT + if the Procedure fails to complete within the optional timeout. + The implementation will update this variable with EFI_NOT_READY + prior to starting Procedure on the target AP + @param[in,out] CPUStatus This optional pointer may be used to get the individual status + returned by every AP that participated in the broadcast. This + parameter if used provides the base address of an array to hold + the EFI_STATUS value of each AP in the system. The size of the + array can be ascertained by the GetNumberOfProcessors function. + As mentioned above, the broadcast may not include every processor + in the system. Some implementations may exclude processors that + have been powered down in such a way that they are not responsive + to interrupts. Additionally the broadcast excludes the processor + which is making the BroadcastProcedure call. For every excluded + processor, the array entry must contain a value of EFI_NOT_STARTED + + @retval EFI_SUCCESS In the blocking case, this indicates that Procedure has completed + execution on the APs. In the non-blocking case this indicates that + the procedure has been successfully scheduled for execution on the + APs. + @retval EFI_INVALID_PARAMETER Procedure or Token is NULL. + @retval EFI_NOT_READY If a target AP is busy executing another procedure. + @retval EFI_TIMEOUT In blocking mode, the timeout expired before all enabled APs have + finished. + @retval EFI_ALREADY_STARTED Before the AP procedure associated with the Token is finished, the + same Token cannot be used to dispatch or broadcast another procedure. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_BROADCAST_PROCEDURE) ( + IN CONST EFI_MM_MP_PROTOCOL *This, + IN EFI_AP_PROCEDURE2 Procedure, + IN UINTN TimeoutInMicroseconds, + IN OUT VOID *ProcedureArguments OPTIONAL, + IN OUT MM_COMPLETION *Token, + IN OUT EFI_STATUS *CPUStatus +); + + +/** + This service allows the caller to set a startup procedure that will be executed when an AP powers + up from a state where core configuration and context is lost. The procedure is execution has the + following properties: + 1. The procedure executes before the processor is handed over to the operating system. + 2. All processors execute the same startup procedure. + 3. The procedure may run in parallel with other procedures invoked through the functions in this + protocol, or with processors that are executing an MM handler or running in the operating system. + + + @param[in] This The EFI_MM_MP_PROTOCOL instance. + @param[in] Procedure A pointer to the code stream to be run on the designated target AP + of the system. Type EFI_AP_PROCEDURE is defined below in Volume 2 + with the related definitions of + EFI_MP_SERVICES_PROTOCOL.StartupAllAPs. + If caller may pass a value of NULL to deregister any existing + startup procedure. + @param[in,out] ProcedureArguments Allows the caller to pass a list of parameters to the code that is + run by the AP. It is an optional common mailbox between APs and + the caller to share information + + @retval EFI_SUCCESS The Procedure has been set successfully. + @retval EFI_INVALID_PARAMETER The Procedure is NULL. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_SET_STARTUP_PROCEDURE) ( + IN CONST EFI_MM_MP_PROTOCOL *This, + IN EFI_AP_PROCEDURE Procedure, + IN OUT VOID *ProcedureArguments OPTIONAL +); + +/** + When non-blocking execution of a procedure on an AP is invoked with DispatchProcedure, + via the use of a token, this function can be used to check for completion of the procedure on the AP. + The function takes the token that was passed into the DispatchProcedure call. If the procedure + is complete, and therefore it is now possible to run another procedure on the same AP, this function + returns EFI_SUCESS. In this case the status returned by the procedure that executed on the AP is + returned in the token's Status field. If the procedure has not yet completed, then this function + returns EFI_NOT_READY. + + When a non-blocking execution of a procedure is invoked with BroadcastProcedure, via the + use of a token, this function can be used to check for completion of the procedure on all the + broadcast APs. The function takes the token that was passed into the BroadcastProcedure + call. If the procedure is complete on all broadcast APs this function returns EFI_SUCESS. In this + case the Status field in the token passed into the function reflects the overall result of the + invocation, which may be EFI_SUCCESS, if all executions succeeded, or the first observed failure. + If the procedure has not yet completed on the broadcast APs, the function returns + EFI_NOT_READY. + + @param[in] This The EFI_MM_MP_PROTOCOL instance. + @param[in] Token This parameter describes the token that was passed into + DispatchProcedure or BroadcastProcedure. + + @retval EFI_SUCCESS Procedure has completed. + @retval EFI_NOT_READY The Procedure has not completed. + @retval EFI_INVALID_PARAMETER Token or Token->Completion is NULL + @retval EFI_NOT_FOUND Token is not currently in use for a non-blocking call + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_CHECK_FOR_PROCEDURE) ( + IN CONST EFI_MM_MP_PROTOCOL *This, + IN MM_COMPLETION Token +); + +/** + When a non-blocking execution of a procedure on an AP is invoked via DispatchProcedure, + this function will block the caller until the remote procedure has completed on the designated AP. + The non-blocking procedure invocation is identified by the Token parameter, which must match the + token that used when DispatchProcedure was called. Upon completion the status returned by + the procedure that executed on the AP is used to update the token's Status field. + + When a non-blocking execution of a procedure on an AP is invoked via BroadcastProcedure + this function will block the caller until the remote procedure has completed on all of the APs that + entered MM. The non-blocking procedure invocation is identified by the Token parameter, which + must match the token that used when BroadcastProcedure was called. Upon completion the + overall status returned by the procedures that executed on the broadcast AP is used to update the + token's Status field. The overall status may be EFI_SUCCESS, if all executions succeeded, or the + first observed failure. + + + @param[in] This The EFI_MM_MP_PROTOCOL instance. + @param[in] Token This parameter describes the token that was passed into + DispatchProcedure or BroadcastProcedure. + + @retval EFI_SUCCESS Procedure has completed. + @retval EFI_INVALID_PARAMETER Token or Token->Completion is NULL + @retval EFI_NOT_FOUND Token is not currently in use for a non-blocking call + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_WAIT_FOR_PROCEDURE) ( + IN CONST EFI_MM_MP_PROTOCOL *This, + IN MM_COMPLETION Token +); + + + +/// +/// The MM MP protocol provides a set of functions to allow execution of procedures on processors that +/// have entered MM. +/// +struct _EFI_MM_MP_PROTOCOL { + UINT32 Revision; + UINT32 Attributes; + EFI_MM_GET_NUMBER_OF_PROCESSORS GetNumberOfProcessors; + EFI_MM_DISPATCH_PROCEDURE DispatchProcedure; + EFI_MM_BROADCAST_PROCEDURE BroadcastProcedure; + EFI_MM_SET_STARTUP_PROCEDURE SetStartupProcedure; + EFI_CHECK_FOR_PROCEDURE CheckForProcedure; + EFI_WAIT_FOR_PROCEDURE WaitForProcedure; +}; + +extern EFI_GUID gEfiMmMpProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/MmPciRootBridgeIo.h b/MdePkg/Include/Protocol/MmPciRootBridgeIo.h new file mode 100644 index 000000000000..cb5f569eec73 --- /dev/null +++ b/MdePkg/Include/Protocol/MmPciRootBridgeIo.h @@ -0,0 +1,31 @@ +/** @file + MM PCI Root Bridge IO protocol as defined in the PI 1.5 specification. + + This protocol provides PCI I/O and memory access within MM. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_PCI_ROOT_BRIDGE_IO_H_ +#define _MM_PCI_ROOT_BRIDGE_IO_H_ + +#include <Protocol/PciRootBridgeIo.h> + +#define EFI_MM_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID \ + { \ + 0x8bc1714d, 0xffcb, 0x41c3, { 0x89, 0xdc, 0x6c, 0x74, 0xd0, 0x6d, 0x98, 0xea } \ + } + +/// +/// This protocol provides the same functionality as the PCI Root Bridge I/O Protocol defined in the +/// UEFI 2.1 Specifcation, section 13.2, except that the functions for Map() and Unmap() may return +/// EFI_UNSUPPORTED. +/// +typedef EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL EFI_MM_PCI_ROOT_BRIDGE_IO_PROTOCOL; + +extern EFI_GUID gEfiMmPciRootBridgeIoProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MmPeriodicTimerDispatch.h b/MdePkg/Include/Protocol/MmPeriodicTimerDispatch.h new file mode 100644 index 000000000000..74b6c0062041 --- /dev/null +++ b/MdePkg/Include/Protocol/MmPeriodicTimerDispatch.h @@ -0,0 +1,164 @@ +/** @file + MM Periodic Timer Dispatch Protocol as defined in PI 1.5 Specification + Volume 4 Management Mode Core Interface. + + This protocol provides the parent dispatch service for the periodical timer MMI source generator. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This protocol is from PI Version 1.5. + +**/ + +#ifndef _MM_PERIODIC_TIMER_DISPATCH_H_ +#define _MM_PERIODIC_TIMER_DISPATCH_H_ + +#include <Pi/PiMmCis.h> + +#define EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL_GUID \ + { \ + 0x4cec368e, 0x8e8e, 0x4d71, {0x8b, 0xe1, 0x95, 0x8c, 0x45, 0xfc, 0x8a, 0x53 } \ + } + +/// +/// Example: A chipset supports periodic MMIs on every 64ms or 2 seconds. +/// A child wishes schedule a period MMI to fire on a period of 3 seconds, there +/// are several ways to approach the problem: +/// 1. The child may accept a 4 second periodic rate, in which case it registers with +/// Period = 40000 +/// MmiTickInterval = 20000 +/// The resulting MMI will occur every 2 seconds with the child called back on +/// every 2nd MMI. +/// NOTE: the same result would occur if the child set MmiTickInterval = 0. +/// 2. The child may choose the finer granularity MMI (64ms): +/// Period = 30000 +/// MmiTickInterval = 640 +/// The resulting MMI will occur every 64ms with the child called back on +/// every 47th MMI. +/// NOTE: the child driver should be aware that this will result in more +/// MMIs occuring during system runtime which can negatively impact system +/// performance. +/// +typedef struct { + /// + /// The minimum period of time in 100 nanosecond units that the child gets called. The + /// child will be called back after a time greater than the time Period. + /// + UINT64 Period; + /// + /// The period of time interval between MMIs. Children of this interface should use this + /// field when registering for periodic timer intervals when a finer granularity periodic + /// MMI is desired. + /// + UINT64 MmiTickInterval; +} EFI_MM_PERIODIC_TIMER_REGISTER_CONTEXT; + +/// +/// The DispatchFunction will be called with Context set to the same value as was passed into +/// Register() in RegisterContext and with CommBuffer pointing to an instance of +/// EFI_MM_PERIODIC_TIMER_CONTEXT and CommBufferSize pointing to its size. +/// +typedef struct { + /// + /// ElapsedTime is the actual time in 100 nanosecond units elapsed since last called, a + /// value of 0 indicates an unknown amount of time. + /// + UINT64 ElapsedTime; +} EFI_MM_PERIODIC_TIMER_CONTEXT; + +typedef struct _EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL; + +/** + Register a child MMI source dispatch function for MM periodic timer. + + This service registers a function (DispatchFunction) which will be called when at least the + amount of time specified by RegisterContext has elapsed. On return, DispatchHandle + contains a unique handle which may be used later to unregister the function using UnRegister(). + The DispatchFunction will be called with Context set to the same value as was passed into + this function in RegisterContext and with CommBuffer pointing to an instance of + EFI_MM_PERIODIC_TIMER_CONTEXT and CommBufferSize pointing to its size. + + @param[in] This Pointer to the EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL instance. + @param[in] DispatchFunction Function to register for handler when at least the specified amount + of time has elapsed. + @param[in] RegisterContext Pointer to the dispatch function's context. + The caller fills this context in before calling + the register function to indicate to the register + function the period at which the dispatch function + should be invoked. + @param[out] DispatchHandle Handle generated by the dispatcher to track the function instance. + + @retval EFI_SUCCESS The dispatch function has been successfully + registered and the MMI source has been enabled. + @retval EFI_DEVICE_ERROR The driver was unable to enable the MMI source. + @retval EFI_INVALID_PARAMETER RegisterContext is invalid. The period input value + is not within valid range. + @retval EFI_OUT_OF_RESOURCES There is not enough memory (system or MM) to manage this child. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_PERIODIC_TIMER_REGISTER)( + IN CONST EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL *This, + IN EFI_MM_HANDLER_ENTRY_POINT DispatchFunction, + IN CONST EFI_MM_PERIODIC_TIMER_REGISTER_CONTEXT *RegisterContext, + OUT EFI_HANDLE *DispatchHandle + ); + +/** + Unregisters a periodic timer service. + + This service removes the handler associated with DispatchHandle so that it will no longer be + called when the time has elapsed. + + @param[in] This Pointer to the EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL instance. + @param[in] DispatchHandle Handle of the service to remove. + + @retval EFI_SUCCESS The service has been successfully removed. + @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_PERIODIC_TIMER_UNREGISTER)( + IN CONST EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL *This, + IN EFI_HANDLE DispatchHandle + ); + +/** + Returns the next MMI tick period supported by the chipset. + + The order returned is from longest to shortest interval period. + + @param[in] This Pointer to the EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL instance. + @param[in,out] MmiTickInterval Pointer to pointer of next shorter MMI interval + period supported by the child. This parameter works as a get-first, + get-next field.The first time this function is called, *MmiTickInterval + should be set to NULL to get the longest MMI interval.The returned + *MmiTickInterval should be passed in on subsequent calls to get the + next shorter interval period until *MmiTickInterval = NULL. + + @retval EFI_SUCCESS The service returned successfully. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_PERIODIC_TIMER_INTERVAL)( + IN CONST EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL *This, + IN OUT UINT64 **MmiTickInterval + ); + +/// +/// Interface structure for the MM Periodic Timer Dispatch Protocol +/// +/// This protocol provides the parent dispatch service for the periodical timer MMI source generator. +/// +struct _EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL { + EFI_MM_PERIODIC_TIMER_REGISTER Register; + EFI_MM_PERIODIC_TIMER_UNREGISTER UnRegister; + EFI_MM_PERIODIC_TIMER_INTERVAL GetNextShorterInterval; +}; + +extern EFI_GUID gEfiMmPeriodicTimerDispatchProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MmPowerButtonDispatch.h b/MdePkg/Include/Protocol/MmPowerButtonDispatch.h new file mode 100644 index 000000000000..f46501dc1c1e --- /dev/null +++ b/MdePkg/Include/Protocol/MmPowerButtonDispatch.h @@ -0,0 +1,111 @@ +/** @file + MM Power Button Dispatch Protocol as defined in PI 1.5 Specification + Volume 4 Management Mode Core Interface. + + This protocol provides the parent dispatch service for the power button MMI source generator. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This protocol is from PI Version 1.5. + +**/ + +#ifndef _MM_POWER_BUTTON_DISPATCH_H_ +#define _MM_POWER_BUTTON_DISPATCH_H_ + +#include <Pi/PiMmCis.h> + +#define EFI_MM_POWER_BUTTON_DISPATCH_PROTOCOL_GUID \ + { \ + 0x1b1183fa, 0x1823, 0x46a7, {0x88, 0x72, 0x9c, 0x57, 0x87, 0x55, 0x40, 0x9d } \ + } + +/// +/// Power Button phases. +/// +typedef enum { + EfiPowerButtonEntry, + EfiPowerButtonExit, + EfiPowerButtonMax +} EFI_POWER_BUTTON_PHASE; + +/// +/// The dispatch function's context. +/// +typedef struct { + /// + /// Designates whether this handler should be invoked upon entry or exit. + /// + EFI_POWER_BUTTON_PHASE Phase; +} EFI_MM_POWER_BUTTON_REGISTER_CONTEXT; + +typedef struct _EFI_MM_POWER_BUTTON_DISPATCH_PROTOCOL EFI_MM_POWER_BUTTON_DISPATCH_PROTOCOL; + +/** + Provides the parent dispatch service for a power button event. + + This service registers a function (DispatchFunction) which will be called when an MMI is + generated because the power button was pressed or released, as specified by RegisterContext. + On return, DispatchHandle contains a unique handle which may be used later to unregister the + function using UnRegister(). + The DispatchFunction will be called with Context set to the same value as was passed into + this function in RegisterContext and with CommBuffer and CommBufferSize set to NULL. + + @param[in] This Pointer to the EFI_MM_POWER_BUTTON_DISPATCH_PROTOCOL instance. + @param[in] DispatchFunction Function to register for handler when power button is pressed or released. + @param[in] RegisterContext Pointer to the dispatch function's context. The caller fills in this context + before calling the Register() function to indicate to the Register() function + the power button MMI phase for which the dispatch function should be invoked. + @param[out] DispatchHandle Handle generated by the dispatcher to track the function instance. + + @retval EFI_SUCCESS The dispatch function has been successfully + registered and the MMI source has been enabled. + @retval EFI_DEVICE_ERROR The driver was unable to enable the MMI source. + @retval EFI_INVALID_PARAMETER RegisterContext is invalid. The power button input value + is not within valid range. + @retval EFI_OUT_OF_RESOURCES There is not enough memory (system or MM) to manage this child. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_POWER_BUTTON_REGISTER)( + IN CONST EFI_MM_POWER_BUTTON_DISPATCH_PROTOCOL *This, + IN EFI_MM_HANDLER_ENTRY_POINT DispatchFunction, + IN EFI_MM_POWER_BUTTON_REGISTER_CONTEXT *RegisterContext, + OUT EFI_HANDLE *DispatchHandle + ); + +/** + Unregisters a power-button service. + + This service removes the handler associated with DispatchHandle so that it will no longer be + called when the standby button is pressed or released. + + @param[in] This Pointer to the EFI_MM_POWER_BUTTON_DISPATCH_PROTOCOL instance. + @param[in] DispatchHandle Handle of the service to remove. + + @retval EFI_SUCCESS The service has been successfully removed. + @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_POWER_BUTTON_UNREGISTER)( + IN CONST EFI_MM_POWER_BUTTON_DISPATCH_PROTOCOL *This, + IN EFI_HANDLE DispatchHandle + ); + +/// +/// Interface structure for the MM Power Button Dispatch Protocol. +/// +/// This protocol provides the parent dispatch service for the power button MMI source generator. +/// +struct _EFI_MM_POWER_BUTTON_DISPATCH_PROTOCOL { + EFI_MM_POWER_BUTTON_REGISTER Register; + EFI_MM_POWER_BUTTON_UNREGISTER UnRegister; +}; + +extern EFI_GUID gEfiMmPowerButtonDispatchProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MmReadyToLock.h b/MdePkg/Include/Protocol/MmReadyToLock.h new file mode 100644 index 000000000000..092fcfdcc0c1 --- /dev/null +++ b/MdePkg/Include/Protocol/MmReadyToLock.h @@ -0,0 +1,26 @@ +/** @file + MM Ready To Lock protocol introduced in the PI 1.5 specification. + + This protocol is a mandatory protocol published by the MM Foundation + code when the system is preparing to lock certain resources and interfaces + in anticipation of the invocation of 3rd party extensible modules. + This protocol is an MM counterpart of the DXE MM Ready to Lock Protocol. + This protocol prorogates resource locking notification into MM environment. + This protocol is installed after installation of the MM End of DXE Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_READY_TO_LOCK_H_ +#define _MM_READY_TO_LOCK_H_ + +#define EFI_MM_READY_TO_LOCK_PROTOCOL_GUID \ + { \ + 0x47b7fa8c, 0xf4bd, 0x4af6, { 0x82, 0x00, 0x33, 0x30, 0x86, 0xf0, 0xd2, 0xc8 } \ + } + +extern EFI_GUID gEfiMmReadyToLockProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/MmReportStatusCodeHandler.h b/MdePkg/Include/Protocol/MmReportStatusCodeHandler.h new file mode 100644 index 000000000000..f8e67ac4e310 --- /dev/null +++ b/MdePkg/Include/Protocol/MmReportStatusCodeHandler.h @@ -0,0 +1,78 @@ +/** @file + This protocol provides registering and unregistering services to status code consumers while in DXE MM. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in PI Specification 1.1. + +**/ + +#ifndef __MM_REPORT_STATUS_CODE_HANDLER_PROTOCOL_H__ +#define __MM_REPORT_STATUS_CODE_HANDLER_PROTOCOL_H__ + +#define EFI_MM_RSC_HANDLER_PROTOCOL_GUID \ + { \ + 0x2ff29fa7, 0x5e80, 0x4ed9, {0xb3, 0x80, 0x1, 0x7d, 0x3c, 0x55, 0x4f, 0xf4} \ + } + +typedef +EFI_STATUS +(EFIAPI *EFI_MM_RSC_HANDLER_CALLBACK)( + IN EFI_STATUS_CODE_TYPE CodeType, + IN EFI_STATUS_CODE_VALUE Value, + IN UINT32 Instance, + IN EFI_GUID *CallerId, + IN EFI_STATUS_CODE_DATA *Data +); + +/** + Register the callback function for ReportStatusCode() notification. + + When this function is called the function pointer is added to an internal list and any future calls to + ReportStatusCode() will be forwarded to the Callback function. + + @param[in] Callback A pointer to a function of type EFI_MM_RSC_HANDLER_CALLBACK that is + called when a call to ReportStatusCode() occurs. + + @retval EFI_SUCCESS Function was successfully registered. + @retval EFI_INVALID_PARAMETER The callback function was NULL. + @retval EFI_OUT_OF_RESOURCES The internal buffer ran out of space. No more functions can be + registered. + @retval EFI_ALREADY_STARTED The function was already registered. It can't be registered again. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_RSC_HANDLER_REGISTER)( + IN EFI_MM_RSC_HANDLER_CALLBACK Callback +); + +/** + Remove a previously registered callback function from the notification list. + + A callback function must be unregistered before it is deallocated. It is important that any registered + callbacks that are not runtime complaint be unregistered when ExitBootServices() is called. + + @param[in] Callback A pointer to a function of type EFI_MM_RSC_HANDLER_CALLBACK that is to be + unregistered. + + @retval EFI_SUCCESS The function was successfully unregistered. + @retval EFI_INVALID_PARAMETER The callback function was NULL. + @retval EFI_NOT_FOUND The callback function was not found to be unregistered. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_RSC_HANDLER_UNREGISTER)( + IN EFI_MM_RSC_HANDLER_CALLBACK Callback +); + +typedef struct _EFI_MM_RSC_HANDLER_PROTOCOL { + EFI_MM_RSC_HANDLER_REGISTER Register; + EFI_MM_RSC_HANDLER_UNREGISTER Unregister; +} EFI_MM_RSC_HANDLER_PROTOCOL; + +extern EFI_GUID gEfiMmRscHandlerProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/MmStandbyButtonDispatch.h b/MdePkg/Include/Protocol/MmStandbyButtonDispatch.h new file mode 100644 index 000000000000..430237862a7e --- /dev/null +++ b/MdePkg/Include/Protocol/MmStandbyButtonDispatch.h @@ -0,0 +1,113 @@ +/** @file + MM Standby Button Dispatch Protocol as defined in PI 1.5 Specification + Volume 4 Management Mode Core Interface. + + This protocol provides the parent dispatch service for the standby button MMI source generator. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This protocol is from PI Version 1.5. + +**/ + +#ifndef _MM_STANDBY_BUTTON_DISPATCH_H_ +#define _MM_STANDBY_BUTTON_DISPATCH_H_ + +#include <Pi/PiMmCis.h> + +#define EFI_MM_STANDBY_BUTTON_DISPATCH_PROTOCOL_GUID \ + { \ + 0x7300c4a1, 0x43f2, 0x4017, {0xa5, 0x1b, 0xc8, 0x1a, 0x7f, 0x40, 0x58, 0x5b } \ + } + +/// +/// Standby Button phases +/// +typedef enum { + EfiStandbyButtonEntry, + EfiStandbyButtonExit, + EfiStandbyButtonMax +} EFI_STANDBY_BUTTON_PHASE; + +/// +/// The dispatch function's context. +/// +typedef struct { + /// + /// Describes whether the child handler should be invoked upon the entry to the button + /// activation or upon exit. + /// + EFI_STANDBY_BUTTON_PHASE Phase; +} EFI_MM_STANDBY_BUTTON_REGISTER_CONTEXT; + +typedef struct _EFI_MM_STANDBY_BUTTON_DISPATCH_PROTOCOL EFI_MM_STANDBY_BUTTON_DISPATCH_PROTOCOL; + +/** + Provides the parent dispatch service for a standby button event. + + This service registers a function (DispatchFunction) which will be called when an MMI is + generated because the standby button was pressed or released, as specified by + RegisterContext. On return, DispatchHandle contains a unique handle which may be used + later to unregister the function using UnRegister(). + The DispatchFunction will be called with Context set to the same value as was passed into + this function in RegisterContext and with CommBuffer and CommBufferSize set to NULL. + + @param[in] This Pointer to the EFI_MM_STANDBY_BUTTON_DISPATCH_PROTOCOL instance. + @param[in] DispatchFunction Function to register for handler when the standby button is pressed or released. + @param[in] RegisterContext Pointer to the dispatch function's context. The caller fills in this context + before calling the register function to indicate to the register function the + standby button MMI source for which the dispatch function should be invoked. + @param[out] DispatchHandle Handle generated by the dispatcher to track the function instance. + + @retval EFI_SUCCESS The dispatch function has been successfully + registered and the MMI source has been enabled. + @retval EFI_DEVICE_ERROR The driver was unable to enable the MMI source. + @retval EFI_INVALID_PARAMETER RegisterContext is invalid. The standby button input value + is not within valid range. + @retval EFI_OUT_OF_RESOURCES There is not enough memory (system or MM) to manage this child. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_STANDBY_BUTTON_REGISTER)( + IN CONST EFI_MM_STANDBY_BUTTON_DISPATCH_PROTOCOL *This, + IN EFI_MM_HANDLER_ENTRY_POINT DispatchFunction, + IN EFI_MM_STANDBY_BUTTON_REGISTER_CONTEXT *RegisterContext, + OUT EFI_HANDLE *DispatchHandle + ); + +/** + Unregisters a child MMI source dispatch function with a parent MM driver. + + This service removes the handler associated with DispatchHandle so that it will no longer be + called when the standby button is pressed or released. + + @param[in] This Pointer to the EFI_MM_STANDBY_BUTTON_DISPATCH_PROTOCOL instance. + @param[in] DispatchHandle Handle of the service to remove. + + @retval EFI_SUCCESS The service has been successfully removed. + @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_STANDBY_BUTTON_UNREGISTER)( + IN CONST EFI_MM_STANDBY_BUTTON_DISPATCH_PROTOCOL *This, + IN EFI_HANDLE DispatchHandle + ); + +/// +/// Interface structure for the MM Standby Button Dispatch Protocol. +/// +/// This protocol provides the parent dispatch service for the standby +/// button MMI source generator. +/// +struct _EFI_MM_STANDBY_BUTTON_DISPATCH_PROTOCOL { + EFI_MM_STANDBY_BUTTON_REGISTER Register; + EFI_MM_STANDBY_BUTTON_UNREGISTER UnRegister; +}; + +extern EFI_GUID gEfiMmStandbyButtonDispatchProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MmStatusCode.h b/MdePkg/Include/Protocol/MmStatusCode.h new file mode 100644 index 000000000000..3ff1a31aa4ee --- /dev/null +++ b/MdePkg/Include/Protocol/MmStatusCode.h @@ -0,0 +1,59 @@ +/** @file + EFI MM Status Code Protocol as defined in the PI 1.5 specification. + + This protocol provides the basic status code services while in MM. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_STATUS_CODE_H__ +#define _MM_STATUS_CODE_H__ + + +#define EFI_MM_STATUS_CODE_PROTOCOL_GUID \ + { \ + 0x6afd2b77, 0x98c1, 0x4acd, {0xa6, 0xf9, 0x8a, 0x94, 0x39, 0xde, 0xf, 0xb1} \ + } + +typedef struct _EFI_MM_STATUS_CODE_PROTOCOL EFI_MM_STATUS_CODE_PROTOCOL; + +/** + Service to emit the status code in MM. + + The EFI_MM_STATUS_CODE_PROTOCOL.ReportStatusCode() function enables a driver + to emit a status code while in MM. The reason that there is a separate protocol definition from the + DXE variant of this service is that the publisher of this protocol will provide a service that is + capability of coexisting with a foreground operational environment, such as an operating system + after the termination of boot services. + + @param[in] This Points to this instance of the EFI_MM_STATUS_CODE_PROTOCOL. + @param[in] CodeType DIndicates the type of status code being reported. + @param[in] Value Describes the current status of a hardware or software entity. + @param[in] Instance The enumeration of a hardware or software entity within the system. + @param[in] CallerId This optional parameter may be used to identify the caller. + @param[in] Data This optional parameter may be used to pass additional data. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER The function should not be completed due to a device error. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_REPORT_STATUS_CODE)( + IN CONST EFI_MM_STATUS_CODE_PROTOCOL *This, + IN EFI_STATUS_CODE_TYPE CodeType, + IN EFI_STATUS_CODE_VALUE Value, + IN UINT32 Instance, + IN CONST EFI_GUID *CallerId, + IN EFI_STATUS_CODE_DATA *Data OPTIONAL + ); + +struct _EFI_MM_STATUS_CODE_PROTOCOL { + EFI_MM_REPORT_STATUS_CODE ReportStatusCode; +}; + +extern EFI_GUID gEfiMmStatusCodeProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MmSwDispatch.h b/MdePkg/Include/Protocol/MmSwDispatch.h new file mode 100644 index 000000000000..49957de65622 --- /dev/null +++ b/MdePkg/Include/Protocol/MmSwDispatch.h @@ -0,0 +1,130 @@ +/** @file + MM Software Dispatch Protocol introduced from PI 1.5 Specification + Volume 4 Management Mode Core Interface. + + This protocol provides the parent dispatch service for a given MMI source generator. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_SW_DISPATCH_H_ +#define _MM_SW_DISPATCH_H_ + +#include <Pi/PiMmCis.h> + +#define EFI_MM_SW_DISPATCH_PROTOCOL_GUID \ + { \ + 0x18a3c6dc, 0x5eea, 0x48c8, {0xa1, 0xc1, 0xb5, 0x33, 0x89, 0xf9, 0x89, 0x99 } \ + } + +/// +/// A particular chipset may not support all possible software MMI input values. +/// For example, the ICH supports only values 00h to 0FFh. The parent only allows a single +/// child registration for each SwMmiInputValue. +/// +typedef struct { + UINTN SwMmiInputValue; +} EFI_MM_SW_REGISTER_CONTEXT; + +/// +/// The DispatchFunction will be called with Context set to the same value as was passed into +/// this function in RegisterContext and with CommBuffer (and CommBufferSize) pointing +/// to an instance of EFI_MM_SW_CONTEXT indicating the index of the CPU which generated the +/// software MMI. +/// +typedef struct { + /// + /// The 0-based index of the CPU which generated the software MMI. + /// + UINTN SwMmiCpuIndex; + /// + /// This value corresponds directly to the CommandPort parameter used in the call to Trigger(). + /// + UINT8 CommandPort; + /// + /// This value corresponds directly to the DataPort parameter used in the call to Trigger(). + /// + UINT8 DataPort; +} EFI_MM_SW_CONTEXT; + +typedef struct _EFI_MM_SW_DISPATCH_PROTOCOL EFI_MM_SW_DISPATCH_PROTOCOL; + +/** + Register a child MMI source dispatch function for the specified software MMI. + + This service registers a function (DispatchFunction) which will be called when the software + MMI source specified by RegisterContext->SwMmiCpuIndex is detected. On return, + DispatchHandle contains a unique handle which may be used later to unregister the function + using UnRegister(). + + @param[in] This Pointer to the EFI_MM_SW_DISPATCH_PROTOCOL instance. + @param[in] DispatchFunction Function to register for handler when the specified software + MMI is generated. + @param[in, out] RegisterContext Pointer to the dispatch function's context. + The caller fills this context in before calling + the register function to indicate to the register + function which Software MMI input value the + dispatch function should be invoked for. + @param[out] DispatchHandle Handle generated by the dispatcher to track the + function instance. + + @retval EFI_SUCCESS The dispatch function has been successfully + registered and the MMI source has been enabled. + @retval EFI_DEVICE_ERROR The SW driver was unable to enable the MMI source. + @retval EFI_INVALID_PARAMETER RegisterContext is invalid. The SW MMI input value + is not within a valid range or is already in use. + @retval EFI_OUT_OF_RESOURCES There is not enough memory (system or MM) to manage this + child. + @retval EFI_OUT_OF_RESOURCES A unique software MMI value could not be assigned + for this dispatch. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_SW_REGISTER)( + IN CONST EFI_MM_SW_DISPATCH_PROTOCOL *This, + IN EFI_MM_HANDLER_ENTRY_POINT DispatchFunction, + IN OUT EFI_MM_SW_REGISTER_CONTEXT *RegisterContext, + OUT EFI_HANDLE *DispatchHandle + ); + +/** + Unregister a child MMI source dispatch function for the specified software MMI. + + This service removes the handler associated with DispatchHandle so that it will no longer be + called in response to a software MMI. + + @param[in] This Pointer to the EFI_MM_SW_DISPATCH_PROTOCOL instance. + @param[in] DispatchHandle Handle of dispatch function to deregister. + + @retval EFI_SUCCESS The dispatch function has been successfully unregistered. + @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_SW_UNREGISTER)( + IN CONST EFI_MM_SW_DISPATCH_PROTOCOL *This, + IN EFI_HANDLE DispatchHandle +); + +/// +/// Interface structure for the MM Software MMI Dispatch Protocol. +/// +/// The EFI_MM_SW_DISPATCH_PROTOCOL provides the ability to install child handlers for the +/// given software. These handlers will respond to software interrupts, and the maximum software +/// interrupt in the EFI_MM_SW_REGISTER_CONTEXT is denoted by MaximumSwiValue. +/// +struct _EFI_MM_SW_DISPATCH_PROTOCOL { + EFI_MM_SW_REGISTER Register; + EFI_MM_SW_UNREGISTER UnRegister; + /// + /// A read-only field that describes the maximum value that can be used in the + /// EFI_MM_SW_DISPATCH_PROTOCOL.Register() service. + /// + UINTN MaximumSwiValue; +}; + +extern EFI_GUID gEfiMmSwDispatchProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/MmSxDispatch.h b/MdePkg/Include/Protocol/MmSxDispatch.h new file mode 100644 index 000000000000..db008e96fa28 --- /dev/null +++ b/MdePkg/Include/Protocol/MmSxDispatch.h @@ -0,0 +1,129 @@ +/** @file + MM Sx Dispatch Protocol as defined in PI 1.5 Specification + Volume 4 Management Mode Core Interface. + + Provides the parent dispatch service for a given Sx-state source generator. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_SX_DISPATCH_H_ +#define _MM_SX_DISPATCH_H_ + +#include <Pi/PiMmCis.h> + +#define EFI_MM_SX_DISPATCH_PROTOCOL_GUID \ + { \ + 0x456d2859, 0xa84b, 0x4e47, {0xa2, 0xee, 0x32, 0x76, 0xd8, 0x86, 0x99, 0x7d } \ + } + +/// +/// Sleep states S0-S5 +/// +typedef enum { + SxS0, + SxS1, + SxS2, + SxS3, + SxS4, + SxS5, + EfiMaximumSleepType +} EFI_SLEEP_TYPE; + +/// +/// Sleep state phase: entry or exit +/// +typedef enum { + SxEntry, + SxExit, + EfiMaximumPhase +} EFI_SLEEP_PHASE; + +/// +/// The dispatch function's context +/// +typedef struct { + EFI_SLEEP_TYPE Type; + EFI_SLEEP_PHASE Phase; +} EFI_MM_SX_REGISTER_CONTEXT; + +typedef struct _EFI_MM_SX_DISPATCH_PROTOCOL EFI_MM_SX_DISPATCH_PROTOCOL; + +/** + Provides the parent dispatch service for a given Sx source generator. + + This service registers a function (DispatchFunction) which will be called when the sleep state + event specified by RegisterContext is detected. On return, DispatchHandle contains a + unique handle which may be used later to unregister the function using UnRegister(). + The DispatchFunction will be called with Context set to the same value as was passed into + this function in RegisterContext and with CommBuffer and CommBufferSize set to + NULL and 0 respectively. + + @param[in] This Pointer to the EFI_MM_SX_DISPATCH_PROTOCOL instance. + @param[in] DispatchFunction Function to register for handler when the specified sleep state event occurs. + @param[in] RegisterContext Pointer to the dispatch function's context. + The caller fills this context in before calling + the register function to indicate to the register + function which Sx state type and phase the caller + wishes to be called back on. For this intertace, + the Sx driver will call the registered handlers for + all Sx type and phases, so the Sx state handler(s) + must check the Type and Phase field of the Dispatch + context and act accordingly. + @param[out] DispatchHandle Handle of dispatch function, for when interfacing + with the parent Sx state MM driver. + + @retval EFI_SUCCESS The dispatch function has been successfully + registered and the MMI source has been enabled. + @retval EFI_UNSUPPORTED The Sx driver or hardware does not support that + Sx Type/Phase. + @retval EFI_DEVICE_ERROR The Sx driver was unable to enable the MMI source. + @retval EFI_INVALID_PARAMETER RegisterContext is invalid. Type & Phase are not + within valid range. + @retval EFI_OUT_OF_RESOURCES There is not enough memory (system or MM) to manage this + child. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_SX_REGISTER)( + IN CONST EFI_MM_SX_DISPATCH_PROTOCOL *This, + IN EFI_MM_HANDLER_ENTRY_POINT DispatchFunction, + IN CONST EFI_MM_SX_REGISTER_CONTEXT *RegisterContext, + OUT EFI_HANDLE *DispatchHandle + ); + +/** + Unregisters an Sx-state service. + + This service removes the handler associated with DispatchHandle so that it will no longer be + called in response to sleep event. + + @param[in] This Pointer to the EFI_MM_SX_DISPATCH_PROTOCOL instance. + @param[in] DispatchHandle Handle of the service to remove. + + @retval EFI_SUCCESS The service has been successfully removed. + @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_SX_UNREGISTER)( + IN CONST EFI_MM_SX_DISPATCH_PROTOCOL *This, + IN EFI_HANDLE DispatchHandle + ); + +/// +/// Interface structure for the MM Sx Dispatch Protocol +/// +/// The EFI_MM_SX_DISPATCH_PROTOCOL provides the ability to install child handlers to +/// respond to sleep state related events. +/// +struct _EFI_MM_SX_DISPATCH_PROTOCOL { + EFI_MM_SX_REGISTER Register; + EFI_MM_SX_UNREGISTER UnRegister; +}; + +extern EFI_GUID gEfiMmSxDispatchProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/MmUsbDispatch.h b/MdePkg/Include/Protocol/MmUsbDispatch.h new file mode 100644 index 000000000000..75abb270b1a5 --- /dev/null +++ b/MdePkg/Include/Protocol/MmUsbDispatch.h @@ -0,0 +1,124 @@ +/** @file + MM USB Dispatch Protocol as defined in PI 1.5 Specification + Volume 4 Management Mode Core Interface. + + Provides the parent dispatch service for the USB MMI source generator. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This protocol is from PI Version 1.5. + +**/ + +#ifndef _MM_USB_DISPATCH_H_ +#define _MM_USB_DISPATCH_H_ + +#include <Pi/PiMmCis.h> + +#define EFI_MM_USB_DISPATCH_PROTOCOL_GUID \ + { \ + 0xee9b8d90, 0xc5a6, 0x40a2, {0xbd, 0xe2, 0x52, 0x55, 0x8d, 0x33, 0xcc, 0xa1 } \ + } + +/// +/// USB MMI event types +/// +typedef enum { + UsbLegacy, + UsbWake +} EFI_USB_MMI_TYPE; + +/// +/// The dispatch function's context. +/// +typedef struct { + /// + /// Describes whether this child handler will be invoked in response to a USB legacy + /// emulation event, such as port-trap on the PS/2* keyboard control registers, or to a + /// USB wake event, such as resumption from a sleep state. + /// + EFI_USB_MMI_TYPE Type; + /// + /// The device path is part of the context structure and describes the location of the + /// particular USB host controller in the system for which this register event will occur. + /// This location is important because of the possible integration of several USB host + /// controllers in a system. + /// + EFI_DEVICE_PATH_PROTOCOL *Device; +} EFI_MM_USB_REGISTER_CONTEXT; + +typedef struct _EFI_MM_USB_DISPATCH_PROTOCOL EFI_MM_USB_DISPATCH_PROTOCOL; + +/** + Provides the parent dispatch service for the USB MMI source generator. + + This service registers a function (DispatchFunction) which will be called when the USB- + related MMI specified by RegisterContext has occurred. On return, DispatchHandle + contains a unique handle which may be used later to unregister the function using UnRegister(). + The DispatchFunction will be called with Context set to the same value as was passed into + this function in RegisterContext and with CommBuffer containing NULL and + CommBufferSize containing zero. + + @param[in] This Pointer to the EFI_MM_USB_DISPATCH_PROTOCOL instance. + @param[in] DispatchFunction Function to register for handler when a USB-related MMI occurs. + @param[in] RegisterContext Pointer to the dispatch function's context. + The caller fills this context in before calling + the register function to indicate to the register + function the USB MMI types for which the dispatch + function should be invoked. + @param[out] DispatchHandle Handle generated by the dispatcher to track the function instance. + + @retval EFI_SUCCESS The dispatch function has been successfully + registered and the MMI source has been enabled. + @retval EFI_DEVICE_ERROR The driver was unable to enable the MMI source. + @retval EFI_INVALID_PARAMETER RegisterContext is invalid. The USB MMI type + is not within valid range. + @retval EFI_OUT_OF_RESOURCES There is not enough memory (system or MM) to manage this child. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_USB_REGISTER)( + IN CONST EFI_MM_USB_DISPATCH_PROTOCOL *This, + IN EFI_MM_HANDLER_ENTRY_POINT DispatchFunction, + IN CONST EFI_MM_USB_REGISTER_CONTEXT *RegisterContext, + OUT EFI_HANDLE *DispatchHandle + ); + +/** + Unregisters a USB service. + + This service removes the handler associated with DispatchHandle so that it will no longer be + called when the USB event occurs. + + @param[in] This Pointer to the EFI_MM_USB_DISPATCH_PROTOCOL instance. + @param[in] DispatchHandle Handle of the service to remove. + + @retval EFI_SUCCESS The dispatch function has been successfully + unregistered and the MMI source has been disabled + if there are no other registered child dispatch + functions for this MMI source. + @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_USB_UNREGISTER)( + IN CONST EFI_MM_USB_DISPATCH_PROTOCOL *This, + IN EFI_HANDLE DispatchHandle + ); + +/// +/// Interface structure for the MM USB MMI Dispatch Protocol +/// +/// This protocol provides the parent dispatch service for the USB MMI source generator. +/// +struct _EFI_MM_USB_DISPATCH_PROTOCOL { + EFI_MM_USB_REGISTER Register; + EFI_MM_USB_UNREGISTER UnRegister; +}; + +extern EFI_GUID gEfiMmUsbDispatchProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/MonotonicCounter.h b/MdePkg/Include/Protocol/MonotonicCounter.h index 1409be2e5f3d..5d56ca788fea 100644 --- a/MdePkg/Include/Protocol/MonotonicCounter.h +++ b/MdePkg/Include/Protocol/MonotonicCounter.h @@ -3,14 +3,8 @@ This code provides the services required to access the system's monotonic counter -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -22,7 +16,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /// #define EFI_MONOTONIC_COUNTER_ARCH_PROTOCOL_GUID \ {0x1da97072, 0xbddc, 0x4b30, {0x99, 0xf1, 0x72, 0xa0, 0xb5, 0x6f, 0xff, 0x2a} } - + extern EFI_GUID gEfiMonotonicCounterArchProtocolGuid; #endif diff --git a/MdePkg/Include/Protocol/MpService.h b/MdePkg/Include/Protocol/MpService.h index e61caebc5816..697d99ebe531 100644 --- a/MdePkg/Include/Protocol/MpService.h +++ b/MdePkg/Include/Protocol/MpService.h @@ -27,14 +27,8 @@ APs to help test system memory in parallel with other device initialization. Diagnostics applications may also use this protocol for multi-processor. -Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is defined in the UEFI Platform Initialization Specification 1.2, @@ -54,6 +48,11 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. } /// +/// Value used in the NumberProcessors parameter of the GetProcessorInfo function +/// +#define CPU_V2_EXTENDED_TOPOLOGY BIT24 + +/// /// Forward declaration for the EFI_MP_SERVICES_PROTOCOL. /// typedef struct _EFI_MP_SERVICES_PROTOCOL EFI_MP_SERVICES_PROTOCOL; @@ -103,6 +102,47 @@ typedef struct { } EFI_CPU_PHYSICAL_LOCATION; /// +/// Structure that defines the 6-level physical location of the processor +/// +typedef struct { +/// +/// Package Zero-based physical package number that identifies the cartridge of the processor. +/// +UINT32 Package; +/// +/// Module Zero-based physical module number within package of the processor. +/// +UINT32 Module; +/// +/// Tile Zero-based physical tile number within module of the processor. +/// +UINT32 Tile; +/// +/// Die Zero-based physical die number within tile of the processor. +/// +UINT32 Die; +/// +/// Core Zero-based physical core number within die of the processor. +/// +UINT32 Core; +/// +/// Thread Zero-based logical thread number within core of the processor. +/// +UINT32 Thread; +} EFI_CPU_PHYSICAL_LOCATION2; + + +typedef union { + /// The 6-level physical location of the processor, including the + /// physical package number that identifies the cartridge, the physical + /// module number within package, the physical tile number within the module, + /// the physical die number within the tile, the physical core number within + /// package, and logical thread number within core. + EFI_CPU_PHYSICAL_LOCATION2 Location2; +} EXTENDED_PROCESSOR_INFORMATION; + + +/// /// Structure that describes information about a logical CPU. /// typedef struct { @@ -138,6 +178,10 @@ typedef struct { /// logical thread number within core. /// EFI_CPU_PHYSICAL_LOCATION Location; + /// + /// The extended information of the processor. This field is filled only when + /// CPU_V2_EXTENDED_TOPOLOGY is set in parameter ProcessorNumber. + EXTENDED_PROCESSOR_INFORMATION ExtendedInformation; } EFI_PROCESSOR_INFORMATION; /** @@ -491,7 +535,7 @@ EFI_STATUS @retval EFI_UNSUPPORTED Switching the BSP cannot be completed prior to this service returning. @retval EFI_UNSUPPORTED Switching the BSP is not supported. - @retval EFI_SUCCESS The calling processor is an AP. + @retval EFI_DEVICE_ERROR The calling processor is an AP. @retval EFI_NOT_FOUND The processor with the handle specified by ProcessorNumber does not exist. @retval EFI_INVALID_PARAMETER ProcessorNumber specifies the current BSP or diff --git a/MdePkg/Include/Protocol/Mtftp4.h b/MdePkg/Include/Protocol/Mtftp4.h index e24751dd5a04..ce7e940229c8 100644 --- a/MdePkg/Include/Protocol/Mtftp4.h +++ b/MdePkg/Include/Protocol/Mtftp4.h @@ -1,14 +1,8 @@ /** @file EFI Multicast Trivial File Transfer Protocol Definition -Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.0 diff --git a/MdePkg/Include/Protocol/Mtftp6.h b/MdePkg/Include/Protocol/Mtftp6.h index 3273550e3369..c15d45fcfd82 100644 --- a/MdePkg/Include/Protocol/Mtftp6.h +++ b/MdePkg/Include/Protocol/Mtftp6.h @@ -6,13 +6,7 @@ Copyright (c) 2008 - 2011, Intel Corporation. All rights reserved.<BR> (C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.2 diff --git a/MdePkg/Include/Protocol/NetworkInterfaceIdentifier.h b/MdePkg/Include/Protocol/NetworkInterfaceIdentifier.h index 1b7654503da0..f80374a07667 100644 --- a/MdePkg/Include/Protocol/NetworkInterfaceIdentifier.h +++ b/MdePkg/Include/Protocol/NetworkInterfaceIdentifier.h @@ -1,14 +1,8 @@ /** @file EFI Network Interface Identifier Protocol. -Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in EFI Specification 1.10. @@ -74,8 +68,8 @@ struct _EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL { UINT8 MajorVer; ///< Major version number. UINT8 MinorVer; ///< Minor version number. BOOLEAN Ipv6Supported; ///< TRUE if the network interface supports IPv6; otherwise FALSE. - UINT16 IfNum; ///< The network interface number that is being identified by this Network - ///< Interface Identifier Protocol. This field must be less than or + UINT16 IfNum; ///< The network interface number that is being identified by this Network + ///< Interface Identifier Protocol. This field must be less than or ///< equal to the (IFcnt | IFcntExt <<8 ) fields in the !PXE structure. }; @@ -109,7 +103,7 @@ struct undiconfig_table { struct { VOID *NII_InterfacePointer; ///< Pointer to the NII interface structure. VOID *DevicePathPointer; ///< Pointer to the device path for this NIC. - } NII_entry[1]; + } NII_entry[1]; }; extern EFI_GUID gEfiNetworkInterfaceIdentifierProtocolGuid; diff --git a/MdePkg/Include/Protocol/NvdimmLabel.h b/MdePkg/Include/Protocol/NvdimmLabel.h new file mode 100644 index 000000000000..c9b5642bc396 --- /dev/null +++ b/MdePkg/Include/Protocol/NvdimmLabel.h @@ -0,0 +1,345 @@ +/** @file + EFI NVDIMM Label Protocol Definition + + The EFI NVDIMM Label Protocol is used to Provides services that allow management + of labels contained in a Label Storage Area that are associated with a specific + NVDIMM Device Path. + +Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.7. + +**/ + +#ifndef __EFI_NVDIMM_LABEL_PROTOCOL_H__ +#define __EFI_NVDIMM_LABEL_PROTOCOL_H__ + +#define EFI_NVDIMM_LABEL_PROTOCOL_GUID \ + { \ + 0xd40b6b80, 0x97d5, 0x4282, {0xbb, 0x1d, 0x22, 0x3a, 0x16, 0x91, 0x80, 0x58 } \ + } + +typedef struct _EFI_NVDIMM_LABEL_PROTOCOL EFI_NVDIMM_LABEL_PROTOCOL; + +#define EFI_NVDIMM_LABEL_INDEX_SIG_LEN 16 +#define EFI_NVDIMM_LABEL_INDEX_ALIGN 256 +typedef struct { + /// + /// Signature of the Index Block data structure. Must be "NAMESPACE_INDEX\0". + /// + CHAR8 Sig[EFI_NVDIMM_LABEL_INDEX_SIG_LEN]; + + /// + /// Attributes of this Label Storage Area. + /// + UINT8 Flags[3]; + + /// + /// Size of each label in bytes, 128 bytes << LabelSize. + /// 1 means 256 bytes, 2 means 512 bytes, etc. Shall be 1 or greater. + /// + UINT8 LabelSize; + + /// + /// Sequence number used to identify which of the two Index Blocks is current. + /// + UINT32 Seq; + + /// + /// The offset of this Index Block in the Label Storage Area. + /// + UINT64 MyOff; + + /// + /// The size of this Index Block in bytes. + /// This field must be a multiple of the EFI_NVDIMM_LABEL_INDEX_ALIGN. + /// + UINT64 MySize; + + /// + /// The offset of the other Index Block paired with this one. + /// + UINT64 OtherOff; + + /// + /// The offset of the first slot where labels are stored in this Label Storage Area. + /// + UINT64 LabelOff; + + /// + /// The total number of slots for storing labels in this Label Storage Area. + /// + UINT32 NSlot; + + /// + /// Major version number. Value shall be 1. + /// + UINT16 Major; + + /// + /// Minor version number. Value shall be 2. + /// + UINT16 Minor; + + /// + /// 64-bit Fletcher64 checksum of all fields in this Index Block. + /// + UINT64 Checksum; + + /// + /// Array of unsigned bytes implementing a bitmask that tracks which label slots are free. + /// A bit value of 0 indicates in use, 1 indicates free. + /// The size of this field is the number of bytes required to hold the bitmask with NSlot bits, + /// padded with additional zero bytes to make the Index Block size a multiple of EFI_NVDIMM_LABEL_INDEX_ALIGN. + /// Any bits allocated beyond NSlot bits must be zero. + /// + UINT8 Free[]; +} EFI_NVDIMM_LABEL_INDEX_BLOCK; + +#define EFI_NVDIMM_LABEL_NAME_LEN 64 + +/// +/// The label is read-only. +/// +#define EFI_NVDIMM_LABEL_FLAGS_ROLABEL 0x00000001 + +/// +/// When set, the complete label set is local to a single NVDIMM Label Storage Area. +/// When clear, the complete label set is contained on multiple NVDIMM Label Storage Areas. +/// +#define EFI_NVDIMM_LABEL_FLAGS_LOCAL 0x00000002 + +/// +/// This reserved flag is utilized on older implementations and has been deprecated. +/// Do not use. +// +#define EFI_NVDIMM_LABEL_FLAGS_RESERVED 0x00000004 + +/// +/// When set, the label set is being updated. +/// +#define EFI_NVDIMM_LABEL_FLAGS_UPDATING 0x00000008 + +typedef struct { + /// + /// Unique Label Identifier UUID per RFC 4122. + /// + EFI_GUID Uuid; + + /// + /// NULL-terminated string using UTF-8 character formatting. + /// + CHAR8 Name[EFI_NVDIMM_LABEL_NAME_LEN]; + + /// + /// Attributes of this namespace. + /// + UINT32 Flags; + + /// + /// Total number of labels describing this namespace. + /// + UINT16 NLabel; + + /// + /// Position of this label in list of labels for this namespace. + /// + UINT16 Position; + + /// + /// The SetCookie is utilized by SW to perform consistency checks on the Interleave Set to verify the current + /// physical device configuration matches the original physical configuration when the labels were created + /// for the set.The label is considered invalid if the actual label set cookie doesn't match the cookie stored here. + /// + UINT64 SetCookie; + + /// + /// This is the default logical block size in bytes and may be superseded by a block size that is specified + /// in the AbstractionGuid. + /// + UINT64 LbaSize; + + /// + /// The DPA is the DIMM Physical address where the NVM contributing to this namespace begins on this NVDIMM. + /// + UINT64 Dpa; + + /// + /// The extent of the DPA contributed by this label. + /// + UINT64 RawSize; + + /// + /// Current slot in the Label Storage Area where this label is stored. + /// + UINT32 Slot; + + /// + /// Alignment hint used to advertise the preferred alignment of the data from within the namespace defined by this label. + /// + UINT8 Alignment; + + /// + /// Shall be 0. + /// + UINT8 Reserved[3]; + + /// + /// Range Type GUID that describes the access mechanism for the specified DPA range. + /// + EFI_GUID TypeGuid; + + /// + /// Identifies the address abstraction mechanism for this namespace. A value of 0 indicates no mechanism used. + /// + EFI_GUID AddressAbstractionGuid; + + /// + /// Shall be 0. + /// + UINT8 Reserved1[88]; + + /// + /// 64-bit Fletcher64 checksum of all fields in this Label. + /// This field is considered zero when the checksum is computed. + /// + UINT64 Checksum; +} EFI_NVDIMM_LABEL; + +typedef struct { + /// + /// The Region Offset field from the ACPI NFIT NVDIMM Region Mapping Structure for a given entry. + /// + UINT64 RegionOffset; + + /// + /// The serial number of the NVDIMM, assigned by the module vendor. + /// + UINT32 SerialNumber; + + /// + /// The identifier indicating the vendor of the NVDIMM. + /// + UINT16 VendorId; + + /// + /// The manufacturing date of the NVDIMM, assigned by the module vendor. + /// + UINT16 ManufacturingDate; + + /// + /// The manufacturing location from for the NVDIMM, assigned by the module vendor. + /// + UINT8 ManufacturingLocation; + + /// + /// Shall be 0. + /// + UINT8 Reserved[31]; +} EFI_NVDIMM_LABEL_SET_COOKIE_MAP; + +typedef struct { + /// + /// Array size is 1 if EFI_NVDIMM_LABEL_FLAGS_LOCAL is set indicating a Local Namespaces. + /// + EFI_NVDIMM_LABEL_SET_COOKIE_MAP Mapping[0]; +} EFI_NVDIMM_LABEL_SET_COOKIE_INFO; + +/** + Retrieves the Label Storage Area size and the maximum transfer size for the LabelStorageRead and + LabelStorageWrite methods. + + @param This A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance. + @param SizeOfLabelStorageArea The size of the Label Storage Area for the NVDIMM in bytes. + @param MaxTransferLength The maximum number of bytes that can be transferred in a single call to + LabelStorageRead or LabelStorageWrite. + + @retval EFI_SUCCESS The size of theLabel Storage Area and maximum transfer size returned are valid. + @retval EFI_ACCESS_DENIED The Label Storage Area for the NVDIMM device is not currently accessible. + @retval EFI_DEVICE_ERROR A physical device error occurred and the data transfer failed to complete. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_NVDIMM_LABEL_STORAGE_INFORMATION) ( + IN EFI_NVDIMM_LABEL_PROTOCOL *This, + OUT UINT32 *SizeOfLabelStorageArea, + OUT UINT32 *MaxTransferLength + ); + +/** + Retrieves the label data for the requested offset and length from within the Label Storage Area for + the NVDIMM. + + @param This A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance. + @param Offset The byte offset within the Label Storage Area to read from. + @param TransferLength Number of bytes to read from the Label Storage Area beginning at the byte + Offset specified. A TransferLength of 0 reads no data. + @param LabelData The return label data read at the requested offset and length from within + the Label Storage Area. + + @retval EFI_SUCCESS The label data from the Label Storage Area for the NVDIMM was read successfully + at the specified Offset and TransferLength and LabelData contains valid data. + @retval EFI_INVALID_PARAMETER Any of the following are true: + - Offset > SizeOfLabelStorageArea reported in the LabelStorageInformation return data. + - Offset + TransferLength is > SizeOfLabelStorageArea reported in the + LabelStorageInformation return data. + - TransferLength is > MaxTransferLength reported in the LabelStorageInformation return + data. + @retval EFI_ACCESS_DENIED The Label Storage Area for the NVDIMM device is not currently accessible and labels + cannot be read at this time. + @retval EFI_DEVICE_ERROR A physical device error occurred and the data transfer failed to complete. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_NVDIMM_LABEL_STORAGE_READ) ( + IN CONST EFI_NVDIMM_LABEL_PROTOCOL *This, + IN UINT32 Offset, + IN UINT32 TransferLength, + OUT UINT8 *LabelData + ); + +/** + Writes the label data for the requested offset and length in to the Label Storage Area for the NVDIMM. + + @param This A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance. + @param Offset The byte offset within the Label Storage Area to write to. + @param TransferLength Number of bytes to write to the Label Storage Area beginning at the byte + Offset specified. A TransferLength of 0 writes no data. + @param LabelData The return label data write at the requested offset and length from within + the Label Storage Area. + + @retval EFI_SUCCESS The label data from the Label Storage Area for the NVDIMM written read successfully + at the specified Offset and TransferLength. + @retval EFI_INVALID_PARAMETER Any of the following are true: + - Offset > SizeOfLabelStorageArea reported in the LabelStorageInformation return data. + - Offset + TransferLength is > SizeOfLabelStorageArea reported in the + LabelStorageInformation return data. + - TransferLength is > MaxTransferLength reported in the LabelStorageInformation return + data. + @retval EFI_ACCESS_DENIED The Label Storage Area for the NVDIMM device is not currently accessible and labels + cannot be written at this time. + @retval EFI_DEVICE_ERROR A physical device error occurred and the data transfer failed to complete. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_NVDIMM_LABEL_STORAGE_WRITE) ( + IN CONST EFI_NVDIMM_LABEL_PROTOCOL *This, + IN UINT32 Offset, + IN UINT32 TransferLength, + IN UINT8 *LabelData + ); + +/// +/// Provides services that allow management of labels contained in a Label Storage Area. +/// +struct _EFI_NVDIMM_LABEL_PROTOCOL { + EFI_NVDIMM_LABEL_STORAGE_INFORMATION LabelStorageInformation; + EFI_NVDIMM_LABEL_STORAGE_READ LabelStorageRead; + EFI_NVDIMM_LABEL_STORAGE_WRITE LabelStorageWrite; +}; + +extern EFI_GUID gEfiNvdimmLabelProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/NvmExpressPassthru.h b/MdePkg/Include/Protocol/NvmExpressPassthru.h index 15879e578d59..f804d0f88d0c 100644 --- a/MdePkg/Include/Protocol/NvmExpressPassthru.h +++ b/MdePkg/Include/Protocol/NvmExpressPassthru.h @@ -3,14 +3,11 @@ NVM Express controller or to a specific namespace in a NVM Express controller. This protocol interface is optimized for storage. - Copyright (c) 2013 - 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php. + Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.5. **/ @@ -132,7 +129,7 @@ typedef struct { @param[in] Event If non-blocking I/O is not supported then Event is ignored, and blocking I/O is performed. If Event is NULL, then blocking I/O is performed. If Event is not NULL and non-blocking I/O is supported, then non-blocking I/O is performed, and Event will be signaled when the NVM - Express Command Packet completes. + Express Command Packet completes. @retval EFI_SUCCESS The NVM Express Command Packet was sent by the host. TransferLength bytes were transferred to, or from DataBuffer. @@ -162,7 +159,7 @@ EFI_STATUS Used to retrieve the next namespace ID for this NVM Express controller. The EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL.GetNextNamespace() function retrieves the next valid - namespace ID on this NVM Express controller. + namespace ID on this NVM Express controller. If on input the value pointed to by NamespaceId is 0xFFFFFFFF, then the first valid namespace ID defined on the NVM Express controller is returned in the location pointed to by NamespaceId @@ -206,7 +203,7 @@ EFI_STATUS If the NamespaceId is not valid, then EFI_NOT_FOUND is returned. - If DevicePath is NULL, then EFI_INVALID_PARAMETER is returned. + If DevicePath is NULL, then EFI_INVALID_PARAMETER is returned. If there are not enough resources to allocate the device path node, then EFI_OUT_OF_RESOURCES is returned. @@ -217,7 +214,7 @@ EFI_STATUS @param[in] NamespaceId The NVM Express namespace ID for which a device path node is to be allocated and built. Caller must set the NamespaceId to zero if the device path node will contain a valid UUID. - @param[in,out] DevicePath A pointer to a single device path node that describes the NVM Express + @param[out] DevicePath A pointer to a single device path node that describes the NVM Express namespace specified by NamespaceId. This function is responsible for allocating the buffer DevicePath with the boot service AllocatePool(). It is the caller's responsibility to free DevicePath when the caller @@ -234,7 +231,7 @@ EFI_STATUS (EFIAPI *EFI_NVM_EXPRESS_PASS_THRU_BUILD_DEVICE_PATH)( IN EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL *This, IN UINT32 NamespaceId, - IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath + OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath ); /** diff --git a/MdePkg/Include/Protocol/PartitionInfo.h b/MdePkg/Include/Protocol/PartitionInfo.h new file mode 100644 index 000000000000..cabf140eb3e9 --- /dev/null +++ b/MdePkg/Include/Protocol/PartitionInfo.h @@ -0,0 +1,68 @@ +/** @file + This file defines the EFI Partition Information Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol is introduced in UEFI Specification 2.7 + +**/ + +#ifndef __PARTITION_INFO_PROTOCOL_H__ +#define __PARTITION_INFO_PROTOCOL_H__ + +#include <IndustryStandard/Mbr.h> +#include <Uefi/UefiGpt.h> + +// +// EFI Partition Information Protocol GUID value +// +#define EFI_PARTITION_INFO_PROTOCOL_GUID \ + { 0x8cf2f62c, 0xbc9b, 0x4821, { 0x80, 0x8d, 0xec, 0x9e, 0xc4, 0x21, 0xa1, 0xa0 }}; + + +#define EFI_PARTITION_INFO_PROTOCOL_REVISION 0x0001000 +#define PARTITION_TYPE_OTHER 0x00 +#define PARTITION_TYPE_MBR 0x01 +#define PARTITION_TYPE_GPT 0x02 + +#pragma pack(1) + +/// +/// Partition Information Protocol structure. +/// +typedef struct { + // + // Set to EFI_PARTITION_INFO_PROTOCOL_REVISION. + // + UINT32 Revision; + // + // Partition info type (PARTITION_TYPE_MBR, PARTITION_TYPE_GPT, or PARTITION_TYPE_OTHER). + // + UINT32 Type; + // + // If 1, partition describes an EFI System Partition. + // + UINT8 System; + UINT8 Reserved[7]; + union { + /// + /// MBR data + /// + MBR_PARTITION_RECORD Mbr; + /// + /// GPT data + /// + EFI_PARTITION_ENTRY Gpt; + } Info; +} EFI_PARTITION_INFO_PROTOCOL; + +#pragma pack() + +/// +/// Partition Information Protocol GUID variable. +/// +extern EFI_GUID gEfiPartitionInfoProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/Pcd.h b/MdePkg/Include/Protocol/Pcd.h index e75b4e513bbc..e0eb679e745d 100644 --- a/MdePkg/Include/Protocol/Pcd.h +++ b/MdePkg/Include/Protocol/Pcd.h @@ -2,18 +2,15 @@ Native Platform Configuration Database (PCD) Protocol Different with the EFI_PCD_PROTOCOL defined in PI 1.2 specification, the native - PCD protocol provide interfaces for dynamic and dynamic-ex type PCD. + PCD protocol provide interfaces for dynamic and dynamic-ex type PCD. The interfaces in dynamic type PCD do not require the token space guid as parameter, but interfaces in dynamic-ex type PCD require token space guid as parameter. - -Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in PI Specification 1.2. **/ @@ -31,26 +28,26 @@ extern EFI_GUID gPcdProtocolGuid; /** Sets the SKU value for subsequent calls to set or get PCD token values. - SetSku() sets the SKU Id to be used for subsequent calls to set or get PCD values. + SetSku() sets the SKU Id to be used for subsequent calls to set or get PCD values. SetSku() is normally called only once by the system. - For each item (token), the database can hold a single value that applies to all SKUs, - or multiple values, where each value is associated with a specific SKU Id. Items with multiple, - SKU-specific values are called SKU enabled. - - The SKU Id of zero is reserved as a default. The valid SkuId range is 1 to 255. - For tokens that are not SKU enabled, the system ignores any set SKU Id and works with the - single value for that token. For SKU-enabled tokens, the system will use the SKU Id set by the - last call to SetSku(). If no SKU Id is set or the currently set SKU Id isn't valid for the specified token, - the system uses the default SKU Id. If the system attempts to use the default SKU Id and no value has been + For each item (token), the database can hold a single value that applies to all SKUs, + or multiple values, where each value is associated with a specific SKU Id. Items with multiple, + SKU-specific values are called SKU enabled. + + The SKU Id of zero is reserved as a default. The valid SkuId range is 1 to 255. + For tokens that are not SKU enabled, the system ignores any set SKU Id and works with the + single value for that token. For SKU-enabled tokens, the system will use the SKU Id set by the + last call to SetSku(). If no SKU Id is set or the currently set SKU Id isn't valid for the specified token, + the system uses the default SKU Id. If the system attempts to use the default SKU Id and no value has been set for that Id, the results are unpredictable. - @param[in] SkuId The SKU value that will be used when the PCD service will retrieve and + @param[in] SkuId The SKU value that will be used when the PCD service will retrieve and set values associated with a PCD token. **/ -typedef +typedef VOID (EFIAPI *PCD_PROTOCOL_SET_SKU)( IN UINTN SkuId @@ -61,13 +58,13 @@ VOID /** Retrieves an 8-bit value for a given PCD token. - Retrieves the current byte-sized value for a PCD token number. + Retrieves the current byte-sized value for a PCD token number. If the TokenNumber is invalid, the results are unpredictable. - - @param[in] TokenNumber The PCD token number. + + @param[in] TokenNumber The PCD token number. @return The UINT8 value. - + **/ typedef UINT8 @@ -80,13 +77,13 @@ UINT8 /** Retrieves a 16-bit value for a given PCD token. - Retrieves the current 16-bit value for a PCD token number. + Retrieves the current 16-bit value for a PCD token number. If the TokenNumber is invalid, the results are unpredictable. - - @param[in] TokenNumber The PCD token number. + + @param[in] TokenNumber The PCD token number. @return The UINT16 value. - + **/ typedef UINT16 @@ -99,13 +96,13 @@ UINT16 /** Retrieves a 32-bit value for a given PCD token. - Retrieves the current 32-bit value for a PCD token number. + Retrieves the current 32-bit value for a PCD token number. If the TokenNumber is invalid, the results are unpredictable. - - @param[in] TokenNumber The PCD token number. + + @param[in] TokenNumber The PCD token number. @return The UINT32 value. - + **/ typedef UINT32 @@ -118,13 +115,13 @@ UINT32 /** Retrieves a 64-bit value for a given PCD token. - Retrieves the current 64-bit value for a PCD token number. + Retrieves the current 64-bit value for a PCD token number. If the TokenNumber is invalid, the results are unpredictable. - - @param[in] TokenNumber The PCD token number. + + @param[in] TokenNumber The PCD token number. @return The UINT64 value. - + **/ typedef UINT64 @@ -137,15 +134,15 @@ UINT64 /** Retrieves a pointer to a value for a given PCD token. - Retrieves the current pointer to the buffer for a PCD token number. - Do not make any assumptions about the alignment of the pointer that - is returned by this function call. If the TokenNumber is invalid, + Retrieves the current pointer to the buffer for a PCD token number. + Do not make any assumptions about the alignment of the pointer that + is returned by this function call. If the TokenNumber is invalid, the results are unpredictable. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @return The pointer to the buffer to be retrived. - + **/ typedef VOID * @@ -158,15 +155,15 @@ VOID * /** Retrieves a Boolean value for a given PCD token. - Retrieves the current boolean value for a PCD token number. - Do not make any assumptions about the alignment of the pointer that - is returned by this function call. If the TokenNumber is invalid, + Retrieves the current boolean value for a PCD token number. + Do not make any assumptions about the alignment of the pointer that + is returned by this function call. If the TokenNumber is invalid, the results are unpredictable. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @return The Boolean value. - + **/ typedef BOOLEAN @@ -179,13 +176,13 @@ BOOLEAN /** Retrieves the size of the value for a given PCD token. - Retrieves the current size of a particular PCD token. + Retrieves the current size of a particular PCD token. If the TokenNumber is invalid, the results are unpredictable. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @return The size of the value for the PCD token. - + **/ typedef UINTN @@ -198,16 +195,16 @@ UINTN /** Retrieves an 8-bit value for a given PCD token. - Retrieves the 8-bit value of a particular PCD token. + Retrieves the 8-bit value of a particular PCD token. If the TokenNumber is invalid or the token space - specified by Guid does not exist, the results are + specified by Guid does not exist, the results are unpredictable. @param[in] Guid The token space for the token number. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @return The size 8-bit value for the PCD token. - + **/ typedef UINT8 @@ -221,16 +218,16 @@ UINT8 /** Retrieves a 16-bit value for a given PCD token. - Retrieves the 16-bit value of a particular PCD token. + Retrieves the 16-bit value of a particular PCD token. If the TokenNumber is invalid or the token space - specified by Guid does not exist, the results are + specified by Guid does not exist, the results are unpredictable. @param[in] Guid The token space for the token number. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @return The size 16-bit value for the PCD token. - + **/ typedef UINT16 @@ -244,16 +241,16 @@ UINT16 /** Retrieves a 32-bit value for a given PCD token. - Retrieves the 32-bit value of a particular PCD token. + Retrieves the 32-bit value of a particular PCD token. If the TokenNumber is invalid or the token space - specified by Guid does not exist, the results are + specified by Guid does not exist, the results are unpredictable. @param[in] Guid The token space for the token number. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @return The size 32-bit value for the PCD token. - + **/ typedef UINT32 @@ -267,16 +264,16 @@ UINT32 /** Retrieves an 64-bit value for a given PCD token. - Retrieves the 64-bit value of a particular PCD token. + Retrieves the 64-bit value of a particular PCD token. If the TokenNumber is invalid or the token space - specified by Guid does not exist, the results are + specified by Guid does not exist, the results are unpredictable. @param[in] Guid The token space for the token number. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @return The size 64-bit value for the PCD token. - + **/ typedef UINT64 @@ -290,16 +287,16 @@ UINT64 /** Retrieves a pointer to a value for a given PCD token. - Retrieves the current pointer to the buffer for a PCD token number. - Do not make any assumptions about the alignment of the pointer that - is returned by this function call. If the TokenNumber is invalid, + Retrieves the current pointer to the buffer for a PCD token number. + Do not make any assumptions about the alignment of the pointer that + is returned by this function call. If the TokenNumber is invalid, the results are unpredictable. @param[in] Guid The token space for the token number. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @return The pointer to the buffer to be retrieved. - + **/ typedef VOID * @@ -313,16 +310,16 @@ VOID * /** Retrieves a Boolean value for a given PCD token. - Retrieves the Boolean value of a particular PCD token. + Retrieves the Boolean value of a particular PCD token. If the TokenNumber is invalid or the token space - specified by Guid does not exist, the results are + specified by Guid does not exist, the results are unpredictable. @param[in] Guid The token space for the token number. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @return The size Boolean value for the PCD token. - + **/ typedef BOOLEAN @@ -336,14 +333,14 @@ BOOLEAN /** Retrieves the size of the value for a given PCD token. - Retrieves the current size of a particular PCD token. + Retrieves the current size of a particular PCD token. If the TokenNumber is invalid, the results are unpredictable. @param[in] Guid The token space for the token number. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @return The size of the value for the PCD token. - + **/ typedef UINTN @@ -357,19 +354,19 @@ UINTN /** Sets an 8-bit value for a given PCD token. - When the PCD service sets a value, it will check to ensure that the - size of the value being set is compatible with the Token's existing definition. + When the PCD service sets a value, it will check to ensure that the + size of the value being set is compatible with the Token's existing definition. If it is not, an error will be returned. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @param[in] Value The value to set for the PCD token. @retval EFI_SUCCESS The procedure returned successfully. - @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data - being set was incompatible with a call to this function. + @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data + being set was incompatible with a call to this function. Use GetSize() to retrieve the size of the target data. @retval EFI_NOT_FOUND The PCD service could not find the requested token number. - + **/ typedef EFI_STATUS @@ -383,19 +380,19 @@ EFI_STATUS /** Sets a 16-bit value for a given PCD token. - When the PCD service sets a value, it will check to ensure that the - size of the value being set is compatible with the Token's existing definition. + When the PCD service sets a value, it will check to ensure that the + size of the value being set is compatible with the Token's existing definition. If it is not, an error will be returned. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @param[in] Value The value to set for the PCD token. @retval EFI_SUCCESS The procedure returned successfully. - @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data - being set was incompatible with a call to this function. + @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data + being set was incompatible with a call to this function. Use GetSize() to retrieve the size of the target data. @retval EFI_NOT_FOUND The PCD service could not find the requested token number. - + **/ typedef EFI_STATUS @@ -409,19 +406,19 @@ EFI_STATUS /** Sets a 32-bit value for a given PCD token. - When the PCD service sets a value, it will check to ensure that the - size of the value being set is compatible with the Token's existing definition. + When the PCD service sets a value, it will check to ensure that the + size of the value being set is compatible with the Token's existing definition. If it is not, an error will be returned. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @param[in] Value The value to set for the PCD token. @retval EFI_SUCCESS The procedure returned successfully. - @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data - being set was incompatible with a call to this function. + @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data + being set was incompatible with a call to this function. Use GetSize() to retrieve the size of the target data. @retval EFI_NOT_FOUND The PCD service could not find the requested token number. - + **/ typedef EFI_STATUS @@ -435,19 +432,19 @@ EFI_STATUS /** Sets a 64-bit value for a given PCD token. - When the PCD service sets a value, it will check to ensure that the - size of the value being set is compatible with the Token's existing definition. + When the PCD service sets a value, it will check to ensure that the + size of the value being set is compatible with the Token's existing definition. If it is not, an error will be returned. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @param[in] Value The value to set for the PCD token. @retval EFI_SUCCESS The procedure returned successfully. - @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data - being set was incompatible with a call to this function. + @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data + being set was incompatible with a call to this function. Use GetSize() to retrieve the size of the target data. @retval EFI_NOT_FOUND The PCD service could not find the requested token number. - + **/ typedef EFI_STATUS @@ -461,23 +458,23 @@ EFI_STATUS /** Sets a value of a specified size for a given PCD token. - When the PCD service sets a value, it will check to ensure that the - size of the value being set is compatible with the Token's existing definition. + When the PCD service sets a value, it will check to ensure that the + size of the value being set is compatible with the Token's existing definition. If it is not, an error will be returned. - @param[in] TokenNumber The PCD token number. - @param[in, out] SizeOfBuffer A pointer to the length of the value being set for the PCD token. - On input, if the SizeOfValue is greater than the maximum size supported - for this TokenNumber then the output value of SizeOfValue will reflect + @param[in] TokenNumber The PCD token number. + @param[in, out] SizeOfBuffer A pointer to the length of the value being set for the PCD token. + On input, if the SizeOfValue is greater than the maximum size supported + for this TokenNumber then the output value of SizeOfValue will reflect the maximum size supported for this TokenNumber. @param[in] Buffer The buffer to set for the PCD token. @retval EFI_SUCCESS The procedure returned successfully. - @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data - being set was incompatible with a call to this function. + @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data + being set was incompatible with a call to this function. Use GetSize() to retrieve the size of the target data. @retval EFI_NOT_FOUND The PCD service could not find the requested token number. - + **/ typedef EFI_STATUS @@ -492,19 +489,19 @@ EFI_STATUS /** Sets a Boolean value for a given PCD token. - When the PCD service sets a value, it will check to ensure that the - size of the value being set is compatible with the Token's existing definition. + When the PCD service sets a value, it will check to ensure that the + size of the value being set is compatible with the Token's existing definition. If it is not, an error will be returned. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @param[in] Value The value to set for the PCD token. @retval EFI_SUCCESS The procedure returned successfully. - @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data - being set was incompatible with a call to this function. + @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data + being set was incompatible with a call to this function. Use GetSize() to retrieve the size of the target data. @retval EFI_NOT_FOUND The PCD service could not find the requested token number. - + **/ typedef EFI_STATUS @@ -518,20 +515,20 @@ EFI_STATUS /** Sets an 8-bit value for a given PCD token. - When the PCD service sets a value, it will check to ensure that the - size of the value being set is compatible with the Token's existing definition. + When the PCD service sets a value, it will check to ensure that the + size of the value being set is compatible with the Token's existing definition. If it is not, an error will be returned. @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @param[in] Value The value to set for the PCD token. @retval EFI_SUCCESS The procedure returned successfully. - @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data - being set was incompatible with a call to this function. + @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data + being set was incompatible with a call to this function. Use GetSize() to retrieve the size of the target data. @retval EFI_NOT_FOUND The PCD service could not find the requested token number. - + **/ typedef EFI_STATUS @@ -546,20 +543,20 @@ EFI_STATUS /** Sets an 16-bit value for a given PCD token. - When the PCD service sets a value, it will check to ensure that the - size of the value being set is compatible with the Token's existing definition. + When the PCD service sets a value, it will check to ensure that the + size of the value being set is compatible with the Token's existing definition. If it is not, an error will be returned. @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @param[in] Value The value to set for the PCD token. @retval EFI_SUCCESS The procedure returned successfully. - @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data - being set was incompatible with a call to this function. + @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data + being set was incompatible with a call to this function. Use GetSize() to retrieve the size of the target data. @retval EFI_NOT_FOUND The PCD service could not find the requested token number. - + **/ typedef EFI_STATUS @@ -574,20 +571,20 @@ EFI_STATUS /** Sets a 32-bit value for a given PCD token. - When the PCD service sets a value, it will check to ensure that the - size of the value being set is compatible with the Token's existing definition. + When the PCD service sets a value, it will check to ensure that the + size of the value being set is compatible with the Token's existing definition. If it is not, an error will be returned. @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @param[in] Value The value to set for the PCD token. @retval EFI_SUCCESS The procedure returned successfully. - @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data - being set was incompatible with a call to this function. + @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data + being set was incompatible with a call to this function. Use GetSize() to retrieve the size of the target data. @retval EFI_NOT_FOUND The PCD service could not find the requested token number. - + **/ typedef EFI_STATUS @@ -602,20 +599,20 @@ EFI_STATUS /** Sets a 64-bit value for a given PCD token. - When the PCD service sets a value, it will check to ensure that the - size of the value being set is compatible with the Token's existing definition. + When the PCD service sets a value, it will check to ensure that the + size of the value being set is compatible with the Token's existing definition. If it is not, an error will be returned. @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @param[in] Value The value to set for the PCD token. @retval EFI_SUCCESS The procedure returned successfully. - @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data - being set was incompatible with a call to this function. + @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data + being set was incompatible with a call to this function. Use GetSize() to retrieve the size of the target data. @retval EFI_NOT_FOUND The PCD service could not find the requested token number. - + **/ typedef EFI_STATUS @@ -630,24 +627,24 @@ EFI_STATUS /** Sets a value of a specified size for a given PCD token. - When the PCD service sets a value, it will check to ensure that the - size of the value being set is compatible with the Token's existing definition. + When the PCD service sets a value, it will check to ensure that the + size of the value being set is compatible with the Token's existing definition. If it is not, an error will be returned. @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value. - @param[in] TokenNumber The PCD token number. - @param[in, out] SizeOfBuffer A pointer to the length of the value being set for the PCD token. - On input, if the SizeOfValue is greater than the maximum size supported - for this TokenNumber then the output value of SizeOfValue will reflect + @param[in] TokenNumber The PCD token number. + @param[in, out] SizeOfBuffer A pointer to the length of the value being set for the PCD token. + On input, if the SizeOfValue is greater than the maximum size supported + for this TokenNumber then the output value of SizeOfValue will reflect the maximum size supported for this TokenNumber. @param[in] Buffer The buffer to set for the PCD token. @retval EFI_SUCCESS The procedure returned successfully. - @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data - being set was incompatible with a call to this function. + @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data + being set was incompatible with a call to this function. Use GetSize() to retrieve the size of the target data. @retval EFI_NOT_FOUND The PCD service could not find the requested token number. - + **/ typedef EFI_STATUS @@ -663,20 +660,20 @@ EFI_STATUS /** Sets a Boolean value for a given PCD token. - When the PCD service sets a value, it will check to ensure that the - size of the value being set is compatible with the Token's existing definition. + When the PCD service sets a value, it will check to ensure that the + size of the value being set is compatible with the Token's existing definition. If it is not, an error will be returned. @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @param[in] Value The value to set for the PCD token. @retval EFI_SUCCESS The procedure returned successfully. - @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data - being set was incompatible with a call to this function. + @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data + being set was incompatible with a call to this function. Use GetSize() to retrieve the size of the target data. @retval EFI_NOT_FOUND The PCD service could not find the requested token number. - + **/ typedef EFI_STATUS @@ -685,18 +682,18 @@ EFI_STATUS IN UINTN TokenNumber, IN BOOLEAN Value ); - + /** Callback on SET function prototype definition. - This notification function serves two purposes. - Firstly, it notifies the module which did the registration that the value - of this PCD token has been set. Secondly, it provides a mechanism for the - module that did the registration to intercept the set operation and override - the value that has been set, if necessary. After the invocation of the callback function, - TokenData will be used by PCD service DXE driver to modify the internal data in + This notification function serves two purposes. + Firstly, it notifies the module which did the registration that the value + of this PCD token has been set. Secondly, it provides a mechanism for the + module that did the registration to intercept the set operation and override + the value that has been set, if necessary. After the invocation of the callback function, + TokenData will be used by PCD service DXE driver to modify the internal data in PCD database. @param[in] CallBackGuid The PCD token GUID being set. @@ -721,11 +718,11 @@ VOID /** Specifies a function to be called anytime the value of a designated token is changed. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value. - @param[in] CallBackFunction The function prototype called when the value associated with the CallBackToken is set. + @param[in] CallBackFunction The function prototype called when the value associated with the CallBackToken is set. - @retval EFI_SUCCESS The PCD service has successfully established a call event + @retval EFI_SUCCESS The PCD service has successfully established a call event for the CallBackToken requested. @retval EFI_NOT_FOUND The PCD service could not find the referenced token number. @@ -743,11 +740,11 @@ EFI_STATUS /** Cancels a previously set callback function for a particular PCD token number. - @param[in] TokenNumber The PCD token number. + @param[in] TokenNumber The PCD token number. @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value. - @param[in] CallBackFunction The function prototype called when the value associated with the CallBackToken is set. + @param[in] CallBackFunction The function prototype called when the value associated with the CallBackToken is set. - @retval EFI_SUCCESS The PCD service has successfully established a call event + @retval EFI_SUCCESS The PCD service has successfully established a call event for the CallBackToken requested. @retval EFI_NOT_FOUND The PCD service could not find the referenced token number. @@ -763,32 +760,32 @@ EFI_STATUS /** - Retrieves the next valid token number in a given namespace. - - This is useful since the PCD infrastructure contains a sparse list of token numbers, + Retrieves the next valid token number in a given namespace. + + This is useful since the PCD infrastructure contains a sparse list of token numbers, and one cannot a priori know what token numbers are valid in the database. - - If TokenNumber is 0 and Guid is not NULL, then the first token from the token space specified by Guid is returned. - If TokenNumber is not 0 and Guid is not NULL, then the next token in the token space specified by Guid is returned. - If TokenNumber is 0 and Guid is NULL, then the first token in the default token space is returned. - If TokenNumber is not 0 and Guid is NULL, then the next token in the default token space is returned. - The token numbers in the default token space may not be related to token numbers in token spaces that are named by Guid. - If the next token number can be retrieved, then it is returned in TokenNumber, and EFI_SUCCESS is returned. - If TokenNumber represents the last token number in the token space specified by Guid, then EFI_NOT_FOUND is returned. + + If TokenNumber is 0 and Guid is not NULL, then the first token from the token space specified by Guid is returned. + If TokenNumber is not 0 and Guid is not NULL, then the next token in the token space specified by Guid is returned. + If TokenNumber is 0 and Guid is NULL, then the first token in the default token space is returned. + If TokenNumber is not 0 and Guid is NULL, then the next token in the default token space is returned. + The token numbers in the default token space may not be related to token numbers in token spaces that are named by Guid. + If the next token number can be retrieved, then it is returned in TokenNumber, and EFI_SUCCESS is returned. + If TokenNumber represents the last token number in the token space specified by Guid, then EFI_NOT_FOUND is returned. If TokenNumber is not present in the token space specified by Guid, then EFI_NOT_FOUND is returned. - @param[in] Guid The 128-bit unique value that designates the namespace from which to retrieve the next token. - This is an optional parameter that may be NULL. If this parameter is NULL, then a request is + @param[in] Guid The 128-bit unique value that designates the namespace from which to retrieve the next token. + This is an optional parameter that may be NULL. If this parameter is NULL, then a request is being made to retrieve tokens from the default token space. - @param[in,out] TokenNumber - A pointer to the PCD token number to use to find the subsequent token number. + @param[in,out] TokenNumber + A pointer to the PCD token number to use to find the subsequent token number. @retval EFI_SUCCESS The PCD service has retrieved the next valid token number. @retval EFI_NOT_FOUND The PCD service could not find data from the requested token number. **/ -typedef +typedef EFI_STATUS (EFIAPI *PCD_PROTOCOL_GET_NEXT_TOKEN)( IN CONST EFI_GUID *Guid, OPTIONAL @@ -813,7 +810,7 @@ EFI_STATUS @retval EFI_NOT_FOUND The PCD service could not find the next valid token namespace. **/ -typedef +typedef EFI_STATUS (EFIAPI *PCD_PROTOCOL_GET_NEXT_TOKENSPACE)( IN OUT CONST EFI_GUID **Guid diff --git a/MdePkg/Include/Protocol/PcdInfo.h b/MdePkg/Include/Protocol/PcdInfo.h index e34967e0a3e8..3f461b978acd 100644 --- a/MdePkg/Include/Protocol/PcdInfo.h +++ b/MdePkg/Include/Protocol/PcdInfo.h @@ -4,18 +4,15 @@ The protocol that provides additional information about items that reside in the PCD database. Different with the EFI_GET_PCD_INFO_PROTOCOL defined in PI 1.2.1 specification, - the native PCD INFO PROTOCOL provide interfaces for dynamic and dynamic-ex type PCD. + the native PCD INFO PROTOCOL provide interfaces for dynamic and dynamic-ex type PCD. The interfaces for dynamic type PCD do not require the token space guid as parameter, but interfaces for dynamic-ex type PCD require token space guid as parameter. - Copyright (c) 2013, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + @par Revision Reference: + This Protocol was introduced in PI Specification 1.2. **/ diff --git a/MdePkg/Include/Protocol/PciEnumerationComplete.h b/MdePkg/Include/Protocol/PciEnumerationComplete.h index c817774cb3c5..8054c48b6af4 100644 --- a/MdePkg/Include/Protocol/PciEnumerationComplete.h +++ b/MdePkg/Include/Protocol/PciEnumerationComplete.h @@ -3,13 +3,7 @@ This protocol indicates that pci enumeration complete Copyright (c) 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is defined in UEFI Platform Initialization Specification 1.2 diff --git a/MdePkg/Include/Protocol/PciHostBridgeResourceAllocation.h b/MdePkg/Include/Protocol/PciHostBridgeResourceAllocation.h index 2d41ac152990..744c47aaac72 100644 --- a/MdePkg/Include/Protocol/PciHostBridgeResourceAllocation.h +++ b/MdePkg/Include/Protocol/PciHostBridgeResourceAllocation.h @@ -1,21 +1,15 @@ /** @file - This file declares PCI Host Bridge Resource Allocation Protocol which - provides the basic interfaces to abstract a PCI host bridge resource allocation. + This file declares PCI Host Bridge Resource Allocation Protocol which + provides the basic interfaces to abstract a PCI host bridge resource allocation. This protocol is mandatory if the system includes PCI devices. - -Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: - This Protocol is defined in UEFI Platform Initialization Specification 1.2 + This Protocol is defined in UEFI Platform Initialization Specification 1.2 Volume 5: Standards. - + **/ #ifndef _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_ @@ -56,14 +50,14 @@ typedef struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL EFI_PCI_HOST_BR #define EFI_PCI_HOST_BRIDGE_MEM64_DECODE 2 /// -/// A UINT64 value that contains the status of a PCI resource requested +/// A UINT64 value that contains the status of a PCI resource requested /// in the Configuration parameter returned by GetProposedResources() /// The legal values are EFI_RESOURCE_SATISFIED and EFI_RESOURCE_NOT_SATISFIED /// typedef UINT64 EFI_RESOURCE_ALLOCATION_STATUS; /// -/// The request of this resource type could be fulfilled. Used in the +/// The request of this resource type could be fulfilled. Used in the /// Configuration parameter returned by GetProposedResources() to identify /// a PCI resources request that can be satisfied. /// @@ -71,7 +65,7 @@ typedef UINT64 EFI_RESOURCE_ALLOCATION_STATUS; /// /// The request of this resource type could not be fulfilled for its -/// absence in the host bridge resource pool. Used in the Configuration parameter +/// absence in the host bridge resource pool. Used in the Configuration parameter /// returned by GetProposedResources() to identify a PCI resources request that /// can not be satisfied. /// @@ -92,45 +86,45 @@ typedef enum { /// /// The bus allocation phase is about to begin. No specific action /// is required here. This notification can be used to perform any - /// chipset specific programming. + /// chipset specific programming. /// EfiPciHostBridgeBeginBusAllocation, /// /// The bus allocation and bus programming phase is complete. No specific /// action is required here. This notification can be used to perform any - /// chipset specific programming. + /// chipset specific programming. /// EfiPciHostBridgeEndBusAllocation, - + /// /// The resource allocation phase is about to begin.No specific action is - /// required here. This notification can be used to perform any chipset specific programming. + /// required here. This notification can be used to perform any chipset specific programming. /// EfiPciHostBridgeBeginResourceAllocation, - + /// /// Allocate resources per previously submitted requests for all the PCI Root /// Bridges. These resource settings are returned on the next call to - /// GetProposedResources(). + /// GetProposedResources(). /// EfiPciHostBridgeAllocateResources, - + /// /// Program the Host Bridge hardware to decode previously allocated resources /// (proposed resources) for all the PCI Root Bridges. /// EfiPciHostBridgeSetResources, - + /// /// De-allocate previously allocated resources previously for all the PCI - /// Root Bridges and reset the I/O and memory apertures to initial state. + /// Root Bridges and reset the I/O and memory apertures to initial state. /// EfiPciHostBridgeFreeResources, - + /// /// The resource allocation phase is completed. No specific action is required - /// here. This notification can be used to perform any chipset specific programming. + /// here. This notification can be used to perform any chipset specific programming. /// EfiPciHostBridgeEndResourceAllocation, @@ -158,30 +152,30 @@ typedef enum { /// /// This notification is sent before the PCI enumerator probes BAR registers - /// for every valid PCI function. + /// for every valid PCI function. /// EfiPciBeforeResourceCollection } EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE; /** - These are the notifications from the PCI bus driver that it is about to enter a certain phase of the PCI + These are the notifications from the PCI bus driver that it is about to enter a certain phase of the PCI enumeration process. - @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance. @param[in] Phase The phase during enumeration. @retval EFI_SUCCESS The notification was accepted without any errors. @retval EFI_INVALID_PARAMETER The Phase is invalid. - @retval EFI_NOT_READY This phase cannot be entered at this time. For example, this error - is valid for a Phase of EfiPciHostBridgeAllocateResources if - SubmitResources() has not been called for one or more + @retval EFI_NOT_READY This phase cannot be entered at this time. For example, this error + is valid for a Phase of EfiPciHostBridgeAllocateResources if + SubmitResources() has not been called for one or more PCI root bridges before this call. - @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. This error is valid for + @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. This error is valid for a Phase of EfiPciHostBridgeSetResources. - @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. This error is valid for a Phase of EfiPciHostBridgeAllocateResources - if the previously submitted resource requests cannot be fulfilled or were only + if the previously submitted resource requests cannot be fulfilled or were only partially fulfilled **/ @@ -195,15 +189,15 @@ EFI_STATUS /** Returns the device handle of the next PCI root bridge that is associated with this host bridge. - @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance. - @param[in,out] RootBridgeHandle Returns the device handle of the next PCI root bridge. On input, it holds the - RootBridgeHandle that was returned by the most recent call to - GetNextRootBridge(). If RootBridgeHandle is NULL on input, the handle + @param[in,out] RootBridgeHandle Returns the device handle of the next PCI root bridge. On input, it holds the + RootBridgeHandle that was returned by the most recent call to + GetNextRootBridge(). If RootBridgeHandle is NULL on input, the handle for the first PCI root bridge is returned. @retval EFI_SUCCESS The requested attribute information was returned. - @retval EFI_INVALID_PARAMETER RootBridgeHandle is not an EFI_HANDLE that was returned + @retval EFI_INVALID_PARAMETER RootBridgeHandle is not an EFI_HANDLE that was returned on a previous call to GetNextRootBridge(). @retval EFI_NOT_FOUND There are no more PCI root bridge device handles. @@ -218,7 +212,7 @@ EFI_STATUS /** Returns the allocation attributes of a PCI root bridge. - @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance. @param[in] RootBridgeHandle The device handle of the PCI root bridge in which the caller is interested. @param[out] Attribute The pointer to attributes of the PCI root bridge. @@ -239,12 +233,12 @@ EFI_STATUS /** Sets up the specified PCI root bridge for the bus enumeration process. - @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance. @param[in] RootBridgeHandle The PCI root bridge to be set up. @param[out] Configuration The pointer to the pointer to the PCI bus resource descriptor. - @retval EFI_SUCCESS The PCI root bridge was set up and the bus range was returned in + @retval EFI_SUCCESS The PCI root bridge was set up and the bus range was returned in Configuration. @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. @@ -263,20 +257,20 @@ EFI_STATUS Programs the PCI root bridge hardware so that it decodes the specified PCI bus range. @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL - instance. + instance. @param[in] RootBridgeHandle The PCI root bridge whose bus range is to be programmed. @param[in] Configuration The pointer to the PCI bus resource descriptor. @retval EFI_SUCCESS The bus range for the PCI root bridge was programmed. @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. @retval EFI_INVALID_PARAMETER Configuration is NULL - @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI (2.0 & 3.0) + @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI (2.0 & 3.0) resource descriptor. @retval EFI_INVALID_PARAMETER Configuration does not include a valid ACPI 2.0 bus resource descriptor. - @retval EFI_INVALID_PARAMETER Configuration includes valid ACPI (2.0 & 3.0) resource + @retval EFI_INVALID_PARAMETER Configuration includes valid ACPI (2.0 & 3.0) resource descriptors other than bus descriptors. - @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid ACPI resource + @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid ACPI resource descriptors. @retval EFI_INVALID_PARAMETER "Address Range Minimum" is invalid for this root bridge. @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this root bridge. @@ -294,26 +288,26 @@ EFI_STATUS /** Submits the I/O and memory resource requirements for the specified PCI root bridge. - @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance. - @param[in] RootBridgeHandle The PCI root bridge whose I/O and memory resource requirements are being + @param[in] RootBridgeHandle The PCI root bridge whose I/O and memory resource requirements are being submitted. @param[in] Configuration The pointer to the PCI I/O and PCI memory resource descriptor. - @retval EFI_SUCCESS The I/O and memory resource requests for a PCI root bridge were + @retval EFI_SUCCESS The I/O and memory resource requests for a PCI root bridge were accepted. @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. @retval EFI_INVALID_PARAMETER Configuration is NULL. - @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI (2.0 & 3.0) + @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI (2.0 & 3.0) resource descriptor. - @retval EFI_INVALID_PARAMETER Configuration includes requests for one or more resource - types that are not supported by this PCI root bridge. This error will - happen if the caller did not combine resources according to + @retval EFI_INVALID_PARAMETER Configuration includes requests for one or more resource + types that are not supported by this PCI root bridge. This error will + happen if the caller did not combine resources according to Attributes that were returned by GetAllocAttributes(). @retval EFI_INVALID_PARAMETER "Address Range Maximum" is invalid. @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this PCI root bridge. @retval EFI_INVALID_PARAMETER "Address Space Granularity" is invalid for this PCI root bridge. - + **/ typedef EFI_STATUS @@ -326,7 +320,7 @@ EFI_STATUS /** Returns the proposed resource settings for the specified PCI root bridge. - @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance. @param[in] RootBridgeHandle The PCI root bridge handle. @param[out] Configuration The pointer to the pointer to the PCI I/O and memory resource descriptor. @@ -346,8 +340,8 @@ EFI_STATUS ); /** - Provides the hooks from the PCI bus driver to every PCI controller (device/function) at various - stages of the PCI enumeration process that allow the host bridge driver to preinitialize individual + Provides the hooks from the PCI bus driver to every PCI controller (device/function) at various + stages of the PCI enumeration process that allow the host bridge driver to preinitialize individual PCI controllers before enumeration. @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance. @@ -357,10 +351,10 @@ EFI_STATUS @retval EFI_SUCCESS The requested parameters were returned. @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. - @retval EFI_INVALID_PARAMETER Phase is not a valid phase that is defined in + @retval EFI_INVALID_PARAMETER Phase is not a valid phase that is defined in EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE. - @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. The PCI enumerator - should not enumerate this device, including its child devices if it is + @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. The PCI enumerator + should not enumerate this device, including its child devices if it is a PCI-to-PCI bridge. **/ @@ -382,43 +376,43 @@ struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL { /// a certain phase during the enumeration process. /// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE NotifyPhase; - + /// /// Retrieves the device handle for the next PCI root bridge that is produced by the - /// host bridge to which this instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is attached. + /// host bridge to which this instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is attached. /// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE GetNextRootBridge; - + /// /// Retrieves the allocation-related attributes of a PCI root bridge. /// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES GetAllocAttributes; - + /// /// Sets up a PCI root bridge for bus enumeration. /// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION StartBusEnumeration; - + /// /// Sets up the PCI root bridge so that it decodes a specific range of bus numbers. /// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS SetBusNumbers; - + /// /// Submits the resource requirements for the specified PCI root bridge. /// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES SubmitResources; - + /// /// Returns the proposed resource assignment for the specified PCI root bridges. /// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES GetProposedResources; - + /// /// Provides hooks from the PCI bus driver to every PCI controller /// (device/function) at various stages of the PCI enumeration process that /// allow the host bridge driver to preinitialize individual PCI controllers - /// before enumeration. + /// before enumeration. /// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER PreprocessController; }; diff --git a/MdePkg/Include/Protocol/PciHotPlugInit.h b/MdePkg/Include/Protocol/PciHotPlugInit.h index 65701773825d..9cf91479ad84 100644 --- a/MdePkg/Include/Protocol/PciHotPlugInit.h +++ b/MdePkg/Include/Protocol/PciHotPlugInit.h @@ -1,56 +1,50 @@ /** @file This file declares EFI PCI Hot Plug Init Protocol. - - This protocol provides the necessary functionality to initialize the Hot Plug - Controllers (HPCs) and the buses that they control. This protocol also provides + + This protocol provides the necessary functionality to initialize the Hot Plug + Controllers (HPCs) and the buses that they control. This protocol also provides information regarding resource padding. - - @par Note: + + @par Note: This protocol is required only on platforms that support one or more PCI Hot - Plug* slots or CardBus sockets. + Plug* slots or CardBus sockets. The EFI_PCI_HOT_PLUG_INIT_PROTOCOL provides a mechanism for the PCI bus enumerator - to properly initialize the HPCs and CardBus sockets that require initialization. - The HPC initialization takes place before the PCI enumeration process is complete. - There cannot be more than one instance of this protocol in a system. This protocol - is installed on its own separate handle. - - Because the system may include multiple HPCs, one instance of this protocol - should represent all of them. The protocol functions use the device path of - the HPC to identify the HPC. When the PCI bus enumerator finds a root HPC, it + to properly initialize the HPCs and CardBus sockets that require initialization. + The HPC initialization takes place before the PCI enumeration process is complete. + There cannot be more than one instance of this protocol in a system. This protocol + is installed on its own separate handle. + + Because the system may include multiple HPCs, one instance of this protocol + should represent all of them. The protocol functions use the device path of + the HPC to identify the HPC. When the PCI bus enumerator finds a root HPC, it will call EFI_PCI_HOT_PLUG_INIT_PROTOCOL.InitializeRootHpc(). If InitializeRootHpc() - is unable to initialize a root HPC, the PCI enumerator will ignore that root HPC - and continue the enumeration process. If the HPC is not initialized, the devices + is unable to initialize a root HPC, the PCI enumerator will ignore that root HPC + and continue the enumeration process. If the HPC is not initialized, the devices that it controls may not be initialized, and no resource padding will be provided. - From the standpoint of the PCI bus enumerator, HPCs are divided into the following + From the standpoint of the PCI bus enumerator, HPCs are divided into the following two classes: - Root HPC: - These HPCs must be initialized by calling InitializeRootHpc() during the - enumeration process. These HPCs will also require resource padding. The - platform code must have a priori knowledge of these devices and must know - how to initialize them. There may not be any way to access their PCI + These HPCs must be initialized by calling InitializeRootHpc() during the + enumeration process. These HPCs will also require resource padding. The + platform code must have a priori knowledge of these devices and must know + how to initialize them. There may not be any way to access their PCI configuration space before the PCI enumerator programs all the upstream - bridges and thus enables the path to these devices. The PCI bus enumerator - is responsible for determining the PCI bus address of the HPC before it + bridges and thus enables the path to these devices. The PCI bus enumerator + is responsible for determining the PCI bus address of the HPC before it calls InitializeRootHpc(). - Nonroot HPC: - These HPCs will not need explicit initialization during enumeration process. - These HPCs will require resource padding. The platform code does not have + These HPCs will not need explicit initialization during enumeration process. + These HPCs will require resource padding. The platform code does not have to have a priori knowledge of these devices. - Copyright (c) 2007 - 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: - This Protocol is defined in UEFI Platform Initialization Specification 1.2 + This Protocol is defined in UEFI Platform Initialization Specification 1.2 Volume 5: Standards **/ @@ -77,15 +71,15 @@ typedef struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL EFI_PCI_HOT_PLUG_INIT_PROTOCOL; typedef UINT16 EFI_HPC_STATE; /// -/// The HPC initialization function was called and the HPC completed -/// initialization, but it was not enabled for some reason. The HPC may be -/// disabled in hardware, or it may be disabled due to user preferences, +/// The HPC initialization function was called and the HPC completed +/// initialization, but it was not enabled for some reason. The HPC may be +/// disabled in hardware, or it may be disabled due to user preferences, /// hardware failure, or other reasons. No resource padding is required. /// #define EFI_HPC_STATE_INITIALIZED 0x01 /// -/// The HPC initialization function was called, the HPC completed +/// The HPC initialization function was called, the HPC completed /// initialization, and it was enabled. Resource padding is required. /// #define EFI_HPC_STATE_ENABLED 0x02 @@ -95,18 +89,18 @@ typedef UINT16 EFI_HPC_STATE; /// typedef struct{ /// - /// + /// /// The device path to the root HPC. An HPC cannot control its parent buses. - /// The PCI bus driver requires this information so that it can pass the - /// correct HpcPciAddress to the InitializeRootHpc() and GetResourcePadding() - /// functions. + /// The PCI bus driver requires this information so that it can pass the + /// correct HpcPciAddress to the InitializeRootHpc() and GetResourcePadding() + /// functions. /// EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath; /// - /// The device path to the Hot Plug Bus (HPB) that is controlled by the root - /// HPC. The PCI bus driver uses this information to check if a particular PCI - /// bus has hot-plug slots. The device path of a PCI bus is the same as the - /// device path of its parent. For Standard(PCI) Hot Plug Controllers (SHPCs) + /// The device path to the Hot Plug Bus (HPB) that is controlled by the root + /// HPC. The PCI bus driver uses this information to check if a particular PCI + /// bus has hot-plug slots. The device path of a PCI bus is the same as the + /// device path of its parent. For Standard(PCI) Hot Plug Controllers (SHPCs) /// and PCI Express*, HpbDevicePath is the same as HpcDevicePath. /// EFI_DEVICE_PATH_PROTOCOL *HpbDevicePath; @@ -131,7 +125,7 @@ typedef enum { /// strategy may reduce the total amount of padding, but requires /// reprogramming of PCI-to-PCI bridges in a hot-add event. If the hotplug /// bus is behind a PCI-to-PCI bridge, the PCI-to-PCI bridge - /// apertures do not indicate the padding for that bus. + /// apertures do not indicate the padding for that bus. /// EfiPaddingPciRootBridge } EFI_HPC_PADDING_ATTRIBUTES; @@ -140,14 +134,14 @@ typedef enum { Returns a list of root Hot Plug Controllers (HPCs) that require initialization during the boot process. - This procedure returns a list of root HPCs. The PCI bus driver must initialize - these controllers during the boot process. The PCI bus driver may or may not be - able to detect these HPCs. If the platform includes a PCI-to-CardBus bridge, it - can be included in this list if it requires initialization. The HpcList must be - self consistent. An HPC cannot control any of its parent buses. Only one HPC can - control a PCI bus. Because this list includes only root HPCs, no HPC in the list - can be a child of another HPC. This policy must be enforced by the - EFI_PCI_HOT_PLUG_INIT_PROTOCOL. The PCI bus driver may not check for such + This procedure returns a list of root HPCs. The PCI bus driver must initialize + these controllers during the boot process. The PCI bus driver may or may not be + able to detect these HPCs. If the platform includes a PCI-to-CardBus bridge, it + can be included in this list if it requires initialization. The HpcList must be + self consistent. An HPC cannot control any of its parent buses. Only one HPC can + control a PCI bus. Because this list includes only root HPCs, no HPC in the list + can be a child of another HPC. This policy must be enforced by the + EFI_PCI_HOT_PLUG_INIT_PROTOCOL. The PCI bus driver may not check for such invalid conditions. The callee allocates the buffer HpcList @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance. @@ -156,7 +150,7 @@ typedef enum { elements in this list. @retval EFI_SUCCESS HpcList was returned. - @retval EFI_OUT_OF_RESOURCES HpcList was not returned due to insufficient + @retval EFI_OUT_OF_RESOURCES HpcList was not returned due to insufficient resources. @retval EFI_INVALID_PARAMETER HpcCount is NULL or HpcList is NULL. @@ -172,26 +166,26 @@ EFI_STATUS /** Initializes one root Hot Plug Controller (HPC). This process may causes initialization of its subordinate buses. - - This function initializes the specified HPC. At the end of initialization, - the hot-plug slots or sockets (controlled by this HPC) are powered and are - connected to the bus. All the necessary registers in the HPC are set up. For - a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set - up are defined in the PCI Standard Hot Plug Controller and Subsystem - Specification. + + This function initializes the specified HPC. At the end of initialization, + the hot-plug slots or sockets (controlled by this HPC) are powered and are + connected to the bus. All the necessary registers in the HPC are set up. For + a Standard (PCI) Hot Plug Controller (SHPC), the registers that must be set + up are defined in the PCI Standard Hot Plug Controller and Subsystem + Specification. @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance. @param[in] HpcDevicePath The device path to the HPC that is being initialized. @param[in] HpcPciAddress The address of the HPC function on the PCI bus. - @param[in] Event The event that should be signaled when the HPC - initialization is complete. Set to NULL if the - caller wants to wait until the entire initialization + @param[in] Event The event that should be signaled when the HPC + initialization is complete. Set to NULL if the + caller wants to wait until the entire initialization process is complete. - @param[out] HpcState The state of the HPC hardware. The state is + @param[out] HpcState The state of the HPC hardware. The state is EFI_HPC_STATE_INITIALIZED or EFI_HPC_STATE_ENABLED. @retval EFI_SUCCESS If Event is NULL, the specific HPC was successfully - initialized. If Event is not NULL, Event will be + initialized. If Event is not NULL, Event will be signaled at a later time when initialization is complete. @retval EFI_UNSUPPORTED This instance of EFI_PCI_HOT_PLUG_INIT_PROTOCOL does not support the specified HPC. @@ -215,10 +209,10 @@ EFI_STATUS by the specified Hot Plug Controller (HPC). This function returns the resource padding that is required by the PCI bus that - is controlled by the specified HPC. This member function is called for all the - root HPCs and nonroot HPCs that are detected by the PCI bus enumerator. This - function will be called before PCI resource allocation is completed. This function - must be called after all the root HPCs, with the possible exception of a + is controlled by the specified HPC. This member function is called for all the + root HPCs and nonroot HPCs that are detected by the PCI bus enumerator. This + function will be called before PCI resource allocation is completed. This function + must be called after all the root HPCs, with the possible exception of a PCI-to-CardBus bridge, have completed initialization. @param[in] This Pointer to the EFI_PCI_HOT_PLUG_INIT_PROTOCOL instance. @@ -261,12 +255,12 @@ struct _EFI_PCI_HOT_PLUG_INIT_PROTOCOL { /// Returns a list of root HPCs and the buses that they control. /// EFI_GET_ROOT_HPC_LIST GetRootHpcList; - + /// /// Initializes the specified root HPC. /// EFI_INITIALIZE_ROOT_HPC InitializeRootHpc; - + /// /// Returns the resource padding that is required by the HPC. /// diff --git a/MdePkg/Include/Protocol/PciHotPlugRequest.h b/MdePkg/Include/Protocol/PciHotPlugRequest.h index c96b789b5695..dff7f6e98039 100644 --- a/MdePkg/Include/Protocol/PciHotPlugRequest.h +++ b/MdePkg/Include/Protocol/PciHotPlugRequest.h @@ -1,46 +1,40 @@ /** @file - Provides services to notify the PCI bus driver that some events have happened - in a hot-plug controller (such as a PC Card socket, or PHPC), and to ask the + Provides services to notify the PCI bus driver that some events have happened + in a hot-plug controller (such as a PC Card socket, or PHPC), and to ask the PCI bus driver to create or destroy handles for PCI-like devices. - A hot-plug capable PCI bus driver should produce the EFI PCI Hot Plug Request + A hot-plug capable PCI bus driver should produce the EFI PCI Hot Plug Request protocol. When a PCI device or a PCI-like device (for example, 32-bit PC Card) - is installed after PCI bus does the enumeration, the PCI bus driver can be + is installed after PCI bus does the enumeration, the PCI bus driver can be notified through this protocol. For example, when a 32-bit PC Card is inserted into the PC Card socket, the PC Card bus driver can call interface of this protocol to notify PCI bus driver to allocate resource and create handles for this PC Card. - - The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL is installed by the PCI bus driver on a - separate handle when PCI bus driver starts up. There is only one instance in + + The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL is installed by the PCI bus driver on a + separate handle when PCI bus driver starts up. There is only one instance in the system. Any driver that wants to use this protocol must locate it globally. - The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL allows the driver of hot-plug controller, - for example, PC Card Bus driver, to notify PCI bus driver that an event has - happened in the hot-plug controller, and the PCI bus driver is requested to - create (add) or destroy (remove) handles for the specified PCI-like devices. - For example, when a 32-bit PC Card is inserted, this protocol interface will - be called with an add operation, and the PCI bus driver will enumerate and - start the devices inserted; when a 32-bit PC Card is removed, this protocol - interface will be called with a remove operation, and the PCI bus driver will - stop the devices and destroy their handles. The existence of this protocol + The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL allows the driver of hot-plug controller, + for example, PC Card Bus driver, to notify PCI bus driver that an event has + happened in the hot-plug controller, and the PCI bus driver is requested to + create (add) or destroy (remove) handles for the specified PCI-like devices. + For example, when a 32-bit PC Card is inserted, this protocol interface will + be called with an add operation, and the PCI bus driver will enumerate and + start the devices inserted; when a 32-bit PC Card is removed, this protocol + interface will be called with a remove operation, and the PCI bus driver will + stop the devices and destroy their handles. The existence of this protocol represents the capability of the PCI bus driver. If this protocol exists in - system, it means PCI bus driver is hot-plug capable, thus together with the + system, it means PCI bus driver is hot-plug capable, thus together with the effort of PC Card bus driver, hot-plug of PC Card can be supported. Otherwise, - the hot-plug capability is not provided. - - Copyright (c) 2006 - 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + the hot-plug capability is not provided. + + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: - This Protocol is defined in UEFI Platform Initialization Specification 1.2 + This Protocol is defined in UEFI Platform Initialization Specification 1.2 Volume 5: Standards - + **/ #ifndef __PCI_HOTPLUG_REQUEST_H_ @@ -61,7 +55,7 @@ typedef struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL EFI_PCI_HOTPLUG_REQUEST_PROTOC /// /// Enumeration of PCI hot plug operations -/// +/// typedef enum { /// /// The PCI bus driver is requested to create handles for the specified devices. @@ -78,65 +72,65 @@ typedef enum { /** This function is used to notify PCI bus driver that some events happened in a - hot-plug controller, and the PCI bus driver is requested to start or stop + hot-plug controller, and the PCI bus driver is requested to start or stop specified PCI-like devices. - + This function allows the PCI bus driver to be notified to act as requested when - a hot-plug event has happened on the hot-plug controller. Currently, the + a hot-plug event has happened on the hot-plug controller. Currently, the operations include add operation and remove operation. If it is a add operation, - the PCI bus driver will enumerate, allocate resources for devices behind the + the PCI bus driver will enumerate, allocate resources for devices behind the hot-plug controller, and create handle for the device specified by RemainingDevicePath. - The RemainingDevicePath is an optional parameter. If it is not NULL, only the - specified device is started; if it is NULL, all devices behind the hot-plug - controller are started. The newly created handles of PC Card functions are + The RemainingDevicePath is an optional parameter. If it is not NULL, only the + specified device is started; if it is NULL, all devices behind the hot-plug + controller are started. The newly created handles of PC Card functions are returned in the ChildHandleBuffer, together with the number of child handle in NumberOfChildren. If it is a remove operation, when NumberOfChildren contains a non-zero value, child handles specified in ChildHandleBuffer are stopped and destroyed; otherwise, PCI bus driver is notified to stop managing the controller - handle. - - @param[in] This A pointer to the EFI_PCI_HOTPLUG_REQUEST_PROTOCOL + handle. + + @param[in] This A pointer to the EFI_PCI_HOTPLUG_REQUEST_PROTOCOL instance. - @param[in] Operation The operation the PCI bus driver is requested - to make. + @param[in] Operation The operation the PCI bus driver is requested + to make. @param[in] Controller The handle of the hot-plug controller. @param[in] RemainingDevicePath The remaining device path for the PCI-like hot-plug device. It only contains device - path nodes behind the hot-plug controller. + path nodes behind the hot-plug controller. It is an optional parameter and only valid - when the Operation is a add operation. If - it is NULL, all devices behind the PC Card + when the Operation is a add operation. If + it is NULL, all devices behind the PC Card socket are started. - @param[in,out] NumberOfChildren The number of child handles. For an add + @param[in,out] NumberOfChildren The number of child handles. For an add operation, it is an output parameter. For a remove operation, it's an input parameter. When it contains a non-zero value, children handles specified in ChildHandleBuffer are - destroyed. Otherwise, PCI bus driver is - notified to stop managing the controller + destroyed. Otherwise, PCI bus driver is + notified to stop managing the controller handle. - @param[in,out] ChildHandleBuffer The buffer which contains the child handles. - For an add operation, it is an output - parameter and contains all newly created + @param[in,out] ChildHandleBuffer The buffer which contains the child handles. + For an add operation, it is an output + parameter and contains all newly created child handles. For a remove operation, it contains child handles to be destroyed when NumberOfChildren contains a non-zero value. It can be NULL when NumberOfChildren is 0. It's the caller's responsibility to allocate and free memory for this buffer. - - @retval EFI_SUCCESS The handles for the specified device have been - created or destroyed as requested, and for an - add operation, the new handles are returned in + + @retval EFI_SUCCESS The handles for the specified device have been + created or destroyed as requested, and for an + add operation, the new handles are returned in ChildHandleBuffer. @retval EFI_INVALID_PARAMETER Operation is not a legal value. @retval EFI_INVALID_PARAMETER Controller is NULL or not a valid handle. @retval EFI_INVALID_PARAMETER NumberOfChildren is NULL. - @retval EFI_INVALID_PARAMETER ChildHandleBuffer is NULL while Operation is - remove and NumberOfChildren contains a non-zero + @retval EFI_INVALID_PARAMETER ChildHandleBuffer is NULL while Operation is + remove and NumberOfChildren contains a non-zero value. @retval EFI_INVALID_PARAMETER ChildHandleBuffer is NULL while Operation is add. - @retval EFI_OUT_OF_RESOURCES There are no enough resources to start the + @retval EFI_OUT_OF_RESOURCES There are no enough resources to start the devices. **/ typedef @@ -151,15 +145,15 @@ EFI_STATUS ); /// -/// Provides services to notify PCI bus driver that some events have happened in -/// a hot-plug controller (for example, PC Card socket, or PHPC), and ask PCI bus +/// Provides services to notify PCI bus driver that some events have happened in +/// a hot-plug controller (for example, PC Card socket, or PHPC), and ask PCI bus /// driver to create or destroy handles for the PCI-like devices. /// struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL { /// - /// Notify the PCI bus driver that some events have happened in a hot-plug - /// controller (for example, PC Card socket, or PHPC), and ask PCI bus driver - /// to create or destroy handles for the PCI-like devices. See Section 0 for + /// Notify the PCI bus driver that some events have happened in a hot-plug + /// controller (for example, PC Card socket, or PHPC), and ask PCI bus driver + /// to create or destroy handles for the PCI-like devices. See Section 0 for /// a detailed description. /// EFI_PCI_HOTPLUG_REQUEST_NOTIFY Notify; diff --git a/MdePkg/Include/Protocol/PciIo.h b/MdePkg/Include/Protocol/PciIo.h index 5bbc54350149..420b8cba6f4e 100644 --- a/MdePkg/Include/Protocol/PciIo.h +++ b/MdePkg/Include/Protocol/PciIo.h @@ -1,15 +1,9 @@ /** @file - EFI PCI I/O Protocol provides the basic Memory, I/O, PCI configuration, + EFI PCI I/O Protocol provides the basic Memory, I/O, PCI configuration, and DMA interfaces that a driver uses to access its PCI controller. - Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -126,27 +120,27 @@ typedef enum { EfiPciIoAttributeOperationMaximum } EFI_PCI_IO_PROTOCOL_ATTRIBUTE_OPERATION; -/** +/** Reads from the memory space of a PCI controller. Returns either when the polling exit criteria is - satisfied or after a defined duration. - + satisfied or after a defined duration. + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. @param Width Signifies the width of the memory or I/O operations. @param BarIndex The BAR index of the standard PCI Configuration header to use as the - base address for the memory operation to perform. + base address for the memory operation to perform. @param Offset The offset within the selected BAR to start the memory operation. @param Mask Mask used for the polling criteria. @param Value The comparison value used for the polling exit criteria. @param Delay The number of 100 ns units to poll. @param Result Pointer to the last value read from the memory location. - + @retval EFI_SUCCESS The last data returned from the access matched the poll exit criteria. @retval EFI_UNSUPPORTED BarIndex not valid for this PCI controller. @retval EFI_UNSUPPORTED Offset is not valid for the BarIndex of this PCI controller. @retval EFI_TIMEOUT Delay expired before a match occurred. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - + **/ typedef EFI_STATUS @@ -161,25 +155,25 @@ EFI_STATUS OUT UINT64 *Result ); -/** +/** Enable a PCI driver to access PCI controller registers in the PCI memory or I/O space. - + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. @param Width Signifies the width of the memory or I/O operations. @param BarIndex The BAR index of the standard PCI Configuration header to use as the - base address for the memory or I/O operation to perform. - @param Offset The offset within the selected BAR to start the memory or I/O operation. + base address for the memory or I/O operation to perform. + @param Offset The offset within the selected BAR to start the memory or I/O operation. @param Count The number of memory or I/O operations to perform. @param Buffer For read operations, the destination buffer to store the results. For write - operations, the source buffer to write data from. - + operations, the source buffer to write data from. + @retval EFI_SUCCESS The data was read from or written to the PCI controller. @retval EFI_UNSUPPORTED BarIndex not valid for this PCI controller. @retval EFI_UNSUPPORTED The address range specified by Offset, Width, and Count is not - valid for the PCI BAR specified by BarIndex. + valid for the PCI BAR specified by BarIndex. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - + **/ typedef EFI_STATUS @@ -203,23 +197,23 @@ typedef struct { EFI_PCI_IO_PROTOCOL_IO_MEM Write; } EFI_PCI_IO_PROTOCOL_ACCESS; -/** +/** Enable a PCI driver to access PCI controller registers in PCI configuration space. - - @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. + + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. @param Width Signifies the width of the memory operations. @param Offset The offset within the PCI configuration space for the PCI controller. @param Count The number of PCI configuration operations to perform. @param Buffer For read operations, the destination buffer to store the results. For write operations, the source buffer to write data from. - - + + @retval EFI_SUCCESS The data was read from or written to the PCI controller. @retval EFI_UNSUPPORTED The address range specified by Offset, Width, and Count is not valid for the PCI configuration header of the PCI controller. - @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. - @retval EFI_INVALID_PARAMETER Buffer is NULL or Width is invalid. - + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + @retval EFI_INVALID_PARAMETER Buffer is NULL or Width is invalid. + **/ typedef EFI_STATUS @@ -242,33 +236,33 @@ typedef struct { EFI_PCI_IO_PROTOCOL_CONFIG Write; } EFI_PCI_IO_PROTOCOL_CONFIG_ACCESS; -/** +/** Enables a PCI driver to copy one region of PCI memory space to another region of PCI memory space. - + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. @param Width Signifies the width of the memory operations. @param DestBarIndex The BAR index in the standard PCI Configuration header to use as the - base address for the memory operation to perform. + base address for the memory operation to perform. @param DestOffset The destination offset within the BAR specified by DestBarIndex to - start the memory writes for the copy operation. + start the memory writes for the copy operation. @param SrcBarIndex The BAR index in the standard PCI Configuration header to use as the - base address for the memory operation to perform. + base address for the memory operation to perform. @param SrcOffset The source offset within the BAR specified by SrcBarIndex to start - the memory reads for the copy operation. + the memory reads for the copy operation. @param Count The number of memory operations to perform. Bytes moved is Width - size * Count, starting at DestOffset and SrcOffset. - + size * Count, starting at DestOffset and SrcOffset. + @retval EFI_SUCCESS The data was copied from one memory region to another memory region. @retval EFI_UNSUPPORTED DestBarIndex not valid for this PCI controller. @retval EFI_UNSUPPORTED SrcBarIndex not valid for this PCI controller. @retval EFI_UNSUPPORTED The address range specified by DestOffset, Width, and Count - is not valid for the PCI BAR specified by DestBarIndex. + is not valid for the PCI BAR specified by DestBarIndex. @retval EFI_UNSUPPORTED The address range specified by SrcOffset, Width, and Count is - not valid for the PCI BAR specified by SrcBarIndex. + not valid for the PCI BAR specified by SrcBarIndex. @retval EFI_INVALID_PARAMETER Width is invalid. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. - + **/ typedef EFI_STATUS @@ -282,24 +276,24 @@ EFI_STATUS IN UINTN Count ); -/** +/** Provides the PCI controller-specific addresses needed to access system memory. - + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. @param Operation Indicates if the bus master is going to read or write to system memory. @param HostAddress The system memory address to map to the PCI controller. @param NumberOfBytes On input the number of bytes to map. On output the number of bytes - that were mapped. + that were mapped. @param DeviceAddress The resulting map address for the bus master PCI controller to use to - access the hosts HostAddress. + access the hosts HostAddress. @param Mapping A resulting value to pass to Unmap(). - + @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes. - @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer. + @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer. @retval EFI_INVALID_PARAMETER One or more parameters are invalid. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @retval EFI_DEVICE_ERROR The system hardware could not map the requested address. - + **/ typedef EFI_STATUS @@ -312,15 +306,15 @@ EFI_STATUS OUT VOID **Mapping ); -/** +/** Completes the Map() operation and releases any corresponding resources. - - @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. + + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. @param Mapping The mapping value returned from Map(). - + @retval EFI_SUCCESS The range was unmapped. @retval EFI_DEVICE_ERROR The data was not committed to the target system memory. - + **/ typedef EFI_STATUS @@ -329,25 +323,25 @@ EFI_STATUS IN VOID *Mapping ); -/** +/** Allocates pages that are suitable for an EfiPciIoOperationBusMasterCommonBuffer - mapping. - + or EfiPciOperationBusMasterCommonBuffer64 mapping. + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. @param Type This parameter is not used and must be ignored. @param MemoryType The type of memory to allocate, EfiBootServicesData or - EfiRuntimeServicesData. - @param Pages The number of pages to allocate. + EfiRuntimeServicesData. + @param Pages The number of pages to allocate. @param HostAddress A pointer to store the base system memory address of the - allocated range. + allocated range. @param Attributes The requested bit mask of attributes for the allocated range. - + @retval EFI_SUCCESS The requested memory pages were allocated. @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are - MEMORY_WRITE_COMBINE and MEMORY_CACHED. + MEMORY_WRITE_COMBINE, MEMORY_CACHED and DUAL_ADDRESS_CYCLE. @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated. - + @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated. + **/ typedef EFI_STATUS @@ -360,17 +354,17 @@ EFI_STATUS IN UINT64 Attributes ); -/** +/** Frees memory that was allocated with AllocateBuffer(). - - @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. - @param Pages The number of pages to free. - @param HostAddress The base system memory address of the allocated range. - + + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. + @param Pages The number of pages to free. + @param HostAddress The base system memory address of the allocated range. + @retval EFI_SUCCESS The requested memory pages were freed. @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages was not allocated with AllocateBuffer(). - + **/ typedef EFI_STATUS @@ -380,16 +374,16 @@ EFI_STATUS IN VOID *HostAddress ); -/** +/** Flushes all PCI posted write transactions from a PCI host bridge to system memory. - - @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. - + + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. + @retval EFI_SUCCESS The PCI posted write transactions were flushed from the PCI host - bridge to system memory. + bridge to system memory. @retval EFI_DEVICE_ERROR The PCI posted write transactions were not flushed from the PCI - host bridge due to a hardware error. - + host bridge due to a hardware error. + **/ typedef EFI_STATUS @@ -397,18 +391,18 @@ EFI_STATUS IN EFI_PCI_IO_PROTOCOL *This ); -/** +/** Retrieves this PCI controller's current PCI bus number, device number, and function number. - - @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. + + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. @param SegmentNumber The PCI controller's current PCI segment number. @param BusNumber The PCI controller's current PCI bus number. @param DeviceNumber The PCI controller's current PCI device number. @param FunctionNumber The PCI controller's current PCI function number. - - @retval EFI_SUCCESS The PCI controller location was returned. - @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - + + @retval EFI_SUCCESS The PCI controller location was returned. + @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + **/ typedef EFI_STATUS @@ -420,24 +414,24 @@ EFI_STATUS OUT UINTN *FunctionNumber ); -/** +/** Performs an operation on the attributes that this PCI controller supports. The operations include - getting the set of supported attributes, retrieving the current attributes, setting the current - attributes, enabling attributes, and disabling attributes. - - @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. + getting the set of supported attributes, retrieving the current attributes, setting the current + attributes, enabling attributes, and disabling attributes. + + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. @param Operation The operation to perform on the attributes for this PCI controller. @param Attributes The mask of attributes that are used for Set, Enable, and Disable - operations. + operations. @param Result A pointer to the result mask of attributes that are returned for the Get - and Supported operations. - + and Supported operations. + @retval EFI_SUCCESS The operation on the PCI controller's attributes was completed. - @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - @retval EFI_UNSUPPORTED one or more of the bits set in + @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + @retval EFI_UNSUPPORTED one or more of the bits set in Attributes are not supported by this PCI controller or one of its parent bridges when Operation is Set, Enable or Disable. - + **/ typedef EFI_STATUS @@ -448,27 +442,26 @@ EFI_STATUS OUT UINT64 *Result OPTIONAL ); -/** +/** Gets the attributes that this PCI controller supports setting on a BAR using SetBarAttributes(), and retrieves the list of resource descriptors for a BAR. - - @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. + + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. @param BarIndex The BAR index of the standard PCI Configuration header to use as the base address for resource range. The legal range for this field is 0..5. @param Supports A pointer to the mask of attributes that this PCI controller supports - setting for this BAR with SetBarAttributes(). - @param Resources A pointer to the ACPI 2.0 resource descriptors that describe the current - configuration of this BAR of the PCI controller. - - @retval EFI_SUCCESS If Supports is not NULL, then the attributes that the PCI - controller supports are returned in Supports. If Resources - is not NULL, then the ACPI 2.0 resource descriptors that the PCI - controller is currently using are returned in Resources. + setting for this BAR with SetBarAttributes(). + @param Resources A pointer to the resource descriptors that describe the current + configuration of this BAR of the PCI controller. + + @retval EFI_SUCCESS If Supports is not NULL, then the attributes that the PCI + controller supports are returned in Supports. If Resources + is not NULL, then the resource descriptors that the PCI + controller is currently using are returned in Resources. @retval EFI_INVALID_PARAMETER Both Supports and Attributes are NULL. @retval EFI_UNSUPPORTED BarIndex not valid for this PCI controller. @retval EFI_OUT_OF_RESOURCES There are not enough resources available to allocate - Resources. - + Resources. **/ typedef EFI_STATUS @@ -479,29 +472,29 @@ EFI_STATUS OUT VOID **Resources OPTIONAL ); -/** +/** Sets the attributes for a range of a BAR on a PCI controller. - - @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. + + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. @param Attributes The mask of attributes to set for the resource range specified by - BarIndex, Offset, and Length. + BarIndex, Offset, and Length. @param BarIndex The BAR index of the standard PCI Configuration header to use as the base address for resource range. The legal range for this field is 0..5. @param Offset A pointer to the BAR relative base address of the resource range to be - modified by the attributes specified by Attributes. + modified by the attributes specified by Attributes. @param Length A pointer to the length of the resource range to be modified by the - attributes specified by Attributes. - - @retval EFI_SUCCESS The set of attributes specified by Attributes for the resource - range specified by BarIndex, Offset, and Length were + attributes specified by Attributes. + + @retval EFI_SUCCESS The set of attributes specified by Attributes for the resource + range specified by BarIndex, Offset, and Length were set on the PCI controller, and the actual resource range is returned - in Offset and Length. + in Offset and Length. @retval EFI_INVALID_PARAMETER Offset or Length is NULL. @retval EFI_UNSUPPORTED BarIndex not valid for this PCI controller. @retval EFI_OUT_OF_RESOURCES There are not enough resources to set the attributes on the - resource range specified by BarIndex, Offset, and - Length. - + resource range specified by BarIndex, Offset, and + Length. + **/ typedef EFI_STATUS @@ -514,11 +507,11 @@ EFI_STATUS ); /// -/// The EFI_PCI_IO_PROTOCOL provides the basic Memory, I/O, PCI configuration, -/// and DMA interfaces used to abstract accesses to PCI controllers. -/// There is one EFI_PCI_IO_PROTOCOL instance for each PCI controller on a PCI bus. -/// A device driver that wishes to manage a PCI controller in a system will have to -/// retrieve the EFI_PCI_IO_PROTOCOL instance that is associated with the PCI controller. +/// The EFI_PCI_IO_PROTOCOL provides the basic Memory, I/O, PCI configuration, +/// and DMA interfaces used to abstract accesses to PCI controllers. +/// There is one EFI_PCI_IO_PROTOCOL instance for each PCI controller on a PCI bus. +/// A device driver that wishes to manage a PCI controller in a system will have to +/// retrieve the EFI_PCI_IO_PROTOCOL instance that is associated with the PCI controller. /// struct _EFI_PCI_IO_PROTOCOL { EFI_PCI_IO_PROTOCOL_POLL_IO_MEM PollMem; @@ -536,20 +529,20 @@ struct _EFI_PCI_IO_PROTOCOL { EFI_PCI_IO_PROTOCOL_ATTRIBUTES Attributes; EFI_PCI_IO_PROTOCOL_GET_BAR_ATTRIBUTES GetBarAttributes; EFI_PCI_IO_PROTOCOL_SET_BAR_ATTRIBUTES SetBarAttributes; - + /// /// The size, in bytes, of the ROM image. /// UINT64 RomSize; /// - /// A pointer to the in memory copy of the ROM image. The PCI Bus Driver is responsible - /// for allocating memory for the ROM image, and copying the contents of the ROM to memory. - /// The contents of this buffer are either from the PCI option ROM that can be accessed - /// through the ROM BAR of the PCI controller, or it is from a platform-specific location. - /// The Attributes() function can be used to determine from which of these two sources + /// A pointer to the in memory copy of the ROM image. The PCI Bus Driver is responsible + /// for allocating memory for the ROM image, and copying the contents of the ROM to memory. + /// The contents of this buffer are either from the PCI option ROM that can be accessed + /// through the ROM BAR of the PCI controller, or it is from a platform-specific location. + /// The Attributes() function can be used to determine from which of these two sources /// the RomImage buffer was initialized. - /// + /// VOID *RomImage; }; diff --git a/MdePkg/Include/Protocol/PciOverride.h b/MdePkg/Include/Protocol/PciOverride.h index c1edcc52fa5f..e5b797177f9c 100644 --- a/MdePkg/Include/Protocol/PciOverride.h +++ b/MdePkg/Include/Protocol/PciOverride.h @@ -5,13 +5,7 @@ This protocol is optional. Copyright (c) 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is defined in UEFI Platform Initialization Specification 1.2 diff --git a/MdePkg/Include/Protocol/PciPlatform.h b/MdePkg/Include/Protocol/PciPlatform.h index 056f92b1ef53..1f514e2d77de 100644 --- a/MdePkg/Include/Protocol/PciPlatform.h +++ b/MdePkg/Include/Protocol/PciPlatform.h @@ -1,20 +1,14 @@ /** @file - This file declares PlatfromOpRom protocols that provide the interface between - the PCI bus driver/PCI Host Bridge Resource Allocation driver and a platform-specific - driver to describe the unique features of a platform. + This file declares PlatfromOpRom protocols that provide the interface between + the PCI bus driver/PCI Host Bridge Resource Allocation driver and a platform-specific + driver to describe the unique features of a platform. This protocol is optional. - -Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: - This Protocol is defined in UEFI Platform Initialization Specification 1.2 + This Protocol is defined in UEFI Platform Initialization Specification 1.2 Volume 5: Standards **/ @@ -320,16 +314,16 @@ EFI_STATUS /// struct _EFI_PCI_PLATFORM_PROTOCOL { /// - /// The notification from the PCI bus enumerator to the platform that it is about to + /// The notification from the PCI bus enumerator to the platform that it is about to /// enter a certain phase during the enumeration process. /// EFI_PCI_PLATFORM_PHASE_NOTIFY PlatformNotify; /// - /// The notification from the PCI bus enumerator to the platform for each PCI + /// The notification from the PCI bus enumerator to the platform for each PCI /// controller at several predefined points during PCI controller initialization. - /// + /// EFI_PCI_PLATFORM_PREPROCESS_CONTROLLER PlatformPrepController; - /// + /// /// Retrieves the platform policy regarding enumeration. /// EFI_PCI_PLATFORM_GET_PLATFORM_POLICY GetPlatformPolicy; diff --git a/MdePkg/Include/Protocol/PciRootBridgeIo.h b/MdePkg/Include/Protocol/PciRootBridgeIo.h index 382dae7b97bd..dffb8a9dee31 100644 --- a/MdePkg/Include/Protocol/PciRootBridgeIo.h +++ b/MdePkg/Include/Protocol/PciRootBridgeIo.h @@ -1,18 +1,12 @@ /** @file PCI Root Bridge I/O protocol as defined in the UEFI 2.0 specification. - PCI Root Bridge I/O protocol is used by PCI Bus Driver to perform PCI Memory, PCI I/O, - and PCI Configuration cycles on a PCI Root Bridge. It also provides services to perform + PCI Root Bridge I/O protocol is used by PCI Bus Driver to perform PCI Memory, PCI I/O, + and PCI Configuration cycles on a PCI Root Bridge. It also provides services to perform defferent types of bus mastering DMA. - Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -122,23 +116,23 @@ typedef struct { UINT32 ExtendedRegister; } EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS; -/** +/** Reads from the I/O space of a PCI Root Bridge. Returns when either the polling exit criteria is satisfied or after a defined duration. - + @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL. @param Width Signifies the width of the memory or I/O operations. - @param Address The base address of the memory or I/O operations. + @param Address The base address of the memory or I/O operations. @param Mask Mask used for the polling criteria. @param Value The comparison value used for the polling exit criteria. @param Delay The number of 100 ns units to poll. @param Result Pointer to the last value read from the memory location. - + @retval EFI_SUCCESS The last data returned from the access matched the poll exit criteria. @retval EFI_TIMEOUT Delay expired before a match occurred. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - + **/ typedef EFI_STATUS @@ -152,20 +146,20 @@ EFI_STATUS OUT UINT64 *Result ); -/** +/** Enables a PCI driver to access PCI controller registers in the PCI root bridge memory space. - + @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL. @param Width Signifies the width of the memory operations. - @param Address The base address of the memory operations. + @param Address The base address of the memory operations. @param Count The number of memory operations to perform. @param Buffer For read operations, the destination buffer to store the results. For write - operations, the source buffer to write data from. - - @retval EFI_SUCCESS The data was read from or written to the PCI root bridge. + operations, the source buffer to write data from. + + @retval EFI_SUCCESS The data was read from or written to the PCI root bridge. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - + **/ typedef EFI_STATUS @@ -188,20 +182,20 @@ typedef struct { EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_IO_MEM Write; } EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS; -/** +/** Enables a PCI driver to copy one region of PCI root bridge memory space to another region of PCI - root bridge memory space. - + root bridge memory space. + @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance. @param Width Signifies the width of the memory operations. - @param DestAddress The destination address of the memory operation. - @param SrcAddress The source address of the memory operation. - @param Count The number of memory operations to perform. - - @retval EFI_SUCCESS The data was copied from one memory region to another memory region. + @param DestAddress The destination address of the memory operation. + @param SrcAddress The source address of the memory operation. + @param Count The number of memory operations to perform. + + @retval EFI_SUCCESS The data was copied from one memory region to another memory region. @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. - + **/ typedef EFI_STATUS @@ -213,25 +207,25 @@ EFI_STATUS IN UINTN Count ); -/** +/** Provides the PCI controller-specific addresses required to access system memory from a - DMA bus master. - + DMA bus master. + @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL. @param Operation Indicates if the bus master is going to read or write to system memory. @param HostAddress The system memory address to map to the PCI controller. @param NumberOfBytes On input the number of bytes to map. On output the number of bytes - that were mapped. + that were mapped. @param DeviceAddress The resulting map address for the bus master PCI controller to use to - access the hosts HostAddress. + access the hosts HostAddress. @param Mapping A resulting value to pass to Unmap(). - + @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes. - @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer. + @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer. @retval EFI_INVALID_PARAMETER One or more parameters are invalid. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @retval EFI_DEVICE_ERROR The system hardware could not map the requested address. - + **/ typedef EFI_STATUS @@ -244,16 +238,16 @@ EFI_STATUS OUT VOID **Mapping ); -/** +/** Completes the Map() operation and releases any corresponding resources. - + @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL. @param Mapping The mapping value returned from Map(). - + @retval EFI_SUCCESS The range was unmapped. @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map(). @retval EFI_DEVICE_ERROR The data was not committed to the target system memory. - + **/ typedef EFI_STATUS @@ -262,25 +256,25 @@ EFI_STATUS IN VOID *Mapping ); -/** +/** Allocates pages that are suitable for an EfiPciOperationBusMasterCommonBuffer or - EfiPciOperationBusMasterCommonBuffer64 mapping. - + EfiPciOperationBusMasterCommonBuffer64 mapping. + @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL. @param Type This parameter is not used and must be ignored. @param MemoryType The type of memory to allocate, EfiBootServicesData or - EfiRuntimeServicesData. - @param Pages The number of pages to allocate. + EfiRuntimeServicesData. + @param Pages The number of pages to allocate. @param HostAddress A pointer to store the base system memory address of the - allocated range. + allocated range. @param Attributes The requested bit mask of attributes for the allocated range. - + @retval EFI_SUCCESS The requested memory pages were allocated. @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are - MEMORY_WRITE_COMBINE and MEMORY_CACHED. + MEMORY_WRITE_COMBINE and MEMORY_CACHED. @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated. - + @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated. + **/ typedef EFI_STATUS @@ -293,17 +287,17 @@ EFI_STATUS IN UINT64 Attributes ); -/** +/** Frees memory that was allocated with AllocateBuffer(). - + @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL. - @param Pages The number of pages to free. - @param HostAddress The base system memory address of the allocated range. - + @param Pages The number of pages to free. + @param HostAddress The base system memory address of the allocated range. + @retval EFI_SUCCESS The requested memory pages were freed. @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages was not allocated with AllocateBuffer(). - + **/ typedef EFI_STATUS @@ -313,16 +307,16 @@ EFI_STATUS IN VOID *HostAddress ); -/** +/** Flushes all PCI posted write transactions from a PCI host bridge to system memory. - + @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL. - + @retval EFI_SUCCESS The PCI posted write transactions were flushed from the PCI host - bridge to system memory. + bridge to system memory. @retval EFI_DEVICE_ERROR The PCI posted write transactions were not flushed from the PCI - host bridge due to a hardware error. - + host bridge due to a hardware error. + **/ typedef EFI_STATUS @@ -330,23 +324,23 @@ EFI_STATUS IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This ); -/** +/** Gets the attributes that a PCI root bridge supports setting with SetAttributes(), and the - attributes that a PCI root bridge is currently using. - + attributes that a PCI root bridge is currently using. + @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL. @param Supports A pointer to the mask of attributes that this PCI root bridge supports - setting with SetAttributes(). + setting with SetAttributes(). @param Attributes A pointer to the mask of attributes that this PCI root bridge is currently - using. - - @retval EFI_SUCCESS If Supports is not NULL, then the attributes that the PCI root - bridge supports is returned in Supports. If Attributes is + using. + + @retval EFI_SUCCESS If Supports is not NULL, then the attributes that the PCI root + bridge supports is returned in Supports. If Attributes is not NULL, then the attributes that the PCI root bridge is currently - using is returned in Attributes. + using is returned in Attributes. @retval EFI_INVALID_PARAMETER Both Supports and Attributes are NULL. - - + + **/ typedef EFI_STATUS @@ -356,26 +350,26 @@ EFI_STATUS OUT UINT64 *Attributes ); -/** +/** Sets attributes for a resource range on a PCI root bridge. - + @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL. @param Attributes The mask of attributes to set. @param ResourceBase A pointer to the base address of the resource range to be modified by the attributes specified by Attributes. @param ResourceLength A pointer to the length of the resource range to be modified by the - attributes specified by Attributes. - - @retval EFI_SUCCESS The set of attributes specified by Attributes for the resource - range specified by ResourceBase and ResourceLength + attributes specified by Attributes. + + @retval EFI_SUCCESS The set of attributes specified by Attributes for the resource + range specified by ResourceBase and ResourceLength were set on the PCI root bridge, and the actual resource range is - returned in ResuourceBase and ResourceLength. + returned in ResuourceBase and ResourceLength. @retval EFI_UNSUPPORTED A bit is set in Attributes that is not supported by the PCI Root - Bridge. - @retval EFI_OUT_OF_RESOURCES There are not enough resources to set the attributes on the - resource range specified by BaseAddress and Length. - @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - + Bridge. + @retval EFI_OUT_OF_RESOURCES There are not enough resources to set the attributes on the + resource range specified by BaseAddress and Length. + @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + **/ typedef EFI_STATUS @@ -386,19 +380,19 @@ EFI_STATUS IN OUT UINT64 *ResourceLength ); -/** - Retrieves the current resource settings of this PCI root bridge in the form of a set of ACPI 2.0 - resource descriptors. - +/** + Retrieves the current resource settings of this PCI root bridge in the form of a set of ACPI + resource descriptors. + @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL. - @param Resources A pointer to the ACPI 2.0 resource descriptors that describe the current - configuration of this PCI root bridge. - + @param Resources A pointer to the resource descriptors that describe the current + configuration of this PCI root bridge. + @retval EFI_SUCCESS The current configuration of this PCI root bridge was returned in - Resources. + Resources. @retval EFI_UNSUPPORTED The current configuration of this PCI root bridge could not be - retrieved. - + retrieved. + **/ typedef EFI_STATUS @@ -408,8 +402,8 @@ EFI_STATUS ); /// -/// Provides the basic Memory, I/O, PCI configuration, and DMA interfaces that are -/// used to abstract accesses to PCI controllers behind a PCI Root Bridge Controller. +/// Provides the basic Memory, I/O, PCI configuration, and DMA interfaces that are +/// used to abstract accesses to PCI controllers behind a PCI Root Bridge Controller. /// struct _EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL { /// @@ -430,7 +424,7 @@ struct _EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL { EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GET_ATTRIBUTES GetAttributes; EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_SET_ATTRIBUTES SetAttributes; EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_CONFIGURATION Configuration; - + /// /// The segment number that this PCI root bridge resides. /// diff --git a/MdePkg/Include/Protocol/PiPcd.h b/MdePkg/Include/Protocol/PiPcd.h index 84d2aa444bd5..b409ba614f79 100644 --- a/MdePkg/Include/Protocol/PiPcd.h +++ b/MdePkg/Include/Protocol/PiPcd.h @@ -13,13 +13,7 @@ firmware component to monitor specific settings and be alerted when a setting is changed. Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: PI Version 1.2 Vol 3. diff --git a/MdePkg/Include/Protocol/PiPcdInfo.h b/MdePkg/Include/Protocol/PiPcdInfo.h index 1b39f0de520a..b8c313312231 100644 --- a/MdePkg/Include/Protocol/PiPcdInfo.h +++ b/MdePkg/Include/Protocol/PiPcdInfo.h @@ -4,13 +4,7 @@ The protocol that provides additional information about items that reside in the PCD database. Copyright (c) 2013, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: PI Version 1.2.1 Vol 3. diff --git a/MdePkg/Include/Protocol/Pkcs7Verify.h b/MdePkg/Include/Protocol/Pkcs7Verify.h index 267cbc81fa13..5cf1ffda1332 100644 --- a/MdePkg/Include/Protocol/Pkcs7Verify.h +++ b/MdePkg/Include/Protocol/Pkcs7Verify.h @@ -6,14 +6,8 @@ PKCS#7 is a general-purpose cryptographic standard (defined by RFC2315, available at http://tools.ietf.org/html/rfc2315). -Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2015 - 2017, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -140,6 +134,14 @@ EFI_STATUS verifies the signature of the content is valid and signing certificate was not revoked and is contained within a list of trusted signers. + Note: because this function uses hashes and the specification contains a variety of + hash choices, you should be aware that the check against the RevokedDb list + will improperly succeed if the signature is revoked using a different hash + algorithm. For this reason, you should either cycle through all UEFI supported + hashes to see if one is forbidden, or rely on a single hash choice only if the + UEFI signature authority only signs and revokes with a single hash (at time + of writing, this hash choice is SHA256). + @param[in] This Pointer to EFI_PKCS7_VERIFY_PROTOCOL instance. @param[in] Signature Points to buffer containing ASN.1 DER-encoded PKCS detached signature. diff --git a/MdePkg/Include/Protocol/PlatformDriverOverride.h b/MdePkg/Include/Protocol/PlatformDriverOverride.h index c84d12d1f02f..e60ca5a82a73 100644 --- a/MdePkg/Include/Protocol/PlatformDriverOverride.h +++ b/MdePkg/Include/Protocol/PlatformDriverOverride.h @@ -1,14 +1,8 @@ /** @file Platform Driver Override protocol as defined in the UEFI 2.1 specification. - Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -29,24 +23,24 @@ typedef struct _EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL EFI_PLATFORM_DRIVER_OVERR // Prototypes for the Platform Driver Override Protocol // -/** +/** Retrieves the image handle of the platform override driver for a controller in the system. - + @param This A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_ - PROTOCOL instance. + PROTOCOL instance. @param ControllerHandle The device handle of the controller to check if a driver override - exists. + exists. @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. - + by GetDriver(). On output, a pointer to the next driver + image handle. + @retval EFI_SUCCESS The driver override for ControllerHandle was returned in - DriverImageHandle. + DriverImageHandle. @retval EFI_NOT_FOUND A driver override for ControllerHandle was not found. @retval EFI_INVALID_PARAMETER The handle specified by ControllerHandle is NULL. @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 @@ -56,25 +50,25 @@ EFI_STATUS IN OUT EFI_HANDLE *DriverImageHandle ); -/** +/** Retrieves the device path of the platform override driver for a controller in the system. - + @param This A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL instance. @param ControllerHandle The device handle of the controller to check if a driver override - exists. + exists. @param DriverImagePath On input, a pointer to the previous driver device path returned by GetDriverPath(). On output, a pointer to the next driver device path. Passing in a pointer to NULL will return the first driver device path for ControllerHandle. - + @retval EFI_SUCCESS The driver override for ControllerHandle was returned in - DriverImageHandle. - @retval EFI_UNSUPPORTED The operation is not supported. + DriverImageHandle. + @retval EFI_UNSUPPORTED The operation is not supported. @retval EFI_NOT_FOUND A driver override for ControllerHandle was not found. @retval EFI_INVALID_PARAMETER The handle specified by ControllerHandle is NULL. @retval EFI_INVALID_PARAMETER DriverImagePath is not a device path that was returned on a - previous call to GetDriverPath(). - + previous call to GetDriverPath(). + **/ typedef EFI_STATUS @@ -84,31 +78,31 @@ EFI_STATUS IN OUT EFI_DEVICE_PATH_PROTOCOL **DriverImagePath ); -/** +/** Used to associate a driver image handle with a device path that was returned on a prior call to the - GetDriverPath() service. This driver image handle will then be available through the - GetDriver() service. - + GetDriverPath() service. This driver image handle will then be available through the + GetDriver() service. + @param This A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_ - PROTOCOL instance. - @param ControllerHandle The device handle of the controller. + PROTOCOL instance. + @param ControllerHandle The device handle of the controller. @param DriverImagePath A pointer to the driver device path that was returned in a prior - call to GetDriverPath(). + call to GetDriverPath(). @param DriverImageHandle The driver image handle that was returned by LoadImage() - when the driver specified by DriverImagePath was loaded - into memory. - - @retval EFI_SUCCESS The association between DriverImagePath and + when the driver specified by DriverImagePath was loaded + into memory. + + @retval EFI_SUCCESS The association between DriverImagePath and DriverImageHandle was established for the controller specified - by ControllerHandle. - @retval EFI_UNSUPPORTED The operation is not supported. + by ControllerHandle. + @retval EFI_UNSUPPORTED The operation is not supported. @retval EFI_NOT_FOUND DriverImagePath is not a device path that was returned on a prior - call to GetDriverPath() for the controller specified by - ControllerHandle. + call to GetDriverPath() for the controller specified by + ControllerHandle. @retval EFI_INVALID_PARAMETER ControllerHandle is NULL. @retval EFI_INVALID_PARAMETER DriverImagePath is not a valid device path. @retval EFI_INVALID_PARAMETER DriverImageHandle is not a valid image handle. - + **/ typedef EFI_STATUS @@ -120,13 +114,13 @@ EFI_STATUS ); /// -/// This protocol matches one or more drivers to a controller. A platform driver -/// produces this protocol, and it is installed on a separate handle. This protocol -/// is used by the ConnectController() boot service to select the best driver -/// for a controller. All of the drivers returned by this protocol have a higher -/// precedence than drivers found from an EFI Bus Specific Driver Override Protocol -/// or drivers found from the general UEFI driver Binding search algorithm. If more -/// than one driver is returned by this protocol, then the drivers are returned in +/// This protocol matches one or more drivers to a controller. A platform driver +/// produces this protocol, and it is installed on a separate handle. This protocol +/// is used by the ConnectController() boot service to select the best driver +/// for a controller. All of the drivers returned by this protocol have a higher +/// precedence than drivers found from an EFI Bus Specific Driver Override Protocol +/// or drivers found from the general UEFI driver Binding search algorithm. If more +/// than one driver is returned by this protocol, then the drivers are returned in /// order from highest precedence to lowest precedence. /// struct _EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL { diff --git a/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h b/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h index 8343cb8beaf9..55d1962d6168 100644 --- a/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h +++ b/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h @@ -1,18 +1,12 @@ /** @file 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 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + 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. - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -58,10 +52,10 @@ typedef struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL EFI_PLATFORM_TO_DR increment the Instance value by one for each successive call to Query. @param This A pointer to the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL instance. - + @param ControllerHandle The handle the platform will return configuration information about. - + @param ChildHandle The handle of the child controller to return information on. This is an optional parameter that may be NULL. It will be @@ -70,8 +64,8 @@ typedef struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL EFI_PLATFORM_TO_DR the bus controller. It will not be NULL for a bus driver that attempts to get options for one of its child controllers. - - + + @param Instance Pointer to the Instance value. Zero means return the first query data. The caller should increment this value by one each time to retrieve @@ -148,26 +142,26 @@ typedef enum { /// configuration settings. /// EfiPlatformConfigurationActionNone = 0, - + /// /// The driver has detected that the controller specified - /// by ControllerHandle is not in a usable state and + /// by ControllerHandle is not in a usable state and /// needs to be stopped. The calling agent can use the /// DisconnectControservice to perform this operation, and - /// it should be performed as soon as possible. + /// it should be performed as soon as possible. /// EfiPlatformConfigurationActionStopController = 1, - + /// /// This controller specified by ControllerHandle needs to /// be stopped and restarted before it can be used again. /// The calling agent can use the DisconnectController() /// and ConnectController() services to perform this /// operation. The restart operation can be delayed until - /// all of the configuration options have been set. + /// all of the configuration options have been set. /// EfiPlatformConfigurationActionRestartController = 2, - + /// /// A configuration change has been made that requires the /// platform to be restarted before the controller @@ -175,7 +169,7 @@ typedef enum { /// calling agent can use the ResetSystem() services to /// perform this operation. The restart operation can be /// delayed until all of the configuration options have - /// been set. + /// been set. /// EfiPlatformConfigurationActionRestartPlatform = 3, @@ -188,8 +182,8 @@ typedef enum { /// are required before this controller can be used again /// with the updated configuration settings, but these /// configuration settings are not guaranteed to persist - /// after ControllerHandle is stopped. - /// + /// after ControllerHandle is stopped. + /// EfiPlatformConfigurationActionNvramFailed = 4, /// @@ -249,17 +243,17 @@ typedef enum { @param ConfigurationAction The driver tells the platform what action is required for ParameterBlock to take effect. - - + + @retval EFI_SUCCESS The platform return parameter information for ControllerHandle. - + @retval EFI_NOT_FOUND Instance was not found. - + @retval EFI_INVALID_PARAMETER ControllerHandle is NULL. - + @retval EFI_INVALID_PARAMETER Instance is zero. - + **/ typedef EFI_STATUS @@ -298,7 +292,7 @@ struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL { {0x345ecc0e, 0xcb6, 0x4b75, { 0xbb, 0x57, 0x1b, 0x12, 0x9c, 0x47, 0x33,0x3e } } /** - + ParameterTypeGuid provides the support for parameters communicated through the DMTF SM CLP Specification 1.0 Final Standard to be used to configure the UEFI driver. In this @@ -311,8 +305,8 @@ struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL { **/ typedef struct { CHAR8 *CLPCommand; ///< A pointer to the null-terminated UTF-8 string that specifies the DMTF SM CLP command - ///< line that the driver is required to parse and process when this function is called. - ///< See the DMTF SM CLP Specification 1.0 Final Standard for details on the + ///< line that the driver is required to parse and process when this function is called. + ///< See the DMTF SM CLP Specification 1.0 Final Standard for details on the ///< format and syntax of the CLP command line string. CLPCommand buffer ///< is allocated by the producer of the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOOL. UINT32 CLPCommandLength; ///< The length of the CLP Command in bytes. @@ -329,20 +323,20 @@ typedef struct { ///< the SM CLP Coutput option requested by the caller is not supported by the ///< UEFI Driver). CLPReturnString buffer is allocated by the consumer of the ///< EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL and undefined prior to the call to - ///< Response(). + ///< Response(). UINT32 CLPReturnStringLength; ///< The length of the CLP return status string in bytes. UINT8 CLPCmdStatus; ///< SM CLP Command Status (see DMTF SM CLP Specification 1.0 Final Standard - ///< Table 4) CLPErrorValue SM CLP Processing Error Value (see DMTF SM ///< CLP Specification 1.0 Final Standard - Table 6). This field is filled in by - ///< the consumer of the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC - ///< OL and undefined prior to the call to Response(). + ///< the consumer of the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC + ///< OL and undefined prior to the call to Response(). UINT8 CLPErrorValue; ///< SM CLP Processing Error Value (see DMTF SM CLP Specification 1.0 Final Standard - Table 6). - ///< This field is filled in by the consumer of the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL and undefined prior to the call to Response(). + ///< This field is filled in by the consumer of the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL and undefined prior to the call to Response(). UINT16 CLPMsgCode; ///< Bit 15: OEM Message Code Flag 0 = Message Code is an SM CLP Probable ///< Cause Value. (see SM CLP Specification Table 11) 1 = Message Code is OEM ///< Specific Bits 14-0: Message Code This field is filled in by the consumer of ///< the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL and undefined prior to the call to - ///< Response(). + ///< Response(). } EFI_CONFIGURE_CLP_PARAMETER_BLK; diff --git a/MdePkg/Include/Protocol/PxeBaseCode.h b/MdePkg/Include/Protocol/PxeBaseCode.h index 497d97204712..388a83a09079 100644 --- a/MdePkg/Include/Protocol/PxeBaseCode.h +++ b/MdePkg/Include/Protocol/PxeBaseCode.h @@ -1,18 +1,14 @@ /** @file - EFI PXE Base Code Protocol definitions, which is used to access PXE-compatible + EFI PXE Base Code Protocol definitions, which is used to access PXE-compatible devices for network access and network booting. -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +Copyright (c) 2020, Hewlett Packard Enterprise Development LP. All rights reserved.<BR> - @par Revision Reference: - This Protocol is introduced in EFI Specification 1.10. +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol is introduced in EFI Specification 1.10. **/ #ifndef __PXE_BASE_CODE_PROTOCOL_H__ @@ -30,7 +26,7 @@ typedef struct _EFI_PXE_BASE_CODE_PROTOCOL EFI_PXE_BASE_CODE_PROTOCOL; /// /// Protocol defined in EFI1.1. -/// +/// typedef EFI_PXE_BASE_CODE_PROTOCOL EFI_PXE_BASE_CODE; /// @@ -146,21 +142,21 @@ typedef UINT16 EFI_PXE_BASE_CODE_UDP_PORT; #define EFI_PXE_BASE_CODE_BOOT_LAYER_INITIAL 0x0000 // -// PXE Tag definition that identifies the processor +// PXE Tag definition that identifies the processor // and programming environment of the client system. // These identifiers are defined by IETF: // http://www.ietf.org/assignments/dhcpv6-parameters/dhcpv6-parameters.xml // #if defined (MDE_CPU_IA32) #define EFI_PXE_CLIENT_SYSTEM_ARCHITECTURE 0x0006 -#elif defined (MDE_CPU_IPF) -#define EFI_PXE_CLIENT_SYSTEM_ARCHITECTURE 0x0002 #elif defined (MDE_CPU_X64) #define EFI_PXE_CLIENT_SYSTEM_ARCHITECTURE 0x0007 #elif defined (MDE_CPU_ARM) #define EFI_PXE_CLIENT_SYSTEM_ARCHITECTURE 0x000A #elif defined (MDE_CPU_AARCH64) #define EFI_PXE_CLIENT_SYSTEM_ARCHITECTURE 0x000B +#elif defined (MDE_CPU_RISCV64) +#define EFI_PXE_CLIENT_SYSTEM_ARCHITECTURE 0x001B #endif @@ -263,7 +259,7 @@ typedef union { /// /// EFI_PXE_BASE_CODE_MODE. -/// The data values in this structure are read-only and +/// The data values in this structure are read-only and /// are updated by the code that produces the /// EFI_PXE_BASE_CODE_PROTOCOL functions. /// @@ -308,7 +304,7 @@ typedef struct { // PXE Base Code Interface Function definitions // -/** +/** Enables the use of the PXE Base Code Protocol functions. This function enables the use of the PXE Base Code Protocol functions. If the @@ -355,22 +351,22 @@ typedef struct { TftpErrorZero-filled. MakeCallbacksSet to TRUE if the PXE Base Code Callback Protocol is available. Set to FALSE if the PXE Base Code Callback Protocol is not available. - + @param This The pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance. @param UseIpv6 Specifies the type of IP addresses that are to be used during the session - that is being started. Set to TRUE for IPv6 addresses, and FALSE for - IPv4 addresses. - + that is being started. Set to TRUE for IPv6 addresses, and FALSE for + IPv4 addresses. + @retval EFI_SUCCESS The PXE Base Code Protocol was started. - @retval EFI_DEVICE_ERROR The network device encountered an error during this oper + @retval EFI_DEVICE_ERROR The network device encountered an error during this oper @retval EFI_UNSUPPORTED UseIpv6 is TRUE, but the Ipv6Supported field of the - EFI_PXE_BASE_CODE_MODE structure is FALSE. - @retval EFI_ALREADY_STARTED The PXE Base Code Protocol is already in the started state. + EFI_PXE_BASE_CODE_MODE structure is FALSE. + @retval EFI_ALREADY_STARTED The PXE Base Code Protocol is already in the started state. @retval EFI_INVALID_PARAMETER The This parameter is NULL or does not point to a valid - EFI_PXE_BASE_CODE_PROTOCOL structure. - @retval EFI_OUT_OF_RESOURCES Could not allocate enough memory or other resources to start the - PXE Base Code Protocol. - + EFI_PXE_BASE_CODE_PROTOCOL structure. + @retval EFI_OUT_OF_RESOURCES Could not allocate enough memory or other resources to start the + PXE Base Code Protocol. + **/ typedef EFI_STATUS @@ -379,22 +375,22 @@ EFI_STATUS IN BOOLEAN UseIpv6 ); -/** +/** Disables the use of the PXE Base Code Protocol functions. This function stops all activity on the network device. All the resources allocated in Start() are released, the Started field of the EFI_PXE_BASE_CODE_MODE structure is set to FALSE and EFI_SUCCESS is returned. If the Started field of the EFI_PXE_BASE_CODE_MODE structure is already FALSE, then EFI_NOT_STARTED will be returned. - + @param This The pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance. - + @retval EFI_SUCCESS The PXE Base Code Protocol was stopped. - @retval EFI_NOT_STARTED The PXE Base Code Protocol is already in the stopped state. + @retval EFI_NOT_STARTED The PXE Base Code Protocol is already in the stopped state. @retval EFI_INVALID_PARAMETER The This parameter is NULL or does not point to a valid - EFI_PXE_BASE_CODE_PROTOCOL structure. - @retval EFI_DEVICE_ERROR The network device encountered an error during this operation. - + EFI_PXE_BASE_CODE_PROTOCOL structure. + @retval EFI_DEVICE_ERROR The network device encountered an error during this operation. + **/ typedef EFI_STATUS @@ -402,7 +398,7 @@ EFI_STATUS IN EFI_PXE_BASE_CODE_PROTOCOL *This ); -/** +/** Attempts to complete a DHCPv4 D.O.R.A. (discover / offer / request / acknowledge) or DHCPv6 S.A.R.R (solicit / advertise / request / reply) sequence. @@ -418,22 +414,22 @@ EFI_STATUS caller. If the DHCP sequence does not complete, then EFI_TIMEOUT will be returned. If the Callback Protocol does not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE, then the DHCP sequence will be stopped and EFI_ABORTED will be returned. - + @param This The pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance. @param SortOffers TRUE if the offers received should be sorted. Set to FALSE to try the - offers in the order that they are received. - + offers in the order that they are received. + @retval EFI_SUCCESS Valid DHCP has completed. @retval EFI_NOT_STARTED The PXE Base Code Protocol is in the stopped state. @retval EFI_INVALID_PARAMETER The This parameter is NULL or does not point to a valid - EFI_PXE_BASE_CODE_PROTOCOL structure. - @retval EFI_DEVICE_ERROR The network device encountered an error during this operation. + EFI_PXE_BASE_CODE_PROTOCOL structure. + @retval EFI_DEVICE_ERROR The network device encountered an error during this operation. @retval EFI_OUT_OF_RESOURCES Could not allocate enough memory to complete the DHCP Protocol. @retval EFI_ABORTED The callback function aborted the DHCP Protocol. @retval EFI_TIMEOUT The DHCP Protocol timed out. @retval EFI_ICMP_ERROR An ICMP error packet was received during the DHCP session. @retval EFI_NO_RESPONSE Valid PXE offer was not received. - + **/ typedef EFI_STATUS @@ -442,7 +438,7 @@ EFI_STATUS IN BOOLEAN SortOffers ); -/** +/** Attempts to complete the PXE Boot Server and/or boot image discovery sequence. This function attempts to complete the PXE Boot Server and/or boot image discovery @@ -464,26 +460,26 @@ EFI_STATUS additional details on the implementation of the Discovery sequence. If the Callback Protocol does not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE, then the Discovery sequence is stopped and EFI_ABORTED will be returned. - + @param This The pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance. @param Type The type of bootstrap to perform. @param Layer The pointer to the boot server layer number to discover, which must be - PXE_BOOT_LAYER_INITIAL when a new server type is being - discovered. - @param UseBis TRUE if Boot Integrity Services are to be used. FALSE otherwise. + PXE_BOOT_LAYER_INITIAL when a new server type is being + discovered. + @param UseBis TRUE if Boot Integrity Services are to be used. FALSE otherwise. @param Info The pointer to a data structure that contains additional information on the - type of discovery operation that is to be performed. - + type of discovery operation that is to be performed. + @retval EFI_SUCCESS The Discovery sequence has been completed. @retval EFI_NOT_STARTED The PXE Base Code Protocol is in the stopped state. - @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - @retval EFI_DEVICE_ERROR The network device encountered an error during this operation. + @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + @retval EFI_DEVICE_ERROR The network device encountered an error during this operation. @retval EFI_OUT_OF_RESOURCES Could not allocate enough memory to complete Discovery. @retval EFI_ABORTED The callback function aborted the Discovery sequence. @retval EFI_TIMEOUT The Discovery sequence timed out. @retval EFI_ICMP_ERROR An ICMP error packet was received during the PXE discovery - session. - + session. + **/ typedef EFI_STATUS @@ -495,7 +491,7 @@ EFI_STATUS IN EFI_PXE_BASE_CODE_DISCOVER_INFO *Info OPTIONAL ); -/** +/** Used to perform TFTP and MTFTP services. This function is used to perform TFTP and MTFTP services. This includes the @@ -540,31 +536,31 @@ EFI_STATUS IP address preceding the filename of the form %d.%d.%d.%d for IP v4. The final entry is itself null-terminated, so that the final information string is terminated with two null octets. - + @param This The pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance. @param Operation The type of operation to perform. - @param BufferPtr A pointer to the data buffer. + @param BufferPtr A pointer to the data buffer. @param Overwrite Only used on write file operations. TRUE if a file on a remote server can - be overwritten. + be overwritten. @param BufferSize For get-file-size operations, *BufferSize returns the size of the - requested file. + requested file. @param BlockSize The requested block size to be used during a TFTP transfer. @param ServerIp The TFTP / MTFTP server IP address. @param Filename A Null-terminated ASCII string that specifies a directory name or a file - name. + name. @param Info The pointer to the MTFTP information. - @param DontUseBuffer Set to FALSE for normal TFTP and MTFTP read file operation. - + @param DontUseBuffer Set to FALSE for normal TFTP and MTFTP read file operation. + @retval EFI_SUCCESS The TFTP/MTFTP operation was completed. @retval EFI_NOT_STARTED The PXE Base Code Protocol is in the stopped state. - @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - @retval EFI_DEVICE_ERROR The network device encountered an error during this operation. - @retval EFI_BUFFER_TOO_SMALL The buffer is not large enough to complete the read operation. + @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + @retval EFI_DEVICE_ERROR The network device encountered an error during this operation. + @retval EFI_BUFFER_TOO_SMALL The buffer is not large enough to complete the read operation. @retval EFI_ABORTED The callback function aborted the TFTP/MTFTP operation. @retval EFI_TIMEOUT The TFTP/MTFTP operation timed out. @retval EFI_ICMP_ERROR An ICMP error packet was received during the MTFTP session. @retval EFI_TFTP_ERROR A TFTP error packet was received during the MTFTP session. - + **/ typedef EFI_STATUS @@ -581,7 +577,7 @@ EFI_STATUS IN BOOLEAN DontUseBuffer ); -/** +/** Writes a UDP packet to the network interface. This function writes a UDP packet specified by the (optional HeaderPtr and) @@ -594,29 +590,29 @@ EFI_STATUS the IcmpErrorReceived field is set to TRUE, the IcmpError field is filled in and EFI_ICMP_ERROR will be returned. If the Callback Protocol does not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE, then EFI_ABORTED will be returned. - + @param This The pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance. - @param OpFlags The UDP operation flags. + @param OpFlags The UDP operation flags. @param DestIp The destination IP address. - @param DestPort The destination UDP port number. - @param GatewayIp The gateway IP address. + @param DestPort The destination UDP port number. + @param GatewayIp The gateway IP address. @param SrcIp The source IP address. @param SrcPort The source UDP port number. @param HeaderSize An optional field which may be set to the length of a header at - HeaderPtr to be prefixed to the data at BufferPtr. + HeaderPtr to be prefixed to the data at BufferPtr. @param HeaderPtr If HeaderSize is not NULL, a pointer to a header to be prefixed to the - data at BufferPtr. + data at BufferPtr. @param BufferSize A pointer to the size of the data at BufferPtr. @param BufferPtr A pointer to the data to be written. - + @retval EFI_SUCCESS The UDP Write operation was completed. @retval EFI_NOT_STARTED The PXE Base Code Protocol is in the stopped state. - @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - @retval EFI_BAD_BUFFER_SIZE The buffer is too long to be transmitted. + @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + @retval EFI_BAD_BUFFER_SIZE The buffer is too long to be transmitted. @retval EFI_ABORTED The callback function aborted the UDP Write operation. @retval EFI_TIMEOUT The UDP Write operation timed out. - @retval EFI_ICMP_ERROR An ICMP error packet was received during the UDP write session. - + @retval EFI_ICMP_ERROR An ICMP error packet was received during the UDP write session. + **/ typedef EFI_STATUS @@ -634,7 +630,7 @@ EFI_STATUS IN VOID *BufferPtr ); -/** +/** Reads a UDP packet from the network interface. This function reads a UDP packet from a network interface. The data contents @@ -649,28 +645,28 @@ EFI_STATUS Depending on the values of OpFlags and the DestIp, DestPort, SrcIp, and SrcPort input values, different types of UDP packet receive filtering will be performed. The following tables summarize these receive filter operations. - + @param This The pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance. - @param OpFlags The UDP operation flags. + @param OpFlags The UDP operation flags. @param DestIp The destination IP address. @param DestPort The destination UDP port number. @param SrcIp The source IP address. @param SrcPort The source UDP port number. @param HeaderSize An optional field which may be set to the length of a header at - HeaderPtr to be prefixed to the data at BufferPtr. + HeaderPtr to be prefixed to the data at BufferPtr. @param HeaderPtr If HeaderSize is not NULL, a pointer to a header to be prefixed to the - data at BufferPtr. + data at BufferPtr. @param BufferSize A pointer to the size of the data at BufferPtr. @param BufferPtr A pointer to the data to be read. - + @retval EFI_SUCCESS The UDP Read operation was completed. @retval EFI_NOT_STARTED The PXE Base Code Protocol is in the stopped state. - @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + @retval EFI_INVALID_PARAMETER One or more parameters are invalid. @retval EFI_DEVICE_ERROR The network device encountered an error during this operation. @retval EFI_BUFFER_TOO_SMALL The packet is larger than Buffer can hold. @retval EFI_ABORTED The callback function aborted the UDP Read operation. - @retval EFI_TIMEOUT The UDP Read operation timed out. - + @retval EFI_TIMEOUT The UDP Read operation timed out. + **/ typedef EFI_STATUS @@ -687,9 +683,9 @@ EFI_STATUS IN VOID *BufferPtr ); -/** +/** Updates the IP receive filters of a network device and enables software filtering. - + The NewFilter field is used to modify the network device's current IP receive filter settings and to enable a software filter. This function updates the IpFilter field of the EFI_PXE_BASE_CODE_MODE structure with the contents of NewIpFilter. @@ -710,14 +706,14 @@ EFI_STATUS The IPlist field is used to enable IPs other than the StationIP. They may be multicast or unicast. If IPcnt is set as well as EFI_PXE_BASE_CODE_IP_FILTER_STATION_IP, then both the StationIP and the IPs from the IPlist will be used. - + @param This The pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance. @param NewFilter The pointer to the new set of IP receive filters. - + @retval EFI_SUCCESS The IP receive filter settings were updated. @retval EFI_NOT_STARTED The PXE Base Code Protocol is in the stopped state. - @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - + @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + **/ typedef EFI_STATUS @@ -726,9 +722,9 @@ EFI_STATUS IN EFI_PXE_BASE_CODE_IP_FILTER *NewFilter ); -/** +/** Uses the ARP protocol to resolve a MAC address. - + This function uses the ARP protocol to resolve a MAC address. The UsingIpv6 field of the EFI_PXE_BASE_CODE_MODE structure is used to determine if IPv4 or IPv6 addresses are being used. The IP address specified by IpAddr is used to resolve @@ -741,19 +737,19 @@ EFI_STATUS to resolve an address, then EFI_TIMEOUT is returned. If the Callback Protocol does not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE, then EFI_ABORTED is returned. - + @param This The pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance. @param IpAddr The pointer to the IP address that is used to resolve a MAC address. @param MacAddr If not NULL, a pointer to the MAC address that was resolved with the - ARP protocol. - + ARP protocol. + @retval EFI_SUCCESS The IP or MAC address was resolved. @retval EFI_NOT_STARTED The PXE Base Code Protocol is in the stopped state. - @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - @retval EFI_DEVICE_ERROR The network device encountered an error during this operation. + @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + @retval EFI_DEVICE_ERROR The network device encountered an error during this operation. @retval EFI_ABORTED The callback function aborted the ARP Protocol. @retval EFI_TIMEOUT The ARP Protocol encountered a timeout condition. - + **/ typedef EFI_STATUS @@ -763,9 +759,9 @@ EFI_STATUS IN EFI_MAC_ADDRESS *MacAddr OPTIONAL ); -/** +/** Updates the parameters that affect the operation of the PXE Base Code Protocol. - + This function sets parameters that affect the operation of the PXE Base Code Protocol. The parameter specified by NewAutoArp is used to control the generation of ARP protocol packets. If NewAutoArp is TRUE, then ARP Protocol packets will be generated @@ -777,23 +773,23 @@ EFI_STATUS the EFI_PXE_BASE_CODE_MODE structure to NewAutoArp. The SetParameters() call must be invoked after a Callback Protocol is installed to enable the use of callbacks. - + @param This The pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance. @param NewAutoArp If not NULL, a pointer to a value that specifies whether to replace the - current value of AutoARP. + current value of AutoARP. @param NewSendGUID If not NULL, a pointer to a value that specifies whether to replace the - current value of SendGUID. + current value of SendGUID. @param NewTTL If not NULL, a pointer to be used in place of the current value of TTL, - the "time to live" field of the IP header. + the "time to live" field of the IP header. @param NewToS If not NULL, a pointer to be used in place of the current value of ToS, - the "type of service" field of the IP header. + the "type of service" field of the IP header. @param NewMakeCallback If not NULL, a pointer to a value that specifies whether to replace the - current value of the MakeCallback field of the Mode structure. - + current value of the MakeCallback field of the Mode structure. + @retval EFI_SUCCESS The new parameters values were updated. @retval EFI_NOT_STARTED The PXE Base Code Protocol is in the stopped state. - @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - + @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + **/ typedef EFI_STATUS @@ -806,9 +802,9 @@ EFI_STATUS IN BOOLEAN *NewMakeCallback OPTIONAL ); -/** +/** Updates the station IP address and/or subnet mask values of a network device. - + This function updates the station IP address and/or subnet mask values of a network device. The NewStationIp field is used to modify the network device's current IP address. @@ -819,15 +815,15 @@ EFI_STATUS mask. If NewSubnetMask is NULL, then the current subnet mask will not be modified. Otherwise, this function updates the SubnetMask field of the EFI_PXE_BASE_CODE_MODE structure with NewSubnetMask. - + @param This The pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance. - @param NewStationIp The pointer to the new IP address to be used by the network device. - @param NewSubnetMask The pointer to the new subnet mask to be used by the network device. - + @param NewStationIp The pointer to the new IP address to be used by the network device. + @param NewSubnetMask The pointer to the new subnet mask to be used by the network device. + @retval EFI_SUCCESS The new station IP address and/or subnet mask were updated. @retval EFI_NOT_STARTED The PXE Base Code Protocol is in the stopped state. - @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - + @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + **/ typedef EFI_STATUS @@ -837,36 +833,36 @@ EFI_STATUS IN EFI_IP_ADDRESS *NewSubnetMask OPTIONAL ); -/** +/** Updates the contents of the cached DHCP and Discover packets. - + The pointers to the new packets are used to update the contents of the cached packets in the EFI_PXE_BASE_CODE_MODE structure. - + @param This The pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance. @param NewDhcpDiscoverValid The pointer to a value that will replace the current - DhcpDiscoverValid field. + DhcpDiscoverValid field. @param NewDhcpAckReceived The pointer to a value that will replace the current - DhcpAckReceived field. + DhcpAckReceived field. @param NewProxyOfferReceived The pointer to a value that will replace the current - ProxyOfferReceived field. - @param NewPxeDiscoverValid The pointer to a value that will replace the current - ProxyOfferReceived field. + ProxyOfferReceived field. + @param NewPxeDiscoverValid The pointer to a value that will replace the current + ProxyOfferReceived field. @param NewPxeReplyReceived The pointer to a value that will replace the current - PxeReplyReceived field. + PxeReplyReceived field. @param NewPxeBisReplyReceived The pointer to a value that will replace the current - PxeBisReplyReceived field. - @param NewDhcpDiscover The pointer to the new cached DHCP Discover packet contents. + PxeBisReplyReceived field. + @param NewDhcpDiscover The pointer to the new cached DHCP Discover packet contents. @param NewDhcpAck The pointer to the new cached DHCP Ack packet contents. @param NewProxyOffer The pointer to the new cached Proxy Offer packet contents. @param NewPxeDiscover The pointer to the new cached PXE Discover packet contents. @param NewPxeReply The pointer to the new cached PXE Reply packet contents. @param NewPxeBisReply The pointer to the new cached PXE BIS Reply packet contents. - + @retval EFI_SUCCESS The cached packet contents were updated. @retval EFI_NOT_STARTED The PXE Base Code Protocol is in the stopped state. @retval EFI_INVALID_PARAMETER This is NULL or not point to a valid EFI_PXE_BASE_CODE_PROTOCOL structure. - + **/ typedef EFI_STATUS @@ -893,7 +889,7 @@ EFI_STATUS // // Revision defined in EFI1.1 -// +// #define EFI_PXE_BASE_CODE_INTERFACE_REVISION EFI_PXE_BASE_CODE_PROTOCOL_REVISION /// @@ -906,8 +902,8 @@ EFI_STATUS /// struct _EFI_PXE_BASE_CODE_PROTOCOL { /// - /// The revision of the EFI_PXE_BASE_CODE_PROTOCOL. All future revisions must - /// be backwards compatible. If a future version is not backwards compatible + /// The revision of the EFI_PXE_BASE_CODE_PROTOCOL. All future revisions must + /// be backwards compatible. If a future version is not backwards compatible /// it is not the same GUID. /// UINT64 Revision; @@ -931,4 +927,4 @@ struct _EFI_PXE_BASE_CODE_PROTOCOL { extern EFI_GUID gEfiPxeBaseCodeProtocolGuid; -#endif +#endif diff --git a/MdePkg/Include/Protocol/PxeBaseCodeCallBack.h b/MdePkg/Include/Protocol/PxeBaseCodeCallBack.h index f653fdf7ff2c..2640a1c2bab5 100644 --- a/MdePkg/Include/Protocol/PxeBaseCodeCallBack.h +++ b/MdePkg/Include/Protocol/PxeBaseCodeCallBack.h @@ -1,17 +1,11 @@ /** @file - It is invoked when the PXE Base Code Protocol is about to transmit, has received, + It is invoked when the PXE Base Code Protocol is about to transmit, has received, or is waiting to receive a packet. -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent - @par Revision Reference: + @par Revision Reference: This Protocol is introduced in EFI Specification 1.10 **/ @@ -45,7 +39,7 @@ typedef struct _EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL EFI_PXE_BASE_CODE_CALLBACK_ /// /// EFI1.1 Protocol name. -/// +/// typedef EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL EFI_PXE_BASE_CODE_CALLBACK; /// @@ -73,10 +67,10 @@ typedef enum { EFI_PXE_BASE_CODE_CALLBACK_STATUS_LAST } EFI_PXE_BASE_CODE_CALLBACK_STATUS; -/** +/** Callback function that is invoked when the PXE Base Code Protocol is about to transmit, has - received, or is waiting to receive a packet. - + received, or is waiting to receive a packet. + This function is invoked when the PXE Base Code Protocol is about to transmit, has received, or is waiting to receive a packet. Parameters Function and Received specify the type of event. Parameters PacketLen and Packet specify the packet that generated the event. If these fields @@ -86,22 +80,22 @@ typedef enum { the polling nature of UEFI device drivers, a callback function should not execute for more than 5 ms. The SetParameters() function must be called after a Callback Protocol is installed to enable the use of callbacks. - + @param This The pointer to the EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL instance. - @param Function The PXE Base Code Protocol function that is waiting for an event. + @param Function The PXE Base Code Protocol function that is waiting for an event. @param Received TRUE if the callback is being invoked due to a receive event. FALSE if - the callback is being invoked due to a transmit event. + the callback is being invoked due to a transmit event. @param PacketLen The length, in bytes, of Packet. This field will have a value of zero if - this is a wait for receive event. + this is a wait for receive event. @param Packet If Received is TRUE, a pointer to the packet that was just received; - otherwise a pointer to the packet that is about to be transmitted. - - @retval EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE if Function specifies a continue operation + otherwise a pointer to the packet that is about to be transmitted. + + @retval EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE if Function specifies a continue operation @retval EFI_PXE_BASE_CODE_CALLBACK_STATUS_ABORT if Function specifies an abort operation - + **/ -typedef -EFI_PXE_BASE_CODE_CALLBACK_STATUS +typedef +EFI_PXE_BASE_CODE_CALLBACK_STATUS (EFIAPI *EFI_PXE_CALLBACK)( IN EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL *This, IN EFI_PXE_BASE_CODE_FUNCTION Function, @@ -111,13 +105,13 @@ EFI_PXE_BASE_CODE_CALLBACK_STATUS ); /// -/// Protocol that is invoked when the PXE Base Code Protocol is about +/// Protocol that is invoked when the PXE Base Code Protocol is about /// to transmit, has received, or is waiting to receive a packet. /// struct _EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL { /// - /// The revision of the EFI_PXE_BASE_CODE_PROTOCOL. All future revisions must - /// be backwards compatible. If a future version is not backwards compatible + /// The revision of the EFI_PXE_BASE_CODE_PROTOCOL. All future revisions must + /// be backwards compatible. If a future version is not backwards compatible /// it is not the same GUID. /// UINT64 Revision; @@ -126,5 +120,5 @@ struct _EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL { extern EFI_GUID gEfiPxeBaseCodeCallbackProtocolGuid; -#endif +#endif diff --git a/MdePkg/Include/Protocol/RamDisk.h b/MdePkg/Include/Protocol/RamDisk.h index 61353fbbd7c9..9861ec64e634 100644 --- a/MdePkg/Include/Protocol/RamDisk.h +++ b/MdePkg/Include/Protocol/RamDisk.h @@ -2,13 +2,7 @@ This file defines the EFI RAM Disk Protocol. Copyright (c) 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.6 diff --git a/MdePkg/Include/Protocol/RealTimeClock.h b/MdePkg/Include/Protocol/RealTimeClock.h index 7a70ae37a5aa..a80ffc305893 100644 --- a/MdePkg/Include/Protocol/RealTimeClock.h +++ b/MdePkg/Include/Protocol/RealTimeClock.h @@ -5,20 +5,14 @@ Time and date related EFI runtime services. The GetTime (), SetTime (), GetWakeupTime (), and SetWakeupTime () UEFI 2.0 - services are added to the EFI system table and the - EFI_REAL_TIME_CLOCK_ARCH_PROTOCOL_GUID protocol is registered with a NULL + services are added to the EFI system table and the + EFI_REAL_TIME_CLOCK_ARCH_PROTOCOL_GUID protocol is registered with a NULL pointer. No CRC of the EFI system table is required, since that is done in the DXE core. - Copyright (c) 2006 - 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Protocol/RegularExpressionProtocol.h b/MdePkg/Include/Protocol/RegularExpressionProtocol.h index 5582e12d36e8..4baf644b8bdd 100644 --- a/MdePkg/Include/Protocol/RegularExpressionProtocol.h +++ b/MdePkg/Include/Protocol/RegularExpressionProtocol.h @@ -2,14 +2,11 @@ This section defines the Regular Expression Protocol. This protocol isused to match Unicode strings against Regular Expression patterns. -Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2015-2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.5. **/ diff --git a/MdePkg/Include/Protocol/ReportStatusCodeHandler.h b/MdePkg/Include/Protocol/ReportStatusCodeHandler.h index 5926e551d85c..7d2fceed55ce 100644 --- a/MdePkg/Include/Protocol/ReportStatusCodeHandler.h +++ b/MdePkg/Include/Protocol/ReportStatusCodeHandler.h @@ -1,15 +1,12 @@ /** @file - This protocol provide registering and unregistering services to status code + This protocol provide registering and unregistering services to status code consumers while in DXE. - - Copyright (c) 2007 - 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in PI Specification 1.2. **/ @@ -33,7 +30,7 @@ EFI_STATUS /** Register the callback function for ReportStatusCode() notification. - + When this function is called the function pointer is added to an internal list and any future calls to ReportStatusCode() will be forwarded to the Callback function. During the bootservices, this is the callback for which this service can be invoked. The report status code router @@ -47,16 +44,16 @@ EFI_STATUS 2. not unregister at exit boot services so that the router will still have its callback address 3. the caller must be self-contained (eg. Not call out into any boot-service interfaces) and be runtime safe, in general. - + @param[in] Callback A pointer to a function of type EFI_RSC_HANDLER_CALLBACK that is called when a call to ReportStatusCode() occurs. - @param[in] Tpl TPL at which callback can be safely invoked. - + @param[in] Tpl TPL at which callback can be safely invoked. + @retval EFI_SUCCESS Function was successfully registered. @retval EFI_INVALID_PARAMETER The callback function was NULL. @retval EFI_OUT_OF_RESOURCES The internal buffer ran out of space. No more functions can be registered. - @retval EFI_ALREADY_STARTED The function was already registered. It can't be registered again. + @retval EFI_ALREADY_STARTED The function was already registered. It can't be registered again. **/ typedef EFI_STATUS @@ -67,16 +64,16 @@ EFI_STATUS /** Remove a previously registered callback function from the notification list. - + A callback function must be unregistered before it is deallocated. It is important that any registered callbacks that are not runtime complaint be unregistered when ExitBootServices() is called. - + @param[in] Callback A pointer to a function of type EFI_RSC_HANDLER_CALLBACK that is to be unregistered. - + @retval EFI_SUCCESS The function was successfully unregistered. @retval EFI_INVALID_PARAMETER The callback function was NULL. - @retval EFI_NOT_FOUND The callback function was not found to be unregistered. + @retval EFI_NOT_FOUND The callback function was not found to be unregistered. **/ typedef EFI_STATUS diff --git a/MdePkg/Include/Protocol/Reset.h b/MdePkg/Include/Protocol/Reset.h index bcd9329ba091..6b96b20f7247 100644 --- a/MdePkg/Include/Protocol/Reset.h +++ b/MdePkg/Include/Protocol/Reset.h @@ -3,17 +3,11 @@ Used to provide ResetSystem runtime services - The ResetSystem () UEFI 2.0 service is added to the EFI system table and the + 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. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Protocol/ResetNotification.h b/MdePkg/Include/Protocol/ResetNotification.h new file mode 100644 index 000000000000..23cb6fac5b38 --- /dev/null +++ b/MdePkg/Include/Protocol/ResetNotification.h @@ -0,0 +1,80 @@ +/** @file + EFI Reset Notification Protocol as defined in UEFI 2.7. + This protocol provides services to register for a notification when ResetSystem is called. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol is introduced in UEFI Specification 2.7 + +**/ + +#ifndef __EFI_RESET_NOTIFICATION_H__ +#define __EFI_RESET_NOTIFICATION_H__ + +#define EFI_RESET_NOTIFICATION_PROTOCOL_GUID \ + { 0x9da34ae0, 0xeaf9, 0x4bbf, { 0x8e, 0xc3, 0xfd, 0x60, 0x22, 0x6c, 0x44, 0xbe } } + +typedef struct _EFI_RESET_NOTIFICATION_PROTOCOL EFI_RESET_NOTIFICATION_PROTOCOL; + +/** + Register a notification function to be called when ResetSystem() is called. + + The RegisterResetNotify() function registers a notification function that is called when + ResetSystem()is called and prior to completing the reset of the platform. + The registered functions must not perform a platform reset themselves. These + notifications are intended only for the notification of components which may need some + special-purpose maintenance prior to the platform resetting. + The list of registered reset notification functions are processed if ResetSystem()is called + before ExitBootServices(). The list of registered reset notification functions is ignored if + ResetSystem()is called after ExitBootServices(). + + @param[in] This A pointer to the EFI_RESET_NOTIFICATION_PROTOCOL instance. + @param[in] ResetFunction Points to the function to be called when a ResetSystem() is executed. + + @retval EFI_SUCCESS The reset notification function was successfully registered. + @retval EFI_INVALID_PARAMETER ResetFunction is NULL. + @retval EFI_OUT_OF_RESOURCES There are not enough resources available to register the reset notification function. + @retval EFI_ALREADY_STARTED The reset notification function specified by ResetFunction has already been registered. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_REGISTER_RESET_NOTIFY) ( + IN EFI_RESET_NOTIFICATION_PROTOCOL *This, + IN EFI_RESET_SYSTEM ResetFunction +); + +/** + Unregister a notification function. + + The UnregisterResetNotify() function removes the previously registered + notification using RegisterResetNotify(). + + @param[in] This A pointer to the EFI_RESET_NOTIFICATION_PROTOCOL instance. + @param[in] ResetFunction The pointer to the ResetFunction being unregistered. + + @retval EFI_SUCCESS The reset notification function was unregistered. + @retval EFI_INVALID_PARAMETER ResetFunction is NULL. + @retval EFI_INVALID_PARAMETER The reset notification function specified by ResetFunction was not previously + registered using RegisterResetNotify(). + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_UNREGISTER_RESET_NOTIFY) ( + IN EFI_RESET_NOTIFICATION_PROTOCOL *This, + IN EFI_RESET_SYSTEM ResetFunction +); + +typedef struct _EFI_RESET_NOTIFICATION_PROTOCOL { + EFI_REGISTER_RESET_NOTIFY RegisterResetNotify; + EFI_UNREGISTER_RESET_NOTIFY UnregisterResetNotify; +} EFI_RESET_NOTIFICATION_PROTOCOL; + + +extern EFI_GUID gEfiResetNotificationProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/Rest.h b/MdePkg/Include/Protocol/Rest.h index 512dd08ec230..57ab880667f9 100644 --- a/MdePkg/Include/Protocol/Rest.h +++ b/MdePkg/Include/Protocol/Rest.h @@ -2,13 +2,7 @@ This file defines the EFI REST Protocol interface. Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.5 diff --git a/MdePkg/Include/Protocol/Rng.h b/MdePkg/Include/Protocol/Rng.h index 95cfdc95d7ce..2db8e9fdc50e 100644 --- a/MdePkg/Include/Protocol/Rng.h +++ b/MdePkg/Include/Protocol/Rng.h @@ -1,16 +1,10 @@ /** @file EFI_RNG_PROTOCOL as defined in UEFI 2.4. - The UEFI Random Number Generator Protocol is used to provide random bits for use + The UEFI Random Number Generator Protocol is used to provide random bits for use in applications, or entropy for seeding other random number generators. -Copyright (c) 2013, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -29,7 +23,7 @@ typedef struct _EFI_RNG_PROTOCOL EFI_RNG_PROTOCOL; /// /// A selection of EFI_RNG_PROTOCOL algorithms. -/// The algorithms listed are optional, not meant to be exhaustive and be argmented by +/// The algorithms listed are optional, not meant to be exhaustive and be argmented by /// vendors or other industry standards. /// @@ -78,7 +72,7 @@ typedef EFI_GUID EFI_RNG_ALGORITHM; Returns information about the random number generation implementation. @param[in] This A pointer to the EFI_RNG_PROTOCOL instance. - @param[in,out] RNGAlgorithmListSize On input, the size in bytes of RNGAlgorithmList. + @param[in,out] RNGAlgorithmListSize On input, the size in bytes of RNGAlgorithmList. On output with a return code of EFI_SUCCESS, the size in bytes of the data returned in RNGAlgorithmList. On output with a return code of EFI_BUFFER_TOO_SMALL, @@ -137,7 +131,7 @@ EFI_STATUS ); /// -/// The Random Number Generator (RNG) protocol provides random bits for use in +/// The Random Number Generator (RNG) protocol provides random bits for use in /// applications, or entropy for seeding other random number generators. /// struct _EFI_RNG_PROTOCOL { diff --git a/MdePkg/Include/Protocol/Runtime.h b/MdePkg/Include/Protocol/Runtime.h index 21e9b75fb756..4986a3979562 100644 --- a/MdePkg/Include/Protocol/Runtime.h +++ b/MdePkg/Include/Protocol/Runtime.h @@ -1,23 +1,17 @@ /** @file Runtime Architectural Protocol as defined in PI Specification VOLUME 2 DXE - 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 + 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.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -33,7 +27,7 @@ typedef struct _EFI_RUNTIME_ARCH_PROTOCOL EFI_RUNTIME_ARCH_PROTOCOL; /// -/// LIST_ENTRY from BaseType +/// LIST_ENTRY from BaseType /// typedef LIST_ENTRY EFI_LIST_ENTRY; @@ -44,7 +38,7 @@ typedef struct _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 + /// 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; @@ -101,13 +95,13 @@ struct _EFI_RUNTIME_EVENT_ENTRY { }; /// -/// 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 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 -/// EFI Runtime Table in the EFI System Partition. This protocol must be produced +/// 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 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 +/// EFI Runtime Table in the EFI System Partition. This protocol must be produced /// by a runtime DXE driver and may only be consumed by the DXE Foundation. /// struct _EFI_RUNTIME_ARCH_PROTOCOL { @@ -115,8 +109,8 @@ struct _EFI_RUNTIME_ARCH_PROTOCOL { EFI_LIST_ENTRY EventHead; ///< A list of type EFI_RUNTIME_EVENT_ENTRY. UINTN MemoryDescriptorSize; ///< Size of a memory descriptor that is returned by GetMemoryMap(). UINT32 MemoryDesciptorVersion; ///< Version of a memory descriptor that is returned by GetMemoryMap(). - UINTN MemoryMapSize;///< Size of the memory map in bytes contained in MemoryMapPhysical and MemoryMapVirtual. - EFI_MEMORY_DESCRIPTOR *MemoryMapPhysical; ///< Pointer to a runtime buffer that contains a copy of + UINTN MemoryMapSize;///< Size of the memory map in bytes contained in MemoryMapPhysical and MemoryMapVirtual. + EFI_MEMORY_DESCRIPTOR *MemoryMapPhysical; ///< Pointer to a runtime buffer that contains a copy of ///< the memory map returned via GetMemoryMap(). EFI_MEMORY_DESCRIPTOR *MemoryMapVirtual; ///< Pointer to MemoryMapPhysical that is updated to virtual mode after SetVirtualAddressMap(). BOOLEAN VirtualMode; ///< Boolean that is TRUE if SetVirtualAddressMap() has been called. diff --git a/MdePkg/Include/Protocol/S3SaveState.h b/MdePkg/Include/Protocol/S3SaveState.h index c25e103f7692..7e7d5cadfd21 100644 --- a/MdePkg/Include/Protocol/S3SaveState.h +++ b/MdePkg/Include/Protocol/S3SaveState.h @@ -1,21 +1,15 @@ /** @file - S3 Save State Protocol as defined in PI1.2 Specification VOLUME 5 Standard. + S3 Save State Protocol as defined in PI 1.6(Errata A) Specification VOLUME 5 Standard. - This protocol is used by DXE PI module to store or record various IO operations + This protocol is used by DXE PI module to store or record various IO operations to be replayed during an S3 resume. This protocol is not required for all platforms. - - Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2019, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: - This PPI is defined in UEFI Platform Initialization Specification 1.2 Volume 5: + This PPI is defined in UEFI Platform Initialization Specification 1.2 Volume 5: Standards **/ @@ -33,32 +27,32 @@ typedef struct _EFI_S3_SAVE_STATE_PROTOCOL EFI_S3_SAVE_STATE_PROTOCOL; /** Record operations that need to be replayed during an S3 resume. - + This function is used to store an OpCode to be replayed as part of the S3 resume boot path. It is assumed this protocol has platform specific mechanism to store the OpCode set and replay them during the S3 resume. - + @param[in] This A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance. @param[in] OpCode The operation code (opcode) number. @param[in] ... Argument list that is specific to each opcode. See the following subsections for the definition of each opcode. - + @retval EFI_SUCCESS The operation succeeded. A record was added into the specified - script table. + script table. @retval EFI_INVALID_PARAMETER The parameter is illegal or the given boot script is not supported. - @retval EFI_OUT_OF_RESOURCES There is insufficient memory to store the boot script. + @retval EFI_OUT_OF_RESOURCES There is insufficient memory to store the boot script. **/ typedef EFI_STATUS (EFIAPI *EFI_S3_SAVE_STATE_WRITE)( IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This, - IN UINT16 OpCode, + IN UINTN OpCode, ... ); /** Record operations that need to be replayed during an S3 resume. - + This function is used to store an OpCode to be replayed as part of the S3 resume boot path. It is assumed this protocol has platform specific mechanism to store the OpCode set and replay them during the S3 resume. @@ -66,14 +60,14 @@ EFI_STATUS NULL then that position is after the last opcode in the table (BeforeOrAfter is TRUE) or before the first opcode in the table (BeforeOrAfter is FALSE). The position which is pointed to by Position upon return can be used for subsequent insertions. - + This function has a variable parameter list. The exact parameter list depends on the OpCode that is passed into the function. If an unsupported OpCode or illegal parameter list is passed in, this function returns EFI_INVALID_PARAMETER. If there are not enough resources available for storing more scripts, this function returns EFI_OUT_OF_RESOURCES. OpCode values of 0x80 - 0xFE are reserved for implementation specific functions. - + @param[in] This A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance. @param[in] BeforeOrAfter Specifies whether the opcode is stored before (TRUE) or after (FALSE) the position in the boot script table specified by Position. If Position is NULL or points to @@ -85,12 +79,12 @@ EFI_STATUS @param[in] OpCode The operation code (opcode) number. See "Related Definitions" in Write() for the defined opcode types. @param[in] ... Argument list that is specific to each opcode. See the following subsections for the - definition of each opcode. - + definition of each opcode. + @retval EFI_SUCCESS The operation succeeded. An opcode was added into the script. @retval EFI_INVALID_PARAMETER The Opcode is an invalid opcode value. @retval EFI_INVALID_PARAMETER The Position is not a valid position in the boot script table. - @retval EFI_OUT_OF_RESOURCES There is insufficient memory to store the boot script table. + @retval EFI_OUT_OF_RESOURCES There is insufficient memory to store the boot script table. **/ typedef EFI_STATUS @@ -98,20 +92,20 @@ EFI_STATUS IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This, IN BOOLEAN BeforeOrAfter, IN OUT EFI_S3_BOOT_SCRIPT_POSITION *Position OPTIONAL, - IN UINT16 OpCode, + IN UINTN OpCode, ... ); /** Find a label within the boot script table and, if not present, optionally create it. - + If the label Label is already exists in the boot script table, then no new label is created, the position of the Label is returned in *Position and EFI_SUCCESS is returned. If the label Label does not already exist and CreateIfNotFound is TRUE, then it will be created before or after the specified position and EFI_SUCCESS is returned. If the label Label does not already exist and CreateIfNotFound is FALSE, then EFI_NOT_FOUND is returned. - + @param[in] This A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance. @param[in] BeforeOrAfter Specifies whether the label is stored before (TRUE) or after (FALSE) the position in the boot script table specified by Position. If Position is NULL or points to @@ -122,7 +116,7 @@ EFI_STATUS either before or after, depending on BeforeOrAfter. On exit, specifies the position of the inserted label in the boot script table. @param[in] Label Points to the label which will be inserted in the boot script table. - + @retval EFI_SUCCESS The label already exists or was inserted. @retval EFI_NOT_FOUND The label did not already exist and CreateifNotFound was FALSE. @retval EFI_INVALID_PARAMETER The Label is NULL or points to an empty string. @@ -141,16 +135,16 @@ EFI_STATUS /** Compare two positions in the boot script table and return their relative position. - + This function compares two positions in the boot script table and returns their relative positions. If Position1 is before Position2, then -1 is returned. If Position1 is equal to Position2, then 0 is returned. If Position1 is after Position2, then 1 is returned. - + @param[in] This A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance. @param[in] Position1 The positions in the boot script table to compare. @param[in] Position2 The positions in the boot script table to compare. @param[out] RelativePosition On return, points to the result of the comparison. - + @retval EFI_SUCCESS The operation succeeded. @retval EFI_INVALID_PARAMETER The Position1 or Position2 is not a valid position in the boot script table. @retval EFI_INVALID_PARAMETER The RelativePosition is NULL. diff --git a/MdePkg/Include/Protocol/S3SmmSaveState.h b/MdePkg/Include/Protocol/S3SmmSaveState.h index 3cdfec7a1701..07f82db05035 100644 --- a/MdePkg/Include/Protocol/S3SmmSaveState.h +++ b/MdePkg/Include/Protocol/S3SmmSaveState.h @@ -13,19 +13,13 @@ EFI_OUT_OF_RESOURCES may be returned from a runtime call. It is the responsibility of the platform to ensure enough memory resource exists to save the system state. It is recommended that runtime calls be minimized by the caller. - - Copyright (c) 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: - This PPI is defined in UEFI Platform Initialization Specification 1.2 Volume 5: - Standards + This PPI is defined in UEFI Platform Initialization Specification 1.2 Volume 5: + Standards **/ @@ -36,11 +30,11 @@ #define EFI_S3_SMM_SAVE_STATE_PROTOCOL_GUID \ {0x320afe62, 0xe593, 0x49cb, { 0xa9, 0xf1, 0xd4, 0xc2, 0xf4, 0xaf, 0x1, 0x4c }} - + typedef EFI_S3_SAVE_STATE_PROTOCOL EFI_S3_SMM_SAVE_STATE_PROTOCOL; extern EFI_GUID gEfiS3SmmSaveStateProtocolGuid; - + #endif // __S3_SMM_SAVE_STATE_H__ diff --git a/MdePkg/Include/Protocol/ScsiIo.h b/MdePkg/Include/Protocol/ScsiIo.h index 833fb1ceeffa..d3db297a97db 100644 --- a/MdePkg/Include/Protocol/ScsiIo.h +++ b/MdePkg/Include/Protocol/ScsiIo.h @@ -1,17 +1,11 @@ /** @file EFI_SCSI_IO_PROTOCOL as defined in UEFI 2.0. - This protocol is used by code, typically drivers, running in the EFI boot - services environment to access SCSI devices. In particular, functions for + This protocol is used by code, typically drivers, running in the EFI boot + services environment to access SCSI devices. In particular, functions for managing devices on SCSI buses are defined here. - Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -301,12 +295,12 @@ struct _EFI_SCSI_IO_PROTOCOL { EFI_SCSI_IO_PROTOCOL_GET_DEVICE_LOCATION GetDeviceLocation; EFI_SCSI_IO_PROTOCOL_RESET_BUS ResetBus; EFI_SCSI_IO_PROTOCOL_RESET_DEVICE ResetDevice; - EFI_SCSI_IO_PROTOCOL_EXEC_SCSI_COMMAND ExecuteScsiCommand; + EFI_SCSI_IO_PROTOCOL_EXEC_SCSI_COMMAND ExecuteScsiCommand; /// - /// Supplies the alignment requirement for any buffer used in a data transfer. - /// IoAlign values of 0 and 1 mean that the buffer can be placed anywhere in memory. - /// Otherwise, IoAlign must be a power of 2, and the requirement is that the + /// Supplies the alignment requirement for any buffer used in a data transfer. + /// IoAlign values of 0 and 1 mean that the buffer can be placed anywhere in memory. + /// Otherwise, IoAlign must be a power of 2, and the requirement is that the /// start address of a buffer must be evenly divisible by IoAlign with no remainder. /// UINT32 IoAlign; diff --git a/MdePkg/Include/Protocol/ScsiPassThru.h b/MdePkg/Include/Protocol/ScsiPassThru.h index baf0d2bfc7fe..1666b248e76d 100644 --- a/MdePkg/Include/Protocol/ScsiPassThru.h +++ b/MdePkg/Include/Protocol/ScsiPassThru.h @@ -1,21 +1,15 @@ /** @file SCSI Pass Through protocol as defined in EFI 1.1. - This protocol allows information about a SCSI channel to be collected, + This protocol allows information about a SCSI channel to be collected, and allows SCSI Request Packets to be sent to any SCSI devices on a SCSI - channel even if those devices are not boot devices. This protocol is attached - to the device handle of each SCSI channel in a system that the protocol - supports, and can be used for diagnostics. It may also be used to build + channel even if those devices are not boot devices. This protocol is attached + to the device handle of each SCSI channel in a system that the protocol + supports, and can be used for diagnostics. It may also be used to build a Block I/O driver for SCSI hard drives and SCSI CD-ROM or DVD drives to allow those devices to become boot devices. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -149,9 +143,9 @@ typedef struct { } EFI_SCSI_PASS_THRU_MODE; /** - Sends a SCSI Request Packet to a SCSI device that is attached to - the SCSI channel. This function supports both blocking I/O and - non-blocking I/O. The blocking I/O functionality is required, + Sends a SCSI Request Packet to a SCSI device that is attached to + the SCSI channel. This function supports both blocking I/O and + non-blocking I/O. The blocking I/O functionality is required, and the non-blocking I/O functionality is optional. @param This Protocol instance pointer. @@ -198,7 +192,7 @@ typedef struct { Request Packet to execute. See HostAdapterStatus, TargetStatus, SenseDataLength, and SenseData in that order for additional status information. - + **/ typedef EFI_STATUS @@ -211,7 +205,7 @@ EFI_STATUS ); /** - Used to retrieve the list of legal Target IDs for SCSI devices + Used to retrieve the list of legal Target IDs for SCSI devices on a SCSI channel. @param This Protocol instance pointer. @@ -243,7 +237,7 @@ EFI_STATUS ); /** - Used to allocate and build a device path node for a SCSI device + Used to allocate and build a device path node for a SCSI device on a SCSI channel. @param This Protocol instance pointer. @@ -311,7 +305,7 @@ EFI_STATUS ); /** - Resets a SCSI channel.This operation resets all the + Resets a SCSI channel.This operation resets all the SCSI devices connected to the SCSI channel. @param This Protocol instance pointer. diff --git a/MdePkg/Include/Protocol/ScsiPassThruExt.h b/MdePkg/Include/Protocol/ScsiPassThruExt.h index a9d4047e0e7a..49e16feb1a4e 100644 --- a/MdePkg/Include/Protocol/ScsiPassThruExt.h +++ b/MdePkg/Include/Protocol/ScsiPassThruExt.h @@ -1,16 +1,10 @@ /** @file EFI_EXT_SCSI_PASS_THRU_PROTOCOL as defined in UEFI 2.0. - This protocol provides services that allow SCSI Pass Thru commands + This protocol provides services that allow SCSI Pass Thru commands to be sent to SCSI devices attached to a SCSI channel. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -148,9 +142,9 @@ typedef struct { } EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET; /** - Sends a SCSI Request Packet to a SCSI device that is attached to the SCSI channel. This function + Sends a SCSI Request Packet to a SCSI device that is attached to the SCSI channel. This function supports both blocking I/O and nonblocking I/O. The blocking I/O functionality is required, and the - nonblocking I/O functionality is optional. + nonblocking I/O functionality is optional. @param This A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance. @param Target The Target is an array of size TARGET_MAX_BYTES and it represents @@ -196,14 +190,14 @@ EFI_STATUS IN UINT64 Lun, IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet, IN EFI_EVENT Event OPTIONAL - ); + ); /** - Used to retrieve the list of legal Target IDs and LUNs for SCSI devices on a SCSI channel. These + Used to retrieve the list of legal Target IDs and LUNs for SCSI devices on a SCSI channel. These can either be the list SCSI devices that are actually present on the SCSI channel, or the list of legal - Target Ids and LUNs for the SCSI channel. Regardless, the caller of this function must probe the - Target ID and LUN returned to see if a SCSI device is actually present at that location on the SCSI - channel. + Target Ids and LUNs for the SCSI channel. Regardless, the caller of this function must probe the + Target ID and LUN returned to see if a SCSI device is actually present at that location on the SCSI + channel. @param This A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance. @param Target On input, a pointer to the Target ID (an array of size @@ -230,7 +224,7 @@ EFI_STATUS IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This, IN OUT UINT8 **Target, IN OUT UINT64 *Lun - ); + ); /** Used to allocate and build a device path node for a SCSI device on a SCSI channel. @@ -265,7 +259,7 @@ EFI_STATUS IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This, IN UINT8 *Target, IN UINT64 Lun, - IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath + OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath ); /** @@ -294,7 +288,7 @@ EFI_STATUS IN EFI_DEVICE_PATH_PROTOCOL *DevicePath, OUT UINT8 **Target, OUT UINT64 *Lun - ); + ); /** Resets a SCSI channel. This operation resets all the SCSI devices connected to the SCSI channel. @@ -311,8 +305,8 @@ typedef EFI_STATUS (EFIAPI *EFI_EXT_SCSI_PASS_THRU_RESET_CHANNEL)( IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This - ); - + ); + /** Resets a SCSI logical unit that is connected to a SCSI channel. @@ -338,13 +332,13 @@ EFI_STATUS IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This, IN UINT8 *Target, IN UINT64 Lun - ); + ); /** - Used to retrieve the list of legal Target IDs for SCSI devices on a SCSI channel. These can either + Used to retrieve the list of legal Target IDs for SCSI devices on a SCSI channel. These can either be the list SCSI devices that are actually present on the SCSI channel, or the list of legal Target IDs - for the SCSI channel. Regardless, the caller of this function must probe the Target ID returned to - see if a SCSI device is actually present at that location on the SCSI channel. + for the SCSI channel. Regardless, the caller of this function must probe the Target ID returned to + see if a SCSI device is actually present at that location on the SCSI channel. @param This A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance. @param Target (TARGET_MAX_BYTES) of a SCSI device present on the SCSI channel. @@ -367,12 +361,12 @@ EFI_STATUS (EFIAPI *EFI_EXT_SCSI_PASS_THRU_GET_NEXT_TARGET)( IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This, IN OUT UINT8 **Target - ); + ); /// -/// The EFI_EXT_SCSI_PASS_THRU_PROTOCOL provides information about a SCSI channel -/// and the ability to send SCI Request Packets to any SCSI device attached to -/// that SCSI channel. The information includes the Target ID of the host controller +/// The EFI_EXT_SCSI_PASS_THRU_PROTOCOL provides information about a SCSI channel +/// and the ability to send SCI Request Packets to any SCSI device attached to +/// that SCSI channel. The information includes the Target ID of the host controller /// on the SCSI channel and the attributes of the SCSI channel. /// struct _EFI_EXT_SCSI_PASS_THRU_PROTOCOL { diff --git a/MdePkg/Include/Protocol/SdMmcPassThru.h b/MdePkg/Include/Protocol/SdMmcPassThru.h index ddbf45632cc5..4135a3ba9e51 100644 --- a/MdePkg/Include/Protocol/SdMmcPassThru.h +++ b/MdePkg/Include/Protocol/SdMmcPassThru.h @@ -3,13 +3,7 @@ to any SD/MMC device attached to the SD compatible pci host controller. Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -170,7 +164,7 @@ EFI_STATUS @param[in] This A pointer to the EFI_SD_MMMC_PASS_THRU_PROTOCOL instance. @param[in] Slot Specifies the slot number of the SD card for which a device path node is to be allocated and built. - @param[in,out] DevicePath A pointer to a single device path node that describes the SD + @param[out] DevicePath A pointer to a single device path node that describes the SD card specified by Slot. This function is responsible for allocating the buffer DevicePath with the boot service AllocatePool(). It is the caller's responsibility to free @@ -188,7 +182,7 @@ EFI_STATUS (EFIAPI *EFI_SD_MMC_PASS_THRU_BUILD_DEVICE_PATH) ( IN EFI_SD_MMC_PASS_THRU_PROTOCOL *This, IN UINT8 Slot, - IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath + OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath ); /** diff --git a/MdePkg/Include/Protocol/Security.h b/MdePkg/Include/Protocol/Security.h index 54c51fa43209..392db311aeab 100644 --- a/MdePkg/Include/Protocol/Security.h +++ b/MdePkg/Include/Protocol/Security.h @@ -1,9 +1,9 @@ /** @file Security Architectural Protocol as defined in PI Specification VOLUME 2 DXE - Used to provide Security services. Specifically, dependening upon the - authentication state of a discovered driver in a Firmware Volume, the - portable DXE Core Dispatcher will call into the Security Architectural + Used to provide Security services. Specifically, dependening upon the + authentication state of a discovered driver in a Firmware Volume, the + portable DXE Core Dispatcher will call into the Security Architectural Protocol (SAP) with the authentication state of the driver. This call-out allows for OEM-specific policy decisions to be made, such @@ -11,17 +11,11 @@ an unsigned driver or failed signature check, or other exception response. The SAP can also change system behavior by having the DXE core put a driver - in the Schedule-On-Request (SOR) state. This will allow for later disposition + in the Schedule-On-Request (SOR) state. This will allow for later disposition of the driver by platform agent, such as Platform BDS. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -37,31 +31,31 @@ typedef struct _EFI_SECURITY_ARCH_PROTOCOL EFI_SECURITY_ARCH_PROTOCOL; /** - The EFI_SECURITY_ARCH_PROTOCOL (SAP) is used to abstract platform-specific - policy from the DXE core response to an attempt to use a file that returns a - given status for the authentication check from the section extraction protocol. + The EFI_SECURITY_ARCH_PROTOCOL (SAP) is used to abstract platform-specific + policy from the DXE core response to an attempt to use a file that returns a + given status for the authentication check from the section extraction protocol. - The possible responses in a given SAP implementation may include locking - flash upon failure to authenticate, attestation logging for all signed drivers, - and other exception operations. The File parameter allows for possible logging + The possible responses in a given SAP implementation may include locking + flash upon failure to authenticate, attestation logging for all signed drivers, + and other exception operations. The File parameter allows for possible logging within the SAP of the driver. If File is NULL, then EFI_INVALID_PARAMETER is returned. - If the file specified by File with an authentication status specified by + If the file specified by File with an authentication status specified by AuthenticationStatus is safe for the DXE Core to use, then EFI_SUCCESS is returned. - If the file specified by File with an authentication status specified by - AuthenticationStatus is not safe for the DXE Core to use under any circumstances, + If the file specified by File with an authentication status specified by + AuthenticationStatus is not safe for the DXE Core to use under any circumstances, then EFI_ACCESS_DENIED is returned. - If the file specified by File with an authentication status specified by - AuthenticationStatus is not safe for the DXE Core to use right now, but it - might be possible to use it at a future time, then EFI_SECURITY_VIOLATION is + If the file specified by File with an authentication status specified by + AuthenticationStatus is not safe for the DXE Core to use right now, but it + might be possible to use it at a future time, then EFI_SECURITY_VIOLATION is returned. @param This The EFI_SECURITY_ARCH_PROTOCOL instance. - @param AuthenticationStatus + @param AuthenticationStatus This is the authentication type returned from the Section Extraction protocol. See the Section Extraction Protocol Specification for details on this type. @@ -81,7 +75,7 @@ typedef struct _EFI_SECURITY_ARCH_PROTOCOL EFI_SECURITY_ARCH_PROTOCOL; used for any purpose. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_SECURITY_FILE_AUTHENTICATION_STATE)( IN CONST EFI_SECURITY_ARCH_PROTOCOL *This, @@ -91,7 +85,7 @@ EFI_STATUS /// /// The EFI_SECURITY_ARCH_PROTOCOL is used to abstract platform-specific policy -/// from the DXE core. This includes locking flash upon failure to authenticate, +/// from the DXE core. This includes locking flash upon failure to authenticate, /// attestation logging, and other exception operations. /// struct _EFI_SECURITY_ARCH_PROTOCOL { diff --git a/MdePkg/Include/Protocol/Security2.h b/MdePkg/Include/Protocol/Security2.h index a8d79156907c..95c5dc1b3a81 100644 --- a/MdePkg/Include/Protocol/Security2.h +++ b/MdePkg/Include/Protocol/Security2.h @@ -4,27 +4,21 @@ Abstracts security-specific functions from the DXE Foundation of UEFI Image Verification, Trusted Computing Group (TCG) measured boot, and User Identity policy for image loading and consoles. This protocol must be produced by a boot service or runtime DXE driver. - + This protocol is optional and must be published prior to the EFI_SECURITY_ARCH_PROTOCOL. As a result, the same driver must publish both of these interfaces. - + When both Security and Security2 Architectural Protocols are published, LoadImage must use them in accordance with the following rules: The Security2 protocol must be used on every image being loaded. - The Security protocol must be used after the Securiy2 protocol and only on images that + The Security protocol must be used after the Securiy2 protocol and only on images that have been read using Firmware Volume protocol. When only Security architectural protocol is published, LoadImage must use it on every image being loaded. - Copyright (c) 2012, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2012 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -36,7 +30,7 @@ /// #define EFI_SECURITY2_ARCH_PROTOCOL_GUID \ { 0x94ab2f58, 0x1438, 0x4ef1, {0x91, 0x52, 0x18, 0x94, 0x1a, 0x3a, 0x0e, 0x68 } } - + typedef struct _EFI_SECURITY2_ARCH_PROTOCOL EFI_SECURITY2_ARCH_PROTOCOL; /** @@ -51,7 +45,7 @@ typedef struct _EFI_SECURITY2_ARCH_PROTOCOL EFI_SECURITY2_ARCH_PROTOCOL; these cases. If the FileBuffer is NULL, the interface will determine if the DevicePath can be connected in order to support the User Identification policy. - + @param This The EFI_SECURITY2_ARCH_PROTOCOL instance. @param File A pointer to the device path of the file that is being dispatched. This will optionally be used for logging. @@ -60,7 +54,7 @@ typedef struct _EFI_SECURITY2_ARCH_PROTOCOL EFI_SECURITY2_ARCH_PROTOCOL; @param BootPolicy A boot policy that was used to call LoadImage() UEFI service. If FileAuthentication() is invoked not from the LoadImage(), BootPolicy must be set to FALSE. - + @retval EFI_SUCCESS The file specified by DevicePath and non-NULL FileBuffer did authenticate, and the platform policy dictates that the DXE Foundation may use the file. @@ -84,9 +78,9 @@ typedef struct _EFI_SECURITY2_ARCH_PROTOCOL EFI_SECURITY2_ARCH_PROTOCOL; drivers from the device path specified by DevicePath. The image has been added into the list of the deferred images. **/ -typedef EFI_STATUS (EFIAPI *EFI_SECURITY2_FILE_AUTHENTICATION) ( +typedef EFI_STATUS (EFIAPI *EFI_SECURITY2_FILE_AUTHENTICATION) ( IN CONST EFI_SECURITY2_ARCH_PROTOCOL *This, - IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, + IN CONST EFI_DEVICE_PATH_PROTOCOL *File, OPTIONAL IN VOID *FileBuffer, IN UINTN FileSize, IN BOOLEAN BootPolicy diff --git a/MdePkg/Include/Protocol/SecurityPolicy.h b/MdePkg/Include/Protocol/SecurityPolicy.h index ceff5ac22752..d36e588d8734 100644 --- a/MdePkg/Include/Protocol/SecurityPolicy.h +++ b/MdePkg/Include/Protocol/SecurityPolicy.h @@ -1,14 +1,8 @@ /** @file Security Policy protocol as defined in PI Specification VOLUME 2 DXE - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Protocol/SerialIo.h b/MdePkg/Include/Protocol/SerialIo.h index 8371f42b2ec9..8d788306e54e 100644 --- a/MdePkg/Include/Protocol/SerialIo.h +++ b/MdePkg/Include/Protocol/SerialIo.h @@ -4,14 +4,8 @@ Abstraction of a basic serial device. Targeted at 16550 UART, but could be much more generic. - Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -25,7 +19,7 @@ /// /// Protocol GUID defined in EFI1.1. -/// +/// #define SERIAL_IO_PROTOCOL EFI_SERIAL_IO_PROTOCOL_GUID typedef struct _EFI_SERIAL_IO_PROTOCOL EFI_SERIAL_IO_PROTOCOL; @@ -33,7 +27,7 @@ typedef struct _EFI_SERIAL_IO_PROTOCOL EFI_SERIAL_IO_PROTOCOL; /// /// Backward-compatible with EFI1.1. -/// +/// typedef EFI_SERIAL_IO_PROTOCOL SERIAL_IO_INTERFACE; /// @@ -92,7 +86,7 @@ typedef enum { Reset the serial device. @param This Protocol instance pointer. - + @retval EFI_SUCCESS The device was reset. @retval EFI_DEVICE_ERROR The serial device could not be reset. @@ -104,7 +98,7 @@ EFI_STATUS ); /** - Sets the baud rate, receive FIFO depth, transmit/receice time out, parity, + Sets the baud rate, receive FIFO depth, transmit/receice time out, parity, data bits, and stop bits on a serial device. @param This Protocol instance pointer. @@ -125,8 +119,9 @@ EFI_STATUS value of DefaultStopBits will use the device's default number of stop bits. - @retval EFI_SUCCESS The device was reset. - @retval EFI_DEVICE_ERROR The serial device could not be reset. + @retval EFI_SUCCESS The device was reset. + @retval EFI_INVALID_PARAMETER One or more attributes has an unsupported value. + @retval EFI_DEVICE_ERROR The serial device is not functioning correctly. **/ typedef @@ -164,7 +159,7 @@ EFI_STATUS @param This Protocol instance pointer. @param Control A pointer to return the current Control signals from the serial device. - + @retval EFI_SUCCESS The control bits were read from the serial device. @retval EFI_DEVICE_ERROR The serial device is not functioning correctly. @@ -220,33 +215,33 @@ EFI_STATUS /** @par Data Structure Description: - The data values in SERIAL_IO_MODE are read-only and are updated by the code + The data values in SERIAL_IO_MODE are read-only and are updated by the code that produces the SERIAL_IO_PROTOCOL member functions. @param ControlMask A mask for the Control bits that the device supports. The device must always support the Input Buffer Empty control bit. - + @param TimeOut If applicable, the number of microseconds to wait before timing out a Read or Write operation. - + @param BaudRate If applicable, the current baud rate setting of the device; otherwise, baud rate has the value of zero to indicate that device runs at the device's designed speed. - + @param ReceiveFifoDepth The number of characters the device will buffer on input - + @param DataBits The number of characters the device will buffer on input - + @param Parity - If applicable, this is the EFI_PARITY_TYPE that is computed or + If applicable, this is the EFI_PARITY_TYPE that is computed or checked as each character is transmitted or reveived. If the device does not support parity the value is the default parity value. - + @param StopBits If applicable, the EFI_STOP_BITS_TYPE number of stop bits per character. If the device does not support stop bits the value is @@ -268,17 +263,18 @@ typedef struct { } EFI_SERIAL_IO_MODE; #define EFI_SERIAL_IO_PROTOCOL_REVISION 0x00010000 +#define EFI_SERIAL_IO_PROTOCOL_REVISION1p1 0x00010001 #define SERIAL_IO_INTERFACE_REVISION EFI_SERIAL_IO_PROTOCOL_REVISION /// -/// The Serial I/O protocol is used to communicate with UART-style serial devices. -/// These can be standard UART serial ports in PC-AT systems, serial ports attached +/// The Serial I/O protocol is used to communicate with UART-style serial devices. +/// These can be standard UART serial ports in PC-AT systems, serial ports attached /// to a USB interface, or potentially any character-based I/O device. /// struct _EFI_SERIAL_IO_PROTOCOL { /// - /// The revision to which the EFI_SERIAL_IO_PROTOCOL adheres. All future revisions - /// must be backwards compatible. If a future version is not backwards compatible, + /// The revision to which the EFI_SERIAL_IO_PROTOCOL adheres. All future revisions + /// must be backwards compatible. If a future version is not backwards compatible, /// it is not the same GUID. /// UINT32 Revision; @@ -292,6 +288,14 @@ struct _EFI_SERIAL_IO_PROTOCOL { /// Pointer to SERIAL_IO_MODE data. /// EFI_SERIAL_IO_MODE *Mode; + /// + /// Pointer to a GUID identifying the device connected to the serial port. + /// This field is NULL when the protocol is installed by the serial port + /// driver and may be populated by a platform driver for a serial port + /// with a known device attached. The field will remain NULL if there is + /// no platform serial device identification information available. + /// + CONST EFI_GUID *DeviceTypeGuid; // Revision 1.1 }; extern EFI_GUID gEfiSerialIoProtocolGuid; diff --git a/MdePkg/Include/Protocol/ServiceBinding.h b/MdePkg/Include/Protocol/ServiceBinding.h index 546a0d0973d2..37f44c554ced 100644 --- a/MdePkg/Include/Protocol/ServiceBinding.h +++ b/MdePkg/Include/Protocol/ServiceBinding.h @@ -1,18 +1,12 @@ -/** @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 + It provides services that are required to create and destroy child handles that support a given set of protocols. - Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -26,14 +20,14 @@ typedef struct _EFI_SERVICE_BINDING_PROTOCOL EFI_SERVICE_BINDING_PROTOCOL; /** 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. + + 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 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 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 protocol was added to ChildHandle. @@ -52,9 +46,9 @@ EFI_STATUS /** 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 + + 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 Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance. @@ -76,14 +70,14 @@ EFI_STATUS ); /// -/// The EFI_SERVICE_BINDING_PROTOCOL provides member functions to create and destroy -/// child handles. A driver is responsible for adding protocols to the child handle -/// in CreateChild() and removing protocols in DestroyChild(). It is also required -/// that the CreateChild() function opens the parent protocol BY_CHILD_CONTROLLER +/// The EFI_SERVICE_BINDING_PROTOCOL provides member functions to create and destroy +/// child handles. A driver is responsible for adding protocols to the child handle +/// in CreateChild() and removing protocols in DestroyChild(). It is also required +/// that the CreateChild() function opens the parent protocol BY_CHILD_CONTROLLER /// to establish the parent-child relationship, and closes the protocol in DestroyChild(). -/// The pseudo code for CreateChild() and DestroyChild() is provided to specify the -/// required behavior, not to specify the required implementation. Each consumer of -/// a software protocol is responsible for calling CreateChild() when it requires the +/// The pseudo code for CreateChild() and DestroyChild() is provided to specify the +/// required behavior, not to specify the required implementation. Each consumer of +/// a software protocol is responsible for calling CreateChild() when it requires the /// protocol and calling DestroyChild() when it is finished with that protocol. /// struct _EFI_SERVICE_BINDING_PROTOCOL { diff --git a/MdePkg/Include/Protocol/Shell.h b/MdePkg/Include/Protocol/Shell.h index c16da382b2a6..9047060ae32e 100644 --- a/MdePkg/Include/Protocol/Shell.h +++ b/MdePkg/Include/Protocol/Shell.h @@ -2,14 +2,8 @@ EFI Shell protocol as defined in the UEFI Shell 2.0 specification including errata. (C) Copyright 2014 Hewlett-Packard Development Company, L.P.<BR> - Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -547,7 +541,7 @@ CONST CHAR16 * ); /** - Gets the environment variable and Attributes, or list of environment variables. Can be + Gets the environment variable and Attributes, or list of environment variables. Can be used instead of GetEnv(). This function returns the current value of the specified environment variable and @@ -555,18 +549,18 @@ CONST CHAR16 * variables will be returned. @param[in] Name A pointer to the environment variable name. If Name is NULL, - then the function will return all of the defined shell + then the function will return all of the defined shell environment variables. In the case where multiple environment - variables are being returned, each variable will be terminated + variables are being returned, each variable will be terminated by a NULL, and the list will be terminated by a double NULL. @param[out] Attributes If not NULL, a pointer to the returned attributes bitmask for the environment variable. In the case where Name is NULL, and multiple environment variables are being returned, Attributes is undefined. - @retval NULL The environment variable doesn't exist. - @return The environment variable's value. The returned pointer does not - need to be freed by the caller. + @retval NULL The environment variable doesn't exist. + @return The environment variable's value. The returned pointer does not + need to be freed by the caller. **/ typedef CONST CHAR16 * @@ -1011,7 +1005,7 @@ EFI_STATUS aliases will be returned in ReturnedData. @param[out] Volatile Upon return of a single command if TRUE indicates this is stored in a volatile fashion. FALSE otherwise. - @return If Alias is not NULL, it will return a pointer to + @return If Alias is not NULL, it will return a pointer to the NULL-terminated command for that alias. If Alias is NULL, ReturnedData points to a ';' delimited list of alias (e.g. @@ -1262,7 +1256,7 @@ extern EFI_GUID gEfiShellProtocolGuid; enum ShellVersion { SHELL_MAJOR_VERSION = 2, - SHELL_MINOR_VERSION = 1 + SHELL_MINOR_VERSION = 2 }; #endif diff --git a/MdePkg/Include/Protocol/ShellDynamicCommand.h b/MdePkg/Include/Protocol/ShellDynamicCommand.h index da2055d2d506..58ae0b844760 100644 --- a/MdePkg/Include/Protocol/ShellDynamicCommand.h +++ b/MdePkg/Include/Protocol/ShellDynamicCommand.h @@ -2,14 +2,8 @@ EFI Shell Dynamic Command registration protocol (C) Copyright 2012-2014 Hewlett-Packard Development Company, L.P.<BR> - Copyright (c) 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2016 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -73,7 +67,7 @@ CHAR16* /// EFI_SHELL_DYNAMIC_COMMAND_PROTOCOL protocol structure. struct _EFI_SHELL_DYNAMIC_COMMAND_PROTOCOL { - + CONST CHAR16 *CommandName; SHELL_COMMAND_HANDLER Handler; SHELL_COMMAND_GETHELP GetHelp; diff --git a/MdePkg/Include/Protocol/ShellParameters.h b/MdePkg/Include/Protocol/ShellParameters.h index e9c0ee5f634e..20091a1537e0 100644 --- a/MdePkg/Include/Protocol/ShellParameters.h +++ b/MdePkg/Include/Protocol/ShellParameters.h @@ -2,13 +2,7 @@ EFI Shell protocol as defined in the UEFI Shell 2.0 specification. Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Protocol/SimpleFileSystem.h b/MdePkg/Include/Protocol/SimpleFileSystem.h index cf39e83c2c33..7762d34ac217 100644 --- a/MdePkg/Include/Protocol/SimpleFileSystem.h +++ b/MdePkg/Include/Protocol/SimpleFileSystem.h @@ -1,20 +1,14 @@ /** @file SimpleFileSystem protocol as defined in the UEFI 2.0 specification. - The SimpleFileSystem protocol is the programmatic access to the FAT (12,16,32) - file system specified in UEFI 2.0. It can also be used to abstract a file + The SimpleFileSystem protocol is the programmatic access to the FAT (12,16,32) + file system specified in UEFI 2.0. It can also be used to abstract a file system other than FAT. UEFI 2.0 can boot from any valid EFI image contained in a SimpleFileSystem. -Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -33,12 +27,12 @@ typedef struct _EFI_FILE_PROTOCOL *EFI_FILE_HANDLE; /// /// Protocol GUID name defined in EFI1.1. -/// +/// #define SIMPLE_FILE_SYSTEM_PROTOCOL EFI_SIMPLE_FILE_SYSTEM_PROTOCOL_GUID /// /// Protocol name defined in EFI1.1. -/// +/// typedef EFI_SIMPLE_FILE_SYSTEM_PROTOCOL EFI_FILE_IO_INTERFACE; typedef EFI_FILE_PROTOCOL EFI_FILE; @@ -73,7 +67,7 @@ EFI_STATUS /// /// Revision defined in EFI1.1 -/// +/// #define EFI_FILE_IO_INTERFACE_REVISION EFI_SIMPLE_FILE_SYSTEM_PROTOCOL_REVISION struct _EFI_SIMPLE_FILE_SYSTEM_PROTOCOL { @@ -99,7 +93,7 @@ struct _EFI_SIMPLE_FILE_SYSTEM_PROTOCOL { and "..". @param OpenMode The mode to open the file. The only valid combinations that the file may be opened with are: Read, Read/Write, or Create/Read/Write. - @param Attributes Only valid for EFI_FILE_MODE_CREATE, in which case these are the + @param Attributes Only valid for EFI_FILE_MODE_CREATE, in which case these are the attribute bits for the newly created file. @retval EFI_SUCCESS The file was opened. @@ -147,7 +141,7 @@ EFI_STATUS /** Closes a specified file handle. - @param This A pointer to the EFI_FILE_PROTOCOL instance that is the file + @param This A pointer to the EFI_FILE_PROTOCOL instance that is the file handle to close. @retval EFI_SUCCESS The file was closed. @@ -345,7 +339,7 @@ EFI_STATUS /** Flushes all modified data associated with a file to a device. - @param This A pointer to the EFI_FILE_PROTOCOL instance that is the file + @param This A pointer to the EFI_FILE_PROTOCOL instance that is the file handle to flush. @retval EFI_SUCCESS The data was flushed. @@ -409,7 +403,7 @@ typedef struct { and "..". @param OpenMode The mode to open the file. The only valid combinations that the file may be opened with are: Read, Read/Write, or Create/Read/Write. - @param Attributes Only valid for EFI_FILE_MODE_CREATE, in which case these are the + @param Attributes Only valid for EFI_FILE_MODE_CREATE, in which case these are the attribute bits for the newly created file. @param Token A pointer to the token associated with the transaction. @@ -488,13 +482,13 @@ typedef EFI_STATUS (EFIAPI *EFI_FILE_WRITE_EX) ( IN EFI_FILE_PROTOCOL *This, - IN OUT EFI_FILE_IO_TOKEN *Token + IN OUT EFI_FILE_IO_TOKEN *Token ); /** Flushes all modified data associated with a file to a device. - @param This A pointer to the EFI_FILE_PROTOCOL instance that is the file + @param This A pointer to the EFI_FILE_PROTOCOL instance that is the file handle to flush. @param Token A pointer to the token associated with the transaction. @@ -523,19 +517,19 @@ EFI_STATUS // // Revision defined in EFI1.1. -// +// #define EFI_FILE_REVISION EFI_FILE_PROTOCOL_REVISION /// /// The EFI_FILE_PROTOCOL provides file IO access to supported file systems. -/// An EFI_FILE_PROTOCOL provides access to a file's or directory's contents, -/// and is also a reference to a location in the directory tree of the file system -/// in which the file resides. With any given file handle, other files may be opened +/// An EFI_FILE_PROTOCOL provides access to a file's or directory's contents, +/// and is also a reference to a location in the directory tree of the file system +/// in which the file resides. With any given file handle, other files may be opened /// relative to this file's location, yielding new file handles. /// struct _EFI_FILE_PROTOCOL { /// - /// The version of the EFI_FILE_PROTOCOL interface. The version specified + /// The version of the EFI_FILE_PROTOCOL interface. The version specified /// by this specification is EFI_FILE_PROTOCOL_LATEST_REVISION. /// Future versions are required to be backward compatible to version 1.0. /// diff --git a/MdePkg/Include/Protocol/SimpleNetwork.h b/MdePkg/Include/Protocol/SimpleNetwork.h index 0dda83aaafd9..a367fa2e3111 100644 --- a/MdePkg/Include/Protocol/SimpleNetwork.h +++ b/MdePkg/Include/Protocol/SimpleNetwork.h @@ -1,5 +1,5 @@ /** @file - The EFI_SIMPLE_NETWORK_PROTOCOL provides services to initialize a network interface, + The EFI_SIMPLE_NETWORK_PROTOCOL provides services to initialize a network interface, transmit packets, receive packets, and close a network interface. Basic network device abstraction. @@ -9,17 +9,11 @@ MCast - MultiCast ... -Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent - @par Revision Reference: - This Protocol is introduced in EFI Specification 1.10. + @par Revision Reference: + This Protocol is introduced in EFI Specification 1.10. **/ @@ -36,7 +30,7 @@ typedef struct _EFI_SIMPLE_NETWORK_PROTOCOL EFI_SIMPLE_NETWORK_PROTOCOL; /// /// Protocol defined in EFI1.1. -/// +/// typedef EFI_SIMPLE_NETWORK_PROTOCOL EFI_SIMPLE_NETWORK; /// @@ -288,8 +282,8 @@ EFI_STATUS ); /** - Resets a network adapter and allocates the transmit and receive buffers - required by the network interface; optionally, also requests allocation + Resets a network adapter and allocates the transmit and receive buffers + required by the network interface; optionally, also requests allocation of additional transmit and receive buffers. @param This The protocol instance pointer. @@ -322,8 +316,8 @@ EFI_STATUS ); /** - Resets a network adapter and re-initializes it with the parameters that were - provided in the previous call to Initialize(). + Resets a network adapter and re-initializes it with the parameters that were + provided in the previous call to Initialize(). @param This The protocol instance pointer. @param ExtendedVerification Indicates that the driver may perform a more @@ -345,7 +339,7 @@ EFI_STATUS ); /** - Resets a network adapter and leaves it in a state that is safe for + Resets a network adapter and leaves it in a state that is safe for another driver to initialize. @param This Protocol instance pointer. @@ -482,7 +476,7 @@ EFI_STATUS ); /** - Performs read and write operations on the NVRAM device attached to a + Performs read and write operations on the NVRAM device attached to a network interface. @param This The protocol instance pointer. @@ -512,7 +506,7 @@ EFI_STATUS ); /** - Reads the current interrupt status and recycled transmit buffer status from + Reads the current interrupt status and recycled transmit buffer status from a network interface. @param This The protocol instance pointer. @@ -570,7 +564,7 @@ EFI_STATUS @retval EFI_SUCCESS The packet was placed on the transmit queue. @retval EFI_NOT_STARTED The network interface has not been started. - @retval EFI_NOT_READY The network interface is too busy to accept this transmit request. + @retval EFI_NOT_READY The network interface is too busy to accept this transmit request. @retval EFI_BUFFER_TOO_SMALL The BufferSize parameter is too small. @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. @retval EFI_DEVICE_ERROR The command could not be sent to the network interface. @@ -637,19 +631,19 @@ EFI_STATUS // // Revision defined in EFI1.1 -// +// #define EFI_SIMPLE_NETWORK_INTERFACE_REVISION EFI_SIMPLE_NETWORK_PROTOCOL_REVISION /// -/// The EFI_SIMPLE_NETWORK_PROTOCOL protocol is used to initialize access -/// to a network adapter. Once the network adapter initializes, -/// the EFI_SIMPLE_NETWORK_PROTOCOL protocol provides services that +/// The EFI_SIMPLE_NETWORK_PROTOCOL protocol is used to initialize access +/// to a network adapter. Once the network adapter initializes, +/// the EFI_SIMPLE_NETWORK_PROTOCOL protocol provides services that /// allow packets to be transmitted and received. /// struct _EFI_SIMPLE_NETWORK_PROTOCOL { /// - /// Revision of the EFI_SIMPLE_NETWORK_PROTOCOL. All future revisions must - /// be backwards compatible. If a future version is not backwards compatible + /// Revision of the EFI_SIMPLE_NETWORK_PROTOCOL. All future revisions must + /// be backwards compatible. If a future version is not backwards compatible /// it is not the same GUID. /// UINT64 Revision; diff --git a/MdePkg/Include/Protocol/SimplePointer.h b/MdePkg/Include/Protocol/SimplePointer.h index d8c0757f6243..cb52ad9ddfb9 100644 --- a/MdePkg/Include/Protocol/SimplePointer.h +++ b/MdePkg/Include/Protocol/SimplePointer.h @@ -3,14 +3,8 @@ Abstraction of a very simple pointer device like a mouse or trackball. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -78,17 +72,17 @@ typedef struct { BOOLEAN RightButton; } EFI_SIMPLE_POINTER_MODE; -/** +/** Resets the pointer device hardware. - + @param This A pointer to the EFI_SIMPLE_POINTER_PROTOCOL - instance. + instance. @param ExtendedVerification Indicates that the driver may perform a more exhaustive - verification operation of the device during reset. - + verification operation of the device during reset. + @retval EFI_SUCCESS The device was reset. - @retval EFI_DEVICE_ERROR The device is not functioning correctly and could not be reset. - + @retval EFI_DEVICE_ERROR The device is not functioning correctly and could not be reset. + **/ typedef EFI_STATUS @@ -97,32 +91,32 @@ EFI_STATUS IN BOOLEAN ExtendedVerification ); -/** +/** Retrieves the current state of a pointer device. - + @param This A pointer to the EFI_SIMPLE_POINTER_PROTOCOL - instance. + instance. @param State A pointer to the state information on the pointer device. - + @retval EFI_SUCCESS The state of the pointer device was returned in State. @retval EFI_NOT_READY The state of the pointer device has not changed since the last call to - GetState(). + GetState(). @retval EFI_DEVICE_ERROR A device error occurred while attempting to retrieve the pointer device's - current state. - + current state. + **/ typedef EFI_STATUS (EFIAPI *EFI_SIMPLE_POINTER_GET_STATE)( IN EFI_SIMPLE_POINTER_PROTOCOL *This, - IN OUT EFI_SIMPLE_POINTER_STATE *State + OUT EFI_SIMPLE_POINTER_STATE *State ); /// -/// The EFI_SIMPLE_POINTER_PROTOCOL provides a set of services for a pointer -/// device that can use used as an input device from an application written -/// to this specification. The services include the ability to reset the -/// pointer device, retrieve get the state of the pointer device, and +/// The EFI_SIMPLE_POINTER_PROTOCOL provides a set of services for a pointer +/// device that can use used as an input device from an application written +/// to this specification. The services include the ability to reset the +/// pointer device, retrieve get the state of the pointer device, and /// retrieve the capabilities of the pointer device. /// struct _EFI_SIMPLE_POINTER_PROTOCOL { diff --git a/MdePkg/Include/Protocol/SimpleTextIn.h b/MdePkg/Include/Protocol/SimpleTextIn.h index d8df5537aa1e..e6884d89c1c8 100644 --- a/MdePkg/Include/Protocol/SimpleTextIn.h +++ b/MdePkg/Include/Protocol/SimpleTextIn.h @@ -5,13 +5,7 @@ terminal. Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Protocol/SimpleTextInEx.h b/MdePkg/Include/Protocol/SimpleTextInEx.h index 5524c720a713..f6a80e7c4f4d 100644 --- a/MdePkg/Include/Protocol/SimpleTextInEx.h +++ b/MdePkg/Include/Protocol/SimpleTextInEx.h @@ -5,14 +5,8 @@ which exposes much more state and modifier information from the input device, also allows one to register a notification for a particular keystroke. - Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -190,13 +184,10 @@ typedef struct { pressed. - @retval EFI_SUCCESS The keystroke information was - returned. - - @retval EFI_NOT_READY There was no keystroke data available. - EFI_DEVICE_ERROR The keystroke - information was not returned due to - hardware errors. + @retval EFI_SUCCESS The keystroke information was returned. + @retval EFI_NOT_READY There was no keystroke data available. + @retval EFI_DEVICE_ERROR The keystroke information was not returned due to + hardware errors. **/ @@ -251,18 +242,19 @@ EFI_STATUS @param KeyData A pointer to a buffer that is filled in with the keystroke information for the key that was - pressed. + pressed. If KeyData.Key, KeyData.KeyState.KeyToggleState + and KeyData.KeyState.KeyShiftState are 0, then any incomplete + keystroke will trigger a notification of the KeyNotificationFunction. - @param KeyNotificationFunction Points to the function to be - called when the key sequence - is typed specified by KeyData. + @param KeyNotificationFunction Points to the function to be called when the key sequence + is typed specified by KeyData. This notification function + should be called at <=TPL_CALLBACK. @param NotifyHandle Points to the unique handle assigned to the registered notification. - @retval EFI_SUCCESS The device state was set - appropriately. + @retval EFI_SUCCESS Key notify was registered successfully. @retval EFI_OUT_OF_RESOURCES Unable to allocate necessary data structures. @@ -286,7 +278,7 @@ EFI_STATUS @param NotificationHandle The handle of the notification function being unregistered. - @retval EFI_SUCCESS The device state was set appropriately. + @retval EFI_SUCCESS Key notify was unregistered successfully. @retval EFI_INVALID_PARAMETER The NotificationHandle is invalid. diff --git a/MdePkg/Include/Protocol/SimpleTextOut.h b/MdePkg/Include/Protocol/SimpleTextOut.h index 4d2612c0a91d..18438d3533ef 100644 --- a/MdePkg/Include/Protocol/SimpleTextOut.h +++ b/MdePkg/Include/Protocol/SimpleTextOut.h @@ -6,14 +6,8 @@ a single hardware device or a virtual device that is an aggregation of multiple physical devices. -Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -27,14 +21,14 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /// /// Protocol GUID defined in EFI1.1. -/// +/// #define SIMPLE_TEXT_OUTPUT_PROTOCOL EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL_GUID typedef struct _EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL; /// /// Backward-compatible with EFI1.1. -/// +/// typedef EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL SIMPLE_TEXT_OUTPUT_INTERFACE; // @@ -125,8 +119,8 @@ typedef EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL SIMPLE_TEXT_OUTPUT_INTERFACE; #define EFI_WHITE (EFI_BLUE | EFI_GREEN | EFI_RED | EFI_BRIGHT) // -// Macro to accept color values in their raw form to create -// a value that represents both a foreground and background +// Macro to accept color values in their raw form to create +// a value that represents both a foreground and background // color in a single byte. // For Foreground, and EFI_* value is valid from EFI_BLACK(0x00) to // EFI_WHITE (0x0F). @@ -148,7 +142,7 @@ typedef EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL SIMPLE_TEXT_OUTPUT_INTERFACE; // // We currently define attributes from 0 - 7F for color manipulations -// To internally handle the local display characteristics for a particular character, +// To internally handle the local display characteristics for a particular character, // Bit 7 signifies the local glyph representation for a character. If turned on, glyphs will be // pulled from the wide glyph database and will display locally as a wide character (16 X 19 versus 8 X 19) // If bit 7 is off, the narrow glyph database will be used. This does NOT affect information that is sent to @@ -201,7 +195,7 @@ EFI_STATUS ); /** - Verifies that all characters in a string can be output to the + Verifies that all characters in a string can be output to the target device. @param This The protocol instance pointer. @@ -231,7 +225,7 @@ EFI_STATUS requested ModeNumber. @param Rows Returns the geometry of the text output device for the requested ModeNumber. - + @retval EFI_SUCCESS The requested mode information was returned. @retval EFI_DEVICE_ERROR The device had an error and could not complete the request. @retval EFI_UNSUPPORTED The mode number was not valid. @@ -286,11 +280,11 @@ EFI_STATUS ); /** - Clears the output device(s) display to the currently selected background + Clears the output device(s) display to the currently selected background color. @param This The protocol instance pointer. - + @retval EFI_SUCCESS The operation completed successfully. @retval EFI_DEVICE_ERROR The device had an error and could not complete the request. @retval EFI_UNSUPPORTED The output device is not in a valid text mode. @@ -385,9 +379,9 @@ typedef struct { } EFI_SIMPLE_TEXT_OUTPUT_MODE; /// -/// The SIMPLE_TEXT_OUTPUT protocol is used to control text-based output devices. -/// It is the minimum required protocol for any handle supplied as the ConsoleOut -/// or StandardError device. In addition, the minimum supported text mode of such +/// The SIMPLE_TEXT_OUTPUT protocol is used to control text-based output devices. +/// It is the minimum required protocol for any handle supplied as the ConsoleOut +/// or StandardError device. In addition, the minimum supported text mode of such /// devices is at least 80 x 25 characters. /// struct _EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL { diff --git a/MdePkg/Include/Protocol/SmartCardEdge.h b/MdePkg/Include/Protocol/SmartCardEdge.h index ac5095c375fc..3107070ee997 100644 --- a/MdePkg/Include/Protocol/SmartCardEdge.h +++ b/MdePkg/Include/Protocol/SmartCardEdge.h @@ -6,14 +6,11 @@ boot process for authentication or data signing/decryption, especially if the application has to make use of PKI. - Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2015-2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.5. **/ diff --git a/MdePkg/Include/Protocol/SmartCardReader.h b/MdePkg/Include/Protocol/SmartCardReader.h index a39b379c5eaf..e1344902fb1b 100644 --- a/MdePkg/Include/Protocol/SmartCardReader.h +++ b/MdePkg/Include/Protocol/SmartCardReader.h @@ -5,13 +5,7 @@ smart card or a smart card reader. Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Protocol/Smbios.h b/MdePkg/Include/Protocol/Smbios.h index 1860ba50259e..1ef57a665a49 100644 --- a/MdePkg/Include/Protocol/Smbios.h +++ b/MdePkg/Include/Protocol/Smbios.h @@ -1,7 +1,7 @@ /** @file SMBIOS Protocol as defined in PI1.2 Specification VOLUME 5 Standard. - SMBIOS protocol allows consumers to log SMBIOS data records, and enables the producer + SMBIOS protocol allows consumers to log SMBIOS data records, and enables the producer to create the SMBIOS tables for a platform. This protocol provides an interface to add, remove or discover SMBIOS records. The driver which @@ -13,14 +13,8 @@ requiring an update to MajorVersion and MinorVersion. The SMBIOS protocol can only be called a TPL < TPL_NOTIFY. - Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -84,12 +78,12 @@ typedef SMBIOS_TABLE_STRING EFI_SMBIOS_STRING; typedef SMBIOS_TYPE EFI_SMBIOS_TYPE; typedef SMBIOS_HANDLE EFI_SMBIOS_HANDLE; typedef SMBIOS_STRUCTURE EFI_SMBIOS_TABLE_HEADER; - + typedef struct _EFI_SMBIOS_PROTOCOL EFI_SMBIOS_PROTOCOL; /** Add an SMBIOS record. - + This function allows any agent to add SMBIOS records. The caller is responsible for ensuring Record is formatted in a way that matches the version of the SMBIOS specification as defined in the MajorRevision and MinorRevision fields of the EFI_SMBIOS_PROTOCOL. @@ -100,7 +94,7 @@ typedef struct _EFI_SMBIOS_PROTOCOL EFI_SMBIOS_PROTOCOL; directly following the last string. The number of optional strings is not defined by the formatted area, but is fixed by the call to Add(). A string can be a place holder, but it must not be a NULL string as two NULL strings look like the double-null that terminates the structure. - + @param[in] This The EFI_SMBIOS_PROTOCOL instance. @param[in] ProducerHandle The handle of the controller or driver associated with the SMBIOS information. NULL means no handle. @param[in, out] SmbiosHandle On entry, the handle of the SMBIOS record to add. If FFFEh, then a unique handle @@ -110,7 +104,7 @@ typedef struct _EFI_SMBIOS_PROTOCOL EFI_SMBIOS_PROTOCOL; determined by EFI_SMBIOS_TABLE_HEADER.Type. The size of the formatted area is defined by EFI_SMBIOS_TABLE_HEADER.Length and either followed by a double-null (0x0000) or a set of null terminated strings and a null. - + @retval EFI_SUCCESS Record was added. @retval EFI_OUT_OF_RESOURCES Record was not added. @retval EFI_ALREADY_STARTED The SmbiosHandle passed in was already in use. @@ -126,19 +120,19 @@ EFI_STATUS /** Update the string associated with an existing SMBIOS record. - + This function allows the update of specific SMBIOS strings. The number of valid strings for any SMBIOS record is defined by how many strings were present when Add() was called. - + @param[in] This The EFI_SMBIOS_PROTOCOL instance. @param[in] SmbiosHandle SMBIOS Handle of structure that will have its string updated. @param[in] StringNumber The non-zero string number of the string to update. @param[in] String Update the StringNumber string with String. - + @retval EFI_SUCCESS SmbiosHandle had its StringNumber String updated. @retval EFI_INVALID_PARAMETER SmbiosHandle does not exist. @retval EFI_UNSUPPORTED String was not added because it is longer than the SMBIOS Table supports. - @retval EFI_NOT_FOUND The StringNumber.is not valid for this SMBIOS record. + @retval EFI_NOT_FOUND The StringNumber.is not valid for this SMBIOS record. **/ typedef EFI_STATUS @@ -151,12 +145,12 @@ EFI_STATUS /** Remove an SMBIOS record. - + This function removes an SMBIOS record using the handle specified by SmbiosHandle. - + @param[in] This The EFI_SMBIOS_PROTOCOL instance. @param[in] SmbiosHandle The handle of the SMBIOS record to remove. - + @retval EFI_SUCCESS SMBIOS record was removed. @retval EFI_INVALID_PARAMETER SmbiosHandle does not specify a valid SMBIOS record. **/ @@ -169,10 +163,10 @@ EFI_STATUS /** Allow the caller to discover all or some of the SMBIOS records. - + This function allows all of the SMBIOS records to be discovered. It's possible to find only the SMBIOS records that match the optional Type argument. - + @param[in] This The EFI_SMBIOS_PROTOCOL instance. @param[in, out] SmbiosHandle On entry, points to the previous handle of the SMBIOS record. On exit, points to the next SMBIOS record handle. If it is FFFEh on entry, then the first SMBIOS record @@ -207,7 +201,7 @@ struct _EFI_SMBIOS_PROTOCOL { UINT8 MajorVersion; ///< The major revision of the SMBIOS specification supported. UINT8 MinorVersion; ///< The minor revision of the SMBIOS specification supported. }; - + extern EFI_GUID gEfiSmbiosProtocolGuid; - + #endif // __SMBIOS_PROTOCOL_H__ diff --git a/MdePkg/Include/Protocol/SmbusHc.h b/MdePkg/Include/Protocol/SmbusHc.h index d5620d7a6c89..219a5cbe0c0c 100644 --- a/MdePkg/Include/Protocol/SmbusHc.h +++ b/MdePkg/Include/Protocol/SmbusHc.h @@ -1,15 +1,9 @@ /** @file - The file provides basic SMBus host controller management + The file provides basic SMBus host controller management and basic data transactions over the SMBus. - Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: PI Version 1.00. @@ -27,13 +21,13 @@ typedef struct _EFI_SMBUS_HC_PROTOCOL EFI_SMBUS_HC_PROTOCOL; /** - + The Execute() function provides a standard way to execute an operation as defined in the System Management Bus (SMBus) Specification. The resulting transaction will be either that the SMBus slave devices accept this transaction or that this - function returns with error. - + function returns with error. + @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance. SlaveAddress The SMBus slave address of the device with which to communicate. Type @@ -65,8 +59,8 @@ typedef struct _EFI_SMBUS_HC_PROTOCOL EFI_SMBUS_HC_PROTOCOL; @param PecCheck Defines if Packet Error Code (PEC) checking is required for this operation. SMBus Host Controller Code Definitions Version 1.0 - August 21, 2006 13 - + August 21, 2006 13 + @param Length Signifies the number of bytes that this operation will do. The maximum number of bytes can be revision specific and operation specific. This field @@ -78,8 +72,8 @@ typedef struct _EFI_SMBUS_HC_PROTOCOL EFI_SMBUS_HC_PROTOCOL; SMBus slave device. Not all operations require this argument. The length of this buffer is identified by Length. - - + + @retval EFI_SUCCESS The last data that was returned from the access matched the poll exit criteria. @@ -113,7 +107,7 @@ typedef struct _EFI_SMBUS_HC_PROTOCOL EFI_SMBUS_HC_PROTOCOL; values. @retval EFI_UNSUPPORTED The SMBus operation or PEC is not - supported. + supported. @retval EFI_BUFFER_TOO_SMALL Buffer is not sufficient for this operation. @@ -134,10 +128,10 @@ EFI_STATUS /** - - The ArpDevice() function provides a standard way for a device driver to + + The ArpDevice() function provides a standard way for a device driver to enumerate the entire SMBus or specific devices on the bus. - + @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance. @param ArpAll A Boolean expression that indicates if the @@ -183,7 +177,7 @@ EFI_STATUS @retval EFI_UNSUPPORTED ArpDevice, GetArpMap, and Notify are not implemented by this driver. - + **/ typedef EFI_STATUS @@ -196,23 +190,23 @@ EFI_STATUS /** - The GetArpMap() function returns the mapping of all the SMBus devices + The GetArpMap() function returns the mapping of all the SMBus devices that were enumerated by the SMBus host driver. - + @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance. - + @param Length Size of the buffer that contains the SMBus device map. - + @param SmbusDeviceMap The pointer to the device map as enumerated by the SMBus controller driver. - + @retval EFI_SUCCESS The SMBus returned the current device map. - + @retval EFI_UNSUPPORTED ArpDevice, GetArpMap, and Notify are not implemented by this driver. - + **/ typedef EFI_STATUS @@ -224,13 +218,13 @@ EFI_STATUS /** The notify function does some actions. - + @param SlaveAddress The SMBUS hardware address to which the SMBUS device is preassigned or allocated. @param Data Data of the SMBus host notify command that the caller wants to be called. - + @return EFI_STATUS **/ typedef @@ -242,13 +236,13 @@ EFI_STATUS /** - + The Notify() function registers all the callback functions to - allow the bus driver to call these functions when the + allow the bus driver to call these functions when the SlaveAddress/Data pair happens. - + @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance. - + @param SlaveAddress Address that the host controller detects as sending a message and calls all the registered function. @@ -261,7 +255,7 @@ EFI_STATUS Data pair. @retval EFI_SUCCESS NotifyFunction was registered. - + @retval EFI_UNSUPPORTED ArpDevice, GetArpMap, and Notify are not implemented by this driver. diff --git a/MdePkg/Include/Protocol/SmmAccess2.h b/MdePkg/Include/Protocol/SmmAccess2.h index 66cdf0c50abd..06475e172205 100644 --- a/MdePkg/Include/Protocol/SmmAccess2.h +++ b/MdePkg/Include/Protocol/SmmAccess2.h @@ -5,127 +5,33 @@ It abstracts the location and characteristics of SMRAM. The expectation is that the north bridge or memory controller would publish this protocol. - The principal functionality found in the memory controller includes the following: + The principal functionality found in the memory controller includes the following: - Exposing the SMRAM to all non-SMM agents, or the "open" state - Shrouding the SMRAM to all but the SMM agents, or the "closed" state - - Preserving the system integrity, or "locking" the SMRAM, such that the settings cannot be - perturbed by either boot service or runtime agents + - Preserving the system integrity, or "locking" the SMRAM, such that the settings cannot be + perturbed by either boot service or runtime agents - Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef _SMM_ACCESS2_H_ #define _SMM_ACCESS2_H_ -#define EFI_SMM_ACCESS2_PROTOCOL_GUID \ - { \ - 0xc2702b74, 0x800c, 0x4131, {0x87, 0x46, 0x8f, 0xb5, 0xb8, 0x9c, 0xe4, 0xac } \ - } - - -typedef struct _EFI_SMM_ACCESS2_PROTOCOL EFI_SMM_ACCESS2_PROTOCOL; - -/** - Opens the SMRAM area to be accessible by a boot-service driver. - - This function "opens" SMRAM so that it is visible while not inside of SMM. The function should - return EFI_UNSUPPORTED if the hardware does not support hiding of SMRAM. The function - should return EFI_DEVICE_ERROR if the SMRAM configuration is locked. - - @param[in] This The EFI_SMM_ACCESS2_PROTOCOL instance. - - @retval EFI_SUCCESS The operation was successful. - @retval EFI_UNSUPPORTED The system does not support opening and closing of SMRAM. - @retval EFI_DEVICE_ERROR SMRAM cannot be opened, perhaps because it is locked. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_OPEN2)( - IN EFI_SMM_ACCESS2_PROTOCOL *This - ); - -/** - Inhibits access to the SMRAM. +#include <Protocol/MmAccess.h> - This function "closes" SMRAM so that it is not visible while outside of SMM. The function should - return EFI_UNSUPPORTED if the hardware does not support hiding of SMRAM. +#define EFI_SMM_ACCESS2_PROTOCOL_GUID EFI_MM_ACCESS_PROTOCOL_GUID - @param[in] This The EFI_SMM_ACCESS2_PROTOCOL instance. +typedef EFI_MM_ACCESS_PROTOCOL EFI_SMM_ACCESS2_PROTOCOL; - @retval EFI_SUCCESS The operation was successful. - @retval EFI_UNSUPPORTED The system does not support opening and closing of SMRAM. - @retval EFI_DEVICE_ERROR SMRAM cannot be closed. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_CLOSE2)( - IN EFI_SMM_ACCESS2_PROTOCOL *This - ); - -/** - Inhibits access to the SMRAM. - - This function prohibits access to the SMRAM region. This function is usually implemented such - that it is a write-once operation. +typedef EFI_MM_OPEN EFI_SMM_OPEN2; - @param[in] This The EFI_SMM_ACCESS2_PROTOCOL instance. - - @retval EFI_SUCCESS The device was successfully locked. - @retval EFI_UNSUPPORTED The system does not support locking of SMRAM. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_LOCK2)( - IN EFI_SMM_ACCESS2_PROTOCOL *This - ); - -/** - Queries the memory controller for the possible regions that will support SMRAM. - - @param[in] This The EFI_SMM_ACCESS2_PROTOCOL instance. - @param[in,out] SmramMapSize A pointer to the size, in bytes, of the SmramMemoryMap buffer. - @param[in,out] SmramMap A pointer to the buffer in which firmware places the current memory map. - - @retval EFI_SUCCESS The chipset supported the given resource. - @retval EFI_BUFFER_TOO_SMALL The SmramMap parameter was too small. The current buffer size - needed to hold the memory map is returned in SmramMapSize. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_CAPABILITIES2)( - IN CONST EFI_SMM_ACCESS2_PROTOCOL *This, - IN OUT UINTN *SmramMapSize, - IN OUT EFI_SMRAM_DESCRIPTOR *SmramMap - ); +typedef EFI_MM_CLOSE EFI_SMM_CLOSE2; -/// -/// EFI SMM Access2 Protocol is used to control the visibility of the SMRAM on the platform. -/// It abstracts the location and characteristics of SMRAM. The expectation is -/// that the north bridge or memory controller would publish this protocol. -/// -struct _EFI_SMM_ACCESS2_PROTOCOL { - EFI_SMM_OPEN2 Open; - EFI_SMM_CLOSE2 Close; - EFI_SMM_LOCK2 Lock; - EFI_SMM_CAPABILITIES2 GetCapabilities; - /// - /// Indicates the current state of the SMRAM. Set to TRUE if SMRAM is locked. - /// - BOOLEAN LockState; - /// - /// Indicates the current state of the SMRAM. Set to TRUE if SMRAM is open. - /// - BOOLEAN OpenState; -}; +typedef EFI_MM_LOCK EFI_SMM_LOCK2; +typedef EFI_MM_CAPABILITIES EFI_SMM_CAPABILITIES2; extern EFI_GUID gEfiSmmAccess2ProtocolGuid; #endif diff --git a/MdePkg/Include/Protocol/SmmBase2.h b/MdePkg/Include/Protocol/SmmBase2.h index 3a1947c43870..492f4001221d 100644 --- a/MdePkg/Include/Protocol/SmmBase2.h +++ b/MdePkg/Include/Protocol/SmmBase2.h @@ -4,14 +4,8 @@ This protocol is utilized by all SMM drivers to locate the SMM infrastructure services and determine whether the driver is being invoked inside SMRAM or outside of SMRAM. - Copyright (c) 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -19,23 +13,21 @@ #define _SMM_BASE2_H_ #include <Pi/PiSmmCis.h> +#include <Protocol/MmBase.h> -#define EFI_SMM_BASE2_PROTOCOL_GUID \ - { \ - 0xf4ccbfb7, 0xf6e0, 0x47fd, {0x9d, 0xd4, 0x10, 0xa8, 0xf1, 0x50, 0xc1, 0x91 } \ - } +#define EFI_SMM_BASE2_PROTOCOL_GUID EFI_MM_BASE_PROTOCOL_GUID typedef struct _EFI_SMM_BASE2_PROTOCOL EFI_SMM_BASE2_PROTOCOL; /** Service to indicate whether the driver is currently executing in the SMM Initialization phase. - - This service is used to indicate whether the driver is currently executing in the SMM Initialization - phase. For SMM drivers, this will return TRUE in InSmram while inside the driver's entry point and + + This service is used to indicate whether the driver is currently executing in the SMM Initialization + phase. For SMM drivers, this will return TRUE in InSmram while inside the driver's entry point and otherwise FALSE. For combination SMM/DXE drivers, this will return FALSE in the DXE launch. For the SMM launch, it behaves as an SMM driver. - @param[in] This The EFI_SMM_BASE2_PROTOCOL instance. + @param[in] This The EFI_SMM_BASE2_PROTOCOL instance. @param[out] InSmram Pointer to a Boolean which, on return, indicates that the driver is currently executing inside of SMRAM (TRUE) or outside of SMRAM (FALSE). @@ -53,8 +45,8 @@ EFI_STATUS /** Returns the location of the System Management Service Table (SMST). - This function returns the location of the System Management Service Table (SMST). The use of the - API is such that a driver can discover the location of the SMST in its entry point and then cache it in + This function returns the location of the System Management Service Table (SMST). The use of the + API is such that a driver can discover the location of the SMST in its entry point and then cache it in some driver global variable so that the SMST can be invoked in subsequent handlers. @param[in] This The EFI_SMM_BASE2_PROTOCOL instance. diff --git a/MdePkg/Include/Protocol/SmmCommunication.h b/MdePkg/Include/Protocol/SmmCommunication.h index acd7a27d6ec5..13b0d29e4b59 100644 --- a/MdePkg/Include/Protocol/SmmCommunication.h +++ b/MdePkg/Include/Protocol/SmmCommunication.h @@ -1,63 +1,25 @@ /** @file EFI SMM Communication Protocol as defined in the PI 1.2 specification. - This protocol provides a means of communicating between drivers outside of SMM and SMI - handlers inside of SMM. + This protocol provides a means of communicating between drivers outside of SMM and SMI + handlers inside of SMM. - Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef _SMM_COMMUNICATION_H_ #define _SMM_COMMUNICATION_H_ -// -// Need include this header file for EFI_SMM_COMMUNICATE_HEADER data structure. -// -#include <Uefi/UefiAcpiDataTable.h> - -#define EFI_SMM_COMMUNICATION_PROTOCOL_GUID \ - { \ - 0xc68ed8e2, 0x9dc6, 0x4cbd, { 0x9d, 0x94, 0xdb, 0x65, 0xac, 0xc5, 0xc3, 0x32 } \ - } +#include <Protocol/MmCommunication.h> -typedef struct _EFI_SMM_COMMUNICATION_PROTOCOL EFI_SMM_COMMUNICATION_PROTOCOL; -/** - Communicates with a registered handler. - - This function provides a service to send and receive messages from a registered UEFI service. +typedef EFI_MM_COMMUNICATE_HEADER EFI_SMM_COMMUNICATE_HEADER; - @param[in] This The EFI_SMM_COMMUNICATION_PROTOCOL instance. - @param[in] CommBuffer A pointer to the buffer to convey into SMRAM. - @param[in] CommSize The size of the data buffer being passed in.On exit, the size of data - being returned. Zero if the handler does not wish to reply with any data. - - @retval EFI_SUCCESS The message was successfully posted. - @retval EFI_INVALID_PARAMETER The CommBuffer was NULL. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_COMMUNICATE2)( - IN CONST EFI_SMM_COMMUNICATION_PROTOCOL *This, - IN OUT VOID *CommBuffer, - IN OUT UINTN *CommSize - ); +#define EFI_SMM_COMMUNICATION_PROTOCOL_GUID EFI_MM_COMMUNICATION_PROTOCOL_GUID -/// -/// EFI SMM Communication Protocol provides runtime services for communicating -/// between DXE drivers and a registered SMI handler. -/// -struct _EFI_SMM_COMMUNICATION_PROTOCOL { - EFI_SMM_COMMUNICATE2 Communicate; -}; +typedef EFI_MM_COMMUNICATION_PROTOCOL EFI_SMM_COMMUNICATION_PROTOCOL; extern EFI_GUID gEfiSmmCommunicationProtocolGuid; diff --git a/MdePkg/Include/Protocol/SmmConfiguration.h b/MdePkg/Include/Protocol/SmmConfiguration.h index f138fde877ee..af6d380947ca 100644 --- a/MdePkg/Include/Protocol/SmmConfiguration.h +++ b/MdePkg/Include/Protocol/SmmConfiguration.h @@ -5,39 +5,31 @@ 1) report the portions of SMRAM regions which cannot be used for the SMRAM heap. 2) register the SMM Foundation entry point with the processor code. The entry point will be invoked by the SMM processor entry code. - - Copyright (c) 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef _SMM_CONFIGURATION_H_ #define _SMM_CONFIGURATION_H_ +#include <Protocol/MmConfiguration.h> #include <Pi/PiSmmCis.h> -#define EFI_SMM_CONFIGURATION_PROTOCOL_GUID \ - { \ - 0x26eeb3de, 0xb689, 0x492e, {0x80, 0xf0, 0xbe, 0x8b, 0xd7, 0xda, 0x4b, 0xa7 } \ - } +#define EFI_SMM_CONFIGURATION_PROTOCOL_GUID EFI_MM_CONFIGURATION_PROTOCOL_GUID /// /// Structure describing a SMRAM region which cannot be used for the SMRAM heap. /// typedef struct _EFI_SMM_RESERVED_SMRAM_REGION { /// - /// Starting address of the reserved SMRAM area, as it appears while SMRAM is open. + /// Starting address of the reserved SMRAM area, as it appears while SMRAM is open. /// Ignored if SmramReservedSize is 0. /// EFI_PHYSICAL_ADDRESS SmramReservedStart; /// - /// Number of bytes occupied by the reserved SMRAM area. A size of zero indicates the + /// Number of bytes occupied by the reserved SMRAM area. A size of zero indicates the /// last SMRAM area. /// UINT64 SmramReservedSize; @@ -47,13 +39,13 @@ typedef struct _EFI_SMM_CONFIGURATION_PROTOCOL EFI_SMM_CONFIGURATION_PROTOCOL; /** Register the SMM Foundation entry point. - - This function registers the SMM Foundation entry point with the processor code. This entry point + + This function registers the SMM Foundation entry point with the processor code. This entry point will be invoked by the SMM Processor entry code. @param[in] This The EFI_SMM_CONFIGURATION_PROTOCOL instance. @param[in] SmmEntryPoint SMM Foundation entry point. - + @retval EFI_SUCCESS Success to register SMM Entry Point. @retval EFI_INVALID_PARAMETER SmmEntryPoint is NULL. **/ @@ -66,10 +58,10 @@ EFI_STATUS /// /// The EFI SMM Configuration Protocol is a mandatory protocol published by a DXE CPU driver to -/// indicate which areas within SMRAM are reserved for use by the CPU for any purpose, +/// indicate which areas within SMRAM are reserved for use by the CPU for any purpose, /// such as stack, save state or SMM entry point. /// -/// The RegisterSmmEntry() function allows the SMM IPL DXE driver to register the SMM +/// The RegisterSmmEntry() function allows the SMM IPL DXE driver to register the SMM /// Foundation entry point with the SMM entry vector code. /// struct _EFI_SMM_CONFIGURATION_PROTOCOL { diff --git a/MdePkg/Include/Protocol/SmmControl2.h b/MdePkg/Include/Protocol/SmmControl2.h index 5908fef945a4..d75efeed4297 100644 --- a/MdePkg/Include/Protocol/SmmControl2.h +++ b/MdePkg/Include/Protocol/SmmControl2.h @@ -3,103 +3,32 @@ This protocol is used initiate synchronous SMI activations. This protocol could be published by a processor driver to abstract the SMI IPI or a driver which abstracts the ASIC that is supporting the - APM port. Because of the possibility of performing SMI IPI transactions, the ability to generate this + APM port. Because of the possibility of performing SMI IPI transactions, the ability to generate this event from a platform chipset agent is an optional capability for both IA-32 and x64-based systems. - The EFI_SMM_CONTROL2_PROTOCOL is produced by a runtime driver. It provides an - abstraction of the platform hardware that generates an SMI. There are often I/O ports that, when - accessed, will generate the SMI. Also, the hardware optionally supports the periodic generation of + The EFI_SMM_CONTROL2_PROTOCOL is produced by a runtime driver. It provides an + abstraction of the platform hardware that generates an SMI. There are often I/O ports that, when + accessed, will generate the SMI. Also, the hardware optionally supports the periodic generation of these signals. - Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef _SMM_CONTROL2_H_ #define _SMM_CONTROL2_H_ -#include <PiDxe.h> - -#define EFI_SMM_CONTROL2_PROTOCOL_GUID \ - { \ - 0x843dc720, 0xab1e, 0x42cb, {0x93, 0x57, 0x8a, 0x0, 0x78, 0xf3, 0x56, 0x1b} \ - } - -typedef struct _EFI_SMM_CONTROL2_PROTOCOL EFI_SMM_CONTROL2_PROTOCOL; -typedef UINTN EFI_SMM_PERIOD; +#include <Protocol/MmControl.h> -/** - Invokes SMI activation from either the preboot or runtime environment. +#define EFI_SMM_CONTROL2_PROTOCOL_GUID EFI_MM_CONTROL_PROTOCOL_GUID - This function generates an SMI. - - @param[in] This The EFI_SMM_CONTROL2_PROTOCOL instance. - @param[in,out] CommandPort The value written to the command port. - @param[in,out] DataPort The value written to the data port. - @param[in] Periodic Optional mechanism to engender a periodic stream. - @param[in] ActivationInterval Optional parameter to repeat at this period one - time or, if the Periodic Boolean is set, periodically. - - @retval EFI_SUCCESS The SMI/PMI has been engendered. - @retval EFI_DEVICE_ERROR The timing is unsupported. - @retval EFI_INVALID_PARAMETER The activation period is unsupported. - @retval EFI_INVALID_PARAMETER The last periodic activation has not been cleared. - @retval EFI_NOT_STARTED The SMM base service has not been initialized. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_ACTIVATE2)( - IN CONST EFI_SMM_CONTROL2_PROTOCOL *This, - IN OUT UINT8 *CommandPort OPTIONAL, - IN OUT UINT8 *DataPort OPTIONAL, - IN BOOLEAN Periodic OPTIONAL, - IN UINTN ActivationInterval OPTIONAL - ); - -/** - Clears any system state that was created in response to the Trigger() call. - - This function acknowledges and causes the deassertion of the SMI activation source. - - @param[in] This The EFI_SMM_CONTROL2_PROTOCOL instance. - @param[in] Periodic Optional parameter to repeat at this period one time - - @retval EFI_SUCCESS The SMI/PMI has been engendered. - @retval EFI_DEVICE_ERROR The source could not be cleared. - @retval EFI_INVALID_PARAMETER The service did not support the Periodic input argument. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_DEACTIVATE2)( - IN CONST EFI_SMM_CONTROL2_PROTOCOL *This, - IN BOOLEAN Periodic OPTIONAL - ); +typedef EFI_MM_CONTROL_PROTOCOL EFI_SMM_CONTROL2_PROTOCOL; +typedef EFI_MM_PERIOD EFI_SMM_PERIOD; -/// -/// The EFI_SMM_CONTROL2_PROTOCOL is produced by a runtime driver. It provides an -/// abstraction of the platform hardware that generates an SMI. There are often I/O ports that, when -/// accessed, will generate the SMI. Also, the hardware optionally supports the periodic generation of -/// these signals. -/// -struct _EFI_SMM_CONTROL2_PROTOCOL { - EFI_SMM_ACTIVATE2 Trigger; - EFI_SMM_DEACTIVATE2 Clear; - /// - /// Minimum interval at which the platform can set the period. A maximum is not - /// specified in that the SMM infrastructure code can emulate a maximum interval that is - /// greater than the hardware capabilities by using software emulation in the SMM - /// infrastructure code. - /// - EFI_SMM_PERIOD MinimumTriggerPeriod; -}; +typedef EFI_MM_ACTIVATE EFI_SMM_ACTIVATE2; +typedef EFI_MM_DEACTIVATE EFI_SMM_DEACTIVATE2; extern EFI_GUID gEfiSmmControl2ProtocolGuid; #endif diff --git a/MdePkg/Include/Protocol/SmmCpu.h b/MdePkg/Include/Protocol/SmmCpu.h index 9990dd25adfa..62144fd55fe8 100644 --- a/MdePkg/Include/Protocol/SmmCpu.h +++ b/MdePkg/Include/Protocol/SmmCpu.h @@ -1,246 +1,129 @@ /** @file EFI SMM CPU Protocol as defined in the PI 1.2 specification. - This protocol allows SMM drivers to access architecture-standard registers from any of the CPU - save state areas. In some cases, difference processors provide the same information in the save state, - but not in the same format. These so-called pseudo-registers provide this information in a standard - format. + This protocol allows SMM drivers to access architecture-standard registers from any of the CPU + save state areas. In some cases, difference processors provide the same information in the save state, + but not in the same format. These so-called pseudo-registers provide this information in a standard + format. - Copyright (c) 2009 - 2012, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef _SMM_CPU_H_ #define _SMM_CPU_H_ -#define EFI_SMM_CPU_PROTOCOL_GUID \ - { \ - 0xeb346b97, 0x975f, 0x4a9f, { 0x8b, 0x22, 0xf8, 0xe9, 0x2b, 0xb3, 0xd5, 0x69 } \ - } - -/// -/// Save State register index -/// -typedef enum { - /// - /// x86/X64 standard registers - /// - EFI_SMM_SAVE_STATE_REGISTER_GDTBASE = 4, - EFI_SMM_SAVE_STATE_REGISTER_IDTBASE = 5, - EFI_SMM_SAVE_STATE_REGISTER_LDTBASE = 6, - EFI_SMM_SAVE_STATE_REGISTER_GDTLIMIT = 7, - EFI_SMM_SAVE_STATE_REGISTER_IDTLIMIT = 8, - EFI_SMM_SAVE_STATE_REGISTER_LDTLIMIT = 9, - EFI_SMM_SAVE_STATE_REGISTER_LDTINFO = 10, - EFI_SMM_SAVE_STATE_REGISTER_ES = 20, - EFI_SMM_SAVE_STATE_REGISTER_CS = 21, - EFI_SMM_SAVE_STATE_REGISTER_SS = 22, - EFI_SMM_SAVE_STATE_REGISTER_DS = 23, - EFI_SMM_SAVE_STATE_REGISTER_FS = 24, - EFI_SMM_SAVE_STATE_REGISTER_GS = 25, - EFI_SMM_SAVE_STATE_REGISTER_LDTR_SEL = 26, - EFI_SMM_SAVE_STATE_REGISTER_TR_SEL = 27, - EFI_SMM_SAVE_STATE_REGISTER_DR7 = 28, - EFI_SMM_SAVE_STATE_REGISTER_DR6 = 29, - EFI_SMM_SAVE_STATE_REGISTER_R8 = 30, - EFI_SMM_SAVE_STATE_REGISTER_R9 = 31, - EFI_SMM_SAVE_STATE_REGISTER_R10 = 32, - EFI_SMM_SAVE_STATE_REGISTER_R11 = 33, - EFI_SMM_SAVE_STATE_REGISTER_R12 = 34, - EFI_SMM_SAVE_STATE_REGISTER_R13 = 35, - EFI_SMM_SAVE_STATE_REGISTER_R14 = 36, - EFI_SMM_SAVE_STATE_REGISTER_R15 = 37, - EFI_SMM_SAVE_STATE_REGISTER_RAX = 38, - EFI_SMM_SAVE_STATE_REGISTER_RBX = 39, - EFI_SMM_SAVE_STATE_REGISTER_RCX = 40, - EFI_SMM_SAVE_STATE_REGISTER_RDX = 41, - EFI_SMM_SAVE_STATE_REGISTER_RSP = 42, - EFI_SMM_SAVE_STATE_REGISTER_RBP = 43, - EFI_SMM_SAVE_STATE_REGISTER_RSI = 44, - EFI_SMM_SAVE_STATE_REGISTER_RDI = 45, - EFI_SMM_SAVE_STATE_REGISTER_RIP = 46, - EFI_SMM_SAVE_STATE_REGISTER_RFLAGS = 51, - EFI_SMM_SAVE_STATE_REGISTER_CR0 = 52, - EFI_SMM_SAVE_STATE_REGISTER_CR3 = 53, - EFI_SMM_SAVE_STATE_REGISTER_CR4 = 54, - EFI_SMM_SAVE_STATE_REGISTER_FCW = 256, - EFI_SMM_SAVE_STATE_REGISTER_FSW = 257, - EFI_SMM_SAVE_STATE_REGISTER_FTW = 258, - EFI_SMM_SAVE_STATE_REGISTER_OPCODE = 259, - EFI_SMM_SAVE_STATE_REGISTER_FP_EIP = 260, - EFI_SMM_SAVE_STATE_REGISTER_FP_CS = 261, - EFI_SMM_SAVE_STATE_REGISTER_DATAOFFSET = 262, - EFI_SMM_SAVE_STATE_REGISTER_FP_DS = 263, - EFI_SMM_SAVE_STATE_REGISTER_MM0 = 264, - EFI_SMM_SAVE_STATE_REGISTER_MM1 = 265, - EFI_SMM_SAVE_STATE_REGISTER_MM2 = 266, - EFI_SMM_SAVE_STATE_REGISTER_MM3 = 267, - EFI_SMM_SAVE_STATE_REGISTER_MM4 = 268, - EFI_SMM_SAVE_STATE_REGISTER_MM5 = 269, - EFI_SMM_SAVE_STATE_REGISTER_MM6 = 270, - EFI_SMM_SAVE_STATE_REGISTER_MM7 = 271, - EFI_SMM_SAVE_STATE_REGISTER_XMM0 = 272, - EFI_SMM_SAVE_STATE_REGISTER_XMM1 = 273, - EFI_SMM_SAVE_STATE_REGISTER_XMM2 = 274, - EFI_SMM_SAVE_STATE_REGISTER_XMM3 = 275, - EFI_SMM_SAVE_STATE_REGISTER_XMM4 = 276, - EFI_SMM_SAVE_STATE_REGISTER_XMM5 = 277, - EFI_SMM_SAVE_STATE_REGISTER_XMM6 = 278, - EFI_SMM_SAVE_STATE_REGISTER_XMM7 = 279, - EFI_SMM_SAVE_STATE_REGISTER_XMM8 = 280, - EFI_SMM_SAVE_STATE_REGISTER_XMM9 = 281, - EFI_SMM_SAVE_STATE_REGISTER_XMM10 = 282, - EFI_SMM_SAVE_STATE_REGISTER_XMM11 = 283, - EFI_SMM_SAVE_STATE_REGISTER_XMM12 = 284, - EFI_SMM_SAVE_STATE_REGISTER_XMM13 = 285, - EFI_SMM_SAVE_STATE_REGISTER_XMM14 = 286, - EFI_SMM_SAVE_STATE_REGISTER_XMM15 = 287, - /// - /// Pseudo-Registers - /// - EFI_SMM_SAVE_STATE_REGISTER_IO = 512, - EFI_SMM_SAVE_STATE_REGISTER_LMA = 513, - EFI_SMM_SAVE_STATE_REGISTER_PROCESSOR_ID = 514 -} EFI_SMM_SAVE_STATE_REGISTER; +#include <Protocol/MmCpu.h> + +#define EFI_SMM_CPU_PROTOCOL_GUID EFI_MM_CPU_PROTOCOL_GUID + +#define EFI_SMM_SAVE_STATE_REGISTER_GDTBASE EFI_MM_SAVE_STATE_REGISTER_GDTBASE +#define EFI_SMM_SAVE_STATE_REGISTER_IDTBASE EFI_MM_SAVE_STATE_REGISTER_IDTBASE +#define EFI_SMM_SAVE_STATE_REGISTER_LDTBASE EFI_MM_SAVE_STATE_REGISTER_LDTBASE +#define EFI_SMM_SAVE_STATE_REGISTER_GDTLIMIT EFI_MM_SAVE_STATE_REGISTER_GDTLIMIT +#define EFI_SMM_SAVE_STATE_REGISTER_IDTLIMIT EFI_MM_SAVE_STATE_REGISTER_IDTLIMIT +#define EFI_SMM_SAVE_STATE_REGISTER_LDTLIMIT EFI_MM_SAVE_STATE_REGISTER_LDTLIMIT +#define EFI_SMM_SAVE_STATE_REGISTER_LDTINFO EFI_MM_SAVE_STATE_REGISTER_LDTINFO +#define EFI_SMM_SAVE_STATE_REGISTER_ES EFI_MM_SAVE_STATE_REGISTER_ES +#define EFI_SMM_SAVE_STATE_REGISTER_CS EFI_MM_SAVE_STATE_REGISTER_CS +#define EFI_SMM_SAVE_STATE_REGISTER_SS EFI_MM_SAVE_STATE_REGISTER_SS +#define EFI_SMM_SAVE_STATE_REGISTER_DS EFI_MM_SAVE_STATE_REGISTER_DS +#define EFI_SMM_SAVE_STATE_REGISTER_FS EFI_MM_SAVE_STATE_REGISTER_FS +#define EFI_SMM_SAVE_STATE_REGISTER_GS EFI_MM_SAVE_STATE_REGISTER_GS +#define EFI_SMM_SAVE_STATE_REGISTER_LDTR_SEL EFI_MM_SAVE_STATE_REGISTER_LDTR_SEL +#define EFI_SMM_SAVE_STATE_REGISTER_TR_SEL EFI_MM_SAVE_STATE_REGISTER_TR_SEL +#define EFI_SMM_SAVE_STATE_REGISTER_DR7 EFI_MM_SAVE_STATE_REGISTER_DR7 +#define EFI_SMM_SAVE_STATE_REGISTER_DR6 EFI_MM_SAVE_STATE_REGISTER_DR6 +#define EFI_SMM_SAVE_STATE_REGISTER_R8 EFI_MM_SAVE_STATE_REGISTER_R8 +#define EFI_SMM_SAVE_STATE_REGISTER_R9 EFI_MM_SAVE_STATE_REGISTER_R9 +#define EFI_SMM_SAVE_STATE_REGISTER_R10 EFI_MM_SAVE_STATE_REGISTER_R10 +#define EFI_SMM_SAVE_STATE_REGISTER_R11 EFI_MM_SAVE_STATE_REGISTER_R11 +#define EFI_SMM_SAVE_STATE_REGISTER_R12 EFI_MM_SAVE_STATE_REGISTER_R12 +#define EFI_SMM_SAVE_STATE_REGISTER_R13 EFI_MM_SAVE_STATE_REGISTER_R13 +#define EFI_SMM_SAVE_STATE_REGISTER_R14 EFI_MM_SAVE_STATE_REGISTER_R14 +#define EFI_SMM_SAVE_STATE_REGISTER_R15 EFI_MM_SAVE_STATE_REGISTER_R15 +#define EFI_SMM_SAVE_STATE_REGISTER_RAX EFI_MM_SAVE_STATE_REGISTER_RAX +#define EFI_SMM_SAVE_STATE_REGISTER_RBX EFI_MM_SAVE_STATE_REGISTER_RBX +#define EFI_SMM_SAVE_STATE_REGISTER_RCX EFI_MM_SAVE_STATE_REGISTER_RCX +#define EFI_SMM_SAVE_STATE_REGISTER_RDX EFI_MM_SAVE_STATE_REGISTER_RDX +#define EFI_SMM_SAVE_STATE_REGISTER_RSP EFI_MM_SAVE_STATE_REGISTER_RSP +#define EFI_SMM_SAVE_STATE_REGISTER_RBP EFI_MM_SAVE_STATE_REGISTER_RBP +#define EFI_SMM_SAVE_STATE_REGISTER_RSI EFI_MM_SAVE_STATE_REGISTER_RSI +#define EFI_SMM_SAVE_STATE_REGISTER_RDI EFI_MM_SAVE_STATE_REGISTER_RDI +#define EFI_SMM_SAVE_STATE_REGISTER_RIP EFI_MM_SAVE_STATE_REGISTER_RIP +#define EFI_SMM_SAVE_STATE_REGISTER_RFLAGS EFI_MM_SAVE_STATE_REGISTER_RFLAGS +#define EFI_SMM_SAVE_STATE_REGISTER_CR0 EFI_MM_SAVE_STATE_REGISTER_CR0 +#define EFI_SMM_SAVE_STATE_REGISTER_CR3 EFI_MM_SAVE_STATE_REGISTER_CR3 +#define EFI_SMM_SAVE_STATE_REGISTER_CR4 EFI_MM_SAVE_STATE_REGISTER_CR4 +#define EFI_SMM_SAVE_STATE_REGISTER_FCW EFI_MM_SAVE_STATE_REGISTER_FCW +#define EFI_SMM_SAVE_STATE_REGISTER_FSW EFI_MM_SAVE_STATE_REGISTER_FSW +#define EFI_SMM_SAVE_STATE_REGISTER_FTW EFI_MM_SAVE_STATE_REGISTER_FTW +#define EFI_SMM_SAVE_STATE_REGISTER_OPCODE EFI_MM_SAVE_STATE_REGISTER_OPCODE +#define EFI_SMM_SAVE_STATE_REGISTER_FP_EIP EFI_MM_SAVE_STATE_REGISTER_FP_EIP +#define EFI_SMM_SAVE_STATE_REGISTER_FP_CS EFI_MM_SAVE_STATE_REGISTER_FP_CS +#define EFI_SMM_SAVE_STATE_REGISTER_DATAOFFSET EFI_MM_SAVE_STATE_REGISTER_DATAOFFSET +#define EFI_SMM_SAVE_STATE_REGISTER_FP_DS EFI_MM_SAVE_STATE_REGISTER_FP_DS +#define EFI_SMM_SAVE_STATE_REGISTER_MM0 EFI_MM_SAVE_STATE_REGISTER_MM0 +#define EFI_SMM_SAVE_STATE_REGISTER_MM1 EFI_MM_SAVE_STATE_REGISTER_MM1 +#define EFI_SMM_SAVE_STATE_REGISTER_MM2 EFI_MM_SAVE_STATE_REGISTER_MM2 +#define EFI_SMM_SAVE_STATE_REGISTER_MM3 EFI_MM_SAVE_STATE_REGISTER_MM3 +#define EFI_SMM_SAVE_STATE_REGISTER_MM4 EFI_MM_SAVE_STATE_REGISTER_MM4 +#define EFI_SMM_SAVE_STATE_REGISTER_MM5 EFI_MM_SAVE_STATE_REGISTER_MM5 +#define EFI_SMM_SAVE_STATE_REGISTER_MM6 EFI_MM_SAVE_STATE_REGISTER_MM6 +#define EFI_SMM_SAVE_STATE_REGISTER_MM7 EFI_MM_SAVE_STATE_REGISTER_MM7 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM0 EFI_MM_SAVE_STATE_REGISTER_XMM0 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM1 EFI_MM_SAVE_STATE_REGISTER_XMM1 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM2 EFI_MM_SAVE_STATE_REGISTER_XMM2 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM3 EFI_MM_SAVE_STATE_REGISTER_XMM3 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM4 EFI_MM_SAVE_STATE_REGISTER_XMM4 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM5 EFI_MM_SAVE_STATE_REGISTER_XMM5 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM6 EFI_MM_SAVE_STATE_REGISTER_XMM6 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM7 EFI_MM_SAVE_STATE_REGISTER_XMM7 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM8 EFI_MM_SAVE_STATE_REGISTER_XMM8 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM9 EFI_MM_SAVE_STATE_REGISTER_XMM9 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM10 EFI_MM_SAVE_STATE_REGISTER_XMM10 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM11 EFI_MM_SAVE_STATE_REGISTER_XMM11 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM12 EFI_MM_SAVE_STATE_REGISTER_XMM12 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM13 EFI_MM_SAVE_STATE_REGISTER_XMM13 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM14 EFI_MM_SAVE_STATE_REGISTER_XMM14 +#define EFI_SMM_SAVE_STATE_REGISTER_XMM15 EFI_MM_SAVE_STATE_REGISTER_XMM15 +#define EFI_SMM_SAVE_STATE_REGISTER_IO EFI_MM_SAVE_STATE_REGISTER_IO +#define EFI_SMM_SAVE_STATE_REGISTER_LMA EFI_MM_SAVE_STATE_REGISTER_LMA +#define EFI_SMM_SAVE_STATE_REGISTER_PROCESSOR_ID EFI_MM_SAVE_STATE_REGISTER_PROCESSOR_ID + +typedef EFI_MM_SAVE_STATE_REGISTER EFI_SMM_SAVE_STATE_REGISTER; + + +#define EFI_SMM_SAVE_STATE_REGISTER_LMA_32BIT EFI_MM_SAVE_STATE_REGISTER_LMA_32BIT +#define EFI_SMM_SAVE_STATE_REGISTER_LMA_64BIT EFI_MM_SAVE_STATE_REGISTER_LMA_64BIT -/// -/// The EFI_SMM_SAVE_STATE_REGISTER_LMA pseudo-register values -/// If the processor acts in 32-bit mode at the time the SMI occurred, the pseudo register value -/// EFI_SMM_SAVE_STATE_REGISTER_LMA_32BIT is returned in Buffer. Otherwise, -/// EFI_SMM_SAVE_STATE_REGISTER_LMA_64BIT is returned in Buffer. -/// -#define EFI_SMM_SAVE_STATE_REGISTER_LMA_32BIT 32 -#define EFI_SMM_SAVE_STATE_REGISTER_LMA_64BIT 64 /// /// Size width of I/O instruction /// -typedef enum { - EFI_SMM_SAVE_STATE_IO_WIDTH_UINT8 = 0, - EFI_SMM_SAVE_STATE_IO_WIDTH_UINT16 = 1, - EFI_SMM_SAVE_STATE_IO_WIDTH_UINT32 = 2, - EFI_SMM_SAVE_STATE_IO_WIDTH_UINT64 = 3 -} EFI_SMM_SAVE_STATE_IO_WIDTH; +#define EFI_SMM_SAVE_STATE_IO_WIDTH_UINT8 EFI_MM_SAVE_STATE_IO_WIDTH_UINT8 +#define EFI_SMM_SAVE_STATE_IO_WIDTH_UINT16 EFI_MM_SAVE_STATE_IO_WIDTH_UINT16 +#define EFI_SMM_SAVE_STATE_IO_WIDTH_UINT32 EFI_MM_SAVE_STATE_IO_WIDTH_UINT32 +#define EFI_SMM_SAVE_STATE_IO_WIDTH_UINT64 EFI_MM_SAVE_STATE_IO_WIDTH_UINT64 +typedef EFI_MM_SAVE_STATE_IO_WIDTH EFI_SMM_SAVE_STATE_IO_WIDTH; /// /// Types of I/O instruction /// -typedef enum { - EFI_SMM_SAVE_STATE_IO_TYPE_INPUT = 1, - EFI_SMM_SAVE_STATE_IO_TYPE_OUTPUT = 2, - EFI_SMM_SAVE_STATE_IO_TYPE_STRING = 4, - EFI_SMM_SAVE_STATE_IO_TYPE_REP_PREFIX = 8 -} EFI_SMM_SAVE_STATE_IO_TYPE; +#define EFI_SMM_SAVE_STATE_IO_TYPE_INPUT EFI_MM_SAVE_STATE_IO_TYPE_INPUT +#define EFI_SMM_SAVE_STATE_IO_TYPE_OUTPUT EFI_MM_SAVE_STATE_IO_TYPE_OUTPUT +#define EFI_SMM_SAVE_STATE_IO_TYPE_STRING EFI_MM_SAVE_STATE_IO_TYPE_STRING +#define EFI_SMM_SAVE_STATE_IO_TYPE_REP_PREFIX EFI_MM_SAVE_STATE_IO_TYPE_REP_PREFIX +typedef EFI_MM_SAVE_STATE_IO_TYPE EFI_SMM_SAVE_STATE_IO_TYPE; -/// -/// Structure of the data which is returned when ReadSaveState() is called with -/// EFI_SMM_SAVE_STATE_REGISTER_IO. If there was no I/O then ReadSaveState() will -/// return EFI_NOT_FOUND. -/// -/// This structure describes the I/O operation which was in process when the SMI was generated. -/// -typedef struct _EFI_SMM_SAVE_STATE_IO_INFO { - /// - /// For input instruction (IN, INS), this is data read before the SMI occurred. For output - /// instructions (OUT, OUTS) this is data that was written before the SMI occurred. The - /// width of the data is specified by IoWidth. - /// - UINT64 IoData; - /// - /// The I/O port that was being accessed when the SMI was triggered. - /// - UINT16 IoPort; - /// - /// Defines the size width (UINT8, UINT16, UINT32, UINT64) for IoData. - /// - EFI_SMM_SAVE_STATE_IO_WIDTH IoWidth; - /// - /// Defines type of I/O instruction. - /// - EFI_SMM_SAVE_STATE_IO_TYPE IoType; -} EFI_SMM_SAVE_STATE_IO_INFO; - -typedef struct _EFI_SMM_CPU_PROTOCOL EFI_SMM_CPU_PROTOCOL; - -/** - Read data from the CPU save state. - - This function is used to read the specified number of bytes of the specified register from the CPU - save state of the specified CPU and place the value into the buffer. If the CPU does not support the - specified register Register, then EFI_NOT_FOUND should be returned. If the CPU does not - support the specified register width Width, then EFI_INVALID_PARAMETER is returned. - - @param[in] This The EFI_SMM_CPU_PROTOCOL instance. - @param[in] Width The number of bytes to read from the CPU save state. - @param[in] Register Specifies the CPU register to read form the save state. - @param[in] CpuIndex Specifies the zero-based index of the CPU save state. - @param[out] Buffer Upon return, this holds the CPU register value read from the save state. - - @retval EFI_SUCCESS The register was read from Save State. - @retval EFI_NOT_FOUND The register is not defined for the Save State of Processor. - @retval EFI_INVALID_PARAMETER Input parameters are not valid, for example, Processor No or register width - is not correct.This or Buffer is NULL. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_READ_SAVE_STATE)( - IN CONST EFI_SMM_CPU_PROTOCOL *This, - IN UINTN Width, - IN EFI_SMM_SAVE_STATE_REGISTER Register, - IN UINTN CpuIndex, - OUT VOID *Buffer - ); - - -/** - Write data to the CPU save state. - - This function is used to write the specified number of bytes of the specified register to the CPU save - state of the specified CPU and place the value into the buffer. If the CPU does not support the - specified register Register, then EFI_UNSUPPORTED should be returned. If the CPU does not - support the specified register width Width, then EFI_INVALID_PARAMETER is returned. - - @param[in] This The EFI_SMM_CPU_PROTOCOL instance. - @param[in] Width The number of bytes to write to the CPU save state. - @param[in] Register Specifies the CPU register to write to the save state. - @param[in] CpuIndex Specifies the zero-based index of the CPU save state. - @param[in] Buffer Upon entry, this holds the new CPU register value. - - @retval EFI_SUCCESS The register was written to Save State. - @retval EFI_NOT_FOUND The register is not defined for the Save State of Processor. - @retval EFI_INVALID_PARAMETER Input parameters are not valid. For example: - ProcessorIndex or Width is not correct. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_WRITE_SAVE_STATE)( - IN CONST EFI_SMM_CPU_PROTOCOL *This, - IN UINTN Width, - IN EFI_SMM_SAVE_STATE_REGISTER Register, - IN UINTN CpuIndex, - IN CONST VOID *Buffer - ); +typedef EFI_MM_SAVE_STATE_IO_INFO EFI_SMM_SAVE_STATE_IO_INFO; -/// -/// EFI SMM CPU Protocol provides access to CPU-related information while in SMM. -/// -/// This protocol allows SMM drivers to access architecture-standard registers from any of the CPU -/// save state areas. In some cases, difference processors provide the same information in the save state, -/// but not in the same format. These so-called pseudo-registers provide this information in a standard -/// format. -/// -struct _EFI_SMM_CPU_PROTOCOL { - EFI_SMM_READ_SAVE_STATE ReadSaveState; - EFI_SMM_WRITE_SAVE_STATE WriteSaveState; -}; +typedef EFI_MM_CPU_PROTOCOL EFI_SMM_CPU_PROTOCOL; + +typedef EFI_MM_READ_SAVE_STATE EFI_SMM_READ_SAVE_STATE; +typedef EFI_MM_WRITE_SAVE_STATE EFI_SMM_WRITE_SAVE_STATE; extern EFI_GUID gEfiSmmCpuProtocolGuid; #endif diff --git a/MdePkg/Include/Protocol/SmmCpuIo2.h b/MdePkg/Include/Protocol/SmmCpuIo2.h index b580faf3cb55..b9d12bca74ef 100644 --- a/MdePkg/Include/Protocol/SmmCpuIo2.h +++ b/MdePkg/Include/Protocol/SmmCpuIo2.h @@ -3,93 +3,32 @@ This protocol provides CPU I/O and memory access within SMM. - Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef _SMM_CPU_IO2_H_ #define _SMM_CPU_IO2_H_ -#define EFI_SMM_CPU_IO2_PROTOCOL_GUID \ - { \ - 0x3242A9D8, 0xCE70, 0x4AA0, { 0x95, 0x5D, 0x5E, 0x7B, 0x14, 0x0D, 0xE4, 0xD2 } \ - } +#include <Protocol/MmCpuIo.h> + +#define EFI_SMM_CPU_IO2_PROTOCOL_GUID EFI_MM_CPU_IO_PROTOCOL_GUID -typedef struct _EFI_SMM_CPU_IO2_PROTOCOL EFI_SMM_CPU_IO2_PROTOCOL; +typedef EFI_MM_CPU_IO_PROTOCOL EFI_SMM_CPU_IO2_PROTOCOL; /// /// Width of the SMM CPU I/O operations /// -typedef enum { - SMM_IO_UINT8 = 0, - SMM_IO_UINT16 = 1, - SMM_IO_UINT32 = 2, - SMM_IO_UINT64 = 3 -} EFI_SMM_IO_WIDTH; - -/** - Provides the basic memory and I/O interfaces used toabstract accesses to devices. +#define SMM_IO_UINT8 MM_IO_UINT8 +#define SMM_IO_UINT16 MM_IO_UINT16 +#define SMM_IO_UINT32 MM_IO_UINT32 +#define SMM_IO_UINT64 MM_IO_UINT64 - The I/O operations are carried out exactly as requested. The caller is - responsible for any alignment and I/O width issues that the bus, device, - platform, or type of I/O might require. +typedef EFI_MM_IO_WIDTH EFI_SMM_IO_WIDTH; +typedef EFI_MM_CPU_IO EFI_SMM_CPU_IO2; - @param[in] This The EFI_SMM_CPU_IO2_PROTOCOL instance. - @param[in] Width Signifies the width of the I/O operations. - @param[in] Address The base address of the I/O operations. The caller is - responsible for aligning the Address if required. - @param[in] Count The number of I/O operations to perform. - @param[in,out] Buffer For read operations, the destination buffer to store - the results. For write operations, the source buffer - from which to write data. - - @retval EFI_SUCCESS The data was read from or written to the device. - @retval EFI_UNSUPPORTED The Address is not valid for this system. - @retval EFI_INVALID_PARAMETER Width or Count, or both, were invalid. - @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack - of resources. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_CPU_IO2)( - IN CONST EFI_SMM_CPU_IO2_PROTOCOL *This, - IN EFI_SMM_IO_WIDTH Width, - IN UINT64 Address, - IN UINTN Count, - IN OUT VOID *Buffer - ); - -typedef struct { - /// - /// This service provides the various modalities of memory and I/O read. - /// - EFI_SMM_CPU_IO2 Read; - /// - /// This service provides the various modalities of memory and I/O write. - /// - EFI_SMM_CPU_IO2 Write; -} EFI_SMM_IO_ACCESS2; - -/// -/// SMM CPU I/O Protocol provides CPU I/O and memory access within SMM. -/// -struct _EFI_SMM_CPU_IO2_PROTOCOL { - /// - /// Allows reads and writes to memory-mapped I/O space. - /// - EFI_SMM_IO_ACCESS2 Mem; - /// - /// Allows reads and writes to I/O space. - /// - EFI_SMM_IO_ACCESS2 Io; -}; +typedef EFI_MM_IO_ACCESS EFI_SMM_IO_ACCESS2; extern EFI_GUID gEfiSmmCpuIo2ProtocolGuid; diff --git a/MdePkg/Include/Protocol/SmmEndOfDxe.h b/MdePkg/Include/Protocol/SmmEndOfDxe.h index 3f92ffc40cc3..aa693ef3eb93 100644 --- a/MdePkg/Include/Protocol/SmmEndOfDxe.h +++ b/MdePkg/Include/Protocol/SmmEndOfDxe.h @@ -9,24 +9,17 @@ This protocol prorogates End of DXE notification into SMM environment. This protocol is installed prior to installation of the SMM Ready to Lock Protocol. - Copyright (c) 2012 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2012 - 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef _SMM_END_OF_DXE_H_ #define _SMM_END_OF_DXE_H_ -#define EFI_SMM_END_OF_DXE_PROTOCOL_GUID \ - { \ - 0x24e70042, 0xd5c5, 0x4260, { 0x8c, 0x39, 0xa, 0xd3, 0xaa, 0x32, 0xe9, 0x3d } \ - } +#include <Protocol/MmEndOfDxe.h> + +#define EFI_SMM_END_OF_DXE_PROTOCOL_GUID EFI_MM_END_OF_DXE_PROTOCOL_GUID extern EFI_GUID gEfiSmmEndOfDxeProtocolGuid; diff --git a/MdePkg/Include/Protocol/SmmGpiDispatch2.h b/MdePkg/Include/Protocol/SmmGpiDispatch2.h index da1868f446e6..2faec309f102 100644 --- a/MdePkg/Include/Protocol/SmmGpiDispatch2.h +++ b/MdePkg/Include/Protocol/SmmGpiDispatch2.h @@ -2,21 +2,15 @@ SMM General Purpose Input (GPI) Dispatch2 Protocol as defined in PI 1.1 Specification Volume 4 System Management Mode Core Interface. - This protocol provides the parent dispatch service for the General Purpose Input + This protocol provides the parent dispatch service for the General Purpose Input (GPI) SMI source generator. - The EFI_SMM_GPI_DISPATCH2_PROTOCOL provides the ability to install child handlers for the - given event types. Several inputs can be enabled. This purpose of this interface is to generate an + The EFI_SMM_GPI_DISPATCH2_PROTOCOL provides the ability to install child handlers for the + given event types. Several inputs can be enabled. This purpose of this interface is to generate an SMI in response to any of these inputs having a true value provided. - Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This protocol is from PI Version 1.1. @@ -26,98 +20,22 @@ #ifndef _SMM_GPI_DISPATCH2_H_ #define _SMM_GPI_DISPATCH2_H_ +#include <Protocol/MmGpiDispatch.h> #include <Pi/PiSmmCis.h> -#define EFI_SMM_GPI_DISPATCH2_PROTOCOL_GUID \ - { \ - 0x25566b03, 0xb577, 0x4cbf, {0x95, 0x8c, 0xed, 0x66, 0x3e, 0xa2, 0x43, 0x80 } \ - } - +#define EFI_SMM_GPI_DISPATCH2_PROTOCOL_GUID EFI_MM_GPI_DISPATCH_PROTOCOL_GUID /// /// The dispatch function's context. /// -typedef struct { - /// - /// A number from one of 2^64 possible GPIs that can generate an SMI. A - /// 0 corresponds to logical GPI[0]; 1 corresponds to logical GPI[1]; and - /// GpiNum of N corresponds to GPI[N], where N can span from 0 to 2^64-1. - /// - UINT64 GpiNum; -} EFI_SMM_GPI_REGISTER_CONTEXT; - -typedef struct _EFI_SMM_GPI_DISPATCH2_PROTOCOL EFI_SMM_GPI_DISPATCH2_PROTOCOL; - -/** - Registers a child SMI source dispatch function with a parent SMM driver. - - This service registers a function (DispatchFunction) which will be called when an SMI is - generated because of one or more of the GPIs specified by RegisterContext. On return, - DispatchHandle contains a unique handle which may be used later to unregister the function - using UnRegister(). - The DispatchFunction will be called with Context set to the same value as was passed into - this function in RegisterContext and with CommBuffer pointing to another instance of - EFI_SMM_GPI_REGISTER_CONTEXT describing the GPIs which actually caused the SMI and - CommBufferSize pointing to the size of the structure. - - @param[in] This Pointer to the EFI_SMM_GPI_DISPATCH2_PROTOCOL instance. - @param[in] DispatchFunction Function to register for handler when the specified GPI causes an SMI. - @param[in] RegisterContext Pointer to the dispatch function's context. - The caller fills this context in before calling - the register function to indicate to the register - function the GPI(s) for which the dispatch function - should be invoked. - @param[out] DispatchHandle Handle generated by the dispatcher to track the - function instance. - - @retval EFI_SUCCESS The dispatch function has been successfully - registered and the SMI source has been enabled. - @retval EFI_DEVICE_ERROR The driver was unable to enable the SMI source. - @retval EFI_INVALID_PARAMETER RegisterContext is invalid. The GPI input value - is not within valid range. - @retval EFI_OUT_OF_RESOURCES There is not enough memory (system or SMM) to manage this child. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_GPI_REGISTER2)( - IN CONST EFI_SMM_GPI_DISPATCH2_PROTOCOL *This, - IN EFI_SMM_HANDLER_ENTRY_POINT2 DispatchFunction, - IN CONST EFI_SMM_GPI_REGISTER_CONTEXT *RegisterContext, - OUT EFI_HANDLE *DispatchHandle - ); - -/** - Unregisters a General Purpose Input (GPI) service. - - This service removes the handler associated with DispatchHandle so that it will no longer be - called when the GPI triggers an SMI. - - @param[in] This Pointer to the EFI_SMM_GPI_DISPATCH2_PROTOCOL instance. - @param[in] DispatchHandle Handle of the service to remove. - - @retval EFI_SUCCESS Handle of the service to remove. - @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_GPI_UNREGISTER2)( - IN CONST EFI_SMM_GPI_DISPATCH2_PROTOCOL *This, - IN EFI_HANDLE DispatchHandle - ); +typedef EFI_MM_GPI_REGISTER_CONTEXT EFI_SMM_GPI_REGISTER_CONTEXT; + +typedef EFI_MM_GPI_REGISTER EFI_SMM_GPI_REGISTER2; + +typedef EFI_MM_GPI_UNREGISTER EFI_SMM_GPI_UNREGISTER2; + +typedef EFI_MM_GPI_DISPATCH_PROTOCOL EFI_SMM_GPI_DISPATCH2_PROTOCOL; + -/// -/// Interface structure for the SMM GPI SMI Dispatch Protocol -/// -/// The SMM GPI SMI Dispatch Protocol provides the parent dispatch service -/// for the General Purpose Input (GPI) SMI source generator. -/// -struct _EFI_SMM_GPI_DISPATCH2_PROTOCOL { - EFI_SMM_GPI_REGISTER2 Register; - EFI_SMM_GPI_UNREGISTER2 UnRegister; - /// - /// Denotes the maximum value of inputs that can have handlers attached. - /// - UINTN NumSupportedGpis; -}; extern EFI_GUID gEfiSmmGpiDispatch2ProtocolGuid; diff --git a/MdePkg/Include/Protocol/SmmIoTrapDispatch2.h b/MdePkg/Include/Protocol/SmmIoTrapDispatch2.h index f57ae522fa1b..a4aea7c6576e 100644 --- a/MdePkg/Include/Protocol/SmmIoTrapDispatch2.h +++ b/MdePkg/Include/Protocol/SmmIoTrapDispatch2.h @@ -4,14 +4,8 @@ This protocol provides a parent dispatch service for IO trap SMI sources. - Copyright (c) 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This protocol is from PI Version 1.1. @@ -21,114 +15,31 @@ #ifndef _SMM_IO_TRAP_DISPATCH2_H_ #define _SMM_IO_TRAP_DISPATCH2_H_ -#include <Pi/PiSmmCis.h> +#include <Protocol/MmIoTrapDispatch.h> -#define EFI_SMM_IO_TRAP_DISPATCH2_PROTOCOL_GUID \ - { \ - 0x58dc368d, 0x7bfa, 0x4e77, {0xab, 0xbc, 0xe, 0x29, 0x41, 0x8d, 0xf9, 0x30 } \ - } +#define EFI_SMM_IO_TRAP_DISPATCH2_PROTOCOL_GUID EFI_MM_IO_TRAP_DISPATCH_PROTOCOL_GUID /// /// IO Trap valid types /// -typedef enum { - WriteTrap, - ReadTrap, - ReadWriteTrap, - IoTrapTypeMaximum -} EFI_SMM_IO_TRAP_DISPATCH_TYPE; +typedef EFI_MM_IO_TRAP_DISPATCH_TYPE EFI_SMM_IO_TRAP_DISPATCH_TYPE; /// /// IO Trap context structure containing information about the /// IO trap event that should invoke the handler /// -typedef struct { - UINT16 Address; - UINT16 Length; - EFI_SMM_IO_TRAP_DISPATCH_TYPE Type; -} EFI_SMM_IO_TRAP_REGISTER_CONTEXT; +typedef EFI_MM_IO_TRAP_REGISTER_CONTEXT EFI_SMM_IO_TRAP_REGISTER_CONTEXT; /// /// IO Trap context structure containing information about the IO trap that occurred /// -typedef struct { - UINT32 WriteData; -} EFI_SMM_IO_TRAP_CONTEXT; - -typedef struct _EFI_SMM_IO_TRAP_DISPATCH2_PROTOCOL EFI_SMM_IO_TRAP_DISPATCH2_PROTOCOL; - -/** - Register an IO trap SMI child handler for a specified SMI. - - This service registers a function (DispatchFunction) which will be called when an SMI is - generated because of an access to an I/O port specified by RegisterContext. On return, - DispatchHandle contains a unique handle which may be used later to unregister the function - using UnRegister(). If the base of the I/O range specified is zero, then an I/O range with the - specified length and characteristics will be allocated and the Address field in RegisterContext - updated. If no range could be allocated, then EFI_OUT_OF_RESOURCES will be returned. - - The service will not perform GCD allocation if the base address is non-zero or - EFI_SMM_READY_TO_LOCK has been installed. In this case, the caller is responsible for the - existence and allocation of the specific IO range. - An error may be returned if some or all of the requested resources conflict with an existing IO trap - child handler. - - It is not required that implementations will allow multiple children for a single IO trap SMI source. - Some implementations may support multiple children. - The DispatchFunction will be called with Context updated to contain information - concerning the I/O action that actually happened and is passed in RegisterContext, with - CommBuffer pointing to the data actually written and CommBufferSize pointing to the size of - the data in CommBuffer. - - @param[in] This Pointer to the EFI_SMM_IO_TRAP_DISPATCH2_PROTOCOL instance. - @param[in] DispatchFunction Function to register for handler when I/O trap location is accessed. - @param[in] RegisterContext Pointer to the dispatch function's context. The caller fills this - context in before calling the register function to indicate to the register - function the IO trap SMI source for which the dispatch function should be invoked. - @param[out] DispatchHandle Handle of the dispatch function, for when interfacing with the parent SMM driver. - - @retval EFI_SUCCESS The dispatch function has been successfully registered. - @retval EFI_DEVICE_ERROR The driver was unable to complete due to hardware error. - @retval EFI_OUT_OF_RESOURCES Insufficient resources are available to fulfill the IO trap range request. - @retval EFI_INVALID_PARAMETER RegisterContext is invalid. The input value is not within a valid range. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_IO_TRAP_DISPATCH2_REGISTER)( - IN CONST EFI_SMM_IO_TRAP_DISPATCH2_PROTOCOL *This, - IN EFI_SMM_HANDLER_ENTRY_POINT2 DispatchFunction, - IN OUT EFI_SMM_IO_TRAP_REGISTER_CONTEXT *RegisterContext, - OUT EFI_HANDLE *DispatchHandle - ); - -/** - Unregister a child SMI source dispatch function with a parent SMM driver. - - This service removes a previously installed child dispatch handler. This does not guarantee that the - system resources will be freed from the GCD. - - @param[in] This Pointer to the EFI_SMM_IO_TRAP_DISPATCH2_PROTOCOL instance. - @param[in] DispatchHandle Handle of the child service to remove. - - @retval EFI_SUCCESS The dispatch function has been successfully unregistered. - @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_IO_TRAP_DISPATCH2_UNREGISTER)( - IN CONST EFI_SMM_IO_TRAP_DISPATCH2_PROTOCOL *This, - IN EFI_HANDLE DispatchHandle - ); +typedef EFI_MM_IO_TRAP_CONTEXT EFI_SMM_IO_TRAP_CONTEXT; -/// -/// Interface structure for the SMM IO Trap Dispatch2 Protocol. -/// -/// This protocol provides a parent dispatch service for IO trap SMI sources. -/// -struct _EFI_SMM_IO_TRAP_DISPATCH2_PROTOCOL { - EFI_SMM_IO_TRAP_DISPATCH2_REGISTER Register; - EFI_SMM_IO_TRAP_DISPATCH2_UNREGISTER UnRegister; -}; +typedef EFI_MM_IO_TRAP_DISPATCH_PROTOCOL EFI_SMM_IO_TRAP_DISPATCH2_PROTOCOL; + +typedef EFI_MM_IO_TRAP_DISPATCH_REGISTER EFI_SMM_IO_TRAP_DISPATCH2_REGISTER; + +typedef EFI_MM_IO_TRAP_DISPATCH_UNREGISTER EFI_SMM_IO_TRAP_DISPATCH2_UNREGISTER; extern EFI_GUID gEfiSmmIoTrapDispatch2ProtocolGuid; diff --git a/MdePkg/Include/Protocol/SmmPciRootBridgeIo.h b/MdePkg/Include/Protocol/SmmPciRootBridgeIo.h index 847418f73c01..02109f8fd1f2 100644 --- a/MdePkg/Include/Protocol/SmmPciRootBridgeIo.h +++ b/MdePkg/Include/Protocol/SmmPciRootBridgeIo.h @@ -3,33 +3,24 @@ This protocol provides PCI I/O and memory access within SMM. - Copyright (c) 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef _SMM_PCI_ROOT_BRIDGE_IO_H_ #define _SMM_PCI_ROOT_BRIDGE_IO_H_ -#include <Protocol/PciRootBridgeIo.h> +#include <Protocol/MmPciRootBridgeIo.h> -#define EFI_SMM_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID \ - { \ - 0x8bc1714d, 0xffcb, 0x41c3, { 0x89, 0xdc, 0x6c, 0x74, 0xd0, 0x6d, 0x98, 0xea } \ - } +#define EFI_SMM_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID EFI_MM_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID /// -/// This protocol provides the same functionality as the PCI Root Bridge I/O Protocol defined in the -/// UEFI 2.1 Specifcation, section 13.2, except that the functions for Map() and Unmap() may return +/// This protocol provides the same functionality as the PCI Root Bridge I/O Protocol defined in the +/// UEFI 2.1 Specifcation, section 13.2, except that the functions for Map() and Unmap() may return /// EFI_UNSUPPORTED. /// -typedef EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL EFI_SMM_PCI_ROOT_BRIDGE_IO_PROTOCOL; +typedef EFI_MM_PCI_ROOT_BRIDGE_IO_PROTOCOL EFI_SMM_PCI_ROOT_BRIDGE_IO_PROTOCOL; extern EFI_GUID gEfiSmmPciRootBridgeIoProtocolGuid; diff --git a/MdePkg/Include/Protocol/SmmPeriodicTimerDispatch2.h b/MdePkg/Include/Protocol/SmmPeriodicTimerDispatch2.h index d0aae046741f..a82ef427612d 100644 --- a/MdePkg/Include/Protocol/SmmPeriodicTimerDispatch2.h +++ b/MdePkg/Include/Protocol/SmmPeriodicTimerDispatch2.h @@ -4,14 +4,8 @@ This protocol provides the parent dispatch service for the periodical timer SMI source generator. - Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This protocol is from PI Version 1.1. @@ -22,11 +16,9 @@ #define _SMM_PERIODIC_TIMER_DISPATCH2_H_ #include <Pi/PiSmmCis.h> +#include <Protocol/MmPeriodicTimerDispatch.h> -#define EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL_GUID \ - { \ - 0x4cec368e, 0x8e8e, 0x4d71, {0x8b, 0xe1, 0x95, 0x8c, 0x45, 0xfc, 0x8a, 0x53 } \ - } +#define EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL_GUID EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL_GUID /// /// Example: A chipset supports periodic SMIs on every 64ms or 2 seconds. @@ -49,52 +41,46 @@ /// typedef struct { /// - /// The minimum period of time in 100 nanosecond units that the child gets called. The + /// The minimum period of time in 100 nanosecond units that the child gets called. The /// child will be called back after a time greater than the time Period. /// UINT64 Period; /// - /// The period of time interval between SMIs. Children of this interface should use this - /// field when registering for periodic timer intervals when a finer granularity periodic + /// The period of time interval between SMIs. Children of this interface should use this + /// field when registering for periodic timer intervals when a finer granularity periodic /// SMI is desired. /// UINT64 SmiTickInterval; } EFI_SMM_PERIODIC_TIMER_REGISTER_CONTEXT; /// -/// The DispatchFunction will be called with Context set to the same value as was passed into -/// Register() in RegisterContext and with CommBuffer pointing to an instance of +/// The DispatchFunction will be called with Context set to the same value as was passed into +/// Register() in RegisterContext and with CommBuffer pointing to an instance of /// EFI_SMM_PERIODIC_TIMER_CONTEXT and CommBufferSize pointing to its size. /// -typedef struct { - /// - /// ElapsedTime is the actual time in 100 nanosecond units elapsed since last called, a - /// value of 0 indicates an unknown amount of time. - /// - UINT64 ElapsedTime; -} EFI_SMM_PERIODIC_TIMER_CONTEXT; +typedef EFI_MM_PERIODIC_TIMER_CONTEXT EFI_SMM_PERIODIC_TIMER_CONTEXT; typedef struct _EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL; /** Register a child SMI source dispatch function for SMM periodic timer. - This service registers a function (DispatchFunction) which will be called when at least the - amount of time specified by RegisterContext has elapsed. On return, DispatchHandle + This service registers a function (DispatchFunction) which will be called when at least the + amount of time specified by RegisterContext has elapsed. On return, DispatchHandle contains a unique handle which may be used later to unregister the function using UnRegister(). - The DispatchFunction will be called with Context set to the same value as was passed into - this function in RegisterContext and with CommBuffer pointing to an instance of + The DispatchFunction will be called with Context set to the same value as was passed into + this function in RegisterContext and with CommBuffer pointing to an instance of EFI_SMM_PERIODIC_TIMER_CONTEXT and CommBufferSize pointing to its size. @param[in] This Pointer to the EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL instance. @param[in] DispatchFunction Function to register for handler when at least the specified amount - of time has elapsed. + of time has elapsed. @param[in] RegisterContext Pointer to the dispatch function's context. The caller fills this context in before calling the register function to indicate to the register function the period at which the dispatch function should be invoked. - @param[out] DispatchHandle Handle generated by the dispatcher to track the function instance. + @param[out] DispatchHandle Handle generated by the dispatcher to track the function instance. @retval EFI_SUCCESS The dispatch function has been successfully registered and the SMI source has been enabled. @@ -115,7 +101,7 @@ EFI_STATUS /** Unregisters a periodic timer service. - This service removes the handler associated with DispatchHandle so that it will no longer be + This service removes the handler associated with DispatchHandle so that it will no longer be called when the time has elapsed. @param[in] This Pointer to the EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL instance. diff --git a/MdePkg/Include/Protocol/SmmPowerButtonDispatch2.h b/MdePkg/Include/Protocol/SmmPowerButtonDispatch2.h index 0bedee8666d5..5fe84b00f2c2 100644 --- a/MdePkg/Include/Protocol/SmmPowerButtonDispatch2.h +++ b/MdePkg/Include/Protocol/SmmPowerButtonDispatch2.h @@ -4,14 +4,8 @@ This protocol provides the parent dispatch service for the power button SMI source generator. - Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This protocol is from PI Version 1.1. @@ -21,95 +15,20 @@ #ifndef _SMM_POWER_BUTTON_DISPATCH2_H_ #define _SMM_POWER_BUTTON_DISPATCH2_H_ -#include <Pi/PiSmmCis.h> - -#define EFI_SMM_POWER_BUTTON_DISPATCH2_PROTOCOL_GUID \ - { \ - 0x1b1183fa, 0x1823, 0x46a7, {0x88, 0x72, 0x9c, 0x57, 0x87, 0x55, 0x40, 0x9d } \ - } +#include <Protocol/MmPowerButtonDispatch.h> -/// -/// Power Button phases. -/// -typedef enum { - EfiPowerButtonEntry, - EfiPowerButtonExit, - EfiPowerButtonMax -} EFI_POWER_BUTTON_PHASE; +#define EFI_SMM_POWER_BUTTON_DISPATCH2_PROTOCOL_GUID EFI_MM_POWER_BUTTON_DISPATCH_PROTOCOL_GUID /// /// The dispatch function's context. /// -typedef struct { - /// - /// Designates whether this handler should be invoked upon entry or exit. - /// - EFI_POWER_BUTTON_PHASE Phase; -} EFI_SMM_POWER_BUTTON_REGISTER_CONTEXT; - -typedef struct _EFI_SMM_POWER_BUTTON_DISPATCH2_PROTOCOL EFI_SMM_POWER_BUTTON_DISPATCH2_PROTOCOL; - -/** - Provides the parent dispatch service for a power button event. - - This service registers a function (DispatchFunction) which will be called when an SMI is - generated because the power button was pressed or released, as specified by RegisterContext. - On return, DispatchHandle contains a unique handle which may be used later to unregister the - function using UnRegister(). - The DispatchFunction will be called with Context set to the same value as was passed into - this function in RegisterContext and with CommBuffer and CommBufferSize set to NULL. - - @param[in] This Pointer to the EFI_SMM_POWER_BUTTON_DISPATCH2_PROTOCOL instance. - @param[in] DispatchFunction Function to register for handler when power button is pressed or released. - @param[in] RegisterContext Pointer to the dispatch function's context. The caller fills in this context - before calling the Register() function to indicate to the Register() function - the power button SMI phase for which the dispatch function should be invoked. - @param[out] DispatchHandle Handle generated by the dispatcher to track the function instance. +typedef EFI_MM_POWER_BUTTON_REGISTER_CONTEXT EFI_SMM_POWER_BUTTON_REGISTER_CONTEXT; - @retval EFI_SUCCESS The dispatch function has been successfully - registered and the SMI source has been enabled. - @retval EFI_DEVICE_ERROR The driver was unable to enable the SMI source. - @retval EFI_INVALID_PARAMETER RegisterContext is invalid. The power button input value - is not within valid range. - @retval EFI_OUT_OF_RESOURCES There is not enough memory (system or SMM) to manage this child. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_POWER_BUTTON_REGISTER2)( - IN CONST EFI_SMM_POWER_BUTTON_DISPATCH2_PROTOCOL *This, - IN EFI_SMM_HANDLER_ENTRY_POINT2 DispatchFunction, - IN EFI_SMM_POWER_BUTTON_REGISTER_CONTEXT *RegisterContext, - OUT EFI_HANDLE *DispatchHandle - ); - -/** - Unregisters a power-button service. - - This service removes the handler associated with DispatchHandle so that it will no longer be - called when the standby button is pressed or released. - - @param[in] This Pointer to the EFI_SMM_POWER_BUTTON_DISPATCH2_PROTOCOL instance. - @param[in] DispatchHandle Handle of the service to remove. +typedef EFI_MM_POWER_BUTTON_DISPATCH_PROTOCOL EFI_SMM_POWER_BUTTON_DISPATCH2_PROTOCOL; - @retval EFI_SUCCESS The service has been successfully removed. - @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_POWER_BUTTON_UNREGISTER2)( - IN CONST EFI_SMM_POWER_BUTTON_DISPATCH2_PROTOCOL *This, - IN EFI_HANDLE DispatchHandle - ); +typedef EFI_MM_POWER_BUTTON_REGISTER EFI_SMM_POWER_BUTTON_REGISTER2; -/// -/// Interface structure for the SMM Power Button Dispatch2 Protocol. -/// -/// This protocol provides the parent dispatch service for the power button SMI source generator. -/// -struct _EFI_SMM_POWER_BUTTON_DISPATCH2_PROTOCOL { - EFI_SMM_POWER_BUTTON_REGISTER2 Register; - EFI_SMM_POWER_BUTTON_UNREGISTER2 UnRegister; -}; +typedef EFI_MM_POWER_BUTTON_UNREGISTER EFI_SMM_POWER_BUTTON_UNREGISTER2; extern EFI_GUID gEfiSmmPowerButtonDispatch2ProtocolGuid; diff --git a/MdePkg/Include/Protocol/SmmReadyToLock.h b/MdePkg/Include/Protocol/SmmReadyToLock.h index a55606deb457..f2661397c303 100644 --- a/MdePkg/Include/Protocol/SmmReadyToLock.h +++ b/MdePkg/Include/Protocol/SmmReadyToLock.h @@ -12,23 +12,16 @@ This protocol is installed after installation of the SMM End of DXE Protocol. Copyright (c) 2009 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef _SMM_READY_TO_LOCK_H_ #define _SMM_READY_TO_LOCK_H_ -#define EFI_SMM_READY_TO_LOCK_PROTOCOL_GUID \ - { \ - 0x47b7fa8c, 0xf4bd, 0x4af6, { 0x82, 0x00, 0x33, 0x30, 0x86, 0xf0, 0xd2, 0xc8 } \ - } +#include <Protocol/MmReadyToLock.h> + +#define EFI_SMM_READY_TO_LOCK_PROTOCOL_GUID EFI_MM_READY_TO_LOCK_PROTOCOL_GUID extern EFI_GUID gEfiSmmReadyToLockProtocolGuid; diff --git a/MdePkg/Include/Protocol/SmmReportStatusCodeHandler.h b/MdePkg/Include/Protocol/SmmReportStatusCodeHandler.h index ca290c7437ed..008d8c9bc84e 100644 --- a/MdePkg/Include/Protocol/SmmReportStatusCodeHandler.h +++ b/MdePkg/Include/Protocol/SmmReportStatusCodeHandler.h @@ -1,80 +1,28 @@ /** @file This protocol provides registering and unregistering services to status code consumers while in DXE SMM. - - Copyright (c) 2007 - 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in PI Specification 1.1. **/ #ifndef __SMM_REPORT_STATUS_CODE_HANDLER_PROTOCOL_H__ #define __SMM_REPORT_STATUS_CODE_HANDLER_PROTOCOL_H__ -#define EFI_SMM_RSC_HANDLER_PROTOCOL_GUID \ - { \ - 0x2ff29fa7, 0x5e80, 0x4ed9, {0xb3, 0x80, 0x1, 0x7d, 0x3c, 0x55, 0x4f, 0xf4} \ - } - -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_RSC_HANDLER_CALLBACK)( - IN EFI_STATUS_CODE_TYPE CodeType, - IN EFI_STATUS_CODE_VALUE Value, - IN UINT32 Instance, - IN EFI_GUID *CallerId, - IN EFI_STATUS_CODE_DATA *Data -); +#include <Protocol/MmReportStatusCodeHandler.h> -/** - Register the callback function for ReportStatusCode() notification. - - When this function is called the function pointer is added to an internal list and any future calls to - ReportStatusCode() will be forwarded to the Callback function. - - @param[in] Callback A pointer to a function of type EFI_RSC_HANDLER_CALLBACK that is called when - a call to ReportStatusCode() occurs. +#define EFI_SMM_RSC_HANDLER_PROTOCOL_GUID EFI_MM_RSC_HANDLER_PROTOCOL_GUID - @retval EFI_SUCCESS Function was successfully registered. - @retval EFI_INVALID_PARAMETER The callback function was NULL. - @retval EFI_OUT_OF_RESOURCES The internal buffer ran out of space. No more functions can be - registered. - @retval EFI_ALREADY_STARTED The function was already registered. It can't be registered again. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_RSC_HANDLER_REGISTER)( - IN EFI_SMM_RSC_HANDLER_CALLBACK Callback -); +typedef EFI_MM_RSC_HANDLER_CALLBACK EFI_SMM_RSC_HANDLER_CALLBACK; -/** - Remove a previously registered callback function from the notification list. - - A callback function must be unregistered before it is deallocated. It is important that any registered - callbacks that are not runtime complaint be unregistered when ExitBootServices() is called. +typedef EFI_MM_RSC_HANDLER_REGISTER EFI_SMM_RSC_HANDLER_REGISTER; - @param[in] Callback A pointer to a function of type EFI_SMM_RSC_HANDLER_CALLBACK that is to be - unregistered. - - @retval EFI_SUCCESS The function was successfully unregistered. - @retval EFI_INVALID_PARAMETER The callback function was NULL. - @retval EFI_NOT_FOUND The callback function was not found to be unregistered. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_RSC_HANDLER_UNREGISTER)( - IN EFI_SMM_RSC_HANDLER_CALLBACK Callback -); +typedef EFI_MM_RSC_HANDLER_UNREGISTER EFI_SMM_RSC_HANDLER_UNREGISTER; -typedef struct _EFI_SMM_RSC_HANDLER_PROTOCOL { - EFI_SMM_RSC_HANDLER_REGISTER Register; - EFI_SMM_RSC_HANDLER_UNREGISTER Unregister; -} EFI_SMM_RSC_HANDLER_PROTOCOL; +typedef EFI_MM_RSC_HANDLER_PROTOCOL EFI_SMM_RSC_HANDLER_PROTOCOL; extern EFI_GUID gEfiSmmRscHandlerProtocolGuid; diff --git a/MdePkg/Include/Protocol/SmmStandbyButtonDispatch2.h b/MdePkg/Include/Protocol/SmmStandbyButtonDispatch2.h index e8249495d2a6..dfe9305fc29f 100644 --- a/MdePkg/Include/Protocol/SmmStandbyButtonDispatch2.h +++ b/MdePkg/Include/Protocol/SmmStandbyButtonDispatch2.h @@ -5,13 +5,7 @@ This protocol provides the parent dispatch service for the standby button SMI source generator. Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This protocol is from PI Version 1.1. @@ -21,97 +15,20 @@ #ifndef _SMM_STANDBY_BUTTON_DISPATCH2_H_ #define _SMM_STANDBY_BUTTON_DISPATCH2_H_ -#include <Pi/PiSmmCis.h> - -#define EFI_SMM_STANDBY_BUTTON_DISPATCH2_PROTOCOL_GUID \ - { \ - 0x7300c4a1, 0x43f2, 0x4017, {0xa5, 0x1b, 0xc8, 0x1a, 0x7f, 0x40, 0x58, 0x5b } \ - } +#include <Protocol/MmStandbyButtonDispatch.h> -/// -/// Standby Button phases -/// -typedef enum { - EfiStandbyButtonEntry, - EfiStandbyButtonExit, - EfiStandbyButtonMax -} EFI_STANDBY_BUTTON_PHASE; +#define EFI_SMM_STANDBY_BUTTON_DISPATCH2_PROTOCOL_GUID EFI_MM_STANDBY_BUTTON_DISPATCH_PROTOCOL_GUID /// /// The dispatch function's context. /// -typedef struct { - /// - /// Describes whether the child handler should be invoked upon the entry to the button - /// activation or upon exit. - /// - EFI_STANDBY_BUTTON_PHASE Phase; -} EFI_SMM_STANDBY_BUTTON_REGISTER_CONTEXT; - -typedef struct _EFI_SMM_STANDBY_BUTTON_DISPATCH2_PROTOCOL EFI_SMM_STANDBY_BUTTON_DISPATCH2_PROTOCOL; - -/** - Provides the parent dispatch service for a standby button event. - - This service registers a function (DispatchFunction) which will be called when an SMI is - generated because the standby button was pressed or released, as specified by - RegisterContext. On return, DispatchHandle contains a unique handle which may be used - later to unregister the function using UnRegister(). - The DispatchFunction will be called with Context set to the same value as was passed into - this function in RegisterContext and with CommBuffer and CommBufferSize set to NULL. - - @param[in] This Pointer to the EFI_SMM_STANDBY_BUTTON_DISPATCH2_PROTOCOL instance. - @param[in] DispatchFunction Function to register for handler when the standby button is pressed or released. - @param[in] RegisterContext Pointer to the dispatch function's context. The caller fills in this context - before calling the register function to indicate to the register function the - standby button SMI source for which the dispatch function should be invoked. - @param[out] DispatchHandle Handle generated by the dispatcher to track the function instance. +typedef EFI_MM_STANDBY_BUTTON_REGISTER_CONTEXT EFI_SMM_STANDBY_BUTTON_REGISTER_CONTEXT; - @retval EFI_SUCCESS The dispatch function has been successfully - registered and the SMI source has been enabled. - @retval EFI_DEVICE_ERROR The driver was unable to enable the SMI source. - @retval EFI_INVALID_PARAMETER RegisterContext is invalid. The standby button input value - is not within valid range. - @retval EFI_OUT_OF_RESOURCES There is not enough memory (system or SMM) to manage this child. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_STANDBY_BUTTON_REGISTER2)( - IN CONST EFI_SMM_STANDBY_BUTTON_DISPATCH2_PROTOCOL *This, - IN EFI_SMM_HANDLER_ENTRY_POINT2 DispatchFunction, - IN EFI_SMM_STANDBY_BUTTON_REGISTER_CONTEXT *RegisterContext, - OUT EFI_HANDLE *DispatchHandle - ); - -/** - Unregisters a child SMI source dispatch function with a parent SMM driver. - - This service removes the handler associated with DispatchHandle so that it will no longer be - called when the standby button is pressed or released. - - @param[in] This Pointer to the EFI_SMM_STANDBY_BUTTON_DISPATCH2_PROTOCOL instance. - @param[in] DispatchHandle Handle of the service to remove. +typedef EFI_MM_STANDBY_BUTTON_DISPATCH_PROTOCOL EFI_SMM_STANDBY_BUTTON_DISPATCH2_PROTOCOL; - @retval EFI_SUCCESS The service has been successfully removed. - @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_STANDBY_BUTTON_UNREGISTER2)( - IN CONST EFI_SMM_STANDBY_BUTTON_DISPATCH2_PROTOCOL *This, - IN EFI_HANDLE DispatchHandle - ); +typedef EFI_MM_STANDBY_BUTTON_REGISTER EFI_SMM_STANDBY_BUTTON_REGISTER2; -/// -/// Interface structure for the SMM Standby Button Dispatch2 Protocol. -/// -/// This protocol provides the parent dispatch service for the standby -/// button SMI source generator. -/// -struct _EFI_SMM_STANDBY_BUTTON_DISPATCH2_PROTOCOL { - EFI_SMM_STANDBY_BUTTON_REGISTER2 Register; - EFI_SMM_STANDBY_BUTTON_UNREGISTER2 UnRegister; -}; +typedef EFI_MM_STANDBY_BUTTON_UNREGISTER EFI_SMM_STANDBY_BUTTON_UNREGISTER2; extern EFI_GUID gEfiSmmStandbyButtonDispatch2ProtocolGuid; diff --git a/MdePkg/Include/Protocol/SmmStatusCode.h b/MdePkg/Include/Protocol/SmmStatusCode.h index cf9740737df8..da396cc11541 100644 --- a/MdePkg/Include/Protocol/SmmStatusCode.h +++ b/MdePkg/Include/Protocol/SmmStatusCode.h @@ -1,63 +1,23 @@ /** @file EFI SMM Status Code Protocol as defined in the PI 1.2 specification. - This protocol provides the basic status code services while in SMM. + This protocol provides the basic status code services while in SMM. - Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef _SMM_STATUS_CODE_H__ #define _SMM_STATUS_CODE_H__ +#include <Protocol/MmStatusCode.h> -#define EFI_SMM_STATUS_CODE_PROTOCOL_GUID \ - { \ - 0x6afd2b77, 0x98c1, 0x4acd, {0xa6, 0xf9, 0x8a, 0x94, 0x39, 0xde, 0xf, 0xb1} \ - } - -typedef struct _EFI_SMM_STATUS_CODE_PROTOCOL EFI_SMM_STATUS_CODE_PROTOCOL; - -/** - Service to emit the status code in SMM. +#define EFI_SMM_STATUS_CODE_PROTOCOL_GUID EFI_MM_STATUS_CODE_PROTOCOL_GUID - The EFI_SMM_STATUS_CODE_PROTOCOL.ReportStatusCode() function enables a driver - to emit a status code while in SMM. The reason that there is a separate protocol definition from the - DXE variant of this service is that the publisher of this protocol will provide a service that is - capability of coexisting with a foreground operational environment, such as an operating system - after the termination of boot services. - - @param[in] This Points to this instance of the EFI_SMM_STATUS_CODE_PROTOCOL. - @param[in] CodeType DIndicates the type of status code being reported. - @param[in] Value Describes the current status of a hardware or software entity. - @param[in] Instance The enumeration of a hardware or software entity within the system. - @param[in] CallerId This optional parameter may be used to identify the caller. - @param[in] Data This optional parameter may be used to pass additional data. - - @retval EFI_SUCCESS The function completed successfully. - @retval EFI_INVALID_PARAMETER The function should not be completed due to a device error. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_REPORT_STATUS_CODE)( - IN CONST EFI_SMM_STATUS_CODE_PROTOCOL *This, - IN EFI_STATUS_CODE_TYPE CodeType, - IN EFI_STATUS_CODE_VALUE Value, - IN UINT32 Instance, - IN CONST EFI_GUID *CallerId, - IN EFI_STATUS_CODE_DATA *Data OPTIONAL - ); +typedef EFI_MM_STATUS_CODE_PROTOCOL EFI_SMM_STATUS_CODE_PROTOCOL; -struct _EFI_SMM_STATUS_CODE_PROTOCOL { - EFI_SMM_REPORT_STATUS_CODE ReportStatusCode; -}; +typedef EFI_MM_REPORT_STATUS_CODE EFI_SMM_REPORT_STATUS_CODE; extern EFI_GUID gEfiSmmStatusCodeProtocolGuid; diff --git a/MdePkg/Include/Protocol/SmmSwDispatch2.h b/MdePkg/Include/Protocol/SmmSwDispatch2.h index 3b2969b9769a..95e7db404837 100644 --- a/MdePkg/Include/Protocol/SmmSwDispatch2.h +++ b/MdePkg/Include/Protocol/SmmSwDispatch2.h @@ -4,26 +4,18 @@ This protocol provides the parent dispatch service for a given SMI source generator. - Copyright (c) 2009 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef _SMM_SW_DISPATCH2_H_ #define _SMM_SW_DISPATCH2_H_ +#include <Protocol/MmSwDispatch.h> #include <Pi/PiSmmCis.h> -#define EFI_SMM_SW_DISPATCH2_PROTOCOL_GUID \ - { \ - 0x18a3c6dc, 0x5eea, 0x48c8, {0xa1, 0xc1, 0xb5, 0x33, 0x89, 0xf9, 0x89, 0x99 } \ - } +#define EFI_SMM_SW_DISPATCH2_PROTOCOL_GUID EFI_MM_SW_DISPATCH_PROTOCOL_GUID /// /// A particular chipset may not support all possible software SMI input values. @@ -35,9 +27,9 @@ typedef struct { } EFI_SMM_SW_REGISTER_CONTEXT; /// -/// The DispatchFunction will be called with Context set to the same value as was passed into +/// The DispatchFunction will be called with Context set to the same value as was passed into /// this function in RegisterContext and with CommBuffer (and CommBufferSize) pointing -/// to an instance of EFI_SMM_SW_CONTEXT indicating the index of the CPU which generated the +/// to an instance of EFI_SMM_SW_CONTEXT indicating the index of the CPU which generated the /// software SMI. /// typedef struct { @@ -60,14 +52,14 @@ typedef struct _EFI_SMM_SW_DISPATCH2_PROTOCOL EFI_SMM_SW_DISPATCH2_PROTOCOL; /** Register a child SMI source dispatch function for the specified software SMI. - This service registers a function (DispatchFunction) which will be called when the software - SMI source specified by RegisterContext->SwSmiCpuIndex is detected. On return, - DispatchHandle contains a unique handle which may be used later to unregister the function + This service registers a function (DispatchFunction) which will be called when the software + SMI source specified by RegisterContext->SwSmiCpuIndex is detected. On return, + DispatchHandle contains a unique handle which may be used later to unregister the function using UnRegister(). @param[in] This Pointer to the EFI_SMM_SW_DISPATCH2_PROTOCOL instance. - @param[in] DispatchFunction Function to register for handler when the specified software - SMI is generated. + @param[in] DispatchFunction Function to register for handler when the specified software + SMI is generated. @param[in, out] RegisterContext Pointer to the dispatch function's context. The caller fills this context in before calling the register function to indicate to the register @@ -98,7 +90,7 @@ EFI_STATUS /** Unregister a child SMI source dispatch function for the specified software SMI. - This service removes the handler associated with DispatchHandle so that it will no longer be + This service removes the handler associated with DispatchHandle so that it will no longer be called in response to a software SMI. @param[in] This Pointer to the EFI_SMM_SW_DISPATCH2_PROTOCOL instance. @@ -117,15 +109,15 @@ EFI_STATUS /// /// Interface structure for the SMM Software SMI Dispatch Protocol. /// -/// The EFI_SMM_SW_DISPATCH2_PROTOCOL provides the ability to install child handlers for the -/// given software. These handlers will respond to software interrupts, and the maximum software +/// The EFI_SMM_SW_DISPATCH2_PROTOCOL provides the ability to install child handlers for the +/// given software. These handlers will respond to software interrupts, and the maximum software /// interrupt in the EFI_SMM_SW_REGISTER_CONTEXT is denoted by MaximumSwiValue. /// struct _EFI_SMM_SW_DISPATCH2_PROTOCOL { EFI_SMM_SW_REGISTER2 Register; EFI_SMM_SW_UNREGISTER2 UnRegister; /// - /// A read-only field that describes the maximum value that can be used in the + /// A read-only field that describes the maximum value that can be used in the /// EFI_SMM_SW_DISPATCH2_PROTOCOL.Register() service. /// UINTN MaximumSwiValue; diff --git a/MdePkg/Include/Protocol/SmmSxDispatch2.h b/MdePkg/Include/Protocol/SmmSxDispatch2.h index 94508f3a3973..d4e3020bd1d1 100644 --- a/MdePkg/Include/Protocol/SmmSxDispatch2.h +++ b/MdePkg/Include/Protocol/SmmSxDispatch2.h @@ -4,131 +4,28 @@ Provides the parent dispatch service for a given Sx-state source generator. - Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef _SMM_SX_DISPATCH2_H_ #define _SMM_SX_DISPATCH2_H_ -#include <Pi/PiSmmCis.h> - -#define EFI_SMM_SX_DISPATCH2_PROTOCOL_GUID \ - { \ - 0x456d2859, 0xa84b, 0x4e47, {0xa2, 0xee, 0x32, 0x76, 0xd8, 0x86, 0x99, 0x7d } \ - } - -/// -/// Sleep states S0-S5 -/// -typedef enum { - SxS0, - SxS1, - SxS2, - SxS3, - SxS4, - SxS5, - EfiMaximumSleepType -} EFI_SLEEP_TYPE; +#include <Protocol/MmSxDispatch.h> -/// -/// Sleep state phase: entry or exit -/// -typedef enum { - SxEntry, - SxExit, - EfiMaximumPhase -} EFI_SLEEP_PHASE; +#define EFI_SMM_SX_DISPATCH2_PROTOCOL_GUID EFI_MM_SX_DISPATCH_PROTOCOL_GUID /// /// The dispatch function's context /// -typedef struct { - EFI_SLEEP_TYPE Type; - EFI_SLEEP_PHASE Phase; -} EFI_SMM_SX_REGISTER_CONTEXT; - -typedef struct _EFI_SMM_SX_DISPATCH2_PROTOCOL EFI_SMM_SX_DISPATCH2_PROTOCOL; +typedef EFI_MM_SX_REGISTER_CONTEXT EFI_SMM_SX_REGISTER_CONTEXT; -/** - Provides the parent dispatch service for a given Sx source generator. +typedef EFI_MM_SX_DISPATCH_PROTOCOL EFI_SMM_SX_DISPATCH2_PROTOCOL; - This service registers a function (DispatchFunction) which will be called when the sleep state - event specified by RegisterContext is detected. On return, DispatchHandle contains a - unique handle which may be used later to unregister the function using UnRegister(). - The DispatchFunction will be called with Context set to the same value as was passed into - this function in RegisterContext and with CommBuffer and CommBufferSize set to - NULL and 0 respectively. +typedef EFI_MM_SX_REGISTER EFI_SMM_SX_REGISTER2; - @param[in] This Pointer to the EFI_SMM_SX_DISPATCH2_PROTOCOL instance. - @param[in] DispatchFunction Function to register for handler when the specified sleep state event occurs. - @param[in] RegisterContext Pointer to the dispatch function's context. - The caller fills this context in before calling - the register function to indicate to the register - function which Sx state type and phase the caller - wishes to be called back on. For this intertace, - the Sx driver will call the registered handlers for - all Sx type and phases, so the Sx state handler(s) - must check the Type and Phase field of the Dispatch - context and act accordingly. - @param[out] DispatchHandle Handle of dispatch function, for when interfacing - with the parent Sx state SMM driver. - - @retval EFI_SUCCESS The dispatch function has been successfully - registered and the SMI source has been enabled. - @retval EFI_UNSUPPORTED The Sx driver or hardware does not support that - Sx Type/Phase. - @retval EFI_DEVICE_ERROR The Sx driver was unable to enable the SMI source. - @retval EFI_INVALID_PARAMETER RegisterContext is invalid. Type & Phase are not - within valid range. - @retval EFI_OUT_OF_RESOURCES There is not enough memory (system or SMM) to manage this - child. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_SX_REGISTER2)( - IN CONST EFI_SMM_SX_DISPATCH2_PROTOCOL *This, - IN EFI_SMM_HANDLER_ENTRY_POINT2 DispatchFunction, - IN CONST EFI_SMM_SX_REGISTER_CONTEXT *RegisterContext, - OUT EFI_HANDLE *DispatchHandle - ); - -/** - Unregisters an Sx-state service. - - This service removes the handler associated with DispatchHandle so that it will no longer be - called in response to sleep event. - - @param[in] This Pointer to the EFI_SMM_SX_DISPATCH2_PROTOCOL instance. - @param[in] DispatchHandle Handle of the service to remove. - - @retval EFI_SUCCESS The service has been successfully removed. - @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_SX_UNREGISTER2)( - IN CONST EFI_SMM_SX_DISPATCH2_PROTOCOL *This, - IN EFI_HANDLE DispatchHandle - ); - -/// -/// Interface structure for the SMM Sx Dispatch Protocol -/// -/// The EFI_SMM_SX_DISPATCH2_PROTOCOL provides the ability to install child handlers to -/// respond to sleep state related events. -/// -struct _EFI_SMM_SX_DISPATCH2_PROTOCOL { - EFI_SMM_SX_REGISTER2 Register; - EFI_SMM_SX_UNREGISTER2 UnRegister; -}; +typedef EFI_MM_SX_UNREGISTER EFI_SMM_SX_UNREGISTER2; extern EFI_GUID gEfiSmmSxDispatch2ProtocolGuid; diff --git a/MdePkg/Include/Protocol/SmmUsbDispatch2.h b/MdePkg/Include/Protocol/SmmUsbDispatch2.h index 75a7a7c0bc7f..8ac127a8bb98 100644 --- a/MdePkg/Include/Protocol/SmmUsbDispatch2.h +++ b/MdePkg/Include/Protocol/SmmUsbDispatch2.h @@ -4,14 +4,8 @@ Provides the parent dispatch service for the USB SMI source generator. - Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This protocol is from PI Version 1.1. @@ -21,108 +15,25 @@ #ifndef _SMM_USB_DISPATCH2_H_ #define _SMM_USB_DISPATCH2_H_ -#include <Pi/PiSmmCis.h> +#include <Protocol/MmUsbDispatch.h> -#define EFI_SMM_USB_DISPATCH2_PROTOCOL_GUID \ - { \ - 0xee9b8d90, 0xc5a6, 0x40a2, {0xbd, 0xe2, 0x52, 0x55, 0x8d, 0x33, 0xcc, 0xa1 } \ - } +#define EFI_SMM_USB_DISPATCH2_PROTOCOL_GUID EFI_MM_USB_DISPATCH_PROTOCOL_GUID /// /// USB SMI event types /// -typedef enum { - UsbLegacy, - UsbWake -} EFI_USB_SMI_TYPE; +typedef EFI_USB_MMI_TYPE EFI_USB_SMI_TYPE; /// /// The dispatch function's context. /// -typedef struct { - /// - /// Describes whether this child handler will be invoked in response to a USB legacy - /// emulation event, such as port-trap on the PS/2* keyboard control registers, or to a - /// USB wake event, such as resumption from a sleep state. - /// - EFI_USB_SMI_TYPE Type; - /// - /// The device path is part of the context structure and describes the location of the - /// particular USB host controller in the system for which this register event will occur. - /// This location is important because of the possible integration of several USB host - /// controllers in a system. - /// - EFI_DEVICE_PATH_PROTOCOL *Device; -} EFI_SMM_USB_REGISTER_CONTEXT; - -typedef struct _EFI_SMM_USB_DISPATCH2_PROTOCOL EFI_SMM_USB_DISPATCH2_PROTOCOL; - -/** - Provides the parent dispatch service for the USB SMI source generator. - - This service registers a function (DispatchFunction) which will be called when the USB- - related SMI specified by RegisterContext has occurred. On return, DispatchHandle - contains a unique handle which may be used later to unregister the function using UnRegister(). - The DispatchFunction will be called with Context set to the same value as was passed into - this function in RegisterContext and with CommBuffer containing NULL and - CommBufferSize containing zero. - - @param[in] This Pointer to the EFI_SMM_USB_DISPATCH2_PROTOCOL instance. - @param[in] DispatchFunction Function to register for handler when a USB-related SMI occurs. - @param[in] RegisterContext Pointer to the dispatch function's context. - The caller fills this context in before calling - the register function to indicate to the register - function the USB SMI types for which the dispatch - function should be invoked. - @param[out] DispatchHandle Handle generated by the dispatcher to track the function instance. - - @retval EFI_SUCCESS The dispatch function has been successfully - registered and the SMI source has been enabled. - @retval EFI_DEVICE_ERROR The driver was unable to enable the SMI source. - @retval EFI_INVALID_PARAMETER RegisterContext is invalid. The USB SMI type - is not within valid range. - @retval EFI_OUT_OF_RESOURCES There is not enough memory (system or SMM) to manage this child. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_USB_REGISTER2)( - IN CONST EFI_SMM_USB_DISPATCH2_PROTOCOL *This, - IN EFI_SMM_HANDLER_ENTRY_POINT2 DispatchFunction, - IN CONST EFI_SMM_USB_REGISTER_CONTEXT *RegisterContext, - OUT EFI_HANDLE *DispatchHandle - ); - -/** - Unregisters a USB service. +typedef EFI_MM_USB_REGISTER_CONTEXT EFI_SMM_USB_REGISTER_CONTEXT; - This service removes the handler associated with DispatchHandle so that it will no longer be - called when the USB event occurs. +typedef EFI_MM_USB_DISPATCH_PROTOCOL EFI_SMM_USB_DISPATCH2_PROTOCOL; - @param[in] This Pointer to the EFI_SMM_USB_DISPATCH2_PROTOCOL instance. - @param[in] DispatchHandle Handle of the service to remove. - - @retval EFI_SUCCESS The dispatch function has been successfully - unregistered and the SMI source has been disabled - if there are no other registered child dispatch - functions for this SMI source. - @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMM_USB_UNREGISTER2)( - IN CONST EFI_SMM_USB_DISPATCH2_PROTOCOL *This, - IN EFI_HANDLE DispatchHandle - ); +typedef EFI_MM_USB_REGISTER EFI_SMM_USB_REGISTER2; -/// -/// Interface structure for the SMM USB SMI Dispatch2 Protocol -/// -/// This protocol provides the parent dispatch service for the USB SMI source generator. -/// -struct _EFI_SMM_USB_DISPATCH2_PROTOCOL { - EFI_SMM_USB_REGISTER2 Register; - EFI_SMM_USB_UNREGISTER2 UnRegister; -}; +typedef EFI_MM_USB_UNREGISTER EFI_SMM_USB_UNREGISTER2; extern EFI_GUID gEfiSmmUsbDispatch2ProtocolGuid; diff --git a/MdePkg/Include/Protocol/SpiConfiguration.h b/MdePkg/Include/Protocol/SpiConfiguration.h new file mode 100644 index 000000000000..c09784b7354e --- /dev/null +++ b/MdePkg/Include/Protocol/SpiConfiguration.h @@ -0,0 +1,287 @@ +/** @file + This file defines the SPI Configuration Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI PI Specification 1.6. + +**/ + +#ifndef __SPI_CONFIGURATION_PROTOCOL_H__ +#define __SPI_CONFIGURATION_PROTOCOL_H__ + +/// +/// Global ID for the SPI Configuration Protocol +/// +#define EFI_SPI_CONFIGURATION_GUID \ + { 0x85a6d3e6, 0xb65b, 0x4afc, \ + { 0xb3, 0x8f, 0xc6, 0xd5, 0x4a, 0xf6, 0xdd, 0xc8 }} + +/// +/// Macros to easily specify frequencies in hertz, kilohertz and megahertz. +/// +#define Hz(Frequency) (Frequency) +#define KHz(Frequency) (1000 * Hz (Frequency)) +#define MHz(Frequency) (1000 * KHz (Frequency)) + +typedef struct _EFI_SPI_PERIPHERAL EFI_SPI_PERIPHERAL; + +/** + Manipulate the chip select for a SPI device. + + This routine must be called at or below TPL_NOTIFY. + Update the value of the chip select line for a SPI peripheral. + The SPI bus layer calls this routine either in the board layer or in the SPI + controller to manipulate the chip select pin at the start and end of a SPI + transaction. + + @param[in] SpiPeripheral The address of an EFI_SPI_PERIPHERAL data structure + describing the SPI peripheral whose chip select pin + is to be manipulated. The routine may access the + ChipSelectParameter field to gain sufficient + context to complete the operation. + @param[in] PinValue The value to be applied to the chip select line of + the SPI peripheral. + + @retval EFI_SUCCESS The chip select was set successfully + @retval EFI_NOT_READY Support for the chip select is not properly + initialized + @retval EFI_INVALID_PARAMETER The SpiPeripheral->ChipSelectParameter value + is invalid + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_CHIP_SELECT) ( + IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral, + IN BOOLEAN PinValue + ); + +/** + Set up the clock generator to produce the correct clock frequency, phase and + polarity for a SPI chip. + + This routine must be called at or below TPL_NOTIFY. + This routine updates the clock generator to generate the correct frequency + and polarity for the SPI clock. + + @param[in] SpiPeripheral Pointer to a EFI_SPI_PERIPHERAL data structure from + which the routine can access the ClockParameter, + ClockPhase and ClockPolarity fields. The routine + also has access to the names for the SPI bus and + chip which can be used during debugging. + @param[in] ClockHz Pointer to the requested clock frequency. The clock + generator will choose a supported clock frequency + which is less then or equal to this value. + Specify zero to turn the clock generator off. + The actual clock frequency supported by the clock + generator will be returned. + + @retval EFI_SUCCESS The clock was set up successfully + @retval EFI_UNSUPPORTED The SPI controller was not able to support the + frequency requested by CLockHz + +**/ +typedef EFI_STATUS +(EFIAPI *EFI_SPI_CLOCK) ( + IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral, + IN UINT32 *ClockHz + ); + +/// +/// The EFI_SPI_PART data structure provides a description of a SPI part which +/// is independent of the use on the board. This data is available directly +/// from the part's datasheet and may be provided by the vendor. +/// +typedef struct _EFI_SPI_PART { + /// + /// A Unicode string specifying the SPI chip vendor. + /// + CONST CHAR16 *Vendor; + + /// + /// A Unicode string specifying the SPI chip part number. + /// + CONST CHAR16 *PartNumber; + + /// + /// The minimum SPI bus clock frequency used to access this chip. This value + /// may be specified in the chip's datasheet. If not, use the value of zero. + /// + UINT32 MinClockHz; + + /// + /// The maximum SPI bus clock frequency used to access this chip. This value + /// is found in the chip's datasheet. + /// + UINT32 MaxClockHz; + + /// + /// Specify the polarity of the chip select pin. This value can be found in + /// the SPI chip's datasheet. Specify TRUE when a one asserts the chip select + ///and FALSE when a zero asserts the chip select. + /// + BOOLEAN ChipSelectPolarity; +} EFI_SPI_PART; + +/// +/// The EFI_SPI_BUS data structure provides the connection details between the +/// physical SPI bus and the EFI_SPI_HC_PROTOCOL instance which controls that +/// SPI bus. This data structure also describes the details of how the clock is +/// generated for that SPI bus. Finally this data structure provides the list +/// of physical SPI devices which are attached to the SPI bus. +/// +typedef struct _EFI_SPI_BUS { + /// + /// A Unicode string describing the SPI bus + /// + CONST CHAR16 *FriendlyName; + + /// + /// Address of the first EFI_SPI_PERIPHERAL data structure connected to this + /// bus. Specify NULL if there are no SPI peripherals connected to this bus. + /// + CONST EFI_SPI_PERIPHERAL *Peripherallist; + + /// + /// Address of an EFI_DEVICE_PATH_PROTOCOL data structure which uniquely + /// describes the SPI controller. + /// + CONST EFI_DEVICE_PATH_PROTOCOL *ControllerPath; + + /// + /// Address of the routine which controls the clock used by the SPI bus for + /// this SPI peripheral. The SPI host co ntroller's clock routine is called + /// when this value is set to NULL. + /// + EFI_SPI_CLOCK Clock; + + /// + /// Address of a data structure containing the additional values which + /// describe the necessary control for the clock. When Clock is NULL, + /// the declaration for this data structure is provided by the vendor of the + /// host's SPI controller driver. When Clock is not NULL, the declaration for + /// this data structure is provided by the board layer. + /// + VOID *ClockParameter; +} EFI_SPI_BUS; + +/// +/// The EFI_SPI_PERIPHERAL data structure describes how a specific block of +/// logic which is connected to the SPI bus. This data structure also selects +/// which upper level driver is used to manipulate this SPI device. +/// The SpiPeripheraLDriverGuid is available from the vendor of the SPI +/// peripheral driver. +/// +struct _EFI_SPI_PERIPHERAL { + /// + /// Address of the next EFI_SPI_PERIPHERAL data structure. Specify NULL if + /// the current data structure is the last one on the SPI bus. + /// + CONST EFI_SPI_PERIPHERAL *NextSpiPeripheral; + + /// + /// A unicode string describing the function of the SPI part. + /// + CONST CHAR16 *FriendlyName; + + /// + /// Address of a GUID provided by the vendor of the SPI peripheral driver. + /// Instead of using a " EFI_SPI_IO_PROTOCOL" GUID, the SPI bus driver uses + /// this GUID to identify an EFI_SPI_IO_PROTOCOL data structure and to + /// provide the connection points for the SPI peripheral drivers. + /// This reduces the comparison logic in the SPI peripheral driver's + /// Supported routine. + /// + CONST GUID *SpiPeripheralDriverGuid; + + /// + /// The address of an EFI_SPI_PART data structure which describes this chip. + /// + CONST EFI_SPI_PART *SpiPart; + + /// + /// The maximum clock frequency is specified in the EFI_SPI_P ART. When this + /// this value is non-zero and less than the value in the EFI_SPI_PART then + /// this value is used for the maximum clock frequency for the SPI part. + /// + UINT32 MaxClockHz; + + /// + /// Specify the idle value of the clock as found in the datasheet. + /// Use zero (0) if the clock'S idle value is low or one (1) if the the + /// clock's idle value is high. + /// + BOOLEAN ClockPolarity; + + /// + /// Specify the clock delay after chip select. Specify zero (0) to delay an + /// entire clock cycle or one (1) to delay only half a clock cycle. + /// + BOOLEAN ClockPhase; + + /// + /// SPI peripheral attributes, select zero or more of: + /// * SPI_PART_SUPPORTS_2_B1T_DATA_BUS_W1DTH - The SPI peripheral is wired to + /// support a 2-bit data bus + /// * SPI_PART_SUPPORTS_4_B1T_DATA_BUS_W1DTH - The SPI peripheral is wired to + /// support a 4-bit data bus + /// + UINT32 Attributes; + + /// + /// Address of a vendor specific data structure containing additional board + /// configuration details related to the SPI chip. The SPI peripheral layer + /// uses this data structure when configuring the chip. + /// + CONST VOID *ConfigurationData; + + /// + /// The address of an EFI_SPI_BUS data structure which describes the SPI bus + /// to which this chip is connected. + /// + CONST EFI_SPI_BUS *SpiBus; + + /// + /// Address of the routine which controls the chip select pin for this SPI + /// peripheral. Call the SPI host controller's chip select routine when this + /// value is set to NULL. + /// + EFI_SPI_CHIP_SELECT ChipSelect; + + /// + /// Address of a data structure containing the additional values which + /// describe the necessary control for the chip select. When ChipSelect is + /// NULL, the declaration for this data structure is provided by the vendor + /// of the host's SPI controller driver. The vendor's documentation specifies + /// the necessary values to use for the chip select pin selection and + /// control. When Chipselect is not NULL, the declaration for this data + /// structure is provided by the board layer. + /// + VOID *ChipSelectParameter; +}; + +/// +/// Describe the details of the board's SPI busses to the SPI driver stack. +/// The board layer uses the EFI_SPI_CONFIGURATION_PROTOCOL to expose the data +/// tables which describe the board's SPI busses, The SPI bus layer uses these +/// tables to configure the clock, chip select and manage the SPI transactions +/// on the SPI controllers. +/// +typedef struct _EFI_SPI_CONFIGURATION_PROTOCOL { + /// + /// The number of SPI busses on the board. + /// + UINT32 BusCount; + + /// + /// The address of an array of EFI_SPI_BUS data structure addresses. + /// + CONST EFI_SPI_BUS *CONST *CONST Buslist; +} EFI_SPI_CONFIGURATION_PROTOCOL; + +extern EFI_GUID gEfiSpiConfigurationProtocolGuid; + +#endif // __SPI_CONFIGURATION_PROTOCOL_H__ diff --git a/MdePkg/Include/Protocol/SpiHc.h b/MdePkg/Include/Protocol/SpiHc.h new file mode 100644 index 000000000000..f875bc706be2 --- /dev/null +++ b/MdePkg/Include/Protocol/SpiHc.h @@ -0,0 +1,188 @@ +/** @file + This file defines the SPI Host Controller Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI PI Specification 1.6. + +**/ + +#ifndef __SPI_HC_PROTOCOL_H__ +#define __SPI_HC_PROTOCOL_H__ + +#include <Protocol/SpiConfiguration.h> +#include <Protocol/SpiIo.h> + +/// +/// Global ID for the SPI Host Controller Protocol +/// +#define EFI_SPI_HOST_GUID \ + { 0xc74e5db2, 0xfa96, 0x4ae2, \ + { 0xb3, 0x99, 0x15, 0x97, 0x7f, 0xe3, 0x0, 0x2d }} + +/// +/// EDK2-style name +/// +#define EFI_SPI_HC_PROTOCOL_GUID EFI_SPI_HOST_GUID + +typedef struct _EFI_SPI_HC_PROTOCOL EFI_SPI_HC_PROTOCOL; + +/** + Assert or deassert the SPI chip select. + + This routine is called at TPL_NOTIFY. + Update the value of the chip select line for a SPI peripheral. The SPI bus + layer calls this routine either in the board layer or in the SPI controller + to manipulate the chip select pin at the start and end of a SPI transaction. + + @param[in] This Pointer to an EFI_SPI_HC_PROTOCOL structure. + @param[in] SpiPeripheral The address of an EFI_SPI_PERIPHERAL data structure + describing the SPI peripheral whose chip select pin + is to be manipulated. The routine may access the + ChipSelectParameter field to gain sufficient + context to complete the operati on. + @param[in] PinValue The value to be applied to the chip select line of + the SPI peripheral. + + @retval EFI_SUCCESS The chip select was set as requested + @retval EFI_NOT_READY Support for the chip select is not properly + initialized + @retval EFI_INVALID_PARAMETER The ChipSeLect value or its contents are + invalid + +**/ +typedef EFI_STATUS +(EFIAPI *EFI_SPI_HC_PROTOCOL_CHIP_SELECT) ( + IN CONST EFI_SPI_HC_PROTOCOL *This, + IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral, + IN BOOLEAN PinValue + ); + +/** + Set up the clock generator to produce the correct clock frequency, phase and + polarity for a SPI chip. + + This routine is called at TPL_NOTIFY. + This routine updates the clock generator to generate the correct frequency + and polarity for the SPI clock. + + @param[in] This Pointer to an EFI_SPI_HC_PROTOCOL structure. + @param[in] SpiPeripheral Pointer to a EFI_SPI_PERIPHERAL data structure from + which the routine can access the ClockParameter, + ClockPhase and ClockPolarity fields. The routine + also has access to the names for the SPI bus and + chip which can be used during debugging. + @param[in] ClockHz Pointer to the requested clock frequency. The SPI + host controller will choose a supported clock + frequency which is less then or equal to this + value. Specify zero to turn the clock generator + off. The actual clock frequency supported by the + SPI host controller will be returned. + + @retval EFI_SUCCESS The clock was set up successfully + @retval EFI_UNSUPPORTED The SPI controller was not able to support the + frequency requested by ClockHz + +**/ +typedef EFI_STATUS +(EFIAPI *EFI_SPI_HC_PROTOCOL_CLOCK) ( + IN CONST EFI_SPI_HC_PROTOCOL *This, + IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral, + IN UINT32 *ClockHz + ); + +/** + Perform the SPI transaction on the SPI peripheral using the SPI host + controller. + + This routine is called at TPL_NOTIFY. + This routine synchronously returns EFI_SUCCESS indicating that the + asynchronous SPI transaction was started. The routine then waits for + completion of the SPI transaction prior to returning the final transaction + status. + + @param[in] This Pointer to an EFI_SPI_HC_PROTOCOL structure. + @param[in] BusTransaction Pointer to a EFI_SPI_BUS_ TRANSACTION containing + the description of the SPI transaction to perform. + + @retval EFI_SUCCESS The transaction completed successfully + @retval EFI_BAD_BUFFER_SIZE The BusTransaction->WriteBytes value is invalid, + or the BusTransaction->ReadinBytes value is + invalid + @retval EFI_UNSUPPORTED The BusTransaction-> Transaction Type is + unsupported + +**/ +typedef EFI_STATUS +(EFIAPI *EFI_SPI_HC_PROTOCOL_TRANSACTION) ( + IN CONST EFI_SPI_HC_PROTOCOL *This, + IN EFI_SPI_BUS_TRANSACTION *BusTransaction + ); + +/// +/// Support a SPI data transaction between the SPI controller and a SPI chip. +/// +struct _EFI_SPI_HC_PROTOCOL { + /// + /// Host control attributes, may have zero or more of the following set: + /// * HC_SUPPORTS_WRITE_ONLY_OPERATIONS + /// * HC_SUPPORTS_READ_ONLY_OPERATIONS + /// * HC_SUPPORTS_WRITE_THEN_READ_OPERATIONS + /// * HC_TX_FRAME_IN_MOST_SIGNIFICANT_BITS + /// - The SPI host controller requires the transmit frame to be in most + /// significant bits instead of least significant bits.The host driver + /// will adjust the frames if necessary. + /// * HC_RX_FRAME_IN_MOST_SIGNIFICANT_BITS + /// - The SPI host controller places the receive frame to be in most + /// significant bits instead of least significant bits.The host driver + /// will adjust the frames to be in the least significant bits if + /// necessary. + /// * HC_SUPPORTS_2_BIT_DATA_BUS_W1DTH + /// - The SPI controller supports a 2 - bit data bus + /// * HC_SUPPORTS_4_B1T_DATA_BUS_WIDTH + /// - The SPI controller supports a 4 - bit data bus + /// * HC_TRANSFER_SIZE_INCLUDES_OPCODE + /// - Transfer size includes the opcode byte + /// * HC_TRANSFER_SIZE_INCLUDES_ADDRESS + /// - Transfer size includes the 3 address bytes + /// The SPI host controller must support full - duplex (receive while + /// sending) operation.The SPI host controller must support a 1 - bit bus + /// width. + /// + UINT32 Attributes; + + /// + /// Mask of frame sizes which the SPI host controller supports. Frame size of + /// N-bits is supported when bit N-1 is set. The host controller must support + /// a frame size of 8-bits. + /// + UINT32 FrameSizeSupportMask; + + /// + /// Maximum transfer size in bytes: 1 - Oxffffffff + /// + UINT32 MaximumTransferBytes; + + /// + /// Assert or deassert the SPI chip select. + /// + EFI_SPI_HC_PROTOCOL_CHIP_SELECT ChipSelect; + + /// + /// Set up the clock generator to produce the correct clock frequency, phase + /// and polarity for a SPI chip. + /// + EFI_SPI_HC_PROTOCOL_CLOCK Clock; + + /// + /// Perform the SPI transaction on the SPI peripheral using the SPI host + /// controller. + /// + EFI_SPI_HC_PROTOCOL_TRANSACTION Transaction; +}; + +extern EFI_GUID gEfiSpiHcProtocolGuid; + +#endif // __SPI_HC_PROTOCOL_H__ diff --git a/MdePkg/Include/Protocol/SpiIo.h b/MdePkg/Include/Protocol/SpiIo.h new file mode 100644 index 000000000000..449707e098e1 --- /dev/null +++ b/MdePkg/Include/Protocol/SpiIo.h @@ -0,0 +1,286 @@ +/** @file + This file defines the SPI I/O Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI PI Specification 1.6. + +**/ + +#ifndef __SPI_IO_PROTOCOL_H__ +#define __SPI_IO_PROTOCOL_H__ + +#include <Protocol/LegacySpiController.h> +#include <Protocol/SpiConfiguration.h> + +typedef struct _EFI_SPI_IO_PROTOCOL EFI_SPI_IO_PROTOCOL; + +/// +/// Note: The UEFI PI 1.6 specification does not specify values for the +/// members below. The order matches the specification. +/// +typedef enum { + /// + /// Data flowing in both direction between the host and + /// SPI peripheral.ReadBytes must equal WriteBytes and both ReadBuffer and + /// WriteBuffer must be provided. + /// + SPI_TRANSACTION_FULL_DUPLEX, + + /// + /// Data flowing from the host to the SPI peripheral.ReadBytes must be + /// zero.WriteBytes must be non - zero and WriteBuffer must be provided. + /// + SPI_TRANSACTION_WRITE_ONLY, + + /// + /// Data flowing from the SPI peripheral to the host.WriteBytes must be + /// zero.ReadBytes must be non - zero and ReadBuffer must be provided. + /// + SPI_TRANSACTION_READ_ONLY, + + /// + /// Data first flowing from the host to the SPI peripheral and then data + /// flows from the SPI peripheral to the host.These types of operations get + /// used for SPI flash devices when control data (opcode, address) must be + /// passed to the SPI peripheral to specify the data to be read. + /// + SPI_TRANSACTION_WRITE_THEN_READ +} EFI_SPI_TRANSACTION_TYPE; + +/** + Initiate a SPI transaction between the host and a SPI peripheral. + + This routine must be called at or below TPL_NOTIFY. + This routine works with the SPI bus layer to pass the SPI transaction to the + SPI controller for execution on the SPI bus. There are four types of + supported transactions supported by this routine: + * Full Duplex: WriteBuffer and ReadBuffer are the same size. + * Write Only: WriteBuffer contains data for SPI peripheral, ReadBytes = 0 + * Read Only: ReadBuffer to receive data from SPI peripheral, WriteBytes = 0 + * Write Then Read: WriteBuffer contains control data to write to SPI + peripheral before data is placed into the ReadBuffer. + Both WriteBytes and ReadBytes must be non-zero. + + @param[in] This Pointer to an EFI_SPI_IO_PROTOCOL structure. + @param[in] TransactionType Type of SPI transaction. + @param[in] DebugTransaction Set TRUE only when debugging is desired. + Debugging may be turned on for a single SPI + transaction. Only this transaction will display + debugging messages. All other transactions with + this value set to FALSE will not display any + debugging messages. + @param[in] ClockHz Specify the ClockHz value as zero (0) to use + the maximum clock frequency supported by the + SPI controller and part. Specify a non-zero + value only when a specific SPI transaction + requires a reduced clock rate. + @param[in] BusWidth Width of the SPI bus in bits: 1, 2, 4 + @param[in] FrameSize Frame size in bits, range: 1 - 32 + @param[in] WriteBytes The length of the WriteBuffer in bytes. + Specify zero for read-only operations. + @param[in] WriteBuffer The buffer containing data to be sent from the + host to the SPI chip. Specify NULL for read + only operations. + * Frame sizes 1-8 bits: UINT8 (one byte) per + frame + * Frame sizes 7-16 bits: UINT16 (two bytes) per + frame + * Frame sizes 17-32 bits: UINT32 (four bytes) + per frame The transmit frame is in the least + significant N bits. + @param[in] ReadBytes The length of the ReadBuffer in bytes. + Specify zero for write-only operations. + @param[out] ReadBuffer The buffer to receeive data from the SPI chip + during the transaction. Specify NULL for write + only operations. + * Frame sizes 1-8 bits: UINT8 (one byte) per + frame + * Frame sizes 7-16 bits: UINT16 (two bytes) per + frame + * Frame sizes 17-32 bits: UINT32 (four bytes) + per frame The received frame is in the least + significant N bits. + + @retval EFI_SUCCESS The SPI transaction completed successfully + @retval EFI_BAD_BUFFER_SIZE The writeBytes value was invalid + @retval EFI_BAD_BUFFER_SIZE The ReadBytes value was invalid + @retval EFI_INVALID_PARAMETER TransactionType is not valid, + or BusWidth not supported by SPI peripheral or + SPI host controller, + or WriteBytes non-zero and WriteBuffer is + NULL, + or ReadBytes non-zero and ReadBuffer is NULL, + or ReadBuffer != WriteBuffer for full-duplex + type, + or WriteBuffer was NULL, + or TPL is too high + @retval EFI_OUT_OF_RESOURCES Insufficient memory for SPI transaction + @retval EFI_UNSUPPORTED The FrameSize is not supported by the SPI bus + layer or the SPI host controller + @retval EFI_UNSUPPORTED The SPI controller was not able to support + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_IO_PROTOCOL_TRANSACTION) ( + IN CONST EFI_SPI_IO_PROTOCOL *This, + IN EFI_SPI_TRANSACTION_TYPE TransactionType, + IN BOOLEAN DebugTransaction, + IN UINT32 ClockHz OPTIONAL, + IN UINT32 BusWidth, + IN UINT32 FrameSize, + IN UINT32 WriteBytes, + IN UINT8 *WriteBuffer, + IN UINT32 ReadBytes, + OUT UINT8 *ReadBuffer + ); + +/** + Update the SPI peripheral associated with this SPI 10 instance. + + Support socketed SPI parts by allowing the SPI peripheral driver to replace + the SPI peripheral after the connection is made. An example use is socketed + SPI NOR flash parts, where the size and parameters change depending upon + device is in the socket. + + @param[in] This Pointer to an EFI_SPI_IO_PROTOCOL structure. + @param[in] SpiPeripheral Pointer to an EFI_SPI_PERIPHERAL structure. + + @retval EFI_SUCCESS The SPI peripheral was updated successfully + @retval EFI_INVALID_PARAMETER The SpiPeripheral value is NULL, + or the SpiPeripheral->SpiBus is NULL, + or the SpiP eripheral - >SpiBus pointing at + wrong bus, + or the SpiP eripheral - >SpiPart is NULL + +**/ +typedef EFI_STATUS +(EFIAPI *EFI_SPI_IO_PROTOCOL_UPDATE_SPI_PERIPHERAL) ( + IN CONST EFI_SPI_IO_PROTOCOL *This, + IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral + ); + +/// +/// The EFI_SPI_BUS_ TRANSACTION data structure contains the description of the +/// SPI transaction to perform on the host controller. +/// +typedef struct _EFI_SPI_BUS_TRANSACTION { + /// + /// Pointer to the SPI peripheral being manipulated. + /// + CONST EFI_SPI_PERIPHERAL *SpiPeripheral; + + /// + /// Type of transaction specified by one of the EFI_SPI_TRANSACTION_TYPE + /// values. + /// + EFI_SPI_TRANSACTION_TYPE TransactionType; + + /// + /// TRUE if the transaction is being debugged. Debugging may be turned on for + /// a single SPI transaction. Only this transaction will display debugging + /// messages. All other transactions with this value set to FALSE will not + /// display any debugging messages. + /// + BOOLEAN DebugTransaction; + + /// + /// SPI bus width in bits: 1, 2, 4 + /// + UINT32 BusWidth; + + /// + /// Frame size in bits, range: 1 - 32 + /// + UINT32 FrameSize; + + /// + /// Length of the write buffer in bytes + /// + UINT32 WriteBytes; + + /// + /// Buffer containing data to send to the SPI peripheral + /// Frame sizes 1 - 8 bits: UINT8 (one byte) per frame + /// Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame + /// + UINT8 *WriteBuffer; + + /// + /// Length of the read buffer in bytes + /// + UINT32 ReadBytes; + + /// + /// Buffer to receive the data from the SPI peripheral + /// * Frame sizes 1 - 8 bits: UINT8 (one byte) per frame + /// * Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame + /// * Frame sizes 17 - 32 bits : UINT32 (four bytes) per frame + /// + UINT8 *ReadBuffer; +} EFI_SPI_BUS_TRANSACTION; + +/// +/// Support managed SPI data transactions between the SPI controller and a SPI +/// chip. +/// +struct _EFI_SPI_IO_PROTOCOL { + /// + /// Address of an EFI_SPI_PERIPHERAL data structure associated with this + /// protocol instance. + /// + CONST EFI_SPI_PERIPHERAL *SpiPeripheral; + + /// + /// Address of the original EFI_SPI_PERIPHERAL data structure associated with + /// this protocol instance. + /// + CONST EFI_SPI_PERIPHERAL *OriginalSpiPeripheral; + + /// + /// Mask of frame sizes which the SPI 10 layer supports. Frame size of N-bits + /// is supported when bit N-1 is set. The host controller must support a + /// frame size of 8-bits. Frame sizes of 16, 24 and 32-bits are converted to + /// 8-bit frame sizes by the SPI bus layer if the frame size is not supported + /// by the SPI host controller. + /// + UINT32 FrameSizeSupportMask; + + /// + /// Maximum transfer size in bytes: 1 - Oxffffffff + /// + UINT32 MaximumTransferBytes; + + /// + /// Transaction attributes: One or more from: + /// * SPI_10_SUPPORTS_2_B1T_DATA_BUS_W1DTH + /// - The SPI host and peripheral supports a 2-bit data bus + /// * SPI_IO_SUPPORTS_4_BIT_DATA_BUS_W1DTH + /// - The SPI host and peripheral supports a 4-bit data bus + /// * SPI_IO_TRANSFER_SIZE_INCLUDES_OPCODE + /// - Transfer size includes the opcode byte + /// * SPI_IO_TRANSFER_SIZE_INCLUDES_ADDRESS + /// - Transfer size includes the 3 address bytes + /// + UINT32 Attributes; + + /// + /// Pointer to legacy SPI controller protocol + /// + CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *LegacySpiProtocol; + + /// + /// Initiate a SPI transaction between the host and a SPI peripheral. + /// + EFI_SPI_IO_PROTOCOL_TRANSACTION Transaction; + + /// + /// Update the SPI peripheral associated with this SPI 10 instance. + /// + EFI_SPI_IO_PROTOCOL_UPDATE_SPI_PERIPHERAL UpdateSpiPeripheral; +}; + +#endif // __SPI_IO_PROTOCOL_H__ diff --git a/MdePkg/Include/Protocol/SpiNorFlash.h b/MdePkg/Include/Protocol/SpiNorFlash.h new file mode 100644 index 000000000000..0c9dca79e6f4 --- /dev/null +++ b/MdePkg/Include/Protocol/SpiNorFlash.h @@ -0,0 +1,256 @@ +/** @file + This file defines the SPI NOR Flash Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI PI Specification 1.6. + +**/ + +#ifndef __SPI_NOR_FLASH_PROTOCOL_H__ +#define __SPI_NOR_FLASH_PROTOCOL_H__ + +#include <Protocol/SpiConfiguration.h> + +/// +/// Global ID for the SPI NOR Flash Protocol +/// +#define EFI_SPI_NOR_FLASH_PROTOCOL_GUID \ + { 0xb57ec3fe, 0xf833, 0x4ba6, \ + { 0x85, 0x78, 0x2a, 0x7d, 0x6a, 0x87, 0x44, 0x4b }} + +typedef struct _EFI_SPI_NOR_FLASH_PROTOCOL EFI_SPI_NOR_FLASH_PROTOCOL; + +/** + Read the 3 byte manufacture and device ID from the SPI flash. + + This routine must be called at or below TPL_NOTIFY. + This routine reads the 3 byte manufacture and device ID from the flash part + filling the buffer provided. + + @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data structure. + @param[out] Buffer Pointer to a 3 byte buffer to receive the manufacture and + device ID. + + + + @retval EFI_SUCCESS The manufacture and device ID was read + successfully. + @retval EFI_INVALID_PARAMETER Buffer is NULL + @retval EFI_DEVICE_ERROR Invalid data received from SPI flash part. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_GET_FLASH_ID) ( + IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, + OUT UINT8 *Buffer + ); + +/** + Read data from the SPI flash. + + This routine must be called at or below TPL_NOTIFY. + This routine reads data from the SPI part in the buffer provided. + + @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data + structure. + @param[in] FlashAddress Address in the flash to start reading + @param[in] LengthInBytes Read length in bytes + @param[out] Buffer Address of a buffer to receive the data + + @retval EFI_SUCCESS The data was read successfully. + @retval EFI_INVALID_PARAMETER Buffer is NULL, or + FlashAddress >= This->FlashSize, or + LengthInBytes > This->FlashSize - FlashAddress + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_READ_DATA) ( + IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, + IN UINT32 FlashAddress, + IN UINT32 LengthInBytes, + OUT UINT8 *Buffer + ); + +/** + Read the flash status register. + + This routine must be called at or below TPL_NOTIFY. + This routine reads the flash part status register. + + @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data + structure. + @param[in] LengthInBytes Number of status bytes to read. + @param[out] FlashStatus Pointer to a buffer to receive the flash status. + + @retval EFI_SUCCESS The status register was read successfully. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_READ_STATUS) ( + IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, + IN UINT32 LengthInBytes, + OUT UINT8 *FlashStatus + ); + +/** + Write the flash status register. + + This routine must be called at or below TPL_N OTIFY. + This routine writes the flash part status register. + + @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data + structure. + @param[in] LengthInBytes Number of status bytes to write. + @param[in] FlashStatus Pointer to a buffer containing the new status. + + @retval EFI_SUCCESS The status write was successful. + @retval EFI_OUT_OF_RESOURCES Failed to allocate the write buffer. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_STATUS) ( + IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, + IN UINT32 LengthInBytes, + IN UINT8 *FlashStatus + ); + +/** + Write data to the SPI flash. + + This routine must be called at or below TPL_NOTIFY. + This routine breaks up the write operation as necessary to write the data to + the SPI part. + + @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data + structure. + @param[in] FlashAddress Address in the flash to start writing + @param[in] LengthInBytes Write length in bytes + @param[in] Buffer Address of a buffer containing the data + + @retval EFI_SUCCESS The data was written successfully. + @retval EFI_INVALID_PARAMETER Buffer is NULL, or + FlashAddress >= This->FlashSize, or + LengthInBytes > This->FlashSize - FlashAddress + @retval EFI_OUT_OF_RESOURCES Insufficient memory to copy buffer. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_DATA) ( + IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, + IN UINT32 FlashAddress, + IN UINT32 LengthInBytes, + IN UINT8 *Buffer + ); + +/** + Efficiently erases one or more 4KiB regions in the SPI flash. + + This routine must be called at or below TPL_NOTIFY. + This routine uses a combination of 4 KiB and larger blocks to erase the + specified area. + + @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data + structure. + @param[in] FlashAddress Address within a 4 KiB block to start erasing + @param[in] BlockCount Number of 4 KiB blocks to erase + + @retval EFI_SUCCESS The erase was completed successfully. + @retval EFI_INVALID_PARAMETER FlashAddress >= This->FlashSize, or + BlockCount * 4 KiB + > This->FlashSize - FlashAddress + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_ERASE) ( + IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, + IN UINT32 FlashAddress, + IN UINT32 BlockCount + ); + +/// +/// The EFI_SPI_NOR_FLASH_PROTOCOL exists in the SPI peripheral layer. +/// This protocol manipulates the SPI NOR flash parts using a common set of +/// commands. The board layer provides the interconnection and configuration +/// details for the SPI NOR flash part. The SPI NOR flash driver uses this +/// configuration data to expose a generic interface which provides the +/// following APls: +/// * Read manufacture and device ID +/// * Read data +/// * Read data using low frequency +/// * Read status +/// * Write data +/// * Erase 4 KiB blocks +/// * Erase 32 or 64 KiB blocks +/// * Write status +/// The EFI_SPI_NOR_FLASH_PROTOCOL also exposes some APls to set the security +/// features on the legacy SPI flash controller. +/// +struct _EFI_SPI_NOR_FLASH_PROTOCOL { + /// + /// Pointer to an EFI_SPI_PERIPHERAL data structure + /// + CONST EFI_SPI_PERIPHERAL *SpiPeripheral; + + /// + /// Flash size in bytes + /// + UINT32 FlashSize; + + /// + /// Manufacture and Device ID + /// + UINT8 Deviceid[3]; + + /// + /// Erase block size in bytes + /// + UINT32 EraseBlockBytes; + + /// + /// Read the 3 byte manufacture and device ID from the SPI flash. + /// + EFI_SPI_NOR_FLASH_PROTOCOL_GET_FLASH_ID GetFlashid; + + /// + /// Read data from the SPI flash. + /// + EFI_SPI_NOR_FLASH_PROTOCOL_READ_DATA ReadData; + + /// + /// Low frequency read data from the SPI flash. + /// + EFI_SPI_NOR_FLASH_PROTOCOL_READ_DATA LfReadData; + + /// + /// Read the flash status register. + /// + EFI_SPI_NOR_FLASH_PROTOCOL_READ_STATUS ReadStatus; + + /// + /// Write the flash status register. + /// + EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_STATUS WriteStatus; + + /// + /// Write data to the SPI flash. + /// + EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_DATA WriteData; + + /// + /// Efficiently erases one or more 4KiB regions in the SPI flash. + /// + EFI_SPI_NOR_FLASH_PROTOCOL_ERASE Erase; +}; + +extern EFI_GUID gEfiSpiNorFlashProtocolGuid; + +#endif // __SPI_NOR_FLASH_PROTOCOL_H__ diff --git a/MdePkg/Include/Protocol/SpiSmmConfiguration.h b/MdePkg/Include/Protocol/SpiSmmConfiguration.h new file mode 100644 index 000000000000..8bb713c80e4c --- /dev/null +++ b/MdePkg/Include/Protocol/SpiSmmConfiguration.h @@ -0,0 +1,30 @@ +/** @file + This file defines the SPI SMM Configuration Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI PI Specification 1.6. + +**/ + +#ifndef __SPI_SMM_CONFIGURATION_PROTOCOL_H__ +#define __SPI_SMM_CONFIGURATION_PROTOCOL_H__ + +#include <Protocol/SpiConfiguration.h> + +/// +/// Global ID for the SPI SMM Configuration Protocol +/// +#define EFI_SPI_SMM_CONFIGURATION_PROTOCOL_GUID \ + { 0x995c6eca, 0x171b, 0x45fd, \ + { 0xa3, 0xaa, 0xfd, 0x4c, 0x9c, 0x9d, 0xef, 0x59 }} + +typedef +struct _EFI_SPI_CONFIGURATION_PROTOCOL +EFI_SPI_SMM_CONFIGURATION_PROTOCOL; + +extern EFI_GUID gEfiSpiSmmConfigurationProtocolGuid; + +#endif // __SPI_SMM_CONFIGURATION_H__ diff --git a/MdePkg/Include/Protocol/SpiSmmHc.h b/MdePkg/Include/Protocol/SpiSmmHc.h new file mode 100644 index 000000000000..fb7a25957107 --- /dev/null +++ b/MdePkg/Include/Protocol/SpiSmmHc.h @@ -0,0 +1,30 @@ +/** @file + This file defines the SPI SMM Host Controller Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI PI Specification 1.6. + +**/ + +#ifndef __SPI_SMM_HC_H__ +#define __SPI_SMM_HC_H__ + +#include <Protocol/SpiHc.h> + +/// +/// Global ID for the SPI SMM Host Controller Protocol +/// +#define EFI_SPI_SMM_HC_PROTOCOL_GUID \ + { 0xe9f02217, 0x2093, 0x4470, \ + { 0x8a, 0x54, 0x5c, 0x2c, 0xff, 0xe7, 0x3e, 0xcb }} + +typedef +struct _EFI_SPI_HC_PROTOCOL +EFI_SPI_SMM_HC_PROTOCOL; + +extern EFI_GUID gEfiSpiSmmHcProtocolGuid; + +#endif // __SPI_SMM_HC_H__ diff --git a/MdePkg/Include/Protocol/SpiSmmNorFlash.h b/MdePkg/Include/Protocol/SpiSmmNorFlash.h new file mode 100644 index 000000000000..dfb61f359ef8 --- /dev/null +++ b/MdePkg/Include/Protocol/SpiSmmNorFlash.h @@ -0,0 +1,30 @@ +/** @file + This file defines the SPI SMM NOR Flash Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol was introduced in UEFI PI Specification 1.6. + +**/ + +#ifndef __SPI_SMM_NOR_FLASH_PROTOCOL_H__ +#define __SPI_SMM_NOR_FLASH_PROTOCOL_H__ + +#include <Protocol/SpiNorFlash.h> + +/// +/// Global ID for the SPI SMM NOR Flash Protocol +/// +#define EFI_SPI_SMM_NOR_FLASH_PROTOCOL_GUID \ + { 0xaab18f19, 0xfe14, 0x4666, \ + { 0x86, 0x04, 0x87, 0xff, 0x6d, 0x66, 0x2c, 0x9a } } + +typedef +struct _EFI_SPI_NOR_FLASH_PROTOCOL +EFI_SPI_SMM_NOR_FLASH_PROTOCOL; + +extern EFI_GUID gEfiSpiSmmNorFlashProtocolGuid; + +#endif // __SPI_SMM_NOR_FLASH_PROTOCOL_H__ diff --git a/MdePkg/Include/Protocol/StatusCode.h b/MdePkg/Include/Protocol/StatusCode.h index d5c62260a01d..90b1f63d3b67 100644 --- a/MdePkg/Include/Protocol/StatusCode.h +++ b/MdePkg/Include/Protocol/StatusCode.h @@ -1,14 +1,8 @@ /** @file Status code Runtime Protocol as defined in PI Specification 1.4a VOLUME 2 DXE - Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Protocol/StorageSecurityCommand.h b/MdePkg/Include/Protocol/StorageSecurityCommand.h index 3fa6cbcd8e3b..db38fb491e02 100644 --- a/MdePkg/Include/Protocol/StorageSecurityCommand.h +++ b/MdePkg/Include/Protocol/StorageSecurityCommand.h @@ -5,14 +5,8 @@ storage devices without specific knowledge of the type of device or controller that manages the device. - Copyright (c) 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -149,7 +143,7 @@ EFI_STATUS of the security protocol command. A Timeout value of 0 means that this function will wait indefinitely for the security protocol command to execute. If Timeout is greater - than zero, then this function will return EFI_TIMEOUT if the + than zero, then this function will return EFI_TIMEOUT if the time required to execute the receive data command is greater than Timeout. @param SecurityProtocolId The value of the "Security Protocol" parameter of the security protocol command to be sent. diff --git a/MdePkg/Include/Protocol/SuperIo.h b/MdePkg/Include/Protocol/SuperIo.h index f9714e2d1f87..fb5ea855c970 100644 --- a/MdePkg/Include/Protocol/SuperIo.h +++ b/MdePkg/Include/Protocol/SuperIo.h @@ -5,14 +5,8 @@ Super I/O is powered up, enabled, and assigned with the default set of resources. In the Stop() routine of the Super I/O driver, the device is disabled and Super I/O protocol is uninstalled. - Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -33,12 +27,12 @@ typedef struct { UINT8 AndMask; ///< Bitwise AND mask. UINT8 OrMask; ///< Bitwise OR mask. } EFI_SIO_REGISTER_MODIFY; - + typedef struct _EFI_SIO_PROTOCOL EFI_SIO_PROTOCOL; - + /** Provides a low level access to the registers for the Super I/O. - + @param[in] This Indicates a pointer to the calling context. @param[in] Write Specifies the type of the register operation. If this parameter is TRUE, Value is interpreted as an input parameter and the operation is a register write. If this parameter @@ -53,13 +47,13 @@ typedef struct _EFI_SIO_PROTOCOL EFI_SIO_PROTOCOL; @param[in] Register Register number. @param[in, out] Value If Write is TRUE, Value is a pointer to the buffer containing the byte of data to be written to the Super I/O register. If Write is FALSE, Value is a pointer to the - destination buffer for the byte of data to be read from the Super I/O register. + destination buffer for the byte of data to be read from the Super I/O register. @retval EFI_SUCCESS The operation completed successfully @retval EFI_INVALID_PARAMETER The Value is NULL @retval EFI_INVALID_PARAMETER Invalid Register number - -**/ + +**/ typedef EFI_STATUS (EFIAPI *EFI_SIO_REGISTER_ACCESS)( @@ -69,36 +63,36 @@ EFI_STATUS IN UINT8 Register, IN OUT UINT8 *Value ); - + /** Provides an interface to get a list of the current resources consumed by the device in the ACPI Resource Descriptor format. - + GetResources() returns a list of resources currently consumed by the device. The ResourceList is a pointer to the buffer containing resource descriptors for the device. The descriptors are in the format of Small or Large ACPI resource descriptor as defined by ACPI specification (2.0 & 3.0). The buffer of resource descriptors is terminated with the 'End tag' resource descriptor. - + @param[in] This Indicates a pointer to the calling context. @param[out] ResourceList A pointer to an ACPI resource descriptor list that defines the current resources used by the device. Type ACPI_RESOURCE_HEADER_PTR is defined in the "Related Definitions" below. - + @retval EFI_SUCCESS The operation completed successfully @retval EFI_INVALID_PARAMETER ResourceList is NULL - -**/ + +**/ typedef EFI_STATUS (EFIAPI *EFI_SIO_GET_RESOURCES)( IN CONST EFI_SIO_PROTOCOL *This, OUT ACPI_RESOURCE_HEADER_PTR *ResourceList ); - + /** Sets the resources for the device. - + @param[in] This Indicates a pointer to the calling context. @param[in] ResourceList Pointer to the ACPI resource descriptor list. Type ACPI_RESOURCE_HEADER_PTR is defined in the "Related Definitions" section of @@ -107,35 +101,35 @@ EFI_STATUS @retval EFI_SUCCESS The operation completed successfully @retval EFI_INVALID_PARAMETER ResourceList is invalid @retval EFI_ACCESS_DENIED Some of the resources in ResourceList are in use - -**/ + +**/ typedef EFI_STATUS (EFIAPI *EFI_SIO_SET_RESOURCES)( IN CONST EFI_SIO_PROTOCOL *This, IN ACPI_RESOURCE_HEADER_PTR ResourceList ); - + /** Provides a collection of resource descriptor lists. Each resource descriptor list in the collection defines a combination of resources that can potentially be used by the device. - + @param[in] This Indicates a pointer to the calling context. @param[out] ResourceCollection Collection of the resource descriptor lists. - + @retval EFI_SUCCESS The operation completed successfully @retval EFI_INVALID_PARAMETER ResourceCollection is NULL -**/ +**/ typedef EFI_STATUS (EFIAPI *EFI_SIO_POSSIBLE_RESOURCES)( IN CONST EFI_SIO_PROTOCOL *This, OUT ACPI_RESOURCE_HEADER_PTR *ResourceCollection ); - + /** Provides an interface for a table based programming of the Super I/O registers. - + The Modify() function provides an interface for table based programming of the Super I/O registers. This function can be used to perform programming of multiple Super I/O registers with a single function call. For each table entry, the Register is read, its content is bitwise ANDed with @@ -148,12 +142,12 @@ EFI_STATUS @param[in] Command A pointer to an array of NumberOfCommands EFI_SIO_REGISTER_MODIFY structures. Each structure specifies a single Super I/O register modify operation. Type EFI_SIO_REGISTER_MODIFY is defined in the "Related Definitions" below. - @param[in] NumberOfCommands Number of elements in the Command array. - + @param[in] NumberOfCommands Number of elements in the Command array. + @retval EFI_SUCCESS The operation completed successfully @retval EFI_INVALID_PARAMETER Command is NULL - -**/ + +**/ typedef EFI_STATUS (EFIAPI *EFI_SIO_MODIFY)( @@ -161,14 +155,14 @@ EFI_STATUS IN CONST EFI_SIO_REGISTER_MODIFY *Command, IN UINTN NumberOfCommands ); - + struct _EFI_SIO_PROTOCOL { EFI_SIO_REGISTER_ACCESS RegisterAccess; EFI_SIO_GET_RESOURCES GetResources; EFI_SIO_SET_RESOURCES SetResources; EFI_SIO_POSSIBLE_RESOURCES PossibleResources; EFI_SIO_MODIFY Modify; -}; +}; extern EFI_GUID gEfiSioProtocolGuid; diff --git a/MdePkg/Include/Protocol/SuperIoControl.h b/MdePkg/Include/Protocol/SuperIoControl.h index 0bcfb5a47388..1f2f62345ac5 100644 --- a/MdePkg/Include/Protocol/SuperIoControl.h +++ b/MdePkg/Include/Protocol/SuperIoControl.h @@ -3,14 +3,8 @@ the low-level services for SIO devices that enable them to be used in the UEFI driver model. - Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This protocol is from PI Version 1.2.1. @@ -38,7 +32,7 @@ typedef struct _EFI_SIO_CONTROL_PROTOCOL *PEFI_SIO_CONTROL_PROTOCOL; @retval EFI_SUCCESS The device is enabled successfully. @retval EFI_OUT_OF_RESOURCES The device could not be enabled because there - were insufficient resources either for the device + were insufficient resources either for the device itself or for the records needed to track the device. @retval EFI_ALREADY_STARTED The device is already enabled. @retval EFI_UNSUPPORTED The device cannot be enabled. @@ -61,7 +55,7 @@ EFI_STATUS @retval EFI_SUCCESS The device is disabled successfully. @retval EFI_OUT_OF_RESOURCES The device could not be disabled because there - were insufficient resources either for the device + were insufficient resources either for the device itself or for the records needed to track the device. @retval EFI_ALREADY_STARTED The device is already disabled. @retval EFI_UNSUPPORTED The device cannot be disabled. diff --git a/MdePkg/Include/Protocol/Supplicant.h b/MdePkg/Include/Protocol/Supplicant.h index 6376823c29ed..d7cfc2ad26af 100644 --- a/MdePkg/Include/Protocol/Supplicant.h +++ b/MdePkg/Include/Protocol/Supplicant.h @@ -1,14 +1,8 @@ /** @file This file defines the EFI Supplicant Protocol. - Copyright (c) 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2016 - 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.6 @@ -152,6 +146,10 @@ typedef enum { // EFI_SUPPLICANT_GTK_LIST. // EfiSupplicant80211IGTK, + // + // 802.11 PMK. The corresponding Data is 32 bytes pairwise master key. + // + EfiSupplicant80211PMK, EfiSupplicantDataTypeMaximum } EFI_SUPPLICANT_DATA_TYPE; diff --git a/MdePkg/Include/Protocol/TapeIo.h b/MdePkg/Include/Protocol/TapeIo.h index 74c7b3f6587d..1eac48c2d78a 100644 --- a/MdePkg/Include/Protocol/TapeIo.h +++ b/MdePkg/Include/Protocol/TapeIo.h @@ -2,14 +2,8 @@ EFI_TAPE_IO_PROTOCOL as defined in the UEFI 2.0. Provide services to control and access a tape device. -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -70,13 +64,13 @@ typedef struct _EFI_TAPE_HEADER { from the media. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_TAPE_READ)( IN EFI_TAPE_IO_PROTOCOL *This, IN OUT UINTN *BufferSize, OUT VOID *Buffer - ); + ); /** Writes to the tape. @@ -106,14 +100,14 @@ EFI_STATUS from the media. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_TAPE_WRITE)( IN EFI_TAPE_IO_PROTOCOL *This, IN UINTN *BufferSize, IN VOID *Buffer - ); - + ); + /** Rewinds the tape. @@ -129,11 +123,11 @@ EFI_STATUS @retval EFI_DEVICE_ERROR A device error occurred while attempting to reposition the media. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_TAPE_REWIND)( IN EFI_TAPE_IO_PROTOCOL *This - ); + ); /** @@ -143,7 +137,7 @@ EFI_STATUS @param Direction Direction and number of data blocks or filemarks to space over on media. @param Type Type of mark to space over on media. The following Type marks are mandatory: - BLOCK type : 0 + BLOCK type : 0 FILEMARK type : 1 @retval EFI_SUCCESS The media was successfully repositioned. @@ -166,7 +160,7 @@ EFI_STATUS IN EFI_TAPE_IO_PROTOCOL *This, IN INTN Direction, IN UINTN Type - ); + ); /** @@ -187,12 +181,12 @@ EFI_STATUS @retval EFI_DEVICE_ERROR A device error occurred while attempting to transfer data from the media. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_TAPE_WRITEFM)( IN EFI_TAPE_IO_PROTOCOL *This, IN UINTN Count - ); + ); /** @@ -210,17 +204,17 @@ EFI_STATUS @retval EFI_DEVICE_ERROR A device error occurred while attempting to reset the bus and/or device. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_TAPE_RESET)( IN EFI_TAPE_IO_PROTOCOL *This, IN BOOLEAN ExtendedVerification - ); + ); /// -/// The EFI_TAPE_IO_PROTOCOL provides basic sequential operations for tape devices. -/// These include read, write, rewind, space, write filemarks and reset functions. -/// Per this specification, a boot application uses the services of this protocol +/// The EFI_TAPE_IO_PROTOCOL provides basic sequential operations for tape devices. +/// These include read, write, rewind, space, write filemarks and reset functions. +/// Per this specification, a boot application uses the services of this protocol /// to load the bootloader image from tape. /// struct _EFI_TAPE_IO_PROTOCOL { diff --git a/MdePkg/Include/Protocol/Tcg2Protocol.h b/MdePkg/Include/Protocol/Tcg2Protocol.h index 042bdffa1f71..04a209cfdfe6 100644 --- a/MdePkg/Include/Protocol/Tcg2Protocol.h +++ b/MdePkg/Include/Protocol/Tcg2Protocol.h @@ -2,14 +2,8 @@ TPM2 Protocol as defined in TCG PC Client Platform EFI Protocol Specification Family "2.0". See http://trustedcomputinggroup.org for the latest specification -Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -44,13 +38,13 @@ typedef struct tdEFI_TCG2_BOOT_SERVICE_CAPABILITY { // // Version of the EFI_TCG2_BOOT_SERVICE_CAPABILITY structure itself. // For this version of the protocol, the Major version shall be set to 1 - // and the Minor version shall be set to 1. + // and the Minor version shall be set to 1. // EFI_TCG2_VERSION StructureVersion; // // Version of the EFI TCG2 protocol. // For this version of the protocol, the Major version shall be set to 1 - // and the Minor version shall be set to 1. + // and the Minor version shall be set to 1. // EFI_TCG2_VERSION ProtocolVersion; // @@ -116,7 +110,7 @@ typedef struct tdEFI_TCG2_BOOT_SERVICE_CAPABILITY { typedef struct { // - // Size of the event header itself (sizeof(EFI_TCG2_EVENT_HEADER)). + // Size of the event header itself (sizeof(EFI_TCG2_EVENT_HEADER)). // UINT32 HeaderSize; // @@ -124,18 +118,18 @@ typedef struct { // UINT16 HeaderVersion; // - // Index of the PCR that shall be extended (0 - 23). + // Index of the PCR that shall be extended (0 - 23). // TCG_PCRINDEX PCRIndex; // - // Type of the event that shall be extended (and optionally logged). + // Type of the event that shall be extended (and optionally logged). // TCG_EVENTTYPE EventType; } EFI_TCG2_EVENT_HEADER; typedef struct tdEFI_TCG2_EVENT { // - // Total size of the event including the Size component, the header and the Event data. + // Total size of the event including the Size component, the header and the Event data. // UINT32 Size; EFI_TCG2_EVENT_HEADER Header; @@ -157,11 +151,11 @@ typedef struct tdEFI_TCG2_EVENT { @retval EFI_SUCCESS Operation completed successfully. @retval EFI_DEVICE_ERROR The command was unsuccessful. - The ProtocolCapability variable will not be populated. + The ProtocolCapability variable will not be populated. @retval EFI_INVALID_PARAMETER One or more of the parameters are incorrect. The ProtocolCapability variable will not be populated. @retval EFI_BUFFER_TOO_SMALL The ProtocolCapability variable is too small to hold the full response. - It will be partially populated (required Size field will be set). + It will be partially populated (required Size field will be set). **/ typedef EFI_STATUS @@ -172,7 +166,7 @@ EFI_STATUS /** The EFI_TCG2_PROTOCOL Get Event Log function call allows a caller to - retrieve the address of a given event log and its last entry. + retrieve the address of a given event log and its last entry. @param[in] This Indicates the calling context @param[in] EventLogFormat The type of the event log for which the information is requested. @@ -200,13 +194,13 @@ EFI_STATUS /** The EFI_TCG2_PROTOCOL HashLogExtendEvent function call provides callers with an opportunity to extend and optionally log events without requiring - knowledge of actual TPM commands. + knowledge of actual TPM commands. The extend operation will occur even if this function cannot create an event - log entry (e.g. due to the event log being full). + log entry (e.g. due to the event log being full). @param[in] This Indicates the calling context @param[in] Flags Bitmap providing additional information. - @param[in] DataToHash Physical address of the start of the data buffer to be hashed. + @param[in] DataToHash Physical address of the start of the data buffer to be hashed. @param[in] DataToHashLen The length in bytes of the buffer referenced by DataToHash. @param[in] EfiTcgEvent Pointer to data buffer containing information about the event. @@ -238,7 +232,7 @@ EFI_STATUS @retval EFI_SUCCESS The command byte stream was successfully sent to the device and a response was successfully received. @retval EFI_DEVICE_ERROR The command was not successfully sent to the device or a response was not successfully received from the device. @retval EFI_INVALID_PARAMETER One or more of the parameters are incorrect. - @retval EFI_BUFFER_TOO_SMALL The output parameter block is too small. + @retval EFI_BUFFER_TOO_SMALL The output parameter block is too small. **/ typedef EFI_STATUS @@ -257,7 +251,7 @@ EFI_STATUS @param[out] ActivePcrBanks Pointer to the variable receiving the bitmap of currently active PCR banks. @retval EFI_SUCCESS The bitmap of active PCR banks was stored in the ActivePcrBanks parameter. - @retval EFI_INVALID_PARAMETER One or more of the parameters are incorrect. + @retval EFI_INVALID_PARAMETER One or more of the parameters are incorrect. **/ typedef EFI_STATUS diff --git a/MdePkg/Include/Protocol/TcgService.h b/MdePkg/Include/Protocol/TcgService.h index 7e8ba0c25669..937bd12f2410 100644 --- a/MdePkg/Include/Protocol/TcgService.h +++ b/MdePkg/Include/Protocol/TcgService.h @@ -2,14 +2,8 @@ TCG Service Protocol as defined in TCG_EFI_Protocol_1_22_Final See http://trustedcomputinggroup.org for the latest specification -Copyright (c) 2007 - 2014, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -19,7 +13,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #include <IndustryStandard/UefiTcgPlatform.h> #define EFI_TCG_PROTOCOL_GUID \ - {0xf541796d, 0xa62e, 0x4954, { 0xa7, 0x75, 0x95, 0x84, 0xf6, 0x1b, 0x9c, 0xdd } } + {0xf541796d, 0xa62e, 0x4954, { 0xa7, 0x75, 0x95, 0x84, 0xf6, 0x1b, 0x9c, 0xdd } } typedef struct _EFI_TCG_PROTOCOL EFI_TCG_PROTOCOL; @@ -32,9 +26,9 @@ typedef struct { typedef struct _TCG_EFI_BOOT_SERVICE_CAPABILITY { UINT8 Size; /// Size of this structure. - TCG_VERSION StructureVersion; + TCG_VERSION StructureVersion; TCG_VERSION ProtocolSpecVersion; - UINT8 HashAlgorithmBitmap; /// Hash algorithms . + UINT8 HashAlgorithmBitmap; /// Hash algorithms . /// This protocol is capable of : 01=SHA-1. BOOLEAN TPMPresentFlag; /// 00h = TPM not present. BOOLEAN TPMDeactivatedFlag; /// 01h = TPM currently deactivated. @@ -43,22 +37,22 @@ typedef struct _TCG_EFI_BOOT_SERVICE_CAPABILITY { typedef UINT32 TCG_ALGORITHM_ID; /** - This service provides EFI protocol capability information, state information + This service provides EFI protocol capability information, state information about the TPM, and Event Log state information. @param This Indicates the calling context - @param ProtocolCapability The callee allocates memory for a TCG_BOOT_SERVICE_CAPABILITY - structure and fills in the fields with the EFI protocol + @param ProtocolCapability The callee allocates memory for a TCG_BOOT_SERVICE_CAPABILITY + structure and fills in the fields with the EFI protocol capability information and the current TPM state information. - @param TCGFeatureFlags This is a pointer to the feature flags. No feature - flags are currently defined so this parameter - MUST be set to 0. However, in the future, - feature flags may be defined that, for example, + @param TCGFeatureFlags This is a pointer to the feature flags. No feature + flags are currently defined so this parameter + MUST be set to 0. However, in the future, + feature flags may be defined that, for example, enable hash algorithm agility. @param EventLogLocation This is a pointer to the address of the event log in memory. - @param EventLogLastEntry If the Event Log contains more than one entry, - this is a pointer to the address of the start of - the last entry in the event log in memory. + @param EventLogLastEntry If the Event Log contains more than one entry, + this is a pointer to the address of the start of + the last entry in the event log in memory. @retval EFI_SUCCESS The operation completed successfully. @retval EFI_INVALID_PARAMETER ProtocolCapability does not match TCG capability. @@ -76,14 +70,14 @@ EFI_STATUS /** This service abstracts the capability to do a hash operation on a data buffer. - + @param This Indicates the calling context. @param HashData The pointer to the data buffer to be hashed. @param HashDataLen The length of the data buffer to be hashed. @param AlgorithmId Identification of the Algorithm to use for the hashing operation. @param HashedDataLen Resultant length of the hashed data. @param HashedDataResult Resultant buffer of the hashed data. - + @retval EFI_SUCCESS The operation completed successfully. @retval EFI_INVALID_PARAMETER HashDataLen is NULL. @retval EFI_INVALID_PARAMETER HashDataLenResult is NULL. @@ -106,15 +100,15 @@ EFI_STATUS This service abstracts the capability to add an entry to the Event Log. @param This Indicates the calling context - @param TCGLogData The pointer to the start of the data buffer containing - the TCG_PCR_EVENT data structure. All fields in + @param TCGLogData The pointer to the start of the data buffer containing + the TCG_PCR_EVENT data structure. All fields in this structure are properly filled by the caller. @param EventNumber The event number of the event just logged. - @param Flags Indicates additional flags. Only one flag has been - defined at this time, which is 0x01 and means the - extend operation should not be performed. All - other bits are reserved. - + @param Flags Indicates additional flags. Only one flag has been + defined at this time, which is 0x01 and means the + extend operation should not be performed. All + other bits are reserved. + @retval EFI_SUCCESS The operation completed successfully. @retval EFI_OUT_OF_RESOURCES Insufficient memory in the event log to complete this action. **/ @@ -155,17 +149,17 @@ EFI_STATUS This service abstracts the capability to do a hash operation on a data buffer, extend a specific TPM PCR with the hash result, and add an entry to the Event Log @param This Indicates the calling context - @param HashData The physical address of the start of the data buffer + @param HashData The physical address of the start of the data buffer to be hashed, extended, and logged. @param HashDataLen The length, in bytes, of the buffer referenced by HashData @param AlgorithmId Identification of the Algorithm to use for the hashing operation - @param TCGLogData The physical address of the start of the data + @param TCGLogData The physical address of the start of the data buffer containing the TCG_PCR_EVENT data structure. @param EventNumber The event number of the event just logged. - @param EventLogLastEntry The physical address of the first byte of the entry - just placed in the Event Log. If the Event Log was - empty when this function was called then this physical - address will be the same as the physical address of + @param EventLogLastEntry The physical address of the first byte of the entry + just placed in the Event Log. If the Event Log was + empty when this function was called then this physical + address will be the same as the physical address of the start of the Event Log. @retval EFI_SUCCESS The operation completed successfully. diff --git a/MdePkg/Include/Protocol/Tcp4.h b/MdePkg/Include/Protocol/Tcp4.h index 49d279b013fb..d1fef270f663 100644 --- a/MdePkg/Include/Protocol/Tcp4.h +++ b/MdePkg/Include/Protocol/Tcp4.h @@ -4,14 +4,8 @@ and destroy child of the driver to communicate with other host using TCP protocol. The EFI TCPv4 Protocol provides services to send and receive data stream. -Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.0. diff --git a/MdePkg/Include/Protocol/Tcp6.h b/MdePkg/Include/Protocol/Tcp6.h index b725391518f2..4b3e471b4479 100644 --- a/MdePkg/Include/Protocol/Tcp6.h +++ b/MdePkg/Include/Protocol/Tcp6.h @@ -5,13 +5,7 @@ The EFI TCPv6 Protocol provides services to send and receive data stream. Copyright (c) 2008 - 2014, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.2 diff --git a/MdePkg/Include/Protocol/Timer.h b/MdePkg/Include/Protocol/Timer.h index 29d65215b184..38c0ffe1d998 100644 --- a/MdePkg/Include/Protocol/Timer.h +++ b/MdePkg/Include/Protocol/Timer.h @@ -3,14 +3,8 @@ This code is used to provide the timer tick for the DXE core. - Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -29,10 +23,10 @@ typedef struct _EFI_TIMER_ARCH_PROTOCOL EFI_TIMER_ARCH_PROTOCOL; /** - This function of this type is called when a timer interrupt fires. This + This function of this type is called when a timer interrupt fires. This function executes at TPL_HIGH_LEVEL. The DXE Core will register a function - of this type to be called for the timer interrupt, so it can know how much - time has passed. This information is used to signal timer based events. + of this type to be called for the timer interrupt, so it can know how much + time has passed. This information is used to signal timer based events. @param Time Time since the last timer interrupt in 100 ns units. This will typically be TimerPeriod, but if a timer interrupt is missed, and the @@ -49,16 +43,16 @@ VOID ); /** - This function registers the handler NotifyFunction so it is called every time - the timer interrupt fires. It also passes the amount of time since the last - handler call to the NotifyFunction. If NotifyFunction is NULL, then the - handler is unregistered. If the handler is registered, then EFI_SUCCESS is - returned. If the CPU does not support registering a timer interrupt handler, - then EFI_UNSUPPORTED is returned. If an attempt is made to register a handler - when a handler is already registered, then EFI_ALREADY_STARTED is returned. - If an attempt is made to unregister a handler when a handler is not registered, - then EFI_INVALID_PARAMETER is returned. If an error occurs attempting to - register the NotifyFunction with the timer interrupt, then EFI_DEVICE_ERROR + This function registers the handler NotifyFunction so it is called every time + the timer interrupt fires. It also passes the amount of time since the last + handler call to the NotifyFunction. If NotifyFunction is NULL, then the + handler is unregistered. If the handler is registered, then EFI_SUCCESS is + returned. If the CPU does not support registering a timer interrupt handler, + then EFI_UNSUPPORTED is returned. If an attempt is made to register a handler + when a handler is already registered, then EFI_ALREADY_STARTED is returned. + If an attempt is made to unregister a handler when a handler is not registered, + then EFI_INVALID_PARAMETER is returned. If an error occurs attempting to + register the NotifyFunction with the timer interrupt, then EFI_DEVICE_ERROR is returned. @param This The EFI_TIMER_ARCH_PROTOCOL instance. @@ -77,7 +71,7 @@ VOID @retval EFI_DEVICE_ERROR The timer handler could not be registered. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_TIMER_REGISTER_HANDLER)( IN EFI_TIMER_ARCH_PROTOCOL *This, @@ -85,17 +79,17 @@ EFI_STATUS ); /** - This function adjusts the period of timer interrupts to the value specified - by TimerPeriod. If the timer period is updated, then the selected timer - period is stored in EFI_TIMER.TimerPeriod, and EFI_SUCCESS is returned. If - the timer hardware is not programmable, then EFI_UNSUPPORTED is returned. - If an error occurs while attempting to update the timer period, then the - timer hardware will be put back in its state prior to this call, and - EFI_DEVICE_ERROR is returned. If TimerPeriod is 0, then the timer interrupt - is disabled. This is not the same as disabling the CPU's interrupts. - Instead, it must either turn off the timer hardware, or it must adjust the - interrupt controller so that a CPU interrupt is not generated when the timer - interrupt fires. + This function adjusts the period of timer interrupts to the value specified + by TimerPeriod. If the timer period is updated, then the selected timer + period is stored in EFI_TIMER.TimerPeriod, and EFI_SUCCESS is returned. If + the timer hardware is not programmable, then EFI_UNSUPPORTED is returned. + If an error occurs while attempting to update the timer period, then the + timer hardware will be put back in its state prior to this call, and + EFI_DEVICE_ERROR is returned. If TimerPeriod is 0, then the timer interrupt + is disabled. This is not the same as disabling the CPU's interrupts. + Instead, it must either turn off the timer hardware, or it must adjust the + interrupt controller so that a CPU interrupt is not generated when the timer + interrupt fires. @param This The EFI_TIMER_ARCH_PROTOCOL instance. @param TimerPeriod The rate to program the timer interrupt in 100 nS units. If @@ -110,7 +104,7 @@ EFI_STATUS @retval EFI_DEVICE_ERROR The timer period could not be changed due to a device error. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_TIMER_SET_TIMER_PERIOD)( IN EFI_TIMER_ARCH_PROTOCOL *This, @@ -118,9 +112,9 @@ EFI_STATUS ); /** - This function retrieves the period of timer interrupts in 100 ns units, - returns that value in TimerPeriod, and returns EFI_SUCCESS. If TimerPeriod - is NULL, then EFI_INVALID_PARAMETER is returned. If a TimerPeriod of 0 is + This function retrieves the period of timer interrupts in 100 ns units, + returns that value in TimerPeriod, and returns EFI_SUCCESS. If TimerPeriod + is NULL, then EFI_INVALID_PARAMETER is returned. If a TimerPeriod of 0 is returned, then the timer is currently disabled. @param This The EFI_TIMER_ARCH_PROTOCOL instance. @@ -131,7 +125,7 @@ EFI_STATUS @retval EFI_INVALID_PARAMETER TimerPeriod is NULL. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_TIMER_GET_TIMER_PERIOD)( IN EFI_TIMER_ARCH_PROTOCOL *This, @@ -139,12 +133,12 @@ EFI_STATUS ); /** - This function generates a soft timer interrupt. If the platform does not support soft - timer interrupts, then EFI_UNSUPPORTED is returned. Otherwise, EFI_SUCCESS is returned. - If a handler has been registered through the EFI_TIMER_ARCH_PROTOCOL.RegisterHandler() - service, then a soft timer interrupt will be generated. If the timer interrupt is - enabled when this service is called, then the registered handler will be invoked. The - registered handler should not be able to distinguish a hardware-generated timer + This function generates a soft timer interrupt. If the platform does not support soft + timer interrupts, then EFI_UNSUPPORTED is returned. Otherwise, EFI_SUCCESS is returned. + If a handler has been registered through the EFI_TIMER_ARCH_PROTOCOL.RegisterHandler() + service, then a soft timer interrupt will be generated. If the timer interrupt is + enabled when this service is called, then the registered handler will be invoked. The + registered handler should not be able to distinguish a hardware-generated timer interrupt from a software-generated timer interrupt. @param This The EFI_TIMER_ARCH_PROTOCOL instance. @@ -153,7 +147,7 @@ EFI_STATUS @retval EFI_UNSUPPORTED The platform does not support the generation of soft timer interrupts. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_TIMER_GENERATE_SOFT_INTERRUPT)( IN EFI_TIMER_ARCH_PROTOCOL *This @@ -161,11 +155,11 @@ EFI_STATUS /// -/// This protocol provides the services to initialize a periodic timer +/// This protocol provides the services to initialize a periodic timer /// interrupt, and to register a handler that is called each time the timer /// interrupt fires. It may also provide a service to adjust the rate of the -/// periodic timer interrupt. When a timer interrupt occurs, the handler is -/// passed the amount of time that has passed since the previous timer +/// periodic timer interrupt. When a timer interrupt occurs, the handler is +/// passed the amount of time that has passed since the previous timer /// interrupt. /// struct _EFI_TIMER_ARCH_PROTOCOL { diff --git a/MdePkg/Include/Protocol/Timestamp.h b/MdePkg/Include/Protocol/Timestamp.h index 9746903922e3..38f60bc8768e 100644 --- a/MdePkg/Include/Protocol/Timestamp.h +++ b/MdePkg/Include/Protocol/Timestamp.h @@ -1,19 +1,13 @@ /** @file - EFI Timestamp Protocol as defined in UEFI2.4 Specification. + EFI Timestamp Protocol as defined in UEFI2.4 Specification. Used to provide a platform independent interface for retrieving a high resolution timestamp counter. - - Copyright (c) 2013, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: - This Protocol is introduced in UEFI Specification 2.4 - + + Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol is introduced in UEFI Specification 2.4 + **/ #ifndef __EFI_TIME_STAMP_PROTOCOL_H__ @@ -32,30 +26,30 @@ typedef struct _EFI_TIMESTAMP_PROTOCOL EFI_TIMESTAMP_PROTOCOL; /// EFI_TIMESTAMP_PROPERTIES /// typedef struct { - /// + /// /// The frequency of the timestamp counter in Hz. - /// + /// UINT64 Frequency; - /// + /// /// The value that the timestamp counter ends with immediately before it rolls over. /// For example, a 64-bit free running counter would have an EndValue of 0xFFFFFFFFFFFFFFFF. /// A 24-bit free running counter would have an EndValue of 0xFFFFFF. /// UINT64 EndValue; } EFI_TIMESTAMP_PROPERTIES; - + /** Retrieves the current value of a 64-bit free running timestamp counter. - + The counter shall count up in proportion to the amount of time that has passed. The counter value will always roll over to zero. The properties of the counter can be retrieved from GetProperties(). The caller should be prepared for the function to return the same value twice across successive calls. The counter value will not go backwards other than when wrapping, as defined by EndValue in GetProperties(). - The frequency of the returned timestamp counter value must remain constant. Power management operations that - affect clocking must not change the returned counter frequency. The quantization of counter value updates may + The frequency of the returned timestamp counter value must remain constant. Power management operations that + affect clocking must not change the returned counter frequency. The quantization of counter value updates may vary as long as the value reflecting time passed remains consistent. - @param None. + @param None. @retval The current value of the free running timestamp counter. @@ -71,13 +65,13 @@ UINT64 @param[out] Properties The properties of the timestamp counter. - @retval EFI_SUCCESS The properties were successfully retrieved. - @retval EFI_DEVICE_ERROR An error occurred trying to retrieve the properties of the timestamp - counter subsystem. Properties is not pedated. + @retval EFI_SUCCESS The properties were successfully retrieved. + @retval EFI_DEVICE_ERROR An error occurred trying to retrieve the properties of the timestamp + counter subsystem. Properties is not pedated. @retval EFI_INVALID_PARAMETER Properties is NULL. **/ -typedef +typedef EFI_STATUS (EFIAPI *TIMESTAMP_GET_PROPERTIES)( OUT EFI_TIMESTAMP_PROPERTIES *Properties @@ -87,7 +81,7 @@ EFI_STATUS /// /// EFI_TIMESTAMP_PROTOCOL -/// The protocol provides a platform independent interface for retrieving a high resolution +/// The protocol provides a platform independent interface for retrieving a high resolution /// timestamp counter. /// struct _EFI_TIMESTAMP_PROTOCOL { diff --git a/MdePkg/Include/Protocol/Tls.h b/MdePkg/Include/Protocol/Tls.h index f3cfccc9538f..954918ea5343 100644 --- a/MdePkg/Include/Protocol/Tls.h +++ b/MdePkg/Include/Protocol/Tls.h @@ -7,13 +7,7 @@ The EFI TLS Protocol provides the ability to manage TLS session. Copyright (c) 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.5 @@ -48,10 +42,6 @@ typedef struct _EFI_TLS_PROTOCOL EFI_TLS_PROTOCOL; /// typedef enum { /// - /// Session Configuration - /// - - /// /// TLS session Version. The corresponding Data is of type EFI_TLS_VERSION. /// EfiTlsVersion, @@ -92,11 +82,6 @@ typedef enum { /// The corresponding Data is of type EFI_TLS_SESSION_STATE. /// EfiTlsSessionState, - - /// - /// Session information - /// - /// /// TLS session data client random. /// The corresponding Data is of type EFI_TLS_RANDOM. @@ -112,9 +97,15 @@ typedef enum { /// The corresponding Data is of type EFI_TLS_MASTER_SECRET. /// EfiTlsKeyMaterial, + /// + /// TLS session hostname for validation which is used to verify whether the name + /// within the peer certificate matches a given host name. + /// This parameter is invalid when EfiTlsVerifyMethod is EFI_TLS_VERIFY_NONE. + /// The corresponding Data is of type EFI_TLS_VERIFY_HOST. + /// + EfiTlsVerifyHost, EfiTlsSessionDataTypeMaximum - } EFI_TLS_SESSION_DATA_TYPE; /// @@ -141,10 +132,12 @@ typedef enum { /// Hello Messages". The value of EFI_TLS_CIPHER is from TLS Cipher /// Suite Registry of IANA. /// +#pragma pack (1) typedef struct { UINT8 Data1; UINT8 Data2; } EFI_TLS_CIPHER; +#pragma pack () /// /// EFI_TLS_COMPRESSION @@ -157,11 +150,13 @@ typedef UINT8 EFI_TLS_COMPRESSION; /// Note: The definition of EFI_TLS_EXTENSION if from "RFC 5246 A.4.1. /// Hello Messages". /// +#pragma pack (1) typedef struct { UINT16 ExtensionType; UINT16 Length; UINT8 Data[1]; } EFI_TLS_EXTENSION; +#pragma pack () /// /// EFI_TLS_VERIFY @@ -180,7 +175,8 @@ typedef UINT32 EFI_TLS_VERIFY; /// #define EFI_TLS_VERIFY_PEER 0x1 /// -/// TLS session will fail peer certificate is absent. +/// EFI_TLS_VERIFY_FAIL_IF_NO_PEER_CERT is only meaningful in the server mode. +/// TLS session will fail if client certificate is absent. /// #define EFI_TLS_VERIFY_FAIL_IF_NO_PEER_CERT 0x2 /// @@ -190,33 +186,87 @@ typedef UINT32 EFI_TLS_VERIFY; #define EFI_TLS_VERIFY_CLIENT_ONCE 0x4 /// +/// EFI_TLS_VERIFY_HOST_FLAG +/// +typedef UINT32 EFI_TLS_VERIFY_HOST_FLAG; +/// +/// There is no additional flags set for hostname validation. +/// Wildcards are supported and they match only in the left-most label. +/// +#define EFI_TLS_VERIFY_FLAG_NONE 0x00 +/// +/// Always check the Subject Distinguished Name (DN) in the peer certificate even if the +/// certificate contains Subject Alternative Name (SAN). +/// +#define EFI_TLS_VERIFY_FLAG_ALWAYS_CHECK_SUBJECT 0x01 +/// +/// Disable the match of all wildcards. +/// +#define EFI_TLS_VERIFY_FLAG_NO_WILDCARDS 0x02 +/// +/// Disable the "*" as wildcard in labels that have a prefix or suffix (e.g. "www*" or "*www"). +/// +#define EFI_TLS_VERIFY_FLAG_NO_PARTIAL_WILDCARDS 0x04 +/// +/// Allow the "*" to match more than one labels. Otherwise, only matches a single label. +/// +#define EFI_TLS_VERIFY_FLAG_MULTI_LABEL_WILDCARDS 0x08 +/// +/// Restrict to only match direct child sub-domains which start with ".". +/// For example, a name of ".example.com" would match "www.example.com" with this flag, +/// but would not match "www.sub.example.com". +/// +#define EFI_TLS_VERIFY_FLAG_SINGLE_LABEL_SUBDOMAINS 0x10 +/// +/// Never check the Subject Distinguished Name (DN) even there is no +/// Subject Alternative Name (SAN) in the certificate. +/// +#define EFI_TLS_VERIFY_FLAG_NEVER_CHECK_SUBJECT 0x20 + +/// +/// EFI_TLS_VERIFY_HOST +/// +#pragma pack (1) +typedef struct { + EFI_TLS_VERIFY_HOST_FLAG Flags; + CHAR8 *HostName; +} EFI_TLS_VERIFY_HOST; +#pragma pack () + +/// /// EFI_TLS_RANDOM /// Note: The definition of EFI_TLS_RANDOM is from "RFC 5246 A.4.1. /// Hello Messages". /// +#pragma pack (1) typedef struct { UINT32 GmtUnixTime; UINT8 RandomBytes[28]; } EFI_TLS_RANDOM; +#pragma pack () /// /// EFI_TLS_MASTER_SECRET /// Note: The definition of EFI_TLS_MASTER_SECRET is from "RFC 5246 8.1. /// Computing the Master Secret". /// +#pragma pack (1) typedef struct { UINT8 Data[48]; } EFI_TLS_MASTER_SECRET; +#pragma pack () /// /// EFI_TLS_SESSION_ID /// Note: The definition of EFI_TLS_SESSION_ID is from "RFC 5246 A.4.1. Hello Messages". /// #define MAX_TLS_SESSION_ID_LENGTH 32 +#pragma pack (1) typedef struct { UINT16 Length; UINT8 Data[MAX_TLS_SESSION_ID_LENGTH]; } EFI_TLS_SESSION_ID; +#pragma pack () /// /// EFI_TLS_SESSION_STATE @@ -458,3 +508,4 @@ extern EFI_GUID gEfiTlsServiceBindingProtocolGuid; extern EFI_GUID gEfiTlsProtocolGuid; #endif // __EFI_TLS_PROTOCOL_H__ + diff --git a/MdePkg/Include/Protocol/TlsConfig.h b/MdePkg/Include/Protocol/TlsConfig.h index 012f4ce75e77..367a13751cd8 100644 --- a/MdePkg/Include/Protocol/TlsConfig.h +++ b/MdePkg/Include/Protocol/TlsConfig.h @@ -3,13 +3,7 @@ The EFI TLS Configuration Protocol provides a way to set and get TLS configuration. Copyright (c) 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.5 @@ -34,7 +28,7 @@ typedef struct _EFI_TLS_CONFIGURATION_PROTOCOL EFI_TLS_CONFIGURATION_PROTOCOL; typedef enum { /// /// Local host configuration data: public certificate data. - /// This data should be DER-encoded binary X.509 certificate + /// This data should be DER-encoded binary X.509 certificate /// or PEM-encoded X.509 certificate. /// EfiTlsConfigDataTypeHostPublicCert, @@ -43,7 +37,7 @@ typedef enum { /// EfiTlsConfigDataTypeHostPrivateKey, /// - /// CA certificate to verify peer. This data should be PEM-encoded + /// CA certificate to verify peer. This data should be PEM-encoded /// RSA or PKCS#8 private key. /// EfiTlsConfigDataTypeCACertificate, @@ -130,3 +124,4 @@ struct _EFI_TLS_CONFIGURATION_PROTOCOL { extern EFI_GUID gEfiTlsConfigurationProtocolGuid; #endif //__EFI_TLS_CONFIGURATION_PROTOCOL_H__ + diff --git a/MdePkg/Include/Protocol/TrEEProtocol.h b/MdePkg/Include/Protocol/TrEEProtocol.h index d98cedcee692..db86c1cdc2ad 100644 --- a/MdePkg/Include/Protocol/TrEEProtocol.h +++ b/MdePkg/Include/Protocol/TrEEProtocol.h @@ -1,14 +1,8 @@ /** @file This protocol is defined to abstract TPM2 hardware access in boot phase. -Copyright (c) 2013 - 2016, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -35,19 +29,19 @@ typedef UINT32 TREE_EVENT_LOG_FORMAT; typedef struct _TREE_BOOT_SERVICE_CAPABILITY { // - // Allocated size of the structure passed in + // Allocated size of the structure passed in // UINT8 Size; // // Version of the TREE_BOOT_SERVICE_CAPABILITY structure itself. // For this version of the protocol, the Major version shall be set to 1 - // and the Minor version shall be set to 0. + // and the Minor version shall be set to 0. // TREE_VERSION StructureVersion; // // Version of the TrEE protocol. // For this version of the protocol, the Major version shall be set to 1 - // and the Minor version shall be set to 0. + // and the Minor version shall be set to 0. // TREE_VERSION ProtocolVersion; // @@ -59,20 +53,20 @@ typedef struct _TREE_BOOT_SERVICE_CAPABILITY { // TREE_EVENT_LOG_BITMAP SupportedEventLogs; // - // False = TrEE not present + // False = TrEE not present // BOOLEAN TrEEPresentFlag; // - // Max size (in bytes) of a command that can be sent to the TrEE + // Max size (in bytes) of a command that can be sent to the TrEE // UINT16 MaxCommandSize; // - // Max size (in bytes) of a response that can be provided by the TrEE + // Max size (in bytes) of a response that can be provided by the TrEE // UINT16 MaxResponseSize; // // 4-byte Vendor ID (see Trusted Computing Group, "TCG Vendor ID Registry," - // Version 1.0, Revision 0.1, August 31, 2007, "TPM Capabilities Vendor ID" section) + // Version 1.0, Revision 0.1, August 31, 2007, "TPM Capabilities Vendor ID" section) // UINT32 ManufacturerID; } TREE_BOOT_SERVICE_CAPABILITY_1_0; @@ -103,7 +97,7 @@ typedef UINT32 TrEE_EVENTTYPE; typedef struct { // - // Size of the event header itself (sizeof(TrEE_EVENT_HEADER)). + // Size of the event header itself (sizeof(TrEE_EVENT_HEADER)). // UINT32 HeaderSize; // @@ -111,18 +105,18 @@ typedef struct { // UINT16 HeaderVersion; // - // Index of the PCR that shall be extended (0 - 23). + // Index of the PCR that shall be extended (0 - 23). // TrEE_PCRINDEX PCRIndex; // - // Type of the event that shall be extended (and optionally logged). + // Type of the event that shall be extended (and optionally logged). // TrEE_EVENTTYPE EventType; } TrEE_EVENT_HEADER; typedef struct { // - // Total size of the event including the Size component, the header and the Event data. + // Total size of the event including the Size component, the header and the Event data. // UINT32 Size; TrEE_EVENT_HEADER Header; @@ -144,11 +138,11 @@ typedef struct { @retval EFI_SUCCESS Operation completed successfully. @retval EFI_DEVICE_ERROR The command was unsuccessful. - The ProtocolCapability variable will not be populated. + The ProtocolCapability variable will not be populated. @retval EFI_INVALID_PARAMETER One or more of the parameters are incorrect. The ProtocolCapability variable will not be populated. @retval EFI_BUFFER_TOO_SMALL The ProtocolCapability variable is too small to hold the full response. - It will be partially populated (required Size field will be set). + It will be partially populated (required Size field will be set). **/ typedef EFI_STATUS @@ -159,7 +153,7 @@ EFI_STATUS /** The EFI_TREE_PROTOCOL Get Event Log function call allows a caller to - retrieve the address of a given event log and its last entry. + retrieve the address of a given event log and its last entry. @param[in] This Indicates the calling context @param[in] EventLogFormat The type of the event log for which the information is requested. @@ -187,13 +181,13 @@ EFI_STATUS /** The EFI_TREE_PROTOCOL HashLogExtendEvent function call provides callers with an opportunity to extend and optionally log events without requiring - knowledge of actual TPM commands. + knowledge of actual TPM commands. The extend operation will occur even if this function cannot create an event - log entry (e.g. due to the event log being full). + log entry (e.g. due to the event log being full). @param[in] This Indicates the calling context @param[in] Flags Bitmap providing additional information. - @param[in] DataToHash Physical address of the start of the data buffer to be hashed. + @param[in] DataToHash Physical address of the start of the data buffer to be hashed. @param[in] DataToHashLen The length in bytes of the buffer referenced by DataToHash. @param[in] Event Pointer to data buffer containing information about the event. @@ -225,7 +219,7 @@ EFI_STATUS @retval EFI_SUCCESS The command byte stream was successfully sent to the device and a response was successfully received. @retval EFI_DEVICE_ERROR The command was not successfully sent to the device or a response was not successfully received from the device. @retval EFI_INVALID_PARAMETER One or more of the parameters are incorrect. - @retval EFI_BUFFER_TOO_SMALL The output parameter block is too small. + @retval EFI_BUFFER_TOO_SMALL The output parameter block is too small. **/ typedef EFI_STATUS diff --git a/MdePkg/Include/Protocol/Udp4.h b/MdePkg/Include/Protocol/Udp4.h index 9163866a0b83..7a3bc418cb31 100644 --- a/MdePkg/Include/Protocol/Udp4.h +++ b/MdePkg/Include/Protocol/Udp4.h @@ -1,20 +1,14 @@ /** @file UDP4 Service Binding Protocol as defined in UEFI specification. - The EFI UDPv4 Protocol provides simple packet-oriented services - to transmit and receive UDP packets. + The EFI UDPv4 Protocol provides simple packet-oriented services + to transmit and receive UDP packets. -Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent - @par Revision Reference: - This Protocol is introduced in UEFI Specification 2.0. + @par Revision Reference: + This Protocol is introduced in UEFI Specification 2.0. **/ @@ -35,8 +29,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 0x3ad9df29, 0x4501, 0x478d, {0xb1, 0xf8, 0x7f, 0x7f, 0xe7, 0x0e, 0x50, 0xf3 } \ } -typedef struct _EFI_UDP4_PROTOCOL EFI_UDP4_PROTOCOL; - +typedef struct _EFI_UDP4_PROTOCOL EFI_UDP4_PROTOCOL; + /// /// EFI_UDP4_SERVICE_POINT is deprecated in the UEFI 2.4B and should not be used any more. /// The definition in here is only present to provide backwards compatability. @@ -47,7 +41,7 @@ typedef struct { UINT16 LocalPort; EFI_IPv4_ADDRESS RemoteAddress; UINT16 RemotePort; -} EFI_UDP4_SERVICE_POINT; +} EFI_UDP4_SERVICE_POINT; /// /// EFI_UDP4_VARIABLE_DATA is deprecated in the UEFI 2.4B and should not be used any more. @@ -101,7 +95,7 @@ typedef struct { EFI_UDP4_SESSION_DATA *UdpSessionData; //OPTIONAL EFI_IPv4_ADDRESS *GatewayAddress; //OPTIONAL UINT32 DataLength; - UINT32 FragmentCount; + UINT32 FragmentCount; EFI_UDP4_FRAGMENT_DATA FragmentTable[1]; } EFI_UDP4_TRANSMIT_DATA; @@ -152,13 +146,13 @@ EFI_STATUS OUT EFI_IP4_MODE_DATA *Ip4ModeData OPTIONAL, OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL, OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL - ); - + ); + /** Initializes, changes, or resets the operational parameters for this instance of the EFI UDPv4 Protocol. - + The Configure() function is used to do the following: * Initialize and start this instance of the EFI UDPv4 Protocol. * Change the filtering rules and operational parameters. @@ -190,7 +184,7 @@ EFI_STATUS @retval EFI_OUT_OF_RESOURCES The EFI UDPv4 Protocol driver cannot allocate memory for this EFI UDPv4 Protocol instance. @retval EFI_DEVICE_ERROR An unexpected network or system error occurred and this instance - was not opened. + was not opened. **/ typedef @@ -198,11 +192,11 @@ EFI_STATUS (EFIAPI *EFI_UDP4_CONFIGURE)( IN EFI_UDP4_PROTOCOL *This, IN EFI_UDP4_CONFIG_DATA *UdpConfigData OPTIONAL - ); + ); /** Joins and leaves multicast groups. - + The Groups() function is used to enable and disable the multicast group filtering. If the JoinFlag is FALSE and the MulticastAddress is NULL, then all currently joined groups are left. @@ -235,11 +229,11 @@ EFI_STATUS IN EFI_UDP4_PROTOCOL *This, IN BOOLEAN JoinFlag, IN EFI_IPv4_ADDRESS *MulticastAddress OPTIONAL - ); + ); /** Adds and deletes routing table entries. - + The Routes() function adds a route to or deletes a route from the routing table. Routes are determined by comparing the SubnetAddress with the destination IP address and arithmetically AND-ing it with the SubnetMask. The gateway address @@ -283,11 +277,11 @@ EFI_STATUS IN EFI_IPv4_ADDRESS *SubnetAddress, IN EFI_IPv4_ADDRESS *SubnetMask, IN EFI_IPv4_ADDRESS *GatewayAddress - ); + ); /** Polls for incoming data packets and processes outgoing data packets. - + The Poll() function can be used by network drivers and applications to increase the rate that data packets are moved between the communications device and the transmit and receive queues. @@ -309,11 +303,11 @@ typedef EFI_STATUS (EFIAPI *EFI_UDP4_POLL)( IN EFI_UDP4_PROTOCOL *This - ); + ); /** Places an asynchronous receive request into the receiving queue. - + The Receive() function places a completion token into the receive packet queue. This function is always asynchronous. The caller must fill in the Token.Event field in the completion token, and this @@ -347,11 +341,11 @@ EFI_STATUS (EFIAPI *EFI_UDP4_RECEIVE)( IN EFI_UDP4_PROTOCOL *This, IN EFI_UDP4_COMPLETION_TOKEN *Token - ); + ); /** Queues outgoing data packets into the transmit queue. - + The Transmit() function places a sending request to this instance of the EFI UDPv4 Protocol, alongside the transmit data that was filled by the user. Whenever the packet in the token is sent out or some errors occur, the Token.Event will @@ -384,11 +378,11 @@ EFI_STATUS (EFIAPI *EFI_UDP4_TRANSMIT)( IN EFI_UDP4_PROTOCOL *This, IN EFI_UDP4_COMPLETION_TOKEN *Token - ); + ); /** Aborts an asynchronous transmit or receive request. - + The Cancel() function is used to abort a pending transmit or receive request. If the token is in the transmit or receive request queues, after calling this function, Token.Status will be set to EFI_ABORTED and then Token.Event will be @@ -419,13 +413,13 @@ EFI_STATUS (EFIAPI *EFI_UDP4_CANCEL)( IN EFI_UDP4_PROTOCOL *This, IN EFI_UDP4_COMPLETION_TOKEN *Token OPTIONAL - ); + ); /// -/// The EFI_UDP4_PROTOCOL defines an EFI UDPv4 Protocol session that can be used -/// by any network drivers, applications, or daemons to transmit or receive UDP packets. -/// This protocol instance can either be bound to a specified port as a service or -/// connected to some remote peer as an active client. Each instance has its own settings, +/// The EFI_UDP4_PROTOCOL defines an EFI UDPv4 Protocol session that can be used +/// by any network drivers, applications, or daemons to transmit or receive UDP packets. +/// This protocol instance can either be bound to a specified port as a service or +/// connected to some remote peer as an active client. Each instance has its own settings, /// such as the routing table and group table, which are independent from each other. /// struct _EFI_UDP4_PROTOCOL { diff --git a/MdePkg/Include/Protocol/Udp6.h b/MdePkg/Include/Protocol/Udp6.h index e1e1dc694e86..276392e14ee8 100644 --- a/MdePkg/Include/Protocol/Udp6.h +++ b/MdePkg/Include/Protocol/Udp6.h @@ -3,16 +3,10 @@ the EFI IPv6 Protocol and provides simple packet-oriented services to transmit and receive UDP packets. - Copyright (c) 2008 - 2014, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: + Copyright (c) 2008 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: This Protocol is introduced in UEFI Specification 2.2 **/ @@ -57,7 +51,7 @@ typedef struct { /// EFI_IPv6_ADDRESS RemoteAddress; /// - /// The port number in host byte order on which the remote host is + /// The port number in host byte order on which the remote host is /// listening. Maybe zero if it is not connected to any remote host. /// UINT16 RemotePort; @@ -115,7 +109,7 @@ typedef struct { /// EFI_IPv6_ADDRESS DestinationAddress; /// - /// Port to which this packet is sent. When sending packet, it'll be + /// Port to which this packet is sent. When sending packet, it'll be /// ignored if it is zero. /// UINT16 DestinationPort; @@ -168,7 +162,7 @@ typedef struct { /// /// The port number to which this EFI UDPv6 Protocol instance is bound. If a client /// of the EFI UDPv6 Protocol does not care about the port number, set StationPort - /// to zero. The EFI UDPv6 Protocol driver will assign a random port number to transmitted + /// to zero. The EFI UDPv6 Protocol driver will assign a random port number to transmitted /// UDP packets. Ignored it if AcceptAnyPort is TRUE. /// UINT16 StationPort; @@ -219,8 +213,8 @@ typedef struct { /// packets, the CompletionToken.Packet.RxData field is updated to this incoming packet and /// the CompletionToken.Event is signaled. The EFI UDPv6 Protocol client must signal the /// RecycleSignal after processing the packet. -/// FragmentTable could contain multiple buffers that are not in the continuous memory locations. -/// The EFI UDPv6 Protocol client might need to combine two or more buffers in FragmentTable to +/// FragmentTable could contain multiple buffers that are not in the continuous memory locations. +/// The EFI UDPv6 Protocol client might need to combine two or more buffers in FragmentTable to /// form their own protocol header. /// typedef struct { @@ -271,15 +265,15 @@ typedef struct { /// - EFI_SUCCESS: The receive or transmit operation completed successfully. /// - EFI_ABORTED: The receive or transmit was aborted. /// - EFI_TIMEOUT: The transmit timeout expired. - /// - EFI_NETWORK_UNREACHABLE: The destination network is unreachable. RxData is set to + /// - EFI_NETWORK_UNREACHABLE: The destination network is unreachable. RxData is set to /// NULL in this situation. - /// - EFI_HOST_UNREACHABLE: The destination host is unreachable. RxData is set to NULL in + /// - EFI_HOST_UNREACHABLE: The destination host is unreachable. RxData is set to NULL in /// this situation. - /// - EFI_PROTOCOL_UNREACHABLE: The UDP protocol is unsupported in the remote system. + /// - EFI_PROTOCOL_UNREACHABLE: The UDP protocol is unsupported in the remote system. /// RxData is set to NULL in this situation. - /// - EFI_PORT_UNREACHABLE: No service is listening on the remote port. RxData is set to + /// - EFI_PORT_UNREACHABLE: No service is listening on the remote port. RxData is set to /// NULL in this situation. - /// - EFI_ICMP_ERROR: Some other Internet Control Message Protocol (ICMP) error report was + /// - EFI_ICMP_ERROR: Some other Internet Control Message Protocol (ICMP) error report was /// received. For example, packets are being sent too fast for the destination to receive them /// and the destination sent an ICMP source quench report. RxData is set to NULL in this situation. /// - EFI_DEVICE_ERROR: An unexpected system or network error occurred. @@ -304,7 +298,7 @@ typedef struct { The GetModeData() function copies the current operational settings of this EFI UDPv6 Protocol instance into user-supplied buffers. This function is used optionally to retrieve the operational - mode data of underlying networks or drivers. + mode data of underlying networks or drivers. @param[in] This Pointer to the EFI_UDP6_PROTOCOL instance. @param[out] Udp6ConfigData The buffer in which the current UDP configuration data is returned. @@ -330,13 +324,13 @@ EFI_STATUS ); /** - Initializes, changes, or resets the operational parameters for this instance of the EFI UDPv6 + Initializes, changes, or resets the operational parameters for this instance of the EFI UDPv6 Protocol. The Configure() function is used to do the following: - Initialize and start this instance of the EFI UDPv6 Protocol. - Change the filtering rules and operational parameters. - - Reset this instance of the EFI UDPv6 Protocol. + - Reset this instance of the EFI UDPv6 Protocol. Until these parameters are initialized, no network traffic can be sent or received by this instance. This instance can be also reset by calling Configure() with UdpConfigData set to NULL. @@ -350,7 +344,7 @@ EFI_STATUS @param[in] UdpConfigData Pointer to the buffer contained the configuration data. @retval EFI_SUCCESS The configuration settings were set, changed, or reset successfully. - @retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source + @retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source address for this instance, but no source address was available for use. @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE: - This is NULL. @@ -363,7 +357,7 @@ EFI_STATUS ReceiveTimeout, and TransmitTimeout can be reconfigured without stopping the current instance of the EFI UDPv6 Protocol. @retval EFI_ACCESS_DENIED UdpConfigData.AllowDuplicatePort is FALSE and UdpConfigData.StationPort - is already used by other instance. + is already used by other instance. @retval EFI_OUT_OF_RESOURCES The EFI UDPv6 Protocol driver cannot allocate memory for this EFI UDPv6 Protocol instance. @retval EFI_DEVICE_ERROR An unexpected network or system error occurred and this instance was not @@ -418,7 +412,7 @@ EFI_STATUS receive the notification and transmitting status. @param[in] This Pointer to the EFI_UDP6_PROTOCOL instance. - @param[in] Token Pointer to the completion token that will be placed into the + @param[in] Token Pointer to the completion token that will be placed into the transmit queue. @retval EFI_SUCCESS The data has been queued for transmission. @@ -440,12 +434,12 @@ EFI_STATUS fields is NULL. - Token.Packet.TxData.UdpSessionData.DestinationAddress is not zero and is not valid unicast Ipv6 address if UdpSessionData is not NULL. - - Token.Packet.TxData.UdpSessionData is NULL and this instance's + - Token.Packet.TxData.UdpSessionData is NULL and this instance's UdpConfigData.RemoteAddress is unspecified. - Token.Packet.TxData.UdpSessionData.DestinationAddress is non-zero when DestinationAddress is configured as non-zero when doing Configure() for this EFI Udp6 protocol instance. - - Token.Packet.TxData.UdpSesionData.DestinationAddress is zero when + - Token.Packet.TxData.UdpSesionData.DestinationAddress is zero when DestinationAddress is unspecified when doing Configure() for this EFI Udp6 protocol instance. @retval EFI_ACCESS_DENIED The transmit completion token with the same Token.Event was already @@ -469,7 +463,7 @@ EFI_STATUS The Receive() function places a completion token into the receive packet queue. This function is always asynchronous. - The caller must fill in the Token.Event field in the completion token, and this field cannot be + The caller must fill in the Token.Event field in the completion token, and this field cannot be NULL. When the receive operation completes, the EFI UDPv6 Protocol driver updates the Token.Status and Token.Packet.RxData fields and the Token.Event is signaled. Providing a proper notification function and context for the event will enable the user to receive @@ -487,11 +481,11 @@ EFI_STATUS - This is NULL. - Token is NULL. - Token.Event is NULL. - @retval EFI_OUT_OF_RESOURCES The receive completion token could not be queued due to a lack of system + @retval EFI_OUT_OF_RESOURCES The receive completion token could not be queued due to a lack of system resources (usually memory). @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI UDPv6 Protocol instance has been reset to startup defaults. - @retval EFI_ACCESS_DENIED A receive completion token with the same Token.Event was already in + @retval EFI_ACCESS_DENIED A receive completion token with the same Token.Event was already in the receive queue. @retval EFI_NOT_READY The receive request could not be queued because the receive queue is full. @@ -547,7 +541,7 @@ EFI_STATUS @retval EFI_SUCCESS Incoming or outgoing data was processed. @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. + @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue. Consider increasing the polling rate. @@ -563,7 +557,7 @@ EFI_STATUS /// applications, or daemons to transmit or receive UDP packets. This protocol instance can either be /// bound to a specified port as a service or connected to some remote peer as an active client. /// Each instance has its own settings, such as group table, that are independent from each other. -/// +/// struct _EFI_UDP6_PROTOCOL { EFI_UDP6_GET_MODE_DATA GetModeData; EFI_UDP6_CONFIGURE Configure; diff --git a/MdePkg/Include/Protocol/UfsDeviceConfig.h b/MdePkg/Include/Protocol/UfsDeviceConfig.h new file mode 100644 index 000000000000..33ba120866fc --- /dev/null +++ b/MdePkg/Include/Protocol/UfsDeviceConfig.h @@ -0,0 +1,137 @@ +/** @file + This file defines the EFI UFS Device Config Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Revision Reference: + This Protocol is introduced in UEFI Specification 2.7 + +**/ + +#ifndef __UFS_DEVICE_CONFIG_PROTOCOL_H__ +#define __UFS_DEVICE_CONFIG_PROTOCOL_H__ + +// +// EFI UFS Device Config Protocol GUID value +// +#define EFI_UFS_DEVICE_CONFIG_GUID \ + { 0xb81bfab0, 0xeb3, 0x4cf9, { 0x84, 0x65, 0x7f, 0xa9, 0x86, 0x36, 0x16, 0x64 }}; + +// +// Forward reference for pure ANSI compatability +// +typedef struct _EFI_UFS_DEVICE_CONFIG_PROTOCOL EFI_UFS_DEVICE_CONFIG_PROTOCOL; + +/** + Read or write specified device descriptor of a UFS device. + + The service is used to read/write UFS device descriptors. The consumer of this API is responsible + for allocating the data buffer pointed by Descriptor. + + @param[in] This The pointer to the EFI_UFS_DEVICE_CONFIG_PROTOCOL instance. + @param[in] Read The boolean variable to show r/w direction. + @param[in] DescId The ID of device descriptor. + @param[in] Index The Index of device descriptor. + @param[in] Selector The Selector of device descriptor. + @param[in, out] Descriptor The buffer of device descriptor to be read or written. + @param[in, out] DescSize The size of device descriptor buffer. On input, the size, in bytes, + of the data buffer specified by Descriptor. On output, the number + of bytes that were actually transferred. + + @retval EFI_SUCCESS The device descriptor is read/written successfully. + @retval EFI_INVALID_PARAMETER This is NULL or Descriptor is NULL or DescSize is NULL. + DescId, Index and Selector are invalid combination to point to a + type of UFS device descriptor. + @retval EFI_DEVICE_ERROR The device descriptor is not read/written successfully. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_UFS_DEVICE_CONFIG_RW_DESCRIPTOR) ( + IN EFI_UFS_DEVICE_CONFIG_PROTOCOL *This, + IN BOOLEAN Read, + IN UINT8 DescId, + IN UINT8 Index, + IN UINT8 Selector, + IN OUT UINT8 *Descriptor, + IN OUT UINT32 *DescSize + ); + +/** + Read or write specified flag of a UFS device. + + The service is used to read/write UFS flag descriptors. The consumer of this API is responsible + for allocating the buffer pointed by Flag. The buffer size is 1 byte as UFS flag descriptor is + just a single Boolean value that represents a TRUE or FALSE, '0' or '1', ON or OFF type of value. + + @param[in] This The pointer to the EFI_UFS_DEVICE_CONFIG_PROTOCOL instance. + @param[in] Read The boolean variable to show r/w direction. + @param[in] FlagId The ID of flag to be read or written. + @param[in, out] Flag The buffer to set or clear flag. + + @retval EFI_SUCCESS The flag descriptor is set/clear successfully. + @retval EFI_INVALID_PARAMETER This is NULL or Flag is NULL. + FlagId is an invalid UFS flag ID. + @retval EFI_DEVICE_ERROR The flag is not set/clear successfully. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_UFS_DEVICE_CONFIG_RW_FLAG) ( + IN EFI_UFS_DEVICE_CONFIG_PROTOCOL *This, + IN BOOLEAN Read, + IN UINT8 FlagId, + IN OUT UINT8 *Flag + ); + +/** + Read or write specified attribute of a UFS device. + + The service is used to read/write UFS attributes. The consumer of this API is responsible for + allocating the data buffer pointed by Attribute. + + @param[in] This The pointer to the EFI_UFS_DEVICE_CONFIG_PROTOCOL instance. + @param[in] Read The boolean variable to show r/w direction. + @param[in] AttrId The ID of Attribute. + @param[in] Index The Index of Attribute. + @param[in] Selector The Selector of Attribute. + @param[in, out] Attribute The buffer of Attribute to be read or written. + @param[in, out] AttrSize The size of Attribute buffer. On input, the size, in bytes, of the + data buffer specified by Attribute. On output, the number of bytes + that were actually transferred. + + @retval EFI_SUCCESS The attribute is read/written successfully. + @retval EFI_INVALID_PARAMETER This is NULL or Attribute is NULL or AttrSize is NULL. + AttrId, Index and Selector are invalid combination to point to a + type of UFS attribute. + @retval EFI_DEVICE_ERROR The attribute is not read/written successfully. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_UFS_DEVICE_CONFIG_RW_ATTRIBUTE) ( + IN EFI_UFS_DEVICE_CONFIG_PROTOCOL *This, + IN BOOLEAN Read, + IN UINT8 AttrId, + IN UINT8 Index, + IN UINT8 Selector, + IN OUT UINT8 *Attribute, + IN OUT UINT32 *AttrSize + ); + +/// +/// UFS Device Config Protocol structure. +/// +struct _EFI_UFS_DEVICE_CONFIG_PROTOCOL { + EFI_UFS_DEVICE_CONFIG_RW_DESCRIPTOR RwUfsDescriptor; + EFI_UFS_DEVICE_CONFIG_RW_FLAG RwUfsFlag; + EFI_UFS_DEVICE_CONFIG_RW_ATTRIBUTE RwUfsAttribute; +}; + +/// +/// UFS Device Config Protocol GUID variable. +/// +extern EFI_GUID gEfiUfsDeviceConfigProtocolGuid; + +#endif diff --git a/MdePkg/Include/Protocol/UgaDraw.h b/MdePkg/Include/Protocol/UgaDraw.h index f501a6c17f43..1b2bd17b4c9a 100644 --- a/MdePkg/Include/Protocol/UgaDraw.h +++ b/MdePkg/Include/Protocol/UgaDraw.h @@ -3,14 +3,8 @@ Abstraction of a very simple graphics device. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -92,26 +86,26 @@ typedef enum { ///< directly to every pixel of the video display rectangle ///< (DestinationX, DestinationY) (DestinationX + Width, DestinationY + Height). ///< Only one pixel will be used from the BltBuffer. Delta is NOT used. - + EfiUgaVideoToBltBuffer, ///< Read data from the video display rectangle ///< (SourceX, SourceY) (SourceX + Width, SourceY + Height) and place it in ///< the BltBuffer rectangle (DestinationX, DestinationY ) ///< (DestinationX + Width, DestinationY + Height). If DestinationX or ///< DestinationY is not zero then Delta must be set to the length in bytes ///< of a row in the BltBuffer. - + EfiUgaBltBufferToVideo, ///< Write data from the BltBuffer rectangle ///< (SourceX, SourceY) (SourceX + Width, SourceY + Height) directly to the ///< video display rectangle (DestinationX, DestinationY) ///< (DestinationX + Width, DestinationY + Height). If SourceX or SourceY is ///< not zero then Delta must be set to the length in bytes of a row in the ///< BltBuffer. - + EfiUgaVideoToVideo, ///< Copy from the video display rectangle (SourceX, SourceY) ///< (SourceX + Width, SourceY + Height) .to the video display rectangle ///< (DestinationX, DestinationY) (DestinationX + Width, DestinationY + Height). ///< The BltBuffer and Delta are not used in this mode. - + EfiUgaBltMax ///< Maxmimum value for enumration value of Blt operation. If a Blt operation ///< larger or equal to this enumration value, it is invalid. } EFI_UGA_BLT_OPERATION; @@ -152,8 +146,8 @@ EFI_STATUS ); /// -/// This protocol provides a basic abstraction to set video modes and -/// copy pixels to and from the graphics controller's frame buffer. +/// This protocol provides a basic abstraction to set video modes and +/// copy pixels to and from the graphics controller's frame buffer. /// struct _EFI_UGA_DRAW_PROTOCOL { EFI_UGA_DRAW_PROTOCOL_GET_MODE GetMode; diff --git a/MdePkg/Include/Protocol/UgaIo.h b/MdePkg/Include/Protocol/UgaIo.h index 9638a72240e5..9bfe59683118 100644 --- a/MdePkg/Include/Protocol/UgaIo.h +++ b/MdePkg/Include/Protocol/UgaIo.h @@ -2,15 +2,9 @@ UGA IO protocol from the EFI 1.10 specification. Abstraction of a very simple graphics device. - - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -90,15 +84,15 @@ typedef struct { /** Dynamically allocate storage for a child UGA_DEVICE. - @param[in] This The EFI_UGA_IO_PROTOCOL instance. + @param[in] This The EFI_UGA_IO_PROTOCOL instance. @param[in] ParentDevice ParentDevice specifies a pointer to the parent device of Device. @param[in] DeviceData A pointer to UGA_DEVICE_DATA returned from a call to DispatchService() - with a UGA_DEVICE of Parent and an IoRequest of type UgaIoGetChildDevice. - @param[in] RunTimeContext Context to associate with Device. + with a UGA_DEVICE of Parent and an IoRequest of type UgaIoGetChildDevice. + @param[in] RunTimeContext Context to associate with Device. @param[out] Device The Device returns a dynamically allocated child UGA_DEVICE object for ParentDevice. The caller is responsible for deleting Device. - + @retval EFI_SUCCESS Device was returned. @retval EFI_INVALID_PARAMETER One of the arguments was not valid. @retval EFI_DEVICE_ERROR The device had an error and could not complete the request. @@ -118,12 +112,12 @@ EFI_STATUS /** Delete a dynamically allocated child UGA_DEVICE object that was allocated via CreateDevice(). - @param[in] This The EFI_UGA_IO_PROTOCOL instance. Type EFI_UGA_IO_PROTOCOL is + @param[in] This The EFI_UGA_IO_PROTOCOL instance. Type EFI_UGA_IO_PROTOCOL is defined in Section 10.7. @param[in] Device The Device points to a UGA_DEVICE object that was dynamically allocated via a CreateDevice() call. - + @retval EFI_SUCCESS Device was returned. @retval EFI_INVALID_PARAMETER The Device was not allocated via CreateDevice(). @@ -138,23 +132,23 @@ EFI_STATUS /** This is the main UGA service dispatch routine for all UGA_IO_REQUEST s. - @param pDevice pDevice specifies a pointer to a device object associated with a - device enumerated by a pIoRequest->ioRequestCode of type - UgaIoGetChildDevice. The root device for the EFI_UGA_IO_PROTOCOL + @param pDevice pDevice specifies a pointer to a device object associated with a + device enumerated by a pIoRequest->ioRequestCode of type + UgaIoGetChildDevice. The root device for the EFI_UGA_IO_PROTOCOL is represented by pDevice being set to NULL. - @param pIoRequest + @param pIoRequest pIoRequest points to a caller allocated buffer that contains data defined by pIoRequest->ioRequestCode. See Related Definitions for - a definition of UGA_IO_REQUEST_CODE s and their associated data + a definition of UGA_IO_REQUEST_CODE s and their associated data structures. @return UGA_STATUS **/ -typedef UGA_STATUS +typedef UGA_STATUS (EFIAPI *PUGA_FW_SERVICE_DISPATCH)( - IN PUGA_DEVICE pDevice, + IN PUGA_DEVICE pDevice, IN OUT PUGA_IO_REQUEST pIoRequest ); diff --git a/MdePkg/Include/Protocol/UnicodeCollation.h b/MdePkg/Include/Protocol/UnicodeCollation.h index 96cff3444e4e..a18c36c55b84 100644 --- a/MdePkg/Include/Protocol/UnicodeCollation.h +++ b/MdePkg/Include/Protocol/UnicodeCollation.h @@ -1,16 +1,10 @@ /** @file Unicode Collation protocol that follows the UEFI 2.0 specification. - This protocol is used to allow code running in the boot services environment + This protocol is used to allow code running in the boot services environment to perform lexical comparison functions on Unicode strings for given languages. -Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -32,12 +26,12 @@ typedef struct _EFI_UNICODE_COLLATION_PROTOCOL EFI_UNICODE_COLLATION_PROTOCOL; /// /// Protocol GUID name defined in EFI1.1. -/// +/// #define UNICODE_COLLATION_PROTOCOL EFI_UNICODE_COLLATION_PROTOCOL_GUID /// /// Protocol defined in EFI1.1. -/// +/// typedef EFI_UNICODE_COLLATION_PROTOCOL UNICODE_COLLATION_INTERFACE; /// @@ -69,7 +63,7 @@ INTN ); /** - Performs a case-insensitive comparison of a Null-terminated + Performs a case-insensitive comparison of a Null-terminated pattern string and a Null-terminated string. @param This A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance. @@ -89,7 +83,7 @@ BOOLEAN ); /** - Converts all the characters in a Null-terminated string to + Converts all the characters in a Null-terminated string to lower case characters. @param This A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance. @@ -119,7 +113,7 @@ VOID ); /** - Converts an 8.3 FAT file name in an OEM character set to a Null-terminated + Converts an 8.3 FAT file name in an OEM character set to a Null-terminated string. @param This A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance. @@ -140,13 +134,13 @@ VOID ); /** - Converts a Null-terminated string to legal characters in a FAT - filename using an OEM character set. + Converts a Null-terminated string to legal characters in a FAT + filename using an OEM character set. @param This A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance. @param String A pointer to a Null-terminated string. @param FatSize The size of the string Fat in bytes. - @param Fat A pointer to a string that contains the converted version of + @param Fat A pointer to a string that contains the converted version of String using legal FAT characters from an OEM character set. @retval TRUE One or more conversions failed and were substituted with '_' @@ -163,8 +157,8 @@ BOOLEAN ); /// -/// The EFI_UNICODE_COLLATION_PROTOCOL is used to perform case-insensitive -/// comparisons of strings. +/// The EFI_UNICODE_COLLATION_PROTOCOL is used to perform case-insensitive +/// comparisons of strings. /// struct _EFI_UNICODE_COLLATION_PROTOCOL { EFI_UNICODE_COLLATION_STRICOLL StriColl; @@ -177,7 +171,7 @@ struct _EFI_UNICODE_COLLATION_PROTOCOL { // EFI_UNICODE_COLLATION_FATTOSTR FatToStr; EFI_UNICODE_COLLATION_STRTOFAT StrToFat; - + /// /// A Null-terminated ASCII string array that contains one or more language codes. /// When this field is used for UnicodeCollation2, it is specified in RFC 4646 format. diff --git a/MdePkg/Include/Protocol/Usb2HostController.h b/MdePkg/Include/Protocol/Usb2HostController.h index 6a0e7be80a0c..01538095c469 100644 --- a/MdePkg/Include/Protocol/Usb2HostController.h +++ b/MdePkg/Include/Protocol/Usb2HostController.h @@ -1,17 +1,11 @@ /** @file EFI_USB2_HC_PROTOCOL as defined in UEFI 2.0. - The USB Host Controller Protocol is used by code, typically USB bus drivers, - running in the EFI boot services environment, to perform data transactions over + The USB Host Controller Protocol is used by code, typically USB bus drivers, + running in the EFI boot services environment, to perform data transactions over a USB bus. In addition, it provides an abstraction for the root hub of the USB bus. - Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -37,7 +31,7 @@ typedef struct { } EFI_USB_PORT_STATUS; /// -/// EFI_USB_PORT_STATUS.PortStatus bit definition +/// EFI_USB_PORT_STATUS.PortStatus bit definition /// #define USB_PORT_STAT_CONNECTION 0x0001 #define USB_PORT_STAT_ENABLE 0x0002 @@ -51,7 +45,7 @@ typedef struct { #define USB_PORT_STAT_OWNER 0x2000 /// -/// EFI_USB_PORT_STATUS.PortChangeStatus bit definition +/// EFI_USB_PORT_STATUS.PortChangeStatus bit definition /// #define USB_PORT_STAT_C_CONNECTION 0x0001 #define USB_PORT_STAT_C_ENABLE 0x0002 @@ -62,7 +56,7 @@ typedef struct { /// /// Usb port features value -/// Each value indicates its bit index in the port status and status change bitmaps, +/// Each value indicates its bit index in the port status and status change bitmaps, /// if combines these two bitmaps into a 32-bit bitmap. /// typedef enum { @@ -158,7 +152,7 @@ typedef enum { ///< Explicitly set by software. 3) ///< Triggered by a fatal error such as ///< consistency check failure. - + EfiUsbHcStateOperational, ///< The host controller is in an ///< operational state. When in ///< this state, the host @@ -166,7 +160,7 @@ typedef enum { ///< traffic. This state must be ///< explicitly set to enable the ///< USB bus traffic. - + EfiUsbHcStateSuspend, ///< The host controller is in the ///< suspend state. No USB ///< transactions can occur while in @@ -176,7 +170,7 @@ typedef enum { ///< set by software. 2) Triggered ///< when there is no bus traffic for ///< 3 microseconds. - + EfiUsbHcStateMaximum ///< Maximum value for enumration value of HC status. } EFI_USB_HC_STATE; @@ -413,30 +407,30 @@ EFI_STATUS /** Submits isochronous transfer to an isochronous endpoint of a USB device. - This function is used to submit isochronous transfer to a target endpoint of a USB device. - The target endpoint is specified by DeviceAddressand EndpointAddress. Isochronous transfers are - used when working with isochronous date. It provides periodic, continuous communication between - the host and a device. Isochronous transfers can beused only by full-speed, high-speed, and + This function is used to submit isochronous transfer to a target endpoint of a USB device. + The target endpoint is specified by DeviceAddressand EndpointAddress. Isochronous transfers are + used when working with isochronous date. It provides periodic, continuous communication between + the host and a device. Isochronous transfers can beused only by full-speed, high-speed, and super-speed devices. - High-speed isochronous transfers can be performed using multiple data buffers. The number of + High-speed isochronous transfers can be performed using multiple data buffers. The number of buffers that are actually prepared for the transfer is specified by DataBuffersNumber. For full-speed isochronous transfers this value is ignored. Data represents a list of pointers to the data buffers. For full-speed isochronous transfers only the data pointed by Data[0]shall be used. For high-speed isochronous transfers and for the split transactions depending on DataLengththere several data buffers canbe used. For the - high-speed isochronous transfers the total number of buffers must not exceed EFI_USB_MAX_ISO_BUFFER_NUM. + high-speed isochronous transfers the total number of buffers must not exceed EFI_USB_MAX_ISO_BUFFER_NUM. For split transactions performed on full-speed device by high-speed host controller the total number of buffers is limited to EFI_USB_MAX_ISO_BUFFER_NUM1. - If the isochronous transfer is successful, then EFI_SUCCESSis returned. The isochronous transfer + If the isochronous transfer is successful, then EFI_SUCCESSis returned. The isochronous transfer is designed to be completed within one USB frame time, if it cannot be completed, EFI_TIMEOUT is returned. If an error other than timeout occurs during the USB transfer, then EFI_DEVICE_ERROR is returned and the detailed status code will be returned in TransferResult. EFI_INVALID_PARAMETERis returned if one of the following conditionsis satisfied: - - Data is NULL. + - Data is NULL. - DataLength is 0. - DeviceSpeed is not one of the supported values listed above. - MaximumPacketLength is invalid. MaximumPacketLength must be 1023 or less for full-speed devices, @@ -447,7 +441,7 @@ EFI_STATUS @param DeviceAddress Represents the address of the target device on the USB. @param EndPointAddress The combination of an endpoint number and an endpoint direction of the target USB device. - @param DeviceSpeed Indicates device speed. The supported values are EFI_USB_SPEED_FULL, + @param DeviceSpeed Indicates device speed. The supported values are EFI_USB_SPEED_FULL, EFI_USB_SPEED_HIGH, or EFI_USB_SPEED_SUPER. @param MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of sending or receiving. @@ -497,7 +491,7 @@ EFI_STATUS between the host and a device. Isochronous transfers can be used only by full-speed, high-speed, and super-speed devices. - High-speed isochronous transfers can be performed using multiple data buffers. The number of + High-speed isochronous transfers can be performed using multiple data buffers. The number of buffers that are actually prepared for the transfer is specified by DataBuffersNumber. For full-speed isochronous transfers this value is ignored. @@ -510,17 +504,17 @@ EFI_STATUS number of buffers is limited to EFI_USB_MAX_ISO_BUFFER_NUM1. EFI_INVALID_PARAMETER is returned if one of the following conditionsis satisfied: - - Data is NULL. + - Data is NULL. - DataLength is 0. - DeviceSpeed is not one of the supported values listed above. - - MaximumPacketLength is invalid. MaximumPacketLength must be 1023 or less for full-speed + - MaximumPacketLength is invalid. MaximumPacketLength must be 1023 or less for full-speed devices and 1024 or less for high-speed and super-speed devices. @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. @param DeviceAddress Represents the address of the target device on the USB. @param EndPointAddress The combination of an endpoint number and an endpoint direction of the target USB device. - @param DeviceSpeed Indicates device speed. The supported values are EFI_USB_SPEED_FULL, + @param DeviceSpeed Indicates device speed. The supported values are EFI_USB_SPEED_FULL, EFI_USB_SPEED_HIGH, or EFI_USB_SPEED_SUPER. @param MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of sending or receiving. @@ -622,11 +616,11 @@ EFI_STATUS ); /// -/// The EFI_USB2_HC_PROTOCOL provides USB host controller management, basic -/// data transactions over a USB bus, and USB root hub access. A device driver -/// that wishes to manage a USB bus in a system retrieves the EFI_USB2_HC_PROTOCOL -/// instance that is associated with the USB bus to be managed. A device handle -/// for a USB host controller will minimally contain an EFI_DEVICE_PATH_PROTOCOL +/// The EFI_USB2_HC_PROTOCOL provides USB host controller management, basic +/// data transactions over a USB bus, and USB root hub access. A device driver +/// that wishes to manage a USB bus in a system retrieves the EFI_USB2_HC_PROTOCOL +/// instance that is associated with the USB bus to be managed. A device handle +/// for a USB host controller will minimally contain an EFI_DEVICE_PATH_PROTOCOL /// instance, and an EFI_USB2_HC_PROTOCOL instance. /// struct _EFI_USB2_HC_PROTOCOL { @@ -643,18 +637,18 @@ struct _EFI_USB2_HC_PROTOCOL { EFI_USB2_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS GetRootHubPortStatus; EFI_USB2_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE SetRootHubPortFeature; EFI_USB2_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE ClearRootHubPortFeature; - + /// - /// The major revision number of the USB host controller. The revision information - /// indicates the release of the Universal Serial Bus Specification with which the + /// The major revision number of the USB host controller. The revision information + /// indicates the release of the Universal Serial Bus Specification with which the /// host controller is compliant. /// UINT16 MajorRevision; /// - /// The minor revision number of the USB host controller. The revision information - /// indicates the release of the Universal Serial Bus Specification with which the - /// host controller is compliant. + /// The minor revision number of the USB host controller. The revision information + /// indicates the release of the Universal Serial Bus Specification with which the + /// host controller is compliant. /// UINT16 MinorRevision; }; diff --git a/MdePkg/Include/Protocol/UsbFunctionIo.h b/MdePkg/Include/Protocol/UsbFunctionIo.h index 4422567f1920..3461bfa7fb73 100644 --- a/MdePkg/Include/Protocol/UsbFunctionIo.h +++ b/MdePkg/Include/Protocol/UsbFunctionIo.h @@ -11,14 +11,11 @@ or interrupt transfers, alternate interfaces, or USB 3.0 functionality. Future revisions of this protocol may support these or additional features. - Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + @par Revision Reference: + This Protocol was introduced in UEFI Specification 2.5. **/ @@ -273,9 +270,13 @@ EFI_STATUS as a Unicode string. @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + BufferSize is NULL. + *BufferSize is not 0 and Buffer is NULL. + Id in invalid. @retval EFI_DEVICE_ERROR The physical device reported an error. - @retval EFI_BUFFER_TOO_SMALL Supplied buffer isn't large enough to hold the request string. + @retval EFI_BUFFER_TOO_SMALL The buffer is too small to hold the buffer. + *BufferSize has been updated with the size needed to hold the request string. **/ typedef diff --git a/MdePkg/Include/Protocol/UsbHostController.h b/MdePkg/Include/Protocol/UsbHostController.h index 2196903a0f32..184d2de45061 100644 --- a/MdePkg/Include/Protocol/UsbHostController.h +++ b/MdePkg/Include/Protocol/UsbHostController.h @@ -1,18 +1,12 @@ /** @file EFI_USB_HC_PROTOCOL as defined in EFI 1.10. - The USB Host Controller Protocol is used by code, typically USB bus drivers, - running in the EFI boot services environment, to perform data transactions + The USB Host Controller Protocol is used by code, typically USB bus drivers, + running in the EFI boot services environment, to perform data transactions over a USB bus. In addition, it provides an abstraction for the root hub of the USB bus. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -35,18 +29,18 @@ typedef struct _EFI_USB_HC_PROTOCOL EFI_USB_HC_PROTOCOL; // Protocol definitions // -/** +/** Provides software reset for the USB host controller. - + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param Attributes A bit mask of the reset operation to perform. - + @retval EFI_SUCCESS The reset operation succeeded. @retval EFI_UNSUPPORTED The type of reset specified by Attributes is not currently supported - by the host controller hardware. + by the host controller hardware. @retval EFI_INVALID_PARAMETER Attributes is not valid. @retval EFI_DEVICE_ERROR An error was encountered while attempting to perform the reset operation. - + **/ typedef EFI_STATUS @@ -55,18 +49,18 @@ EFI_STATUS IN UINT16 Attributes ); -/** +/** Retrieves current state of the USB host controller. - + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param State A pointer to the EFI_USB_HC_STATE data structure that - indicates current state of the USB host controller. - + indicates current state of the USB host controller. + @retval EFI_SUCCESS The state information of the host controller was returned in State. @retval EFI_INVALID_PARAMETER State is NULL. @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the host controller's - current state. - + current state. + **/ typedef EFI_STATUS @@ -75,17 +69,17 @@ EFI_STATUS OUT EFI_USB_HC_STATE *State ); -/** +/** Sets the USB host controller to a specific state. - + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. - @param State Indicates the state of the host controller that will be set. - + @param State Indicates the state of the host controller that will be set. + @retval EFI_SUCCESS The USB host controller was successfully placed in the state specified by - State. + State. @retval EFI_INVALID_PARAMETER State is NULL. - @retval EFI_DEVICE_ERROR Failed to set the state specified by State due to device error. - + @retval EFI_DEVICE_ERROR Failed to set the state specified by State due to device error. + **/ typedef EFI_STATUS @@ -94,36 +88,36 @@ EFI_STATUS IN EFI_USB_HC_STATE State ); -/** +/** Submits control transfer to a target USB device. - + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param DeviceAddress Represents the address of the target device on the USB, which is - assigned during USB enumeration. + assigned during USB enumeration. @param IsSlowDevice Indicates whether the target device is slow device or full-speed - device. - @param MaximumPacketLength Indicates the maximum packet size that the default control - transfer endpoint is capable of sending or receiving. + device. + @param MaximumPacketLength Indicates the maximum packet size that the default control + transfer endpoint is capable of sending or receiving. @param Request A pointer to the USB device request that will be sent to the USB device. - @param TransferDirection Specifies the data direction for the transfer. There are three + @param TransferDirection Specifies the data direction for the transfer. There are three values available, EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData. - @param Data A pointer to the buffer of data that will be transmitted to USB - device or received from USB device. + @param Data A pointer to the buffer of data that will be transmitted to USB + device or received from USB device. @param DataLength On input, indicates the size, in bytes, of the data buffer specified - by Data. On output, indicates the amount of data actually - transferred. + by Data. On output, indicates the amount of data actually + transferred. @param TimeOut Indicates the maximum time, in milliseconds, which the transfer - is allowed to complete. - @param TransferResult A pointer to the detailed result information generated by this + is allowed to complete. + @param TransferResult A pointer to the detailed result information generated by this control transfer. - + @retval EFI_SUCCESS The control transfer was completed successfully. - @retval EFI_OUT_OF_RESOURCES The control transfer could not be completed due to a lack of resources. + @retval EFI_OUT_OF_RESOURCES The control transfer could not be completed due to a lack of resources. @retval EFI_INVALID_PARAMETER Some parameters are invalid. @retval EFI_TIMEOUT The control transfer failed due to timeout. @retval EFI_DEVICE_ERROR The control transfer failed due to host controller or device error. - + **/ typedef EFI_STATUS @@ -140,36 +134,36 @@ EFI_STATUS OUT UINT32 *TransferResult ); -/** +/** Submits bulk transfer to a bulk endpoint of a USB device. - + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param DeviceAddress Represents the address of the target device on the USB, which is - assigned during USB enumeration. - @param EndPointAddress The combination of an endpoint number and an endpoint - direction of the target USB device. Each endpoint address - supports data transfer in one direction except the control - endpoint (whose default endpoint address is 0). It is the - caller's responsibility to make sure that the EndPointAddress - represents a bulk endpoint. - @param MaximumPacketLength Indicates the maximum packet size that the default control - transfer endpoint is capable of sending or receiving. - @param Data A pointer to the buffer of data that will be transmitted to USB - device or received from USB device. + assigned during USB enumeration. + @param EndPointAddress The combination of an endpoint number and an endpoint + direction of the target USB device. Each endpoint address + supports data transfer in one direction except the control + endpoint (whose default endpoint address is 0). It is the + caller's responsibility to make sure that the EndPointAddress + represents a bulk endpoint. + @param MaximumPacketLength Indicates the maximum packet size that the default control + transfer endpoint is capable of sending or receiving. + @param Data A pointer to the buffer of data that will be transmitted to USB + device or received from USB device. @param DataLength On input, indicates the size, in bytes, of the data buffer specified - by Data. On output, indicates the amount of data actually - transferred. - @param DataToggle A pointer to the data toggle value. + by Data. On output, indicates the amount of data actually + transferred. + @param DataToggle A pointer to the data toggle value. @param TimeOut Indicates the maximum time, in milliseconds, which the transfer - is allowed to complete. + is allowed to complete. @param TransferResult A pointer to the detailed result information of the bulk transfer. - + @retval EFI_SUCCESS The bulk transfer was completed successfully. - @retval EFI_OUT_OF_RESOURCES The bulk transfer could not be completed due to a lack of resources. + @retval EFI_OUT_OF_RESOURCES The bulk transfer could not be completed due to a lack of resources. @retval EFI_INVALID_PARAMETER Some parameters are invalid. @retval EFI_TIMEOUT The bulk transfer failed due to timeout. @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error. - + **/ typedef EFI_STATUS @@ -185,47 +179,47 @@ EFI_STATUS OUT UINT32 *TransferResult ); -/** +/** Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device. - + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param DeviceAddress Represents the address of the target device on the USB, which is - assigned during USB enumeration. + assigned during USB enumeration. @param EndPointAddress The combination of an endpoint number and an endpoint direction of the target USB device. Each endpoint address supports data transfer in one direction except the control endpoint (whose default endpoint address is zero). It is the caller's responsibility to make sure that the - EndPointAddress represents an interrupt endpoint. + EndPointAddress represents an interrupt endpoint. @param IsSlowDevice Indicates whether the target device is slow device or full-speed - device. - @param MaximumPacketLength Indicates the maximum packet size that the default control - transfer endpoint is capable of sending or receiving. - @param IsNewTransfer If TRUE, an asynchronous interrupt pipe is built between the host - and the target interrupt endpoint. If FALSE, the specified asynchronous - interrupt pipe is canceled. If TRUE, and an interrupt transfer exists - for the target end point, then EFI_INVALID_PARAMETER is returned. - @param DataToggle A pointer to the data toggle value. On input, it is valid when - IsNewTransfer is TRUE, and it indicates the initial data toggle - value the asynchronous interrupt transfer should adopt. On output, - it is valid when IsNewTransfer is FALSE, and it is updated to indicate - the data toggle value of the subsequent asynchronous interrupt transfer. + device. + @param MaximumPacketLength Indicates the maximum packet size that the default control + transfer endpoint is capable of sending or receiving. + @param IsNewTransfer If TRUE, an asynchronous interrupt pipe is built between the host + and the target interrupt endpoint. If FALSE, the specified asynchronous + interrupt pipe is canceled. If TRUE, and an interrupt transfer exists + for the target end point, then EFI_INVALID_PARAMETER is returned. + @param DataToggle A pointer to the data toggle value. On input, it is valid when + IsNewTransfer is TRUE, and it indicates the initial data toggle + value the asynchronous interrupt transfer should adopt. On output, + it is valid when IsNewTransfer is FALSE, and it is updated to indicate + the data toggle value of the subsequent asynchronous interrupt transfer. @param PollingInterval Indicates the interval, in milliseconds, that the asynchronous - interrupt transfer is polled. + interrupt transfer is polled. @param DataLength Indicates the length of data to be received at the rate specified by - PollingInterval from the target asynchronous interrupt - endpoint. This parameter is only required when IsNewTransfer is TRUE. - @param CallBackFunction The Callback function. This function is called at the rate specified by - PollingInterval. This parameter is only required when IsNewTransfer is TRUE. + PollingInterval from the target asynchronous interrupt + endpoint. This parameter is only required when IsNewTransfer is TRUE. + @param CallBackFunction The Callback function. This function is called at the rate specified by + PollingInterval. This parameter is only required when IsNewTransfer is TRUE. @param Context The context that is passed to the CallBackFunction. - + @retval EFI_SUCCESS The asynchronous interrupt transfer request has been successfully - submitted or canceled. - @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + submitted or canceled. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @retval EFI_INVALID_PARAMETER Some parameters are invalid. @retval EFI_TIMEOUT The bulk transfer failed due to timeout. @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error. - + **/ typedef EFI_STATUS @@ -243,41 +237,41 @@ EFI_STATUS IN VOID *Context OPTIONAL ); -/** +/** Submits synchronous interrupt transfer to an interrupt endpoint of a USB device. - + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param DeviceAddress Represents the address of the target device on the USB, which is - assigned during USB enumeration. + assigned during USB enumeration. @param EndPointAddress The combination of an endpoint number and an endpoint direction of the target USB device. Each endpoint address supports data transfer in one direction except the control endpoint (whose default endpoint address is zero). It is the caller's responsibility to make sure that the - EndPointAddress represents an interrupt endpoint. + EndPointAddress represents an interrupt endpoint. @param IsSlowDevice Indicates whether the target device is slow device or full-speed - device. - @param MaximumPacketLength Indicates the maximum packet size that the default control - transfer endpoint is capable of sending or receiving. + device. + @param MaximumPacketLength Indicates the maximum packet size that the default control + transfer endpoint is capable of sending or receiving. @param Data A pointer to the buffer of data that will be transmitted to USB - device or received from USB device. asynchronous interrupt pipe is canceled. + device or received from USB device. asynchronous interrupt pipe is canceled. @param DataLength On input, the size, in bytes, of the data buffer specified by Data. - On output, the number of bytes transferred. - @param DataToggle A pointer to the data toggle value. On input, it indicates the initial - data toggle value the synchronous interrupt transfer should adopt; - on output, it is updated to indicate the data toggle value of the - subsequent synchronous interrupt transfer. - @param TimeOut Indicates the maximum time, in milliseconds, which the transfer - is allowed to complete. + On output, the number of bytes transferred. + @param DataToggle A pointer to the data toggle value. On input, it indicates the initial + data toggle value the synchronous interrupt transfer should adopt; + on output, it is updated to indicate the data toggle value of the + subsequent synchronous interrupt transfer. + @param TimeOut Indicates the maximum time, in milliseconds, which the transfer + is allowed to complete. @param TransferResult A pointer to the detailed result information from the synchronous interrupt transfer. - + @retval EFI_SUCCESS The synchronous interrupt transfer was completed successfully. - @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @retval EFI_INVALID_PARAMETER Some parameters are invalid. @retval EFI_TIMEOUT The synchronous interrupt transfer failed due to timeout. @retval EFI_DEVICE_ERROR The synchronous interrupt transfer failed due to host controller or device error. - + **/ typedef EFI_STATUS @@ -294,33 +288,33 @@ EFI_STATUS OUT UINT32 *TransferResult ); -/** +/** Submits isochronous transfer to an isochronous endpoint of a USB device. - + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param DeviceAddress Represents the address of the target device on the USB, which is - assigned during USB enumeration. + assigned during USB enumeration. @param EndPointAddress The combination of an endpoint number and an endpoint direction of the target USB device. Each endpoint address supports data transfer in one direction except the control endpoint (whose default endpoint address is 0). It is the caller's responsibility to make sure that the EndPointAddress - represents an isochronous endpoint. - @param MaximumPacketLength Indicates the maximum packet size that the default control - transfer endpoint is capable of sending or receiving. + represents an isochronous endpoint. + @param MaximumPacketLength Indicates the maximum packet size that the default control + transfer endpoint is capable of sending or receiving. @param Data A pointer to the buffer of data that will be transmitted to USB - device or received from USB device. asynchronous interrupt pipe is canceled. + device or received from USB device. asynchronous interrupt pipe is canceled. @param DataLength Specifies the length, in bytes, of the data to be sent to or received - from the USB device. + from the USB device. @param TransferResult A pointer to the detailed result information from the isochronous transfer. - + @retval EFI_SUCCESS The isochronous transfer was completed successfully. - @retval EFI_OUT_OF_RESOURCES The isochronous could not be completed due to a lack of resources. + @retval EFI_OUT_OF_RESOURCES The isochronous could not be completed due to a lack of resources. @retval EFI_INVALID_PARAMETER Some parameters are invalid. @retval EFI_TIMEOUT The isochronous transfer failed due to timeout. @retval EFI_DEVICE_ERROR The isochronous transfer failed due to host controller or device error. - + **/ typedef EFI_STATUS @@ -334,36 +328,36 @@ EFI_STATUS OUT UINT32 *TransferResult ); -/** +/** Submits nonblocking isochronous transfer to an isochronous endpoint of a USB device. - + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param DeviceAddress Represents the address of the target device on the USB, which is - assigned during USB enumeration. + assigned during USB enumeration. @param EndPointAddress The combination of an endpoint number and an endpoint direction of the target USB device. Each endpoint address supports data transfer in one direction except the control endpoint (whose default endpoint address is zero). It is the caller's responsibility to make sure that the - EndPointAddress represents an isochronous endpoint. - @param MaximumPacketLength Indicates the maximum packet size that the default control - transfer endpoint is capable of sending or receiving. For isochronous - endpoints, this value is used to reserve the bus time in the schedule, + EndPointAddress represents an isochronous endpoint. + @param MaximumPacketLength Indicates the maximum packet size that the default control + transfer endpoint is capable of sending or receiving. For isochronous + endpoints, this value is used to reserve the bus time in the schedule, required for the perframe data payloads. The pipe may, on an ongoing basis, - actually use less bandwidth than that reserved. + actually use less bandwidth than that reserved. @param Data A pointer to the buffer of data that will be transmitted to USB - device or received from USB device. asynchronous interrupt pipe is canceled. + device or received from USB device. asynchronous interrupt pipe is canceled. @param DataLength Specifies the length, in bytes, of the data to be sent to or received - from the USB device. + from the USB device. @param IsochronousCallback The Callback function.This function is called if the requested isochronous transfer is completed. @param Context Data passed to the IsochronousCallback function. This is an optional parameter and may be NULL. - + @retval EFI_SUCCESS The asynchronous isochronous transfer was completed successfully. - @retval EFI_OUT_OF_RESOURCES The asynchronous isochronous could not be completed due to a lack of resources. + @retval EFI_OUT_OF_RESOURCES The asynchronous isochronous could not be completed due to a lack of resources. @retval EFI_INVALID_PARAMETER Some parameters are invalid. - + **/ typedef EFI_STATUS @@ -378,16 +372,16 @@ EFI_STATUS IN VOID *Context OPTIONAL ); -/** +/** Retrieves the number of root hub ports. - + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. - @param PortNumber A pointer to the number of the root hub ports. - + @param PortNumber A pointer to the number of the root hub ports. + @retval EFI_SUCCESS The port number was retrieved successfully. @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the port number. @retval EFI_INVALID_PARAMETER PortNumber is NULL. - + **/ typedef EFI_STATUS @@ -396,20 +390,20 @@ EFI_STATUS OUT UINT8 *PortNumber ); -/** +/** Retrieves the current status of a USB root hub port. - + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param PortNumber Specifies the root hub port from which the status is to be retrieved. This value is zero based. For example, if a root hub has two ports, then the first port is numbered 0, and the second port is numbered 1. - @param PortStatus A pointer to the current port status bits and port status change bits. - + @param PortStatus A pointer to the current port status bits and port status change bits. + @retval EFI_SUCCESS The status of the USB root hub port specified by PortNumber - was returned in PortStatus. + was returned in PortStatus. @retval EFI_INVALID_PARAMETER PortNumber is invalid. - + **/ typedef EFI_STATUS @@ -419,9 +413,9 @@ EFI_STATUS OUT EFI_USB_PORT_STATUS *PortStatus ); -/** +/** Sets a feature for the specified root hub port. - + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param PortNumber Specifies the root hub port from which the status is to be retrieved. This value is zero based. For example, if a root hub has two ports, @@ -429,11 +423,11 @@ EFI_STATUS numbered 1. @param PortFeature Indicates the feature selector associated with the feature set request. - + @retval EFI_SUCCESS The feature specified by PortFeature was set for the USB - root hub port specified by PortNumber. + root hub port specified by PortNumber. @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function. - + **/ typedef EFI_STATUS @@ -443,9 +437,9 @@ EFI_STATUS IN EFI_USB_PORT_FEATURE PortFeature ); -/** +/** Clears a feature for the specified root hub port. - + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param PortNumber Specifies the root hub port from which the status is to be retrieved. This value is zero based. For example, if a root hub has two ports, @@ -453,11 +447,11 @@ EFI_STATUS numbered 1. @param PortFeature Indicates the feature selector associated with the feature clear request. - + @retval EFI_SUCCESS The feature specified by PortFeature was cleared for the USB - root hub port specified by PortNumber. + root hub port specified by PortNumber. @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function. - + **/ typedef EFI_STATUS @@ -473,7 +467,7 @@ EFI_STATUS /// over a USB bus, and USB root hub access. A device driver that wishes to manage a USB bus in a /// system retrieves the EFI_USB_HC_PROTOCOL instance that is associated with the USB bus to be /// managed. A device handle for a USB host controller will minimally contain an -/// EFI_DEVICE_PATH_PROTOCOL instance, and an EFI_USB_HC_PROTOCOL instance. +/// EFI_DEVICE_PATH_PROTOCOL instance, and an EFI_USB_HC_PROTOCOL instance. /// struct _EFI_USB_HC_PROTOCOL { EFI_USB_HC_PROTOCOL_RESET Reset; @@ -490,16 +484,16 @@ struct _EFI_USB_HC_PROTOCOL { EFI_USB_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE SetRootHubPortFeature; EFI_USB_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE ClearRootHubPortFeature; /// - /// The major revision number of the USB host controller. The revision information - /// indicates the release of the Universal Serial Bus Specification with which the + /// The major revision number of the USB host controller. The revision information + /// indicates the release of the Universal Serial Bus Specification with which the /// host controller is compliant. - /// + /// UINT16 MajorRevision; /// - /// The minor revision number of the USB host controller. The revision information - /// indicates the release of the Universal Serial Bus Specification with which the - /// host controller is compliant. - /// + /// The minor revision number of the USB host controller. The revision information + /// indicates the release of the Universal Serial Bus Specification with which the + /// host controller is compliant. + /// UINT16 MinorRevision; }; diff --git a/MdePkg/Include/Protocol/UsbIo.h b/MdePkg/Include/Protocol/UsbIo.h index cc7263b6aa67..dec246521122 100644 --- a/MdePkg/Include/Protocol/UsbIo.h +++ b/MdePkg/Include/Protocol/UsbIo.h @@ -1,18 +1,12 @@ /** @file EFI Usb I/O Protocol as defined in UEFI specification. - This protocol is used by code, typically drivers, running in the EFI - boot services environment to access USB devices like USB keyboards, - mice and mass storage devices. In particular, functions for managing devices + This protocol is used by code, typically drivers, running in the EFI + boot services environment to access USB devices like USB keyboards, + mice and mass storage devices. In particular, functions for managing devices on USB buses are defined here. - - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -134,13 +128,13 @@ EFI_STATUS typically used to transfer large amounts of data to/from USB devices. @param This A pointer to the EFI_USB_IO_PROTOCOL instance. - @param DeviceEndpoint The destination USB device endpoint to which the - device request is being sent. DeviceEndpoint must - be between 0x01 and 0x0F or between 0x81 and 0x8F, - otherwise EFI_INVALID_PARAMETER is returned. If - the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER - is returned. The MSB of this parameter indicates - the endpoint direction. The number "1" stands for + @param DeviceEndpoint The destination USB device endpoint to which the + device request is being sent. DeviceEndpoint must + be between 0x01 and 0x0F or between 0x81 and 0x8F, + otherwise EFI_INVALID_PARAMETER is returned. If + the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER + is returned. The MSB of this parameter indicates + the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint. @param Data A pointer to the buffer of data that will be transmitted to USB device or received from USB device. @@ -148,8 +142,8 @@ EFI_STATUS On input, the size, in bytes, of the data buffer specified by Data. On output, the number of bytes that were actually transferred. @param Timeout Indicating the transfer should be completed within this time frame. - The units are in milliseconds. If Timeout is 0, then the - caller must wait for the function to be completed until + The units are in milliseconds. If Timeout is 0, then the + caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. @param Status This parameter indicates the USB transfer status. @@ -178,27 +172,27 @@ EFI_STATUS a fixed rate. @param This A pointer to the EFI_USB_IO_PROTOCOL instance. - @param DeviceEndpoint The destination USB device endpoint to which the - device request is being sent. DeviceEndpoint must - be between 0x01 and 0x0F or between 0x81 and 0x8F, - otherwise EFI_INVALID_PARAMETER is returned. If - the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER - is returned. The MSB of this parameter indicates - the endpoint direction. The number "1" stands for + @param DeviceEndpoint The destination USB device endpoint to which the + device request is being sent. DeviceEndpoint must + be between 0x01 and 0x0F or between 0x81 and 0x8F, + otherwise EFI_INVALID_PARAMETER is returned. If + the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER + is returned. The MSB of this parameter indicates + the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint. @param IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If FALSE, the interrupt transfer is deleted from the device's interrupt transfer queue. @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be - executed.This parameter is required when IsNewTransfer is TRUE. The - value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned. + executed.This parameter is required when IsNewTransfer is TRUE. The + value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned. The units are in milliseconds. @param DataLength Specifies the length, in bytes, of the data to be received from the USB device. This parameter is only required when IsNewTransfer is TRUE. @param InterruptCallback The Callback function. This function is called if the asynchronous - interrupt transfer is completed. This parameter is required + interrupt transfer is completed. This parameter is required when IsNewTransfer is TRUE. - @param Context Data passed to the InterruptCallback function. This is an optional + @param Context Data passed to the InterruptCallback function. This is an optional parameter and may be NULL. @retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed. @@ -221,21 +215,21 @@ EFI_STATUS This function is used to manage a USB device with an interrupt transfer pipe. @param This A pointer to the EFI_USB_IO_PROTOCOL instance. - @param DeviceEndpoint The destination USB device endpoint to which the - device request is being sent. DeviceEndpoint must - be between 0x01 and 0x0F or between 0x81 and 0x8F, - otherwise EFI_INVALID_PARAMETER is returned. If - the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER - is returned. The MSB of this parameter indicates - the endpoint direction. The number "1" stands for + @param DeviceEndpoint The destination USB device endpoint to which the + device request is being sent. DeviceEndpoint must + be between 0x01 and 0x0F or between 0x81 and 0x8F, + otherwise EFI_INVALID_PARAMETER is returned. If + the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER + is returned. The MSB of this parameter indicates + the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint. @param Data A pointer to the buffer of data that will be transmitted to USB device or received from USB device. @param DataLength On input, then size, in bytes, of the buffer Data. On output, the amount of data actually transferred. - @param Timeout The time out, in seconds, for this transfer. If Timeout is 0, - then the caller must wait for the function to be completed - until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the + @param Timeout The time out, in seconds, for this transfer. If Timeout is 0, + then the caller must wait for the function to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the transfer is not completed in this time frame, then EFI_TIMEOUT is returned. @param Status This parameter indicates the USB transfer status. @@ -261,13 +255,13 @@ EFI_STATUS transfer is typically used to transfer streaming data. @param This A pointer to the EFI_USB_IO_PROTOCOL instance. - @param DeviceEndpoint The destination USB device endpoint to which the - device request is being sent. DeviceEndpoint must - be between 0x01 and 0x0F or between 0x81 and 0x8F, - otherwise EFI_INVALID_PARAMETER is returned. If - the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER - is returned. The MSB of this parameter indicates - the endpoint direction. The number "1" stands for + @param DeviceEndpoint The destination USB device endpoint to which the + device request is being sent. DeviceEndpoint must + be between 0x01 and 0x0F or between 0x81 and 0x8F, + otherwise EFI_INVALID_PARAMETER is returned. If + the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER + is returned. The MSB of this parameter indicates + the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint. @param Data A pointer to the buffer of data that will be transmitted to USB device or received from USB device. @@ -296,19 +290,19 @@ EFI_STATUS transfer is typically used to transfer streaming data. @param This A pointer to the EFI_USB_IO_PROTOCOL instance. - @param DeviceEndpoint The destination USB device endpoint to which the - device request is being sent. DeviceEndpoint must - be between 0x01 and 0x0F or between 0x81 and 0x8F, - otherwise EFI_INVALID_PARAMETER is returned. If - the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER - is returned. The MSB of this parameter indicates - the endpoint direction. The number "1" stands for + @param DeviceEndpoint The destination USB device endpoint to which the + device request is being sent. DeviceEndpoint must + be between 0x01 and 0x0F or between 0x81 and 0x8F, + otherwise EFI_INVALID_PARAMETER is returned. If + the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER + is returned. The MSB of this parameter indicates + the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint. @param Data A pointer to the buffer of data that will be transmitted to USB device or received from USB device. @param DataLength The size, in bytes, of the data buffer specified by Data. This is an optional parameter and may be NULL. - @param IsochronousCallback The IsochronousCallback() function.This function is + @param IsochronousCallback The IsochronousCallback() function.This function is called if the requested isochronous transfer is completed. @param Context Data passed to the IsochronousCallback() function. @@ -432,9 +426,9 @@ EFI_STATUS @param LangID The Language ID for the string being retrieved. @param StringID The ID of the string being retrieved. @param String A pointer to a buffer allocated by this function with - AllocatePool() to store the string.If this function - returns EFI_SUCCESS, it stores the string the caller - wants to get. The caller should release the string + AllocatePool() to store the string.If this function + returns EFI_SUCCESS, it stores the string the caller + wants to get. The caller should release the string buffer with FreePool() after the string is not used any more. @retval EFI_SUCCESS The string was retrieved successfully. @@ -456,9 +450,9 @@ EFI_STATUS @param This A pointer to the EFI_USB_IO_PROTOCOL instance. @param LangIDTable Language ID for the string the caller wants to get. - This is a 16-bit ID defined by Microsoft. This - buffer pointer is allocated and maintained by - the USB Bus Driver, the caller should not modify + This is a 16-bit ID defined by Microsoft. This + buffer pointer is allocated and maintained by + the USB Bus Driver, the caller should not modify its contents. @param TableSize The size, in bytes, of the table LangIDTable. @@ -474,11 +468,11 @@ EFI_STATUS ); /// -/// The EFI_USB_IO_PROTOCOL provides four basic transfers types described -/// in the USB 1.1 Specification. These include control transfer, interrupt -/// transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL -/// also provides some basic USB device/controller management and configuration -/// interfaces. A USB device driver uses the services of this protocol to manage USB devices. +/// The EFI_USB_IO_PROTOCOL provides four basic transfers types described +/// in the USB 1.1 Specification. These include control transfer, interrupt +/// transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL +/// also provides some basic USB device/controller management and configuration +/// interfaces. A USB device driver uses the services of this protocol to manage USB devices. /// struct _EFI_USB_IO_PROTOCOL { // diff --git a/MdePkg/Include/Protocol/UserCredential.h b/MdePkg/Include/Protocol/UserCredential.h index 6dea64358732..d572f97b774b 100644 --- a/MdePkg/Include/Protocol/UserCredential.h +++ b/MdePkg/Include/Protocol/UserCredential.h @@ -4,14 +4,8 @@ Attached to a device handle, this protocol identifies a single means of identifying the user. - Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -31,16 +25,16 @@ typedef struct _EFI_USER_CREDENTIAL_PROTOCOL EFI_USER_CREDENTIAL_PROTOCOL; Enroll a user on a credential provider. This function enrolls and deletes a user profile using this credential provider. If a user profile - is successfully enrolled, it calls the User Manager Protocol function Notify() to notify the user - manager driver that credential information has changed. If an enrolled user does exist, delete the + is successfully enrolled, it calls the User Manager Protocol function Notify() to notify the user + manager driver that credential information has changed. If an enrolled user does exist, delete the user on the credential provider. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL_PROTOCOL. @param[in] User The user profile to enroll. - + @retval EFI_SUCCESS User profile was successfully enrolled. - @retval EFI_ACCESS_DENIED Current user profile does not permit enrollment on the user profile - handle. Either the user profile cannot enroll on any user profile or + @retval EFI_ACCESS_DENIED Current user profile does not permit enrollment on the user profile + handle. Either the user profile cannot enroll on any user profile or cannot enroll on a user profile other than the current user profile. @retval EFI_UNSUPPORTED This credential provider does not support enrollment in the pre-OS. @retval EFI_DEVICE_ERROR The new credential could not be created because of a device error. @@ -56,19 +50,19 @@ EFI_STATUS /** Returns the user interface information used during user identification. - This function returns information about the form used when interacting with the user during user - identification. The form is the first enabled form in the form-set class - EFI_HII_USER_CREDENTIAL_FORMSET_GUID installed on the HII handle HiiHandle. If - the user credential provider does not require a form to identify the user, then this function should + This function returns information about the form used when interacting with the user during user + identification. The form is the first enabled form in the form-set class + EFI_HII_USER_CREDENTIAL_FORMSET_GUID installed on the HII handle HiiHandle. If + the user credential provider does not require a form to identify the user, then this function should return EFI_NOT_FOUND. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL_PROTOCOL. @param[out] Hii On return, holds the HII database handle. @param[out] FormSetId On return, holds the identifier of the form set which contains the form used during user identification. - @param[out] FormId On return, holds the identifier of the form used during user + @param[out] FormId On return, holds the identifier of the form used during user identification. - + @retval EFI_SUCCESS Form returned successfully. @retval EFI_NOT_FOUND Form not returned. @retval EFI_INVALID_PARAMETER Hii is NULL or FormSetId is NULL or FormId is NULL. @@ -85,19 +79,19 @@ EFI_STATUS /** Returns bitmap used to describe the credential provider type. - This optional function returns a bitmap which is less than or equal to the number of pixels specified - by Width and Height. If no such bitmap exists, then EFI_NOT_FOUND is returned. + This optional function returns a bitmap which is less than or equal to the number of pixels specified + by Width and Height. If no such bitmap exists, then EFI_NOT_FOUND is returned. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL_PROTOCOL. @param[in, out] Width On entry, points to the desired bitmap width. If NULL then no bitmap - information will be returned. On exit, points to the width of the + information will be returned. On exit, points to the width of the bitmap returned. - @param[in, out] Height On entry, points to the desired bitmap height. If NULL then no bitmap - information will be returned. On exit, points to the height of the + @param[in, out] Height On entry, points to the desired bitmap height. If NULL then no bitmap + information will be returned. On exit, points to the height of the bitmap returned - @param[out] Hii On return, holds the HII database handle. - @param[out] Image On return, holds the HII image identifier. - + @param[out] Hii On return, holds the HII database handle. + @param[out] Image On return, holds the HII image identifier. + @retval EFI_SUCCESS Image identifier returned successfully. @retval EFI_NOT_FOUND Image identifier not returned. @retval EFI_INVALID_PARAMETER Hii is NULL or Image is NULL. @@ -115,13 +109,13 @@ EFI_STATUS /** Returns string used to describe the credential provider type. - This function returns a string which describes the credential provider. If no such string exists, then - EFI_NOT_FOUND is returned. + This function returns a string which describes the credential provider. If no such string exists, then + EFI_NOT_FOUND is returned. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL_PROTOCOL. @param[out] Hii On return, holds the HII database handle. @param[out] String On return, holds the HII string identifier. - + @retval EFI_SUCCESS String identifier returned successfully. @retval EFI_NOT_FOUND String identifier not returned. @retval EFI_INVALID_PARAMETER Hii is NULL or String is NULL. @@ -137,21 +131,21 @@ EFI_STATUS /** Return the user identifier associated with the currently authenticated user. - This function returns the user identifier of the user authenticated by this credential provider. This - function is called after the credential-related information has been submitted on a form OR after a + This function returns the user identifier of the user authenticated by this credential provider. This + function is called after the credential-related information has been submitted on a form OR after a call to Default() has returned that this credential is ready to log on. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL_PROTOCOL. - @param[in] User The user profile handle of the user profile currently being considered - by the user identity manager. If NULL, then no user profile is currently + @param[in] User The user profile handle of the user profile currently being considered + by the user identity manager. If NULL, then no user profile is currently under consideration. - @param[out] Identifier On return, points to the user identifier. - + @param[out] Identifier On return, points to the user identifier. + @retval EFI_SUCCESS User identifier returned successfully. @retval EFI_NOT_READY No user identifier can be returned. @retval EFI_ACCESS_DENIED The user has been locked out of this user credential. - @retval EFI_NOT_FOUND User is not NULL, and the specified user handle can't be found in user - profile database + @retval EFI_NOT_FOUND User is not NULL, and the specified user handle can't be found in user + profile database @retval EFI_INVALID_PARAMETER Identifier is NULL. **/ typedef @@ -165,13 +159,13 @@ EFI_STATUS /** Indicate that user interface interaction has begun for the specified credential. - This function is called when a credential provider is selected by the user. If AutoLogon returns - FALSE, then the user interface will be constructed by the User Identity Manager. + This function is called when a credential provider is selected by the user. If AutoLogon returns + FALSE, then the user interface will be constructed by the User Identity Manager. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL_PROTOCOL. - @param[out] AutoLogon On return, points to the credential provider's capabilities after - the credential provider has been selected by the user. - + @param[out] AutoLogon On return, points to the credential provider's capabilities after + the credential provider has been selected by the user. + @retval EFI_SUCCESS Credential provider successfully selected. @retval EFI_INVALID_PARAMETER AutoLogon is NULL. **/ @@ -180,7 +174,7 @@ EFI_STATUS (EFIAPI *EFI_CREDENTIAL_SELECT)( IN CONST EFI_USER_CREDENTIAL_PROTOCOL *This, OUT EFI_CREDENTIAL_LOGON_FLAGS *AutoLogon - ); + ); /** Indicate that user interface interaction has ended for the specified credential. @@ -188,7 +182,7 @@ EFI_STATUS This function is called when a credential provider is deselected by the user. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL_PROTOCOL. - + @retval EFI_SUCCESS Credential provider successfully deselected. **/ typedef @@ -200,16 +194,16 @@ EFI_STATUS /** Return the default logon behavior for this user credential. - This function reports the default login behavior regarding this credential provider. + This function reports the default login behavior regarding this credential provider. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL_PROTOCOL. - @param[out] AutoLogon On return, holds whether the credential provider should be - used by default to automatically log on the user. - + @param[out] AutoLogon On return, holds whether the credential provider should be + used by default to automatically log on the user. + @retval EFI_SUCCESS Default information successfully returned. @retval EFI_INVALID_PARAMETER AutoLogon is NULL. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_CREDENTIAL_DEFAULT)( IN CONST EFI_USER_CREDENTIAL_PROTOCOL *This, @@ -219,22 +213,22 @@ EFI_STATUS /** Return information attached to the credential provider. - This function returns user information. + This function returns user information. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL_PROTOCOL. - @param[in] UserInfo Handle of the user information data record. - @param[out] Info On entry, points to a buffer of at least *InfoSize bytes. On exit, holds the user - information. If the buffer is too small to hold the information, then - EFI_BUFFER_TOO_SMALL is returned and InfoSize is updated to contain the + @param[in] UserInfo Handle of the user information data record. + @param[out] Info On entry, points to a buffer of at least *InfoSize bytes. On exit, holds the user + information. If the buffer is too small to hold the information, then + EFI_BUFFER_TOO_SMALL is returned and InfoSize is updated to contain the number of bytes actually required. - @param[in,out] InfoSize On entry, points to the size of Info. On return, points to the size of the user - information. - + @param[in,out] InfoSize On entry, points to the size of Info. On return, points to the size of the user + information. + @retval EFI_SUCCESS Information returned successfully. - @retval EFI_BUFFER_TOO_SMALL The size specified by InfoSize is too small to hold all of the user + @retval EFI_BUFFER_TOO_SMALL The size specified by InfoSize is too small to hold all of the user information. The size required is returned in *InfoSize. @retval EFI_NOT_FOUND The specified UserInfo does not refer to a valid user info handle. - @retval EFI_INVALID_PARAMETER Info is NULL or InfoSize is NULL. + @retval EFI_INVALID_PARAMETER Info is NULL or InfoSize is NULL. **/ typedef EFI_STATUS @@ -248,15 +242,15 @@ EFI_STATUS /** Enumerate all of the user information records on the credential provider. - This function returns the next user information record. To retrieve the first user information record - handle, point UserInfo at a NULL. Each subsequent call will retrieve another user information - record handle until there are no more, at which point UserInfo will point to NULL. + This function returns the next user information record. To retrieve the first user information record + handle, point UserInfo at a NULL. Each subsequent call will retrieve another user information + record handle until there are no more, at which point UserInfo will point to NULL. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL_PROTOCOL. - @param[in,out] UserInfo On entry, points to the previous user information handle or NULL to - start enumeration. On exit, points to the next user information handle + @param[in,out] UserInfo On entry, points to the previous user information handle or NULL to + start enumeration. On exit, points to the next user information handle or NULL if there is no more user information. - + @retval EFI_SUCCESS User information returned. @retval EFI_NOT_FOUND No more user information found. @retval EFI_INVALID_PARAMETER UserInfo is NULL. @@ -279,7 +273,7 @@ struct _EFI_USER_CREDENTIAL_PROTOCOL { EFI_CREDENTIAL_TILE Tile; EFI_CREDENTIAL_TITLE Title; EFI_CREDENTIAL_USER User; - EFI_CREDENTIAL_SELECT Select; + EFI_CREDENTIAL_SELECT Select; EFI_CREDENTIAL_DESELECT Deselect; EFI_CREDENTIAL_DEFAULT Default; EFI_CREDENTIAL_GET_INFO GetInfo; diff --git a/MdePkg/Include/Protocol/UserCredential2.h b/MdePkg/Include/Protocol/UserCredential2.h index ed3423b47f6f..e5adb66276f9 100644 --- a/MdePkg/Include/Protocol/UserCredential2.h +++ b/MdePkg/Include/Protocol/UserCredential2.h @@ -3,14 +3,8 @@ Attached to a device handle, this protocol identifies a single means of identifying the user. - Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -29,16 +23,16 @@ typedef struct _EFI_USER_CREDENTIAL2_PROTOCOL EFI_USER_CREDENTIAL2_PROTOCOL; /** Enroll a user on a credential provider. - This function enrolls a user on this credential provider. If the user exists on this credential - provider, update the user information on this credential provider; otherwise add the user information + This function enrolls a user on this credential provider. If the user exists on this credential + provider, update the user information on this credential provider; otherwise add the user information on credential provider. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL2_PROTOCOL. @param[in] User The user profile to enroll. - + @retval EFI_SUCCESS User profile was successfully enrolled. - @retval EFI_ACCESS_DENIED Current user profile does not permit enrollment on the user profile - handle. Either the user profile cannot enroll on any user profile or + @retval EFI_ACCESS_DENIED Current user profile does not permit enrollment on the user profile + handle. Either the user profile cannot enroll on any user profile or cannot enroll on a user profile other than the current user profile. @retval EFI_UNSUPPORTED This credential provider does not support enrollment in the pre-OS. @retval EFI_DEVICE_ERROR The new credential could not be created because of a device error. @@ -54,19 +48,19 @@ EFI_STATUS /** Returns the user interface information used during user identification. - This function returns information about the form used when interacting with the user during user - identification. The form is the first enabled form in the form-set class - EFI_HII_USER_CREDENTIAL_FORMSET_GUID installed on the HII handle HiiHandle. If - the user credential provider does not require a form to identify the user, then this function should + This function returns information about the form used when interacting with the user during user + identification. The form is the first enabled form in the form-set class + EFI_HII_USER_CREDENTIAL_FORMSET_GUID installed on the HII handle HiiHandle. If + the user credential provider does not require a form to identify the user, then this function should return EFI_NOT_FOUND. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL2_PROTOCOL. @param[out] Hii On return, holds the HII database handle. @param[out] FormSetId On return, holds the identifier of the form set which contains the form used during user identification. - @param[out] FormId On return, holds the identifier of the form used during user + @param[out] FormId On return, holds the identifier of the form used during user identification. - + @retval EFI_SUCCESS Form returned successfully. @retval EFI_NOT_FOUND Form not returned. @retval EFI_INVALID_PARAMETER Hii is NULL or FormSetId is NULL or FormId is NULL. @@ -83,19 +77,19 @@ EFI_STATUS /** Returns bitmap used to describe the credential provider type. - This optional function returns a bitmap which is less than or equal to the number of pixels specified - by Width and Height. If no such bitmap exists, then EFI_NOT_FOUND is returned. + This optional function returns a bitmap which is less than or equal to the number of pixels specified + by Width and Height. If no such bitmap exists, then EFI_NOT_FOUND is returned. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL2_PROTOCOL. @param[in, out] Width On entry, points to the desired bitmap width. If NULL then no bitmap - information will be returned. On exit, points to the width of the + information will be returned. On exit, points to the width of the bitmap returned. - @param[in, out] Height On entry, points to the desired bitmap height. If NULL then no bitmap - information will be returned. On exit, points to the height of the + @param[in, out] Height On entry, points to the desired bitmap height. If NULL then no bitmap + information will be returned. On exit, points to the height of the bitmap returned - @param[out] Hii On return, holds the HII database handle. - @param[out] Image On return, holds the HII image identifier. - + @param[out] Hii On return, holds the HII database handle. + @param[out] Image On return, holds the HII image identifier. + @retval EFI_SUCCESS Image identifier returned successfully. @retval EFI_NOT_FOUND Image identifier not returned. @retval EFI_INVALID_PARAMETER Hii is NULL or Image is NULL. @@ -113,13 +107,13 @@ EFI_STATUS /** Returns string used to describe the credential provider type. - This function returns a string which describes the credential provider. If no such string exists, then - EFI_NOT_FOUND is returned. + This function returns a string which describes the credential provider. If no such string exists, then + EFI_NOT_FOUND is returned. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL2_PROTOCOL. @param[out] Hii On return, holds the HII database handle. @param[out] String On return, holds the HII string identifier. - + @retval EFI_SUCCESS String identifier returned successfully. @retval EFI_NOT_FOUND String identifier not returned. @retval EFI_INVALID_PARAMETER Hii is NULL or String is NULL. @@ -135,21 +129,21 @@ EFI_STATUS /** Return the user identifier associated with the currently authenticated user. - This function returns the user identifier of the user authenticated by this credential provider. This - function is called after the credential-related information has been submitted on a form OR after a + This function returns the user identifier of the user authenticated by this credential provider. This + function is called after the credential-related information has been submitted on a form OR after a call to Default() has returned that this credential is ready to log on. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL2_PROTOCOL. - @param[in] User The user profile handle of the user profile currently being considered - by the user identity manager. If NULL, then no user profile is currently + @param[in] User The user profile handle of the user profile currently being considered + by the user identity manager. If NULL, then no user profile is currently under consideration. - @param[out] Identifier On return, points to the user identifier. - + @param[out] Identifier On return, points to the user identifier. + @retval EFI_SUCCESS User identifier returned successfully. @retval EFI_NOT_READY No user identifier can be returned. @retval EFI_ACCESS_DENIED The user has been locked out of this user credential. - @retval EFI_NOT_FOUND User is not NULL, and the specified user handle can't be found in user - profile database + @retval EFI_NOT_FOUND User is not NULL, and the specified user handle can't be found in user + profile database @retval EFI_INVALID_PARAMETER Identifier is NULL. **/ typedef @@ -163,13 +157,13 @@ EFI_STATUS /** Indicate that user interface interaction has begun for the specified credential. - This function is called when a credential provider is selected by the user. If AutoLogon returns - FALSE, then the user interface will be constructed by the User Identity Manager. + This function is called when a credential provider is selected by the user. If AutoLogon returns + FALSE, then the user interface will be constructed by the User Identity Manager. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL2_PROTOCOL. - @param[out] AutoLogon On return, points to the credential provider's capabilities after - the credential provider has been selected by the user. - + @param[out] AutoLogon On return, points to the credential provider's capabilities after + the credential provider has been selected by the user. + @retval EFI_SUCCESS Credential provider successfully selected. @retval EFI_INVALID_PARAMETER AutoLogon is NULL. **/ @@ -178,7 +172,7 @@ EFI_STATUS (EFIAPI *EFI_CREDENTIAL2_SELECT)( IN CONST EFI_USER_CREDENTIAL2_PROTOCOL *This, OUT EFI_CREDENTIAL_LOGON_FLAGS *AutoLogon - ); + ); /** Indicate that user interface interaction has ended for the specified credential. @@ -186,7 +180,7 @@ EFI_STATUS This function is called when a credential provider is deselected by the user. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL2_PROTOCOL. - + @retval EFI_SUCCESS Credential provider successfully deselected. **/ typedef @@ -198,16 +192,16 @@ EFI_STATUS /** Return the default logon behavior for this user credential. - This function reports the default login behavior regarding this credential provider. + This function reports the default login behavior regarding this credential provider. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL2_PROTOCOL. - @param[out] AutoLogon On return, holds whether the credential provider should be - used by default to automatically log on the user. - + @param[out] AutoLogon On return, holds whether the credential provider should be + used by default to automatically log on the user. + @retval EFI_SUCCESS Default information successfully returned. @retval EFI_INVALID_PARAMETER AutoLogon is NULL. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_CREDENTIAL2_DEFAULT)( IN CONST EFI_USER_CREDENTIAL2_PROTOCOL *This, @@ -217,22 +211,22 @@ EFI_STATUS /** Return information attached to the credential provider. - This function returns user information. + This function returns user information. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL2_PROTOCOL. - @param[in] UserInfo Handle of the user information data record. - @param[out] Info On entry, points to a buffer of at least *InfoSize bytes. On exit, holds the user - information. If the buffer is too small to hold the information, then - EFI_BUFFER_TOO_SMALL is returned and InfoSize is updated to contain the + @param[in] UserInfo Handle of the user information data record. + @param[out] Info On entry, points to a buffer of at least *InfoSize bytes. On exit, holds the user + information. If the buffer is too small to hold the information, then + EFI_BUFFER_TOO_SMALL is returned and InfoSize is updated to contain the number of bytes actually required. - @param[in,out] InfoSize On entry, points to the size of Info. On return, points to the size of the user - information. - + @param[in,out] InfoSize On entry, points to the size of Info. On return, points to the size of the user + information. + @retval EFI_SUCCESS Information returned successfully. - @retval EFI_BUFFER_TOO_SMALL The size specified by InfoSize is too small to hold all of the user + @retval EFI_BUFFER_TOO_SMALL The size specified by InfoSize is too small to hold all of the user information. The size required is returned in *InfoSize. @retval EFI_NOT_FOUND The specified UserInfo does not refer to a valid user info handle. - @retval EFI_INVALID_PARAMETER Info is NULL or InfoSize is NULL. + @retval EFI_INVALID_PARAMETER Info is NULL or InfoSize is NULL. **/ typedef EFI_STATUS @@ -246,15 +240,15 @@ EFI_STATUS /** Enumerate all of the user information records on the credential provider. - This function returns the next user information record. To retrieve the first user information record - handle, point UserInfo at a NULL. Each subsequent call will retrieve another user information - record handle until there are no more, at which point UserInfo will point to NULL. + This function returns the next user information record. To retrieve the first user information record + handle, point UserInfo at a NULL. Each subsequent call will retrieve another user information + record handle until there are no more, at which point UserInfo will point to NULL. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL2_PROTOCOL. - @param[in,out] UserInfo On entry, points to the previous user information handle or NULL to - start enumeration. On exit, points to the next user information handle + @param[in,out] UserInfo On entry, points to the previous user information handle or NULL to + start enumeration. On exit, points to the next user information handle or NULL if there is no more user information. - + @retval EFI_SUCCESS User information returned. @retval EFI_NOT_FOUND No more user information found. @retval EFI_INVALID_PARAMETER UserInfo is NULL. @@ -269,21 +263,21 @@ EFI_STATUS /** Delete a user on this credential provider. - This function deletes a user on this credential provider. + This function deletes a user on this credential provider. @param[in] This Points to this instance of the EFI_USER_CREDENTIAL2_PROTOCOL. @param[in] User The user profile handle to delete. @retval EFI_SUCCESS User profile was successfully deleted. - @retval EFI_ACCESS_DENIED Current user profile does not permit deletion on the user profile handle. - Either the user profile cannot delete on any user profile or cannot delete - on a user profile other than the current user profile. + @retval EFI_ACCESS_DENIED Current user profile does not permit deletion on the user profile handle. + Either the user profile cannot delete on any user profile or cannot delete + on a user profile other than the current user profile. @retval EFI_UNSUPPORTED This credential provider does not support deletion in the pre-OS. @retval EFI_DEVICE_ERROR The new credential could not be deleted because of a device error. @retval EFI_INVALID_PARAMETER User does not refer to a valid user profile handle. **/ -typedef -EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_CREDENTIAL2_DELETE)( IN CONST EFI_USER_CREDENTIAL2_PROTOCOL *This, IN EFI_USER_PROFILE_HANDLE User @@ -300,13 +294,13 @@ struct _EFI_USER_CREDENTIAL2_PROTOCOL { EFI_CREDENTIAL2_TILE Tile; EFI_CREDENTIAL2_TITLE Title; EFI_CREDENTIAL2_USER User; - EFI_CREDENTIAL2_SELECT Select; + EFI_CREDENTIAL2_SELECT Select; EFI_CREDENTIAL2_DESELECT Deselect; EFI_CREDENTIAL2_DEFAULT Default; EFI_CREDENTIAL2_GET_INFO GetInfo; EFI_CREDENTIAL2_GET_NEXT_INFO GetNextInfo; EFI_CREDENTIAL_CAPABILITIES Capabilities; - EFI_CREDENTIAL2_DELETE Delete; + EFI_CREDENTIAL2_DELETE Delete; }; extern EFI_GUID gEfiUserCredential2ProtocolGuid; diff --git a/MdePkg/Include/Protocol/UserManager.h b/MdePkg/Include/Protocol/UserManager.h index 73fa672a5915..0496af76955d 100644 --- a/MdePkg/Include/Protocol/UserManager.h +++ b/MdePkg/Include/Protocol/UserManager.h @@ -3,14 +3,8 @@ This protocol manages user profiles. - Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -53,7 +47,7 @@ typedef UINT16 EFI_USER_INFO_ATTRIBS; /// typedef struct { /// - /// The user credential identifier associated with this user information or else Nil if the + /// The user credential identifier associated with this user information or else Nil if the /// information is not associated with any specific credential. /// EFI_GUID Credential; @@ -95,7 +89,7 @@ typedef UINT64 EFI_CREDENTIAL_CAPABILITIES; #define EFI_CREDENTIAL_CAPABILITIES_ENROLL 0x0000000000000001 /// -/// Credential logon flags +/// Credential logon flags /// typedef UINT32 EFI_CREDENTIAL_LOGON_FLAGS; #define EFI_CREDENTIAL_LOGON_FLAG_AUTO 0x00000001 @@ -159,7 +153,7 @@ typedef CHAR16 *EFI_USER_INFO_CREDENTIAL_PROVIDER_NAME; /// #define EFI_USER_INFO_PKCS11_RECORD 0x0A /// -/// Provides standard biometric information in the format specified by the ISO 19785 (Common +/// Provides standard biometric information in the format specified by the ISO 19785 (Common /// Biometric Exchange Formats Framework) specification. /// #define EFI_USER_INFO_CBEFF_RECORD 0x0B @@ -170,7 +164,7 @@ typedef VOID *EFI_USER_INFO_CBEFF; #define EFI_USER_INFO_FAR_RECORD 0x0C typedef UINT8 EFI_USER_INFO_FAR; /// -/// Indicates how many attempts the user has to with a particular credential before the system prevents +/// Indicates how many attempts the user has to with a particular credential before the system prevents /// further attempts. /// #define EFI_USER_INFO_RETRY_RECORD 0x0D @@ -192,12 +186,12 @@ typedef EFI_USER_INFO_ACCESS_CONTROL EFI_USER_INFO_ACCESS_POLICY; /// /// -/// Forbids the user from booting or loading executables from the specified device path or any child +/// Forbids the user from booting or loading executables from the specified device path or any child /// device paths. /// #define EFI_USER_INFO_ACCESS_FORBID_LOAD 0x00000001 /// -/// Permits the user from booting or loading executables from the specified device path or any child +/// Permits the user from booting or loading executables from the specified device path or any child /// device paths. /// Note: in-consistency between code and the UEFI 2.3 specification here. /// The definition EFI_USER_INFO_ACCESS_PERMIT_BOOT in the specification should be typo and wait for @@ -258,7 +252,7 @@ typedef UINT32 EFI_USER_INFO_ACCESS_BOOT_ORDER_HDR; /// #define EFI_USER_INFO_ACCESS_BOOT_ORDER_REPLACE 0x00000002 /// -/// The Boot Manager will not attempt find a default boot device +/// The Boot Manager will not attempt find a default boot device /// when the default boot order is does not lead to a bootable device. /// #define EFI_USER_INFO_ACCESS_BOOT_ORDER_NODEFAULT 0x00000010 @@ -269,7 +263,7 @@ typedef UINT32 EFI_USER_INFO_ACCESS_BOOT_ORDER_HDR; #define EFI_USER_INFO_IDENTITY_POLICY_RECORD 0x0F typedef struct { - UINT32 Type; ///< Specifies either an operator or a data item. + UINT32 Type; ///< Specifies either an operator or a data item. UINT32 Length; ///< The length of this block, in bytes, including this header. } EFI_USER_INFO_IDENTITY_POLICY; @@ -303,13 +297,13 @@ typedef struct _EFI_USER_MANAGER_PROTOCOL EFI_USER_MANAGER_PROTOCOL; /** Create a new user profile. - This function creates a new user profile with only a new user identifier attached and returns its + This function creates a new user profile with only a new user identifier attached and returns its handle. The user profile is non-volatile, but the handle User can change across reboots. @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL. - @param[out] User On return, points to the new user profile handle. + @param[out] User On return, points to the new user profile handle. The user profile handle is unique only during this boot. - + @retval EFI_SUCCESS User profile was successfully created. @retval EFI_ACCESS_DENIED Current user does not have sufficient permissions to create a user profile. @retval EFI_UNSUPPORTED Creation of new user profiles is not supported. @@ -326,7 +320,7 @@ EFI_STATUS Delete an existing user profile. @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL. - @param[in] User User profile handle. + @param[in] User User profile handle. @retval EFI_SUCCESS User profile was successfully deleted. @retval EFI_ACCESS_DENIED Current user does not have sufficient permissions to delete a user @@ -344,16 +338,16 @@ EFI_STATUS /** Enumerate all of the enrolled users on the platform. - This function returns the next enrolled user profile. To retrieve the first user profile handle, point - User at a NULL. Each subsequent call will retrieve another user profile handle until there are no - more, at which point User will point to NULL. + This function returns the next enrolled user profile. To retrieve the first user profile handle, point + User at a NULL. Each subsequent call will retrieve another user profile handle until there are no + more, at which point User will point to NULL. @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL. - @param[in,out] User On entry, points to the previous user profile handle or NULL to + @param[in,out] User On entry, points to the previous user profile handle or NULL to start enumeration. On exit, points to the next user profile handle or NULL if there are no more user profiles. - @retval EFI_SUCCESS Next enrolled user profile successfully returned. + @retval EFI_SUCCESS Next enrolled user profile successfully returned. @retval EFI_ACCESS_DENIED Next enrolled user profile was not successfully returned. @retval EFI_INVALID_PARAMETER The User parameter is NULL. **/ @@ -370,7 +364,7 @@ EFI_STATUS @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL. @param[out] CurrentUser On return, points to the current user profile handle. - @retval EFI_SUCCESS Current user profile handle returned successfully. + @retval EFI_SUCCESS Current user profile handle returned successfully. @retval EFI_INVALID_PARAMETER The CurrentUser parameter is NULL. **/ typedef @@ -384,9 +378,9 @@ EFI_STATUS Identify a user. Identify the user and, if authenticated, returns the user handle and changes the current user profile. - All user information marked as private in a previously selected profile is no longer available for - inspection. - Whenever the current user profile is changed then the an event with the GUID + All user information marked as private in a previously selected profile is no longer available for + inspection. + Whenever the current user profile is changed then the an event with the GUID EFI_EVENT_GROUP_USER_PROFILE_CHANGED is signaled. @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL. @@ -406,26 +400,26 @@ EFI_STATUS /** Find a user using a user information record. - This function searches all user profiles for the specified user information record. The search starts - with the user information record handle following UserInfo and continues until either the + This function searches all user profiles for the specified user information record. The search starts + with the user information record handle following UserInfo and continues until either the information is found or there are no more user profiles. - A match occurs when the Info.InfoType field matches the user information record type and the + A match occurs when the Info.InfoType field matches the user information record type and the user information record data matches the portion of Info. @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL. - @param[in,out] User On entry, points to the previously returned user profile handle or NULL to start - searching with the first user profile. On return, points to the user profile handle or + @param[in,out] User On entry, points to the previously returned user profile handle or NULL to start + searching with the first user profile. On return, points to the user profile handle or NULL if not found. - @param[in,out] UserInfo On entry, points to the previously returned user information handle or NULL to start - searching with the first. On return, points to the user information handle of the user - information record or NULL if not found. Can be NULL, in which case only one user - information record per user can be returned. - @param[in] Info Points to the buffer containing the user information to be compared to the user - information record. If the user information record data is empty, then only the user - information record type is compared. + @param[in,out] UserInfo On entry, points to the previously returned user information handle or NULL to start + searching with the first. On return, points to the user information handle of the user + information record or NULL if not found. Can be NULL, in which case only one user + information record per user can be returned. + @param[in] Info Points to the buffer containing the user information to be compared to the user + information record. If the user information record data is empty, then only the user + information record type is compared. If InfoSize is 0, then the user information record must be empty. - @param[in] InfoSize The size of Info, in bytes. + @param[in] InfoSize The size of Info, in bytes. @retval EFI_SUCCESS User information was found. User points to the user profile handle and UserInfo points to the user information handle. @@ -445,15 +439,15 @@ EFI_STATUS /** Called by credential provider to notify of information change. - This function allows the credential provider to notify the User Identity Manager when user status + This function allows the credential provider to notify the User Identity Manager when user status has changed. - If the User Identity Manager doesn't support asynchronous changes in credentials, then this function - should return EFI_UNSUPPORTED. - If current user does not exist, and the credential provider can identify a user, then make the user + If the User Identity Manager doesn't support asynchronous changes in credentials, then this function + should return EFI_UNSUPPORTED. + If current user does not exist, and the credential provider can identify a user, then make the user to be current user and signal the EFI_EVENT_GROUP_USER_PROFILE_CHANGED event. - If current user already exists, and the credential provider can identify another user, then switch + If current user already exists, and the credential provider can identify another user, then switch current user to the newly identified user, and signal the EFI_EVENT_GROUP_USER_PROFILE_CHANGED event. - If current user was identified by this credential provider and now the credential provider cannot identify + If current user was identified by this credential provider and now the credential provider cannot identify current user, then logout current user and signal the EFI_EVENT_GROUP_USER_PROFILE_CHANGED event. @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL. @@ -474,30 +468,30 @@ EFI_STATUS /** Return information attached to the user. - This function returns user information. The format of the information is described in User - Information. The function may return EFI_ACCESS_DENIED if the information is marked private - and the handle specified by User is not the current user profile. The function may return - EFI_ACCESS_DENIED if the information is marked protected and the information is associated + This function returns user information. The format of the information is described in User + Information. The function may return EFI_ACCESS_DENIED if the information is marked private + and the handle specified by User is not the current user profile. The function may return + EFI_ACCESS_DENIED if the information is marked protected and the information is associated with a credential provider for which the user has not been authenticated. @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL. - @param[in] User Handle of the user whose profile will be retrieved. - @param[in] UserInfo Handle of the user information data record. - @param[out] Info On entry, points to a buffer of at least *InfoSize bytes. On exit, holds the user - information. If the buffer is too small to hold the information, then - EFI_BUFFER_TOO_SMALL is returned and InfoSize is updated to contain the - number of bytes actually required. - @param[in,out] InfoSize On entry, points to the size of Info. On return, points to the size of the user - information. + @param[in] User Handle of the user whose profile will be retrieved. + @param[in] UserInfo Handle of the user information data record. + @param[out] Info On entry, points to a buffer of at least *InfoSize bytes. On exit, holds the user + information. If the buffer is too small to hold the information, then + EFI_BUFFER_TOO_SMALL is returned and InfoSize is updated to contain the + number of bytes actually required. + @param[in,out] InfoSize On entry, points to the size of Info. On return, points to the size of the user + information. @retval EFI_SUCCESS Information returned successfully. @retval EFI_ACCESS_DENIED The information about the specified user cannot be accessed by the current user. - @retval EFI_BUFFER_TOO_SMALL The number of bytes specified by *InfoSize is too small to hold + @retval EFI_BUFFER_TOO_SMALL The number of bytes specified by *InfoSize is too small to hold the returned data. The actual size required is returned in *InfoSize. @retval EFI_NOT_FOUND User does not refer to a valid user profile or UserInfo does not refer to a valid user info handle. @retval EFI_INVALID_PARAMETER Info is NULL or InfoSize is NULL. -**/ +**/ typedef EFI_STATUS (EFIAPI *EFI_USER_PROFILE_GET_INFO)( @@ -511,33 +505,33 @@ EFI_STATUS /** Add or update user information. - This function changes user information. If NULL is pointed to by UserInfo, then a new user - information record is created and its handle is returned in UserInfo. Otherwise, the existing one is + This function changes user information. If NULL is pointed to by UserInfo, then a new user + information record is created and its handle is returned in UserInfo. Otherwise, the existing one is replaced. - If EFI_USER_INFO_IDENTITY_POLICY_RECORD is changed, it is the caller's responsibility to keep it to + If EFI_USER_INFO_IDENTITY_POLICY_RECORD is changed, it is the caller's responsibility to keep it to be synced with the information on credential providers. - If EFI_USER_INFO_EXCLUSIVE is specified in Info and a user information record of the same - type already exists in the user profile, then EFI_ACCESS_DENIED will be returned and + If EFI_USER_INFO_EXCLUSIVE is specified in Info and a user information record of the same + type already exists in the user profile, then EFI_ACCESS_DENIED will be returned and UserInfo will point to the handle of the existing record. @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL. - @param[in] User Handle of the user whose profile will be retrieved. - @param[in,out] UserInfo Handle of the user information data record. - @param[in] Info On entry, points to a buffer of at least *InfoSize bytes. On exit, holds the user - information. If the buffer is too small to hold the information, then - EFI_BUFFER_TOO_SMALL is returned and InfoSize is updated to contain the - number of bytes actually required. - @param[in] InfoSize On entry, points to the size of Info. On return, points to the size of the user - information. + @param[in] User Handle of the user whose profile will be retrieved. + @param[in,out] UserInfo Handle of the user information data record. + @param[in] Info On entry, points to a buffer of at least *InfoSize bytes. On exit, holds the user + information. If the buffer is too small to hold the information, then + EFI_BUFFER_TOO_SMALL is returned and InfoSize is updated to contain the + number of bytes actually required. + @param[in] InfoSize On entry, points to the size of Info. On return, points to the size of the user + information. @retval EFI_SUCCESS Information returned successfully. @retval EFI_ACCESS_DENIED The record is exclusive. - @retval EFI_SECURITY_VIOLATION The current user does not have permission to change the specified + @retval EFI_SECURITY_VIOLATION The current user does not have permission to change the specified user profile or user information record. @retval EFI_NOT_FOUND User does not refer to a valid user profile or UserInfo does not refer to a valid user info handle. - @retval EFI_INVALID_PARAMETER UserInfo is NULL or Info is NULL. -**/ + @retval EFI_INVALID_PARAMETER UserInfo is NULL or Info is NULL. +**/ typedef EFI_STATUS (EFIAPI *EFI_USER_PROFILE_SET_INFO)( @@ -559,8 +553,8 @@ EFI_STATUS @retval EFI_SUCCESS User information deleted successfully. @retval EFI_NOT_FOUND User information record UserInfo does not exist in the user profile. - @retval EFI_ACCESS_DENIED The current user does not have permission to delete this user information. -**/ + @retval EFI_ACCESS_DENIED The current user does not have permission to delete this user information. +**/ typedef EFI_STATUS (EFIAPI *EFI_USER_PROFILE_DELETE_INFO)( @@ -572,9 +566,9 @@ EFI_STATUS /** Enumerate user information of all the enrolled users on the platform. - This function returns the next user information record. To retrieve the first user information record - handle, point UserInfo at a NULL. Each subsequent call will retrieve another user information - record handle until there are no more, at which point UserInfo will point to NULL. + This function returns the next user information record. To retrieve the first user information record + handle, point UserInfo at a NULL. Each subsequent call will retrieve another user information + record handle until there are no more, at which point UserInfo will point to NULL. @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL. @param[in] User Handle of the user whose information will be deleted. @@ -583,7 +577,7 @@ EFI_STATUS @retval EFI_SUCCESS User information returned. @retval EFI_NOT_FOUND No more user information found. @retval EFI_INVALID_PARAMETER UserInfo is NULL. -**/ +**/ typedef EFI_STATUS (EFIAPI *EFI_USER_PROFILE_GET_NEXT_INFO)( diff --git a/MdePkg/Include/Protocol/Variable.h b/MdePkg/Include/Protocol/Variable.h index c9e86026f7ae..c20934471206 100644 --- a/MdePkg/Include/Protocol/Variable.h +++ b/MdePkg/Include/Protocol/Variable.h @@ -1,33 +1,27 @@ /** @file Variable Architectural Protocol as defined in PI Specification VOLUME 2 DXE - This provides the services required to get and set environment variables. This - protocol must be produced by a runtime DXE driver and may be consumed only by - the DXE Foundation. The DXE driver that produces this protocol must be a runtime - driver. This driver is responsible for initializing the GetVariable(), + This provides the services required to get and set environment variables. This + protocol must be produced by a runtime DXE driver and may be consumed only by + the DXE Foundation. The DXE driver that produces this protocol must be a runtime + driver. This driver is responsible for initializing the GetVariable(), GetNextVariableName(), and SetVariable() fields of the UEFI Runtime Services Table. - After the three fields of the UEFI Runtime Services Table have been initialized, - the driver must install the EFI_VARIABLE_ARCH_PROTOCOL_GUID on a new handle with - a NULL interface pointer. The installation of this protocol informs the DXE Foundation - that the read-only and the volatile environment variable related services are - now available and that the DXE Foundation must update the 32-bit CRC of the UEFI - Runtime Services Table. The full complement of environment variable services are - not available until both this protocol and EFI_VARIABLE_WRITE_ARCH_PROTOCOL are - installed. DXE drivers that require read-only access or read/write access to volatile - environment variables must have this architectural protocol in their dependency - expressions. DXE drivers that require write access to nonvolatile environment - variables must have the EFI_VARIABLE_WRITE_ARCH_PROTOCOL in their dependency + After the three fields of the UEFI Runtime Services Table have been initialized, + the driver must install the EFI_VARIABLE_ARCH_PROTOCOL_GUID on a new handle with + a NULL interface pointer. The installation of this protocol informs the DXE Foundation + that the read-only and the volatile environment variable related services are + now available and that the DXE Foundation must update the 32-bit CRC of the UEFI + Runtime Services Table. The full complement of environment variable services are + not available until both this protocol and EFI_VARIABLE_WRITE_ARCH_PROTOCOL are + installed. DXE drivers that require read-only access or read/write access to volatile + environment variables must have this architectural protocol in their dependency + expressions. DXE drivers that require write access to nonvolatile environment + variables must have the EFI_VARIABLE_WRITE_ARCH_PROTOCOL in their dependency expressions. - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -42,4 +36,4 @@ extern EFI_GUID gEfiVariableArchProtocolGuid; -#endif +#endif diff --git a/MdePkg/Include/Protocol/VariableWrite.h b/MdePkg/Include/Protocol/VariableWrite.h index 96971d9e8586..9131e1945ec4 100644 --- a/MdePkg/Include/Protocol/VariableWrite.h +++ b/MdePkg/Include/Protocol/VariableWrite.h @@ -1,33 +1,27 @@ /** @file Variable Write Architectural Protocol as defined in PI Specification VOLUME 2 DXE - This provides the services required to set nonvolatile environment variables. - This protocol must be produced by a runtime DXE driver and may be consumed only + This provides the services required to set nonvolatile environment variables. + This protocol must be produced by a runtime DXE driver and may be consumed only by the DXE Foundation. - The DXE driver that produces this protocol must be a runtime driver. This driver + The DXE driver that produces this protocol must be a runtime driver. This driver may update the SetVariable() field of the UEFI Runtime Services Table. - - After the UEFI Runtime Services Table has been initialized, the driver must - install the EFI_VARIABLE_WRITE_ARCH_PROTOCOL_GUID on a new handle with a NULL - interface pointer. The installation of this protocol informs the DXE Foundation - that the write services for nonvolatile environment variables are now available - and that the DXE Foundation must update the 32-bit CRC of the UEFI Runtime Services - Table. The full complement of environment variable services are not available - until both this protocol and EFI_VARIABLE_ARCH_PROTOCOL are installed. DXE drivers + + After the UEFI Runtime Services Table has been initialized, the driver must + install the EFI_VARIABLE_WRITE_ARCH_PROTOCOL_GUID on a new handle with a NULL + interface pointer. The installation of this protocol informs the DXE Foundation + that the write services for nonvolatile environment variables are now available + and that the DXE Foundation must update the 32-bit CRC of the UEFI Runtime Services + Table. The full complement of environment variable services are not available + until both this protocol and EFI_VARIABLE_ARCH_PROTOCOL are installed. DXE drivers that require read-only access or read/write access to volatile environment variables must have the EFI_VARIABLE_WRITE_ARCH_PROTOCOL in their dependency expressions. - DXE drivers that require write access to nonvolatile environment variables must - have this architectural protocol in their dependency expressions. - - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + DXE drivers that require write access to nonvolatile environment variables must + have this architectural protocol in their dependency expressions. + + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -42,4 +36,4 @@ extern EFI_GUID gEfiVariableWriteArchProtocolGuid; -#endif +#endif diff --git a/MdePkg/Include/Protocol/VlanConfig.h b/MdePkg/Include/Protocol/VlanConfig.h index 5d980a642134..ae53d9aac78a 100644 --- a/MdePkg/Include/Protocol/VlanConfig.h +++ b/MdePkg/Include/Protocol/VlanConfig.h @@ -1,16 +1,10 @@ /** @file EFI VLAN Config protocol is to provide manageability interface for VLAN configuration. - Copyright (c) 2009, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - @par Revision Reference: + @par Revision Reference: This Protocol is introduced in UEFI Specification 2.2 **/ @@ -37,28 +31,28 @@ typedef struct { /** - Create a VLAN device or modify the configuration parameter of an + Create a VLAN device or modify the configuration parameter of an already-configured VLAN. The Set() function is used to create a new VLAN device or change the VLAN - configuration parameters. If the VlanId hasn't been configured in the + configuration parameters. If the VlanId hasn't been configured in the physical Ethernet device, a new VLAN device will be created. If a VLAN with this VlanId is already configured, then related configuration will be updated - as the input parameters. - + as the input parameters. + If VlanId is zero, the VLAN device will send and receive untagged frames. Otherwise, the VLAN device will send and receive VLAN-tagged frames containing the VlanId. If VlanId is out of scope of (0-4094), EFI_INVALID_PARAMETER is returned. - If Priority is out of the scope of (0-7), then EFI_INVALID_PARAMETER is returned. - If there is not enough system memory to perform the registration, then + If Priority is out of the scope of (0-7), then EFI_INVALID_PARAMETER is returned. + If there is not enough system memory to perform the registration, then EFI_OUT_OF_RESOURCES is returned. @param[in] This Points to the EFI_VLAN_CONFIG_PROTOCOL. - @param[in] VlanId A unique identifier (1-4094) of the VLAN which is being created + @param[in] VlanId A unique identifier (1-4094) of the VLAN which is being created or modified, or zero (0). - @param[in] Priority 3 bit priority in VLAN header. Priority 0 is default value. If + @param[in] Priority 3 bit priority in VLAN header. Priority 0 is default value. If VlanId is zero (0), Priority is ignored. - + @retval EFI_SUCCESS The VLAN is successfully configured. @retval EFI_INVALID_PARAMETER One or more of following conditions is TRUE: - This is NULL. @@ -79,14 +73,14 @@ EFI_STATUS Find configuration information for specified VLAN or all configured VLANs. The Find() function is used to find the configuration information for matching - VLAN and allocate a buffer into which those entries are copied. + VLAN and allocate a buffer into which those entries are copied. @param[in] This Points to the EFI_VLAN_CONFIG_PROTOCOL. @param[in] VlanId Pointer to VLAN identifier. Set to NULL to find all configured VLANs. @param[out] NumberOfVlan The number of VLANs which is found by the specified criteria. @param[out] Entries The buffer which receive the VLAN configuration. - + @retval EFI_SUCCESS The VLAN is successfully found. @retval EFI_INVALID_PARAMETER One or more of following conditions is TRUE: - This is NULL. @@ -106,13 +100,13 @@ EFI_STATUS /** Remove the configured VLAN device. - The Remove() function is used to remove the specified VLAN device. + The Remove() function is used to remove the specified VLAN device. If the VlanId is out of the scope of (0-4094), EFI_INVALID_PARAMETER is returned. - If specified VLAN hasn't been previously configured, EFI_NOT_FOUND is returned. + If specified VLAN hasn't been previously configured, EFI_NOT_FOUND is returned. @param[in] This Points to the EFI_VLAN_CONFIG_PROTOCOL. @param[in] VlanId Identifier (0-4094) of the VLAN to be removed. - + @retval EFI_SUCCESS The VLAN is successfully removed. @retval EFI_INVALID_PARAMETER One or more of following conditions is TRUE: - This is NULL. @@ -129,7 +123,7 @@ EFI_STATUS /// /// EFI_VLAN_CONFIG_PROTOCOL -/// provide manageability interface for VLAN setting. The intended +/// provide manageability interface for VLAN setting. The intended /// VLAN tagging implementation is IEEE802.1Q. /// struct _EFI_VLAN_CONFIG_PROTOCOL { diff --git a/MdePkg/Include/Protocol/WatchdogTimer.h b/MdePkg/Include/Protocol/WatchdogTimer.h index b48f943db2d1..94fa0e3ef110 100644 --- a/MdePkg/Include/Protocol/WatchdogTimer.h +++ b/MdePkg/Include/Protocol/WatchdogTimer.h @@ -3,14 +3,8 @@ Used to provide system watchdog timer services - Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef __ARCH_PROTOCOL_WATCHDOG_TIMER_H__ @@ -28,7 +22,7 @@ typedef struct _EFI_WATCHDOG_TIMER_ARCH_PROTOCOL EFI_WATCHDOG_TIMER_ARCH_PROTOCOL; /** - A function of this type is called when the watchdog timer fires if a + A function of this type is called when the watchdog timer fires if a handler has been registered. @param Time The time in 100 ns units that has passed since the watchdog @@ -45,15 +39,15 @@ VOID ); /** - This function registers a handler that is to be invoked when the watchdog - timer fires. By default, the EFI_WATCHDOG_TIMER protocol will call the - Runtime Service ResetSystem() when the watchdog timer fires. If a - NotifyFunction is registered, then the NotifyFunction will be called before - the Runtime Service ResetSystem() is called. If NotifyFunction is NULL, then - the watchdog handler is unregistered. If a watchdog handler is registered, - then EFI_SUCCESS is returned. If an attempt is made to register a handler - when a handler is already registered, then EFI_ALREADY_STARTED is returned. - If an attempt is made to uninstall a handler when a handler is not installed, + This function registers a handler that is to be invoked when the watchdog + timer fires. By default, the EFI_WATCHDOG_TIMER protocol will call the + Runtime Service ResetSystem() when the watchdog timer fires. If a + NotifyFunction is registered, then the NotifyFunction will be called before + the Runtime Service ResetSystem() is called. If NotifyFunction is NULL, then + the watchdog handler is unregistered. If a watchdog handler is registered, + then EFI_SUCCESS is returned. If an attempt is made to register a handler + when a handler is already registered, then EFI_ALREADY_STARTED is returned. + If an attempt is made to uninstall a handler when a handler is not installed, then return EFI_INVALID_PARAMETER. @param This The EFI_WATCHDOG_TIMER_ARCH_PROTOCOL instance. @@ -68,7 +62,7 @@ VOID previously registered. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_WATCHDOG_TIMER_REGISTER_HANDLER)( IN EFI_WATCHDOG_TIMER_ARCH_PROTOCOL *This, @@ -76,8 +70,8 @@ EFI_STATUS ); /** - This function sets the amount of time to wait before firing the watchdog - timer to TimerPeriod 100 nS units. If TimerPeriod is 0, then the watchdog + This function sets the amount of time to wait before firing the watchdog + timer to TimerPeriod 100 nS units. If TimerPeriod is 0, then the watchdog timer is disabled. @param This The EFI_WATCHDOG_TIMER_ARCH_PROTOCOL instance. @@ -91,7 +85,7 @@ EFI_STATUS error. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_WATCHDOG_TIMER_SET_TIMER_PERIOD)( IN EFI_WATCHDOG_TIMER_ARCH_PROTOCOL *This, @@ -99,8 +93,8 @@ EFI_STATUS ); /** - This function retrieves the amount of time the system will wait before firing - the watchdog timer. This period is returned in TimerPeriod, and EFI_SUCCESS + This function retrieves the amount of time the system will wait before firing + the watchdog timer. This period is returned in TimerPeriod, and EFI_SUCCESS is returned. If TimerPeriod is NULL, then EFI_INVALID_PARAMETER is returned. @param This The EFI_WATCHDOG_TIMER_ARCH_PROTOCOL instance. @@ -113,7 +107,7 @@ EFI_STATUS @retval EFI_INVALID_PARAMETER TimerPeriod is NULL. **/ -typedef +typedef EFI_STATUS (EFIAPI *EFI_WATCHDOG_TIMER_GET_TIMER_PERIOD)( IN EFI_WATCHDOG_TIMER_ARCH_PROTOCOL *This, @@ -122,14 +116,14 @@ EFI_STATUS /// -/// This protocol provides the services required to implement the Boot Service -/// SetWatchdogTimer(). It provides a service to set the amount of time to wait -/// before firing the watchdog timer, and it also provides a service to register -/// a handler that is invoked when the watchdog timer fires. This protocol can -/// implement the watchdog timer by using the event and timer Boot Services, or -/// it can make use of custom hardware. When the watchdog timer fires, control -/// will be passed to a handler if one has been registered. If no handler has -/// been registered, or the registered handler returns, then the system will be +/// This protocol provides the services required to implement the Boot Service +/// SetWatchdogTimer(). It provides a service to set the amount of time to wait +/// before firing the watchdog timer, and it also provides a service to register +/// a handler that is invoked when the watchdog timer fires. This protocol can +/// implement the watchdog timer by using the event and timer Boot Services, or +/// it can make use of custom hardware. When the watchdog timer fires, control +/// will be passed to a handler if one has been registered. If no handler has +/// been registered, or the registered handler returns, then the system will be /// reset by calling the Runtime Service ResetSystem(). /// struct _EFI_WATCHDOG_TIMER_ARCH_PROTOCOL { diff --git a/MdePkg/Include/Protocol/WiFi.h b/MdePkg/Include/Protocol/WiFi.h index cbc1a17bc6f6..58c248d1eea7 100644 --- a/MdePkg/Include/Protocol/WiFi.h +++ b/MdePkg/Include/Protocol/WiFi.h @@ -4,13 +4,7 @@ point (AP). Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.5 diff --git a/MdePkg/Include/Protocol/WiFi2.h b/MdePkg/Include/Protocol/WiFi2.h index c28f9fc492c8..2fb1790f3ad6 100644 --- a/MdePkg/Include/Protocol/WiFi2.h +++ b/MdePkg/Include/Protocol/WiFi2.h @@ -1,14 +1,8 @@ /** @file This file defines the EFI Wireless MAC Connection II Protocol. - Copyright (c) 2016, Intel Corporation. All rights reserved.<BR> - This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent @par Revision Reference: This Protocol is introduced in UEFI Specification 2.6 @@ -202,7 +196,7 @@ typedef struct { // The NetworkDesc is a pointer to an array of EFI_80211_NETWORK_DESCRIPTION // instances. It is caller's responsibility to free this buffer. // - EFI_80211_NETWORK_DESCRIPTION **NetworkDesc; + EFI_80211_NETWORK_DESCRIPTION NetworkDesc[1]; } EFI_80211_GET_NETWORKS_RESULT; /// |