Checked in the Protocols introduced in UEFI/PI.
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@2674 6f19259b-4bc3-4df7-8a09-765794883524
This commit is contained in:
397
MdePkg/Include/Protocol/PlatformToDriverConfiguration.h
Normal file
397
MdePkg/Include/Protocol/PlatformToDriverConfiguration.h
Normal file
@@ -0,0 +1,397 @@
|
||||
/** @file
|
||||
The file provides the protocol to retrieve configuration
|
||||
information for a device that a UEFI driver is about to start.
|
||||
|
||||
Copyright (c) 2006 - 2007, Intel Corporation
|
||||
All rights reserved. This program and the accompanying materials
|
||||
are licensed and made available under the terms and conditions of the BSD License
|
||||
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.
|
||||
|
||||
Module Name: PlatformToDriverConfiguration.h
|
||||
|
||||
**/
|
||||
|
||||
#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 returned from the
|
||||
corresponding call to Query. The UEFI driver must continuously
|
||||
call Query and Response until EFI_NOT_FOUND is returned by
|
||||
Query. The only value of Instance that has meaning to the UEFI
|
||||
driver is zero. An Instance value of zero means return the first
|
||||
ParameterBlock in the set of unprocessed parameter blocks. If a
|
||||
ParameterBlock has been processed via a Query and corresponding
|
||||
Response call it must not be returned again via a Query call.
|
||||
|
||||
@param This A pointer to the
|
||||
EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOC OL
|
||||
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. On output the
|
||||
instance associated with the parameter data
|
||||
return. On input zero means return the first
|
||||
query data or pass in a valid instance
|
||||
number returned from a previous call to
|
||||
Query.
|
||||
|
||||
@param ParameterTypeGuid An EFI_GUID that defines the
|
||||
contents of ParameterBlock. UEFI
|
||||
drivers must use the
|
||||
ParameterTypeGuid to determine how
|
||||
to parser the ParameterBlock.
|
||||
|
||||
@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
|
||||
ProtocolGuid. 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 not a valid
|
||||
EFI_HANDLE.
|
||||
|
||||
@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 OUT UINTN *Instance,
|
||||
IN OUT EFI_GUID **ParameterTypeGuid,
|
||||
IN OUT VOID **ParameterBlock,
|
||||
IN OUT UINTN *ParameterBlockSize
|
||||
);
|
||||
|
||||
/**
|
||||
|
||||
@param EfiPlatformConfigurationActionNone
|
||||
The controller specified by ControllerHandle is still
|
||||
in a usable state, it's 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.
|
||||
|
||||
|
||||
@param EfiPlatformConfigurationStopController
|
||||
The driver has detected that the controller specified
|
||||
by ControllerHandle is not in a usable state, and it
|
||||
needs to be stopped. The calling agent can use the
|
||||
DisconnectControservice to perform this operation, and
|
||||
it should be performed as soon as possible.
|
||||
|
||||
@param EfiPlatformConfigurationRestartController
|
||||
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 configuratiooptions have been set.
|
||||
|
||||
|
||||
@param EfiPlatformConfigurationRestartPlatform
|
||||
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.
|
||||
|
||||
@param EfiPlatformConfigurationActionNvramFailed
|
||||
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.
|
||||
|
||||
**/
|
||||
typedef enum {
|
||||
EfiPlatformConfigurationActionNone = 0,
|
||||
EfiPlatformConfigurationActionStopController = 1,
|
||||
EfiPlatformConfigurationActionRestartController = 2,
|
||||
EfiPlatformConfigurationActionRestartPlatform = 3,
|
||||
EfiPlatformConfigurationActionNvramFailed = 4,
|
||||
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_PROTOC OL
|
||||
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 ParameterTypeGuid ParameterTypeGuid returned from
|
||||
Query.
|
||||
|
||||
@param ParameterBlock ParameterBlock returned from Query.
|
||||
|
||||
@param ParameterBlockSize The ParameterBlock size returned
|
||||
from Query.
|
||||
|
||||
@param Configuration ActionThe 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 not a valid
|
||||
EFI_HANDLE.
|
||||
|
||||
@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<49><74>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.
|
||||
|
||||
@param Query Called by the UEFI Driver Start() function to
|
||||
get configuration information from the
|
||||
platform.
|
||||
|
||||
@param Response Called by the UEFI Driver Start() function
|
||||
to let the platform know how UEFI driver
|
||||
processed the data return from Query.
|
||||
|
||||
|
||||
**/
|
||||
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, newer ParameterTypeGuid will be
|
||||
used.
|
||||
|
||||
@param CLPCommand A pointer to the DMTF SM CLP command line
|
||||
null-terminated string that the driver is
|
||||
required to parse and process when this
|
||||
EFI_SUCCESS The platform return parameter
|
||||
information for ControllerHandle.
|
||||
EFI_NOT_FOUND Instance was not found.
|
||||
EFI_INVALID_PARAMETER ControllerHandle is
|
||||
not a valid EFI_HANDLE.
|
||||
EFI_INVALID_PARAMETER Instance is zero.
|
||||
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.
|
||||
|
||||
@param CLPCommandLength The length of the CLP Command in
|
||||
bytes.
|
||||
|
||||
@param CLPReturnString A pointer to the CLP return status
|
||||
string 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().
|
||||
|
||||
@param CLPReturnStringLength The length of the CLP return
|
||||
status string in bytes.
|
||||
|
||||
@param CLPReturnStatus 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().
|
||||
|
||||
@param CLPMessageCode 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().
|
||||
|
||||
**/
|
||||
typedef struct {
|
||||
CHAR8 *CLPCommand;
|
||||
UINT32 CLPCommandLength;
|
||||
CHAR8 *CLPReturnString;
|
||||
UINT32 CLPReturnStringLength;
|
||||
UINT8 CLPCmdStatus;
|
||||
UINT8 CLPErrorValue;
|
||||
UINT16 CLPMsgCode;
|
||||
} EFI_CONFIGURE_CLP_PARAMETER_BLK;
|
||||
|
||||
|
||||
|
||||
extern EFI_GUID gEfiPlatformToDriverConfigurationClpGuid;
|
||||
|
||||
extern EFI_GUID gEfiPlatformToDriverConfigurationProtocolGuid;
|
||||
|
||||
#endif
|
Reference in New Issue
Block a user