/** @file\r
- The file provides the protocol to retrieve configuration\r
- information for a device that a UEFI driver is about to start.\r
+ UEFI Platform to Driver Configuration Protocol is defined in UEFI specification.\r
+ \r
+ This is a protocol that is optionally produced by the platform and optionally consumed \r
+ by a UEFI Driver in its Start() function. This protocol allows the driver to receive \r
+ configuration information as part of being started.\r
\r
- Copyright (c) 2006 - 2007, Intel Corporation\r
+ Copyright (c) 2006 - 2008, Intel Corporation \r
All rights reserved. This program and the accompanying materials \r
are licensed and made available under the terms and conditions of the BSD License \r
which accompanies this distribution. The full text of the license may be found at \r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
\r
- Module Name: PlatformToDriverConfiguration.h\r
-\r
**/\r
\r
#ifndef __PLATFORM_TO_DRIVER_CONFIGUARTION_H__\r
ParameterBlock has been processed via a Query and corresponding\r
Response call it must not be returned again via a Query call.\r
\r
- @param This A pointer to the\r
- EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL\r
- instance.\r
+ @param This A pointer to the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL instance.\r
\r
- @param ControllerHandle The handle the platform will return\r
- configuration information about.\r
+ @param ControllerHandle The handle the platform will return\r
+ configuration information about.\r
\r
- @param ChildHandle The handle of the child controller to\r
- return information on. This is an optional\r
- parameter that may be NULL. It will be\r
- NULL for device drivers, and for bus\r
- drivers that attempt to get options for\r
- the bus controller. It will not be NULL\r
- for a bus driver that attempts to get\r
- options for one of its child controllers.\r
+ @param ChildHandle The handle of the child controller to\r
+ return information on. This is an optional\r
+ parameter that may be NULL. It will be\r
+ NULL for device drivers, and for bus\r
+ drivers that attempt to get options for\r
+ the bus controller. It will not be NULL\r
+ for a bus driver that attempts to get\r
+ options for one of its child controllers.\r
\r
\r
- @param Instance Pointer to the Instance value. On output the\r
- instance associated with the parameter data\r
- return. On input zero means return the first\r
- query data or pass in a valid instance\r
- number returned from a previous call to\r
- Query.\r
-\r
- @param ParameterTypeGuid An EFI_GUID that defines the\r
- contents of ParameterBlock. UEFI\r
- drivers must use the\r
- ParameterTypeGuid to determine how\r
- to parser the ParameterBlock.\r
-\r
- @param ParameterBlock The platform returns a pointer to the\r
- ParameterBlock structure which\r
- contains details about the\r
- configuration parameters specific to\r
- the ParameterTypeGuid. This structure\r
- is defined based on the protocol and\r
- may be different for different\r
- protocols. UEFI driver decodes this\r
- structure and its contents based on\r
- ProtocolGuid. ParameterBlock is\r
- allocated by the platform and the\r
- platform is responsible for freeing\r
- the ParameterBlock after Result is\r
- called.\r
+ @param Instance Pointer to the Instance value. On output the\r
+ instance associated with the parameter data\r
+ return. On input zero means return the first\r
+ query data or pass in a valid instance\r
+ number returned from a previous call to\r
+ Query.\r
+\r
+ @param ParameterTypeGuid An EFI_GUID that defines the\r
+ contents of ParameterBlock. UEFI\r
+ drivers must use the\r
+ ParameterTypeGuid to determine how\r
+ to parser the ParameterBlock.\r
+\r
+ @param ParameterBlock The platform returns a pointer to the\r
+ ParameterBlock structure which\r
+ contains details about the\r
+ configuration parameters specific to\r
+ the ParameterTypeGuid. This structure\r
+ is defined based on the protocol and\r
+ may be different for different\r
+ protocols. UEFI driver decodes this\r
+ structure and its contents based on\r
+ ProtocolGuid. ParameterBlock is\r
+ allocated by the platform and the\r
+ platform is responsible for freeing\r
+ the ParameterBlock after Result is\r
+ called.\r
\r
@param ParameterBlockSize The platform returns the size of\r
the ParameterBlock in bytes.\r
\r
\r
- @retval EFI_SUCCESS The platform return parameter\r
- information for ControllerHandle.\r
+ @retval EFI_SUCCESS The platform return parameter\r
+ information for ControllerHandle.\r
\r
- @retval EFI_NOT_FOUND No more unread Instance exists.\r
+ @retval EFI_NOT_FOUND No more unread Instance exists.\r
\r
@retval EFI_INVALID_PARAMETER ControllerHandle is not a valid\r
EFI_HANDLE.\r
\r
@retval EFI_INVALID_PARAMETER Instance is NULL.\r
\r
- @retval EFI_DEVICE_ERROR A device error occurred while\r
- attempting to return parameter block\r
- information for the controller\r
- specified by ControllerHandle and\r
- ChildHandle.\r
+ @retval EFI_DEVICE_ERROR A device error occurred while\r
+ attempting to return parameter block\r
+ information for the controller\r
+ specified by ControllerHandle and\r
+ ChildHandle.\r
\r
- @retval EFI_OUT_RESOURCES There are not enough resources\r
- available to set the configuration\r
- options for the controller specified\r
- by ControllerHandle and ChildHandle.\r
+ @retval EFI_OUT_RESOURCES There are not enough resources\r
+ available to set the configuration\r
+ options for the controller specified\r
+ by ControllerHandle and ChildHandle.\r
\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_QUERY) (\r
+(EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_QUERY)(\r
IN CONST EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL *This,\r
IN CONST EFI_HANDLE ControllerHandle,\r
IN CONST EFI_HANDLE ChildHandle OPTIONAL,\r
IN OUT UINTN *ParameterBlockSize\r
);\r
\r
-/**\r
-\r
- @param EfiPlatformConfigurationActionNone\r
- The controller specified by ControllerHandle is still\r
- in a usable state, it's configuration has been updated\r
- via parsing the ParameterBlock. If required by the\r
- parameter block and the module supports an NVRAM store\r
- the configuration information from PB was successfully\r
- saved to the NVRAM. No actions are required before\r
- this controller can be used again with the updated\r
- configuration settings.\r
-\r
-\r
- @param EfiPlatformConfigurationStopController \r
- The driver has detected that the controller specified\r
- by ControllerHandle is not in a usable state, and it\r
- needs to be stopped. The calling agent can use the\r
- DisconnectControservice to perform this operation, and\r
- it should be performed as soon as possible.\r
-\r
- @param EfiPlatformConfigurationRestartController\r
- This controller specified by ControllerHandle needs to\r
- be stopped and restarted before it can be used again.\r
- The calling agent can use the DisconnectController()\r
- and ConnectController() services to perform this\r
- operation. The restart operation can be delayed until\r
- all of the configuratiooptions have been set.\r
-\r
-\r
- @param EfiPlatformConfigurationRestartPlatform\r
- A configuration change has been made that requires the\r
- platform to be restarted before the controller\r
- specified by ControllerHandle can be used again. The\r
- calling agent can use the ResetSystem() services to\r
- perform this operation. The restart operation can be\r
- delayed until all of the configuration options have\r
- been set.\r
-\r
- @param EfiPlatformConfigurationActionNvramFailed \r
- The controller specified by ControllerHandle is still\r
- in a usable state; its configuration has been updated\r
- via parsing the ParameterBlock. The driver tried to\r
- update the driver's private NVRAM store with\r
- information from ParameterBlock and failed. No actions\r
- are required before this controller can be used again\r
- with the updated configuration settings, but these\r
- configuration settings are not guaranteed to persist\r
- after ControllerHandle is stopped.\r
-\r
-**/\r
typedef enum {\r
+ ///\r
+ /// The controller specified by ControllerHandle is still\r
+ /// in a usable state, it's configuration has been updated\r
+ /// via parsing the ParameterBlock. If required by the\r
+ /// parameter block and the module supports an NVRAM store\r
+ /// the configuration information from PB was successfully\r
+ /// saved to the NVRAM. No actions are required before\r
+ /// this controller can be used again with the updated\r
+ /// configuration settings.\r
+ ///\r
EfiPlatformConfigurationActionNone = 0,\r
+ \r
+ ///\r
+ /// The driver has detected that the controller specified\r
+ /// by ControllerHandle is not in a usable state, and it\r
+ /// needs to be stopped. The calling agent can use the\r
+ /// DisconnectControservice to perform this operation, and\r
+ /// it should be performed as soon as possible. \r
+ ///\r
EfiPlatformConfigurationActionStopController = 1,\r
+ \r
+ ///\r
+ /// This controller specified by ControllerHandle needs to\r
+ /// be stopped and restarted before it can be used again.\r
+ /// The calling agent can use the DisconnectController()\r
+ /// and ConnectController() services to perform this\r
+ /// operation. The restart operation can be delayed until\r
+ /// all of the configuratiooptions have been set. \r
+ ///\r
EfiPlatformConfigurationActionRestartController = 2,\r
+ \r
+ ///\r
+ /// A configuration change has been made that requires the\r
+ /// platform to be restarted before the controller\r
+ /// specified by ControllerHandle can be used again. The\r
+ /// calling agent can use the ResetSystem() services to\r
+ /// perform this operation. The restart operation can be\r
+ /// delayed until all of the configuration options have\r
+ /// been set. \r
+ ///\r
EfiPlatformConfigurationActionRestartPlatform = 3,\r
+\r
+ ///\r
+ /// The controller specified by ControllerHandle is still\r
+ /// in a usable state; its configuration has been updated\r
+ /// via parsing the ParameterBlock. The driver tried to\r
+ /// update the driver's private NVRAM store with\r
+ /// information from ParameterBlock and failed. No actions\r
+ /// are required before this controller can be used again\r
+ /// with the updated configuration settings, but these\r
+ /// configuration settings are not guaranteed to persist\r
+ /// after ControllerHandle is stopped. \r
+ /// \r
EfiPlatformConfigurationActionNvramFailed = 4,\r
EfiPlatformConfigurationActionMaximum\r
} EFI_PLATFORM_CONFIGURATION_ACTION;\r
ParameterTypeGuid. The platform is responsible for freeing\r
ParameterBlock and the UEFI driver must not try to free it\r
\r
- @param This A pointer to the\r
- EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL\r
- instance.\r
+ @param This A pointer to the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL instance.\r
\r
- @param ControllerHandle The handle the driver is returning\r
- configuration information about.\r
+ @param ControllerHandle The handle the driver is returning\r
+ configuration information about.\r
\r
- @param ChildHandle The handle of the child controller to\r
- return information on. This is an optional\r
- parameter that may be NULL. It will be\r
- NULL for device drivers, and for bus\r
- drivers that attempt to get options for\r
- the bus controller. It will not be NULL\r
- for a bus driver that attempts to get\r
- options for one of its child controllers.\r
- Instance Instance data returned from\r
- Query().\r
+ @param ChildHandle The handle of the child controller to\r
+ return information on. This is an optional\r
+ parameter that may be NULL. It will be\r
+ NULL for device drivers, and for bus\r
+ drivers that attempt to get options for\r
+ the bus controller. It will not be NULL\r
+ for a bus driver that attempts to get\r
+ options for one of its child controllers.\r
+ Instance Instance data returned from\r
+ Query().\r
\r
- @param ParameterTypeGuid ParameterTypeGuid returned from\r
- Query.\r
+ @param ParameterTypeGuid ParameterTypeGuid returned from Query.\r
\r
- @param ParameterBlock ParameterBlock returned from Query.\r
+ @param ParameterBlock ParameterBlock returned from Query.\r
\r
- @param ParameterBlockSize The ParameterBlock size returned\r
- from Query.\r
+ @param ParameterBlockSize The ParameterBlock size returned from Query.\r
\r
- @param Configuration ActionThe driver tells the platform what\r
- action is required for ParameterBlock to\r
- take effect.\r
+ @param Configuration ActionThe driver tells the platform what\r
+ action is required for ParameterBlock to\r
+ take effect.\r
\r
\r
- @retval EFI_SUCCESS The platform return parameter information\r
- for ControllerHandle.\r
+ @retval EFI_SUCCESS The platform return parameter information\r
+ for ControllerHandle.\r
\r
- @retval EFI_NOT_FOUND Instance was not found.\r
- \r
- @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid\r
- EFI_HANDLE.\r
+ @retval EFI_NOT_FOUND Instance was not found.\r
\r
+ @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.\r
+ \r
@retval EFI_INVALID_PARAMETER Instance is zero.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_RESPONSE) (\r
+(EFIAPI *EFI_PLATFORM_TO_DRIVER_CONFIGURATION_RESPONSE)(\r
IN CONST EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL *This,\r
IN CONST EFI_HANDLE ControllerHandle,\r
IN CONST EFI_HANDLE ChildHandle OPTIONAL,\r
);\r
\r
\r
-/**\r
- The EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL is used by the\r
- UEFI driver to query the platform for configuration information.\r
- The UEFI driver calls Query() multiple times to get\r
- configuration information from the platform. For every call to\r
- Query() there must be a matching call to Response() so the\r
- UEFI driver can inform the platform how it used the\r
- information passed in from Query(). It¡¯s legal for a UEFI\r
- driver to use Response() to inform the platform it does not\r
- understand the data returned via Query() and thus no action was\r
- taken.\r
-\r
- @param Query Called by the UEFI Driver Start() function to\r
- get configuration information from the\r
- platform.\r
- \r
- @param Response Called by the UEFI Driver Start() function\r
- to let the platform know how UEFI driver\r
- processed the data return from Query.\r
- \r
-\r
-**/\r
+///\r
+/// The EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL is used by the\r
+/// UEFI driver to query the platform for configuration information.\r
+/// The UEFI driver calls Query() multiple times to get\r
+/// configuration information from the platform. For every call to\r
+/// Query() there must be a matching call to Response() so the\r
+/// UEFI driver can inform the platform how it used the\r
+/// information passed in from Query(). It's legal for a UEFI\r
+/// driver to use Response() to inform the platform it does not\r
+/// understand the data returned via Query() and thus no action was\r
+/// taken.\r
+///\r
struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL {\r
EFI_PLATFORM_TO_DRIVER_CONFIGURATION_QUERY Query;\r
EFI_PLATFORM_TO_DRIVER_CONFIGURATION_RESPONSE Response;\r
versions of the DMTF SM CLP Specification require changes to the\r
parameter block definition, newer ParameterTypeGuid will be\r
used.\r
-\r
- @param CLPCommand A pointer to the DMTF SM CLP command line\r
- null-terminated string that the driver is\r
- required to parse and process when this\r
- EFI_SUCCESS The platform return parameter\r
- information for ControllerHandle.\r
- EFI_NOT_FOUND Instance was not found.\r
- EFI_INVALID_PARAMETER ControllerHandle is\r
- not a valid EFI_HANDLE.\r
- EFI_INVALID_PARAMETER Instance is zero.\r
- function is called. See the DMTF SM CLP\r
- Specification 1.0 Final Standard for\r
- details on the format and syntax of the\r
- CLP command line string. CLPCommand buffer\r
- is allocated by the producer of the\r
- EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOOL.\r
-\r
- @param CLPCommandLength The length of the CLP Command in\r
- bytes.\r
-\r
- @param CLPReturnString A pointer to the CLP return status\r
- string that the driver is required to\r
- provide to the calling agent. The\r
- calling agent may parse and/ or pass\r
- this for processing and user feedback.\r
- The SM CLP Command Response string\r
- buffer is filled in by the UEFI driver\r
- in the "keyword=value" format\r
- described in the SM CLP Specification,\r
- unless otherwise requested via the SM\r
- CLP Coutput option in the Command Line\r
- string buffer. UEFI driver's support\r
- for this default "keyword=value"\r
- output format is required if the UEFI\r
- driver supports this protocol, while\r
- support for other SM CLP output\r
- formats is optional (the UEFI Driver\r
- should return an EFI_UNSUPPORTED if\r
- the SM CLP Coutput option requested by\r
- the caller is not supported by the\r
- UEFI Driver). CLPReturnString buffer\r
- is allocated by the consumer of the\r
- EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC\r
- OL and undefined prior to the call to\r
- Response().\r
-\r
- @param CLPReturnStringLength The length of the CLP return\r
- status string in bytes.\r
-\r
- @param CLPReturnStatus SM CLP Command Status (see DMTF SM CLP\r
- Specification 1.0 Final Standard -\r
- Table 4) CLPErrorValue SM CLP\r
- Processing Error Value (see DMTF SM\r
- CLP Specification 1.0 Final Standard -\r
- Table 6). This field is filled in by\r
- the consumer of the\r
- EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC \r
- OL and undefined prior to the call to\r
- Response().\r
-\r
- @param CLPMessageCode Bit 15: OEM Message Code Flag 0 =\r
- Message Code is an SM CLP Probable\r
- Cause Value. (see SM CLP Specification\r
- Table 11) 1 = Message Code is OEM\r
- Specific Bits 14-0: Message Code This\r
- field is filled in by the consumer of\r
- the\r
- EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC\r
- OL and undefined prior to the call to\r
- Response().\r
-\r
**/\r
typedef struct {\r
- CHAR8 *CLPCommand;\r
- UINT32 CLPCommandLength;\r
- CHAR8 *CLPReturnString;\r
- UINT32 CLPReturnStringLength;\r
- UINT8 CLPCmdStatus;\r
- UINT8 CLPErrorValue;\r
- UINT16 CLPMsgCode;\r
+ CHAR8 *CLPCommand; ///< A pointer to the DMTF SM CLP command line null-terminated string that the \r
+ ///< driver is required to parse and process when this EFI_SUCCESS The platform \r
+ ///< return parameter information for ControllerHandle. EFI_NOT_FOUND Instance \r
+ ///< was not found. EFI_INVALID_PARAMETER ControllerHandle is not a valid \r
+ ///< EFI_HANDLE. EFI_INVALID_PARAMETER Instance is zero. function is called. \r
+ ///< See the DMTF SM CLP Specification 1.0 Final Standard for details on the \r
+ ///< format and syntax of the CLP command line string. CLPCommand buffer\r
+ ///< is allocated by the producer of the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOOL.\r
+ UINT32 CLPCommandLength; ///< The length of the CLP Command in bytes.\r
+ CHAR8 *CLPReturnString; ///< A pointer to the CLP return status string that the driver is required to\r
+ ///< provide to the calling agent. The calling agent may parse and/ or pass\r
+ ///< this for processing and user feedback. The SM CLP Command Response string\r
+ ///< buffer is filled in by the UEFI driver in the "keyword=value" format\r
+ ///< described in the SM CLP Specification, unless otherwise requested via the SM\r
+ ///< CLP Coutput option in the Command Line string buffer. UEFI driver's support\r
+ ///< for this default "keyword=value" output format is required if the UEFI\r
+ ///< driver supports this protocol, while support for other SM CLP output\r
+ ///< formats is optional (the UEFI Driver should return an EFI_UNSUPPORTED if\r
+ ///< the SM CLP Coutput option requested by the caller is not supported by the\r
+ ///< UEFI Driver). CLPReturnString buffer is allocated by the consumer of the\r
+ ///< EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL and undefined prior to the call to\r
+ ///< Response(). \r
+ UINT32 CLPReturnStringLength; ///< The length of the CLP return status string in bytes.\r
+ UINT8 CLPCmdStatus; ///< SM CLP Command Status (see DMTF SM CLP Specification 1.0 Final Standard -\r
+ ///< Table 4) CLPErrorValue SM CLP Processing Error Value (see DMTF SM\r
+ ///< CLP Specification 1.0 Final Standard - Table 6). This field is filled in by\r
+ ///< the consumer of the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC \r
+ ///< OL and undefined prior to the call to Response(). \r
+ UINT8 CLPErrorValue; ///< SM CLP Processing Error Value (see DMTF SM CLP Specification 1.0 Final Standard - Table 6).\r
+ ///< This field is filled in by the consumer of the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL and undefined prior to the call to Response(). \r
+ UINT16 CLPMsgCode; ///< Bit 15: OEM Message Code Flag 0 = Message Code is an SM CLP Probable\r
+ ///< Cause Value. (see SM CLP Specification Table 11) 1 = Message Code is OEM\r
+ ///< Specific Bits 14-0: Message Code This field is filled in by the consumer of\r
+ ///< the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL and undefined prior to the call to\r
+ ///< Response(). \r
+\r
} EFI_CONFIGURE_CLP_PARAMETER_BLK;\r
\r
\r
projects / mirror_edk2.git / blobdiff