diff options
Diffstat (limited to 'src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h')
| -rw-r--r-- | src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h | 355 |
1 files changed, 355 insertions, 0 deletions
diff --git a/src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h b/src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h new file mode 100644 index 0000000000..8343cb8bea --- /dev/null +++ b/src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h @@ -0,0 +1,355 @@ +/** @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 + + 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 __PLATFORM_TO_DRIVER_CONFIGUARTION_H__ +#define __PLATFORM_TO_DRIVER_CONFIGUARTION_H__ + +#define EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL_GUID \ + { 0x642cd590, 0x8059, 0x4c0a, { 0xa9, 0x58, 0xc5, 0xec, 0x7, 0xd2, 0x3c, 0x4b } } + + +typedef struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL; + + +/** + The UEFI driver must call Query early in the Start() function + before any time consuming operations are performed. If + ChildHandle is NULL the driver is requesting information from + the platform about the ControllerHandle that is being started. + Information returned from Query may lead to the drivers Start() + function failing. + If the UEFI driver is a bus driver and producing a ChildHandle, + the driver must call Query after the child handle has been created + and an EFI_DEVICE_PATH_PROTOCOL has been placed on that handle, + but before any time consuming operation is performed. If information + return by Query may lead the driver to decide to not create the + ChildHandle. The driver must then cleanup and remove the ChildHandle + from the system. + The UEFI driver repeatedly calls Query, processes the information + returned by the platform, and calls Response passing in the + arguments returned from Query. The Instance value passed into + Response must be the same value passed into the corresponding + call to Query. The UEFI driver must continuously call Query and + Response until EFI_NOT_FOUND is returned by Query. + If the UEFI driver does not recognize the ParameterTypeGuid, it + calls Response with a ConfigurationAction of + EfiPlatformConfigurationActionUnsupportedGuid. The UEFI driver + must then continue calling Query and Response until EFI_NOT_FOUND + is returned by Query. This gives the platform an opportunity to + pass additional configuration settings using a different + ParameterTypeGuid that may be supported by the driver. + An Instance value of zero means return the first ParameterBlock + in the set of unprocessed parameter blocks. The driver should + 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 + NULL for device drivers and for bus + drivers that attempt to get options for + 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 + successive data. + + @param ParameterTypeGuid An EFI_GUID that defines the contents + of ParameterBlock. UEFI drivers must + use the ParameterTypeGuid to determine + how to parse the ParameterBlock. The caller + should not attempt to free ParameterTypeGuid. + + @param ParameterBlock The platform returns a pointer to the + ParameterBlock structure which + contains details about the + configuration parameters specific to + the ParameterTypeGuid. This structure + is defined based on the protocol and + may be different for different + protocols. UEFI driver decodes this + structure and its contents based on + ParameterTypeGuid. ParameterBlock is + allocated by the platform and the + platform is responsible for freeing + the ParameterBlock after Result is + called. + + @param ParameterBlockSize The platform returns the size of + the ParameterBlock in bytes. + + + @retval EFI_SUCCESS The platform return parameter + information for ControllerHandle. + + @retval EFI_NOT_FOUND No more unread Instance exists. + + @retval EFI_INVALID_PARAMETER ControllerHandle is NULL. + + @retval EFI_INVALID_PARAMETER Instance is NULL. + + @retval EFI_DEVICE_ERROR A device error occurred while + attempting to return parameter block + information for the controller + specified by ControllerHandle and + ChildHandle. + + @retval EFI_OUT_RESOURCES There are not enough resources + available to set the configuration + options for the controller specified + by ControllerHandle and ChildHandle. + + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_QUERY)( + IN CONST EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL *This, + IN CONST EFI_HANDLE ControllerHandle, + IN CONST EFI_HANDLE ChildHandle OPTIONAL, + IN CONST UINTN *Instance, + OUT EFI_GUID **ParameterTypeGuid, + OUT VOID **ParameterBlock, + OUT UINTN *ParameterBlockSize +); + +typedef enum { + /// + /// The controller specified by ControllerHandle is still + /// in a usable state, and its configuration has been updated + /// via parsing the ParameterBlock. If required by the + /// parameter block, and the module supports an NVRAM store, + /// the configuration information from PB was successfully + /// saved to the NVRAM. No actions are required before + /// this controller can be used again with the updated + /// configuration settings. + /// + EfiPlatformConfigurationActionNone = 0, + + /// + /// The driver has detected that the controller specified + /// 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. + /// + 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. + /// + EfiPlatformConfigurationActionRestartController = 2, + + /// + /// A configuration change has been made that requires the + /// platform to be restarted before the controller + /// specified by ControllerHandle can be used again. The + /// 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. + /// + EfiPlatformConfigurationActionRestartPlatform = 3, + + /// + /// The controller specified by ControllerHandle is still + /// in a usable state; its configuration has been updated + /// via parsing the ParameterBlock. The driver tried to + /// update the driver's private NVRAM store with + /// information from ParameterBlock and failed. No actions + /// 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. + /// + EfiPlatformConfigurationActionNvramFailed = 4, + + /// + /// The controller specified by ControllerHandle is still + /// in a usable state; its configuration has not been updated + /// via parsing the ParameterBlock. The driver did not support + /// the ParameterBlock format identified by ParameterTypeGuid. + /// No actions are required before this controller can be used + /// again. On additional Query calls from this ControllerHandle, + /// the platform should stop returning a ParameterBlock + /// qualified by this same ParameterTypeGuid. If no other + /// ParameterTypeGuid is supported by the platform, Query + /// should return EFI_NOT_FOUND. + /// + EfiPlatformConfigurationActionUnsupportedGuid = 5, + EfiPlatformConfigurationActionMaximum +} EFI_PLATFORM_CONFIGURATION_ACTION; + + +/** + The UEFI driver repeatedly calls Query, processes the + information returned by the platform, and calls Response passing + in the arguments returned from Query. The UEFI driver must + continuously call Query until EFI_NOT_FOUND is returned. For + every call to Query that returns EFI_SUCCESS a corrisponding + call to Response is required passing in the same + ContollerHandle, ChildHandle, Instance, ParameterTypeGuid, + ParameterBlock, and ParameterBlockSize. The UEFI driver may + update values in ParameterBlock based on rules defined by + ParameterTypeGuid. The platform is responsible for freeing + ParameterBlock and the UEFI driver must not try to free it. + + @param This A pointer to the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL instance. + + @param ControllerHandle The handle the driver is returning + 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 + NULL for device drivers, and for bus + drivers that attempt to get options for + the bus controller. It will not be NULL + for a bus driver that attempts to get + options for one of its child controllers. + Instance Instance data returned from + Query(). + + @param Instance Instance data passed to Query(). + + @param ParameterTypeGuid ParameterTypeGuid returned from Query. + + @param ParameterBlock ParameterBlock returned from Query. + + @param ParameterBlockSize The ParameterBlock size returned from Query. + + @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 +(EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_RESPONSE)( + IN CONST EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL *This, + IN CONST EFI_HANDLE ControllerHandle, + IN CONST EFI_HANDLE ChildHandle OPTIONAL, + IN CONST UINTN *Instance, + IN CONST EFI_GUID *ParameterTypeGuid, + IN CONST VOID *ParameterBlock, + IN CONST UINTN ParameterBlockSize , + IN CONST EFI_PLATFORM_CONFIGURATION_ACTION ConfigurationAction +); + + +/// +/// The EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL is used by the +/// UEFI driver to query the platform for configuration information. +/// The UEFI driver calls Query() multiple times to get +/// configuration information from the platform. For every call to +/// Query() there must be a matching call to Response() so the +/// UEFI driver can inform the platform how it used the +/// information passed in from Query(). It's legal for a UEFI +/// driver to use Response() to inform the platform it does not +/// understand the data returned via Query() and thus no action was +/// taken. +/// +struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL { + EFI_PLATFORM_TO_DRIVER_CONFIGURATION_QUERY Query; + EFI_PLATFORM_TO_DRIVER_CONFIGURATION_RESPONSE Response; +}; + + + +#define EFI_PLATFORM_TO_DRIVER_CONFIGURATION_CLP_GUID \ + {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 + section the producer of the + EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL is platform + firmware and the consumer is the UEFI driver. Note: if future + versions of the DMTF SM CLP Specification require changes to the + parameter block definition, a newer ParameterTypeGuid will be + used. +**/ +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 + ///< 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. + CHAR8 *CLPReturnString; ///< A pointer to the null-terminated UTF-8 string that indicates the CLP return status + ///< that the driver is required to provide to the calling agent. + ///< The calling agent may parse and/ or pass + ///< this for processing and user feedback. The SM CLP Command Response string + ///< buffer is filled in by the UEFI driver in the "keyword=value" format + ///< described in the SM CLP Specification, unless otherwise requested via the SM + ///< CLP Coutput option in the Command Line string buffer. UEFI driver's support + ///< for this default "keyword=value" output format is required if the UEFI + ///< driver supports this protocol, while support for other SM CLP output + ///< formats is optional (the UEFI Driver should return an EFI_UNSUPPORTED if + ///< 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(). + 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(). + 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(). + 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(). + +} EFI_CONFIGURE_CLP_PARAMETER_BLK; + + + +extern EFI_GUID gEfiPlatformToDriverConfigurationClpGuid; + +extern EFI_GUID gEfiPlatformToDriverConfigurationProtocolGuid; + +#endif |