mirror of https://github.com/acidanthera/audk.git
396 lines
18 KiB
C
396 lines
18 KiB
C
/** @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.
|
||
|
||
**/
|
||
|
||
#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
|