Add new protocol definitions:

Efi Dirver Family Override protocol, Efi Driver Health protocol & Efi Loaded Image Protocol

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@4633 6f19259b-4bc3-4df7-8a09-765794883524

4 files changed, 334 insertions, 0 deletions

diff --git a/MdePkg/Include/Protocol/DriverFamilyOverride.h b/MdePkg/Include/Protocol/DriverFamilyOverride.h
new file mode 100644
index 0000000000..7295d9b825
--- /dev/null
+++ b/MdePkg/Include/Protocol/DriverFamilyOverride.h
@@ -0,0 +1,70 @@
+/** @file

+  EFI Driver Family Protocol

+

+  Copyright (c) 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 __EFI_DRIVER_FAMILY_OVERRIDE_H__

+#define __EFI_DRIVER_FAMILY_OVERRIDE_H__

+

+#define EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL_GUID \

+  { \

+    0xb1ee129e, 0xda36, 0x4181, { 0x91, 0xf8, 0x4, 0xa4, 0x92, 0x37, 0x66, 0xa7 } \

+  }

+  

+typedef struct _EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL  EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL;

+

+//

+// Prototypes for the Driver Family Override Protocol

+//

+// 

+/**                                                                 

+  This function returns the version value associated with the driver specified by This.

+

+  Retrieves the version of the driver that is used by the EFI Boot Service ConnectController()

+  to sort the set of Driver Binding Protocols in order from highest priority to lowest priority.

+  For drivers that support the Driver Family Override Protocol, those drivers are sorted so that

+  the drivers with higher values returned by GetVersion() are high priority that drivers that

+  return lower values from GetVersion().

+

+  @param  This                  A pointer to the EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL instance.                            

+                                

+  @return The version value associated with the driver specified by This.                                  

+                                   

+**/

+typedef

+UINT32

+(EFIAPI *EFI_DRIVER_FAMILY_OVERRIDE_GET_VERSION) (

+  IN EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL    *This

+  );

+

+/**

+  When installed, the Driver Family Override Protocol produces a GUID that represets 

+  a family of drivers.  Drivers with the same GUID are members of the same family 

+  When drivers are connected to controllers, drivers with a higher revision value 

+  in the same driver family are connected with a higher priority than drivers 

+  with a lower revision value in the same driver family.  The EFI Boot Service

+  Connect Controller uses five rules to build a prioritied list of drivers when 

+  a request is made to connect a driver to a controller.  The Driver Family Protocol

+  rule is between the Platform Specific Driver Override Protocol and above the 

+  Bus Specific Driver Override Protocol  

+

+  @param FamilyGuid    A pointer to the GUID that represnets the family of drivers

+                       that the driver producing this protocol is a member.

+

+**/

+struct _EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL {

+  EFI_DRIVER_FAMILY_OVERRIDE_GET_VERSION GetVersion;

+};

+

+extern EFI_GUID gEfiDriverFamilyOverrideProtocolGuid;

+

+#endif

diff --git a/MdePkg/Include/Protocol/DriverHealth.h b/MdePkg/Include/Protocol/DriverHealth.h
new file mode 100644
index 0000000000..c717eb426b
--- /dev/null
+++ b/MdePkg/Include/Protocol/DriverHealth.h
@@ -0,0 +1,255 @@
+/** @file

+  EFI Driver Health Protocol

+

+  Copyright (c) 2006, 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 __EFI_DRIVER_HEALTH_H__

+#define __EFI_DRIVER_HEALTH_H__

+

+#define EFI_DRIVER_HEALTH_PROTOCOL_GUID \

+  { \

+    0x2a534210, 0x9280, 0x41d8, { 0xae, 0x79, 0xca, 0xda, 0x1, 0xa2, 0xb1, 0x27 } \

+  }

+  

+typedef struct _EFI_DRIVER_HEALTH_PROTOCOL  EFI_DRIVER_HEALTH_PROTOCOL;

+

+//

+// EFI_DRIVER_HEALTH_HEALTH_STATUS

+//

+typedef enum {

+  EfiDriverHealthStatusHealthy,

+  EfiDriverHealthStatusRepairRequired,

+  EfiDriverHealthStatusConfigurationRequired,

+  EfiDriverHealthStatusFailed,

+  EfiDriverHealthStatusReconnectRequired,

+  EfiDriverHealthStatusRebootRequired

+} EFI_DRIVER_HEALTH_HEALTH_STATUS;

+

+//

+// EFI_DRIVER_HEALTH_HII_MESSAGE

+//

+typedef struct {

+  EFI_HII_HANDLE  HiiHandle;

+  EFI_STRING_ID   StringId;

+  UINT64          Reserved;

+} EFI_DRIVER_HEALTH_HII_MESSAGE;

+

+/**

+  Reports the progress of a repair operation

+

+  @param  Value            A value between 0 and Limit that identifies the current 

+                           progress of the repair operation.

+  

+  @param  Limit            The maximum value of Value for the current repair operation.

+                           For example, a driver that wants to specify progress in 

+                           percent would use a Limit value of 100.

+**/

+typedef

+VOID

+(EFIAPI *EFI_DRIVER_HEALTH_REPAIR_PROGRESS_NOTIFY) (

+  IN UINTN  Value,

+  IN UINTN  Limit

+  );

+

+/**

+  Retrieves the health status of a controller in the platform.  This function can also 

+  optionally return warning messages, error messages, and a set of HII Forms that may 

+  be repair a controller that is not proper configured. 

+  

+  @param  This             A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.

+

+  @param  ControllerHandle The handle of the controller to retrieve the health status 

+                           on.  This is an optional parameter that may be NULL.  If 

+                           this parameter is NULL, then the value of ChildHandle is 

+                           ignored, and the combined health status of all the devices 

+                           that the driver is managing is returned.

+

+  @param  ChildHandle      The handle of the child controller to retrieve the health 

+                           status on.  This is an optional parameter that may be NULL.  

+                           This parameter is ignored of ControllerHandle is NULL.  It 

+                           will be NULL for device drivers.  It will also be NULL for 

+                           bus drivers when an attempt is made to collect the health 

+                           status of the bus controller.  If will not be NULL when an 

+                           attempt is made to collect the health status for a child 

+                           controller produced by the driver.

+

+  @param  HealthStatus     A pointer to the health status that is returned by this 

+                           function.  This is an optional parameter that may be NULL.  

+                           This parameter is ignored of ControllerHandle is NULL.  

+                           The health status for the controller specified by 

+                           ControllerHandle and ChildHandle is returned. 

+

+  @param  MessageList      A pointer to an array of warning or error messages associated 

+                           with the controller specified by ControllerHandle and 

+                           ChildHandle.  This is an optional parameter that may be NULL.  

+                           MessageList is allocated by this function with the EFI Boot 

+                           Service AllocatePool(), and it is the caller's responsibility 

+                           to free MessageList with the EFI Boot Service FreePool().  

+                           Each message is specified by tuple of an EFI_HII_HANDLE and 

+                           an EFI_STRING_ID.  The array of messages is terminated by tuple 

+                           containing a EFI_HII_HANDLE with a value of NULL.  The 

+                           EFI_HII_STRING_PROTOCOL.GetString() function can be used to 

+                           retrieve the warning or error message as a Null-terminated 

+                           Unicode string in a specific language.  Messages may be 

+                           returned for any of the HealthStatus values except 

+                           EfiDriverHealthStatusReconnectRequired and 

+                           EfiDriverHealthStatusRebootRequired.

+

+  @param  FormHiiHandle    A pointer to the HII handle for an HII form associated with the 

+                           controller specified by ControllerHandle and ChildHandle.  

+                           This is an optional parameter that may be NULL.  An HII form 

+                           is specified by a combination of an EFI_HII_HANDLE and an 

+                           EFI_GUID that identifies the Form Set GUID.  The 

+                           EFI_FORM_BROWSER2_PROTOCOL.SendForm() function can be used 

+                           to display and allow the user to make configuration changes 

+                           to the HII Form.  An HII form may only be returned with a 

+                           HealthStatus value of EfiDriverHealthStatusConfigurationRequired.

+

+  @param  FormSetGuid      A pointer to the GUID for an HII form associated with the 

+                           controller specified by ControllerHandle and ChildHandle.  

+                           This is an optional parameter that may be NULL.  An HII form 

+                           is specified by a combination of an EFI_HII_HANDLE and an 

+                           EFI_GUID that identifies the Form Set GUID.  The 

+                           EFI_FORM_BROWSER2_PROTOCOL.SendForm() function can be used 

+                           to display and allow the user to make configuration changes 

+                           to the HII Form.  An HII form may only be returned with a 

+                           HealthStatus value of EfiDriverHealthStatusConfigurationRequired.

+

+  @retval EFI_SUCCESS           ControllerHandle is NULL, and all the controllers 

+                                managed by this driver specified by This have a health 

+                                status of EfiDriverHealthStatusHealthy with no warning 

+                                messages to be returned.  The ChildHandle, HealthStatus, 

+                                MessageList, and FormList parameters are ignored.

+

+  @retval EFI_DEVICE_ERROR      ControllerHandle is NULL, and one or more of the 

+                                controllers managed by this driver specified by This 

+                                do not have a health status of EfiDriverHealthStatusHealthy.  

+                                The ChildHandle, HealthStatus, MessageList, and 

+                                FormList parameters are ignored.

+

+  @retval EFI_DEVICE_ERROR      ControllerHandle is NULL, and one or more of the 

+                                controllers managed by this driver specified by This 

+                                have one or more warning and/or error messages.  

+                                The ChildHandle, HealthStatus, MessageList, and 

+                                FormList parameters are ignored.

+

+  @retval EFI_SUCCESS           ControllerHandle is not NULL and the health status 

+                                of the controller specified by ControllerHandle and 

+                                ChildHandle was returned in HealthStatus.  A list 

+                                of warning and error messages may be optionally 

+                                returned in MessageList, and a list of HII Forms 

+                                may be optionally returned in FormList.

+

+  @retval EFI_UNSUPPORTED	      ControllerHandle is not NULL, and the controller 

+                                specified by ControllerHandle and ChildHandle is not 

+                                currently being managed by the driver specified by This.

+

+  @retval EFI_INVALID_PARAMETER	HealthStatus is NULL.

+

+  @retval EFI_OUT_OF_RESOURCES	MessageList is not NULL, and there are not enough 

+                                resource available to allocate memory for MessageList.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_DRIVER_HEALTH_GET_HEALTH_STATUS) (

+  IN  EFI_DRIVER_HEALTH_PROTOCOL       *This,

+  IN  EFI_HANDLE                       ControllerHandle  OPTIONAL,

+  IN  EFI_HANDLE                       ChildHandle       OPTIONAL,

+  OUT EFI_DRIVER_HEALTH_HEALTH_STATUS  *HealthStatus,

+  OUT EFI_DRIVER_HEALTH_HII_MESSAGE    **MessageList     OPTIONAL,

+  OUT EFI_HII_HANDLE                   *FormHiiHandle    OPTIONAL,

+  OUT EFI_GUID                         **FormSetGuid     OPTIONAL

+  );

+

+/**

+  Performs a repair operation on a controller in the platform.  This function can 

+  optionally report repair progress information back to the platform. 

+  

+  @param  This             A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.

+  @param  ControllerHandle The handle of the controller to repair.

+  @param  ChildHandle      The handle of the child controller to repair.  This is 

+                           an optional parameter that may be NULL.  It will be NULL 

+                           for device drivers.  It will also be NULL for bus 

+                           drivers when an attempt is made to repair a bus controller.

+                           If will not be NULL when an attempt is made to repair a 

+                           child controller produced by the driver.

+  @param  RepairNotify     A notification function that may be used by a driver to 

+                           report the progress of the repair operation.  This is 

+                           an optional parameter that may be NULL.  

+

+

+  @retval EFI_SUCCESS	          An attempt to repair the controller specified by 

+                                ControllerHandle and ChildHandle was performed.  

+                                The result of the repair operation can bet 

+                                determined by calling GetHealthStatus().

+  @retval EFI_UNSUPPORTED	      The driver specified by This is not currently 

+                                managing the controller specified by ControllerHandle 

+                                and ChildHandle.

+  @retval EFI_OUT_OF_RESOURCES	There are not enough resources to perform the 

+                                repair operation.

+

+*/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_DRIVER_HEALTH_REPAIR) (

+  IN  EFI_DRIVER_HEALTH_PROTOCOL                *This,

+  IN  EFI_HANDLE                                ControllerHandle,

+  IN  EFI_HANDLE                                ChildHandle           OPTIONAL,

+  IN  EFI_DRIVER_HEALTH_REPAIR_PROGRESS_NOTIFY  ProgressNotification  OPTIONAL

+  );

+

+/**

+  When installed, the Driver Health Protocol produces a collection of services 

+  that allow the health status for a controller to be retrieved.  If a controller 

+  is not in a usable state, status messages may be reported to the user, repair 

+  operations can be invoked, and the user may be asked to make software and/or 

+  hardware configuration changes. 

+

+  @par Protocol Description:

+  The Driver Health Protocol is optionally produced by a driver that follows the 

+  EFI Driver Model.  If an EFI Driver needs to report health status to the platform, 

+  provide warning or error messages to the user, perform length repair operations, 

+  or request the user to make hardware or software configuration changes, then the 

+  Driver Health Protocol must be produced.

+  

+  A controller that is managed by driver that follows the EFI Driver Model and 

+  produces the Driver Health Protocol must report the current health of the 

+  controllers that the driver is currently managing.  The controller can initially 

+  be healthy, failed, require repair, or require configuration.  If a controller 

+  requires configuration, and the user make configuration changes, the controller 

+  may then need to be reconnected or the system may need to be rebooted for the 

+  configuration changes to take affect.  Figure 2-1 below shows all the possible 

+  health states of a controller and the legal transitions between the health states. 

+

+  @param GetHealthStatus     Retrieves the health status of a controller in the 

+                             platform.  This function can also optionally return 

+                             warning messages, error messages, and a set of HII 

+                             Forms that may be repair a controller that is not 

+                             properly configured.

+  @param Repair              Performs a repair operation on a controller in the 

+                             platform.  This function can optionally report repair 

+                             progress information back to the platform.

+

+**/

+struct _EFI_DRIVER_HEALTH_PROTOCOL {

+  EFI_DRIVER_HEALTH_GET_HEALTH_STATUS  GetHealthStatus;

+  EFI_DRIVER_HEALTH_REPAIR             Repair;

+};

+

+extern EFI_GUID gEfiDriverHealthProtocolGuid;

+

+#endif

+

+

+

+

diff --git a/MdePkg/Include/Protocol/LoadedImage.h b/MdePkg/Include/Protocol/LoadedImage.h
index 93b5a45afe..c9e5741fad 100644
--- a/MdePkg/Include/Protocol/LoadedImage.h
+++ b/MdePkg/Include/Protocol/LoadedImage.h
@@ -25,6 +25,11 @@
     0x5B1B31A1, 0x9562, 0x11d2, {0x8E, 0x3F, 0x00, 0xA0, 0xC9, 0x69, 0x72, 0x3B } \

   }

 

+#define EFI_LOADED_IMAGE_DEVICE_PATH_PROTOCOL_GUID \

+  { \

+    0xbc62157e, 0x3e33, 0x4fec, {0x99, 0x20, 0x2d, 0x3b, 0x36, 0xd7, 0x50, 0xdf } \

+  }

+

 //

 // Protocol GUID defined in EFI1.1.

 // 

@@ -80,5 +85,6 @@ typedef struct {
 typedef EFI_LOADED_IMAGE_PROTOCOL EFI_LOADED_IMAGE;

 

 extern EFI_GUID gEfiLoadedImageProtocolGuid;

+extern EFI_GUID gEfiLoadedImageDevicePathProtocolGuid;

 

 #endif

diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec
index 02d1c943f6..0811cd66fb 100644
--- a/MdePkg/MdePkg.dec
+++ b/MdePkg/MdePkg.dec
@@ -205,7 +205,9 @@
   gEfiDevicePathUtilitiesProtocolGuid = { 0x0379BE4E, 0xD706, 0x437D, { 0xB0, 0x37, 0xED, 0xB8, 0x2F, 0xB7, 0x72, 0xA4 }}

   gEfiDriverBindingProtocolGuid  = { 0x18A031AB, 0xB443, 0x4D1A, { 0xA5, 0xC0, 0x0C, 0x09, 0x26, 0x1E, 0x9F, 0x71 }}

   gEfiPlatformDriverOverrideProtocolGuid = { 0x6b30c738, 0xa391, 0x11d4, {0x9a, 0x3b, 0x00, 0x90, 0x27, 0x3f, 0xc1, 0x4d } }

+  gEfiDriverFamilyOverrideProtocolGuid = {0x6b30c738, 0xa391, 0x11d4, {0x9a, 0x3b, 0x00, 0x90, 0x27, 0x3f, 0xc1, 0x4d }}

   gEfiBusSpecificDriverOverrideProtocolGuid = { 0x3BC1B285, 0x8A15, 0x4A82, { 0xAA, 0xBF, 0x4D, 0x7D, 0x13, 0xFB, 0x32, 0x65 }}

+  gEfiDriverHealthProtocolGuid = {0x2a534210, 0x9280, 0x41d8, { 0xae, 0x79, 0xca, 0xda, 0x1, 0xa2, 0xb1, 0x27 }}

   gEfiDriverDiagnostics2ProtocolGuid = { 0x4D330321, 0x025F, 0x4AAC, { 0x90, 0xD8, 0x5E, 0xD9, 0x00, 0x17, 0x3B, 0x63 }}

   gEfiDriverDiagnosticsProtocolGuid = { 0x0784924F, 0xE296, 0x11D4, { 0x9A, 0x49, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0x4D }}

   gEfiComponentName2ProtocolGuid = { 0x6A7A5CFF, 0xE8D9, 0x4F70, { 0xBA, 0xDA, 0x75, 0xAB, 0x30, 0x25, 0xCE, 0x14 }}

@@ -228,6 +230,7 @@
   gEfiUgaDrawProtocolGuid        = { 0x982C298B, 0xF4FA, 0x41CB, { 0xB8, 0x38, 0x77, 0xAA, 0x68, 0x8F, 0xB8, 0x39 }}

   gEfiUgaIoProtocolGuid          = { 0x61a4d49e, 0x6f68, 0x4f1b, { 0xb9, 0x22, 0xa8, 0x6e, 0xed, 0x0b, 0x07, 0xa2 }}

   gEfiLoadedImageProtocolGuid    = { 0x5B1B31A1, 0x9562, 0x11D2, { 0x8E, 0x3F, 0x00, 0xA0, 0xC9, 0x69, 0x72, 0x3B }}

+  gEfiLoadedImageDevicePathProtocolGuid = { 0xbc62157e, 0x3e33, 0x4fec, {0x99, 0x20, 0x2d, 0x3b, 0x36, 0xd7, 0x50, 0xdf }}

   gEfiLoadFileProtocolGuid       = { 0x56EC3091, 0x954C, 0x11D2, { 0x8E, 0x3F, 0x00, 0xA0, 0xC9, 0x69, 0x72, 0x3B }}

   gEfiSimpleFileSystemProtocolGuid = { 0x964E5B22, 0x6459, 0x11D2, { 0x8E, 0x39, 0x00, 0xA0, 0xC9, 0x69, 0x72, 0x3B }}

   gEfiTapeIoProtocolGuid         = { 0x1E93E633, 0xD65A, 0x459E, { 0xAB, 0x84, 0x93, 0xD9, 0xEC, 0x26, 0x6D, 0x18 }}