text: /** @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 - 2018, Intel Corporation. All rights reserved.<BR>
    SPDX-License-Identifier: BSD-2-Clause-Patent
  
  **/
  
  #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
  