tyler.durden
/
audk
mirror of https://github.com/acidanthera/audk.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
audk/MdePkg/Include/Protocol/PlatformToDriverConfigurati...

396 lines
18 KiB
C
Raw Normal View History

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
2007-06-19 12:12:02 +02:00
/** @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<EFBFBD><EFBFBD>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