EFI DRIVER CONFIGURATION PROTOCOL

From PhoenixWiki

Jump to: navigation, search

Used to set configuration options for a controller that an EFI Driver is managing.

Contents

GUID

#define EFI_DRIVER_CONFIGURATION_PROTOCOL_GUID \
  { 0x107a772b,0xd5e1,0x11d4,0x9a,0x46,0x0,0x90,0x27,0x3f,0xc1,0x4d }

Protocol Interface Structure

typedef struct _EFI_DRIVER_CONFIGURATION_PROTOCOL {
  EFI_DRIVER_CONFIGURATION_SET_OPTIONS SetOptions;
  EFI_DRIVER_CONFIGURATION_OPTIONS_VALID OptionsValid;
  EFI_DRIVER_CONFIGURATION_FORCE_DEFAULTS ForceDefaults;
  CHAR8 *SupportedLanguages;
} EFI_DRIVER_CONFIGURATION_PROTOCOL;

Members

Member Description
SetOptions Allows the use to set drivers specific configuration options for a controller that the driver is currently managing.
OptionsValid Tests to see if a controller’s current configuration options are valid.
ForceDefaults Forces a driver to set the default configuration options for a controller.
SupportedLanguages A null-terminated ASCII string that contains one or more ISO 639-2 language codes. This is the list of language codes that this protocol supports.

Description

The EFI_DRIVER_CONFIGURATION_PROTOCOL is used by a platform management utility to allow the user to set controller specific options. This protocol is optionally attached to the image handle of driver in the driver’s entry point. The platform management utility can collect all the EFI_DRIVER_CONFIGURATION_PROTOCOL instances present in the system, and present the user with a menu of the controllers than have user selectable options. This platform management utility is invoked through a platform component such as the EFI Boot Manager.

SetOptions()

Allows the user to set controller specific options for a controller that a driver is currently managing.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_DRIVER_CONFIGURATION_SET_OPTIONS) (
  IN EFI_DRIVER_CONFIGURATION_PROTOCOL *This,
  IN EFI_HANDLE ControllerHandle,
  IN EFI_HANDLE ChildHandle OPTIONAL,
  IN CHAR8 *Language,
  OUT EFI_DRIVER_CONFIGURATION_ACTION_REQUIRED *ActionRequired);

Parameters

Parameter Description
This A pointer to the EFI_DRIVER_CONFIGURATION_PROTOCOL instance.
ControllerHandle The handle of the controller to set options on. If ControllerHandle is a valid EFI_HANDLE that is being managed by this driver, then the user will be allowed to set options for the controller specified by ControllerHandle. If this parameter is NULL, then the options will be set for all the controllers that this driver is currently managing. If ControllerHandle is NULL, then setting options for a child controller is not supported, so ChildHandle must also be NULL.
ChildHandle The handle of the child controller to set options on. This is an optional parameter that may be NULL. It will be NULL for device drivers, and for a bus drivers that wish to set options for the bus controller. It will not be NULL for a bus driver that wishes to set options for one of its child controllers.
Language A pointer to a three character ISO 639-2 language identifier. This is the language of the user interface that should be presented to the user, and it must match one of the languages specified in SupportedLanguages. The number of languages supported by a driver is up to the driver writer.
ActionRequired A pointer to the action that the calling agent is required to perform when this function returns.

Description
This function allows the configuration options to be set for the driver specified by This on the controller specified by ControllerHandle and ChildHandle. This function must only use the EFI_SIMPLE_TEXT_INPUT_PROTOCOL and EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL from the EFI_SYSTEM_TABLE to interact with the user, and it must use the language specified by Language. If the driver specified by This does not support the language specified by Language, then EFI_UNSUPPORTED is returned. If the controller specified by ControllerHandle and ChildHandle is not supported by the driver specified by This, then EFI_UNSUPPORTED is returned. If a device error occurs while setting the configuration options, EFI_DEVICE_ERROR is returned. If there are not enough resources available to set the configuration options, then EFI_OUT_OF_RESOURCES is returned.

The ActionRequired return value must always be set to a legal value by this function. The caller must perform the required action regardless of the return status. The calling agent must also perform the action described by ActionRequired prior to using any of the services produced by ControllerHandle or any of its children.

Status Codes Returned
EFI_SUCCESS The driver specified by This successfully set the configuration options for the controller specified by ControllerHandle. EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid EFI_HANDLE. EFI_INVALID_PARAMETER ActionRequired is NULL. EFI_UNSUPPORTED The driver specified by This does not support setting configuration options for the controller specified by ControllerHandle and ChildHandle. EFI_UNSUPPORTED The driver specified by This does not support the language specified by Language. EFI_DEVICE_ERROR A device error occurred while attempt to set the configuration options for the controller specified by ControllerHandle and ChildHandle. EFI_OUT_RESOURCES There are not enough resources available to set the configuration options for the controller specified by ControllerHandle and ChildHandle.

OptionsValid()

Tests to see if a controller’s current configuration options are valid. Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_DRIVER_CONFIGURATION_OPTIONS_VALID) (
  IN EFI_DRIVER_CONFIGURATION_PROTOCOL *This,
  IN EFI_HANDLE ControllerHandle,
  IN EFI_HANDLE ChildHandle OPTIONAL);

Parameters

Parameter Description
This A pointer to the EFI_DRIVER_CONFIGURATION_PROTOCOL instance.
ControllerHandle The handle of the controller to test if it’s current configuration options are valid.
ChildHandle The handle of the child controller to test if it’s current configuration options are valid. This is an optional parameter that may be NULL. It will be NULL for device drivers. It will also be NULL for a bus drivers that wish to test the configuration options for the bus controller. It will not be NULL for a bus driver that wishes to test configuration options for one of its child controllers.

Description
This function tests to see if the configuration options for the driver specified by This on the controller specified by ControllerHandle and ChildHandle are valid. If they are, then EFI_SUCCESS is returned. If they are not valid, then EFI_DEVICE_ERROR is returned. If the controller specified by ControllerHandle and ChildHandle is not currently being managed by the driver specified by This, then EFI_UNSUPPORTED is returned. This function is not allowed to interact with the user. Since the driver is responsible for maintaining the configuration options for each controller it manages, the exact method by which the configuration options are validated is driver specific.

Status Codes Returned
EFI_SUCCESS The controller specified by ControllerHandle and ChildHandle that is being managed by the driver specified by This has a valid set of configuration options. EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid EFI_HANDLE. EFI_UNSUPPORTED The driver specified by This is not currently managing the controller specified by ControllerHandle and ChildHandle. EFI_DEVICE_ERROR The controller specified by ControllerHandle and ChildHandle that is being managed by the driver specified by This has an invalid set of configuration options.

ForceDefaults()

Forces a driver to set the default configuration options for a controller.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_DRIVER_CONFIGURATION_FORCE_DEFAULTS) (
  IN EFI_DRIVER_CONFIGURATION_PROTOCOL *This,
  IN EFI_HANDLE ControllerHandle,
  IN EFI_HANDLE ChildHandle OPTIONAL,
  IN UINT32 DefaultType,
  OUT EFI_DRIVER_CONFIGURATION_ACTION_REQUIRED *ActionRequired);

Parameters

Parameter Description
This A pointer to the EFI_DRIVER_CONFIGURATION_PROTOCOL instance.
ControllerHandle The handle of the controller to force default configuration options on.
ChildHandle The handle of the child controller to force default configuration options on. This is an optional parameter that may be NULL. It will be NULL for device drivers. It will also be NULL for a bus drivers that wish to force default configuration options for the bus controller. It will not be NULL for a bus driver that wishes to force default configuration options for one of its child controllers.
DefaultType The type of default configuration options to force on the controller specified by ControllerHandle and ChildHandle. A DefaultType of 0x00000000 must be supported by this protocol.
ActionRequired A pointer to the action that the calling agent is required to perform when this function returns.

Description
This function forces the default configuration options specified by DefaultType for the driver specified by This on the controller specified by ControllerHandle and ChildHandle.

This function is not allowed to interact with the user. If the controller specified by ControllerHandle and ChildHandle is not supported by the driver specified by This, then EFI_UNSUPPORTED is returned. If the configuration type specified by DefaultType is not supported, then EFI_UNSUPPORTED is returned. If a device error occurs while setting the default configuration options, EFI_DEVICE_ERROR is returned. If there are not enough resources available to set the default configuration options, then EFI_OUT_OF_RESOURCES is returned.

The ActionRequired return value must always be set to a legal value by this function. The caller must perform the required action regardless of the return status. The calling agent must also perform the action described by ActionRequired prior to using any of the services produced by ControllerHandle or any of its children.

Status Codes Returned
EFI_SUCCESS The driver specified by This successfully forced the default configuration options on the controller specified by ControllerHandle and ChildHandle. EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid EFI_HANDLE. EFI_INVALID_PARAMETER ActionRequired is NULL. EFI_UNSUPPORTED The driver specified by This does not support forcing the default configuration options on the controller specified by ControllerHandle and ChildHandle. EFI_UNSUPPORTED The driver specified by This does not support the configuration type specified by DefaultType. EFI_DEVICE_ERROR A device error occurred while attempt to force the default configuration options on the controller specified by ControllerHandle and ChildHandle. EFI_OUT_RESOURCES There are not enough resources available to force the default configuration options on the controller specified by ControllerHandle and ChildHandle.


Copyright (C) 2009 Phoenix Technologies Ltd. All Rights Reserved. Portions Copyright (C) 2009 UEFI Forum, Inc. Used by permission.

Personal tools