xref: /illumos-gate/usr/src/boot/efi/include/Protocol/PlatformDriverOverride.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
1 /** @file
2   Platform Driver Override protocol as defined in the UEFI 2.1 specification.
3 
4   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5   SPDX-License-Identifier: BSD-2-Clause-Patent
6 
7 **/
8 
9 #ifndef __EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL_H__
10 #define __EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL_H__
11 
12 ///
13 /// Global ID for the Platform Driver Override Protocol
14 ///
15 #define EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL_GUID \
16   { \
17     0x6b30c738, 0xa391, 0x11d4, {0x9a, 0x3b, 0x00, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \
18   }
19 
20 typedef struct _EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL;
21 
22 //
23 // Prototypes for the Platform Driver Override Protocol
24 //
25 
26 /**
27   Retrieves the image handle of the platform override driver for a controller in the system.
28 
29   @param  This                  A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_
30                                 PROTOCOL instance.
31   @param  ControllerHandle      The device handle of the controller to check if a driver override
32                                 exists.
33   @param  DriverImageHandle     On input, a pointer to the previous driver image handle returned
34                                 by GetDriver(). On output, a pointer to the next driver
35                                 image handle.
36 
37   @retval EFI_SUCCESS           The driver override for ControllerHandle was returned in
38                                 DriverImageHandle.
39   @retval EFI_NOT_FOUND         A driver override for ControllerHandle was not found.
40   @retval EFI_INVALID_PARAMETER The handle specified by ControllerHandle is NULL.
41   @retval EFI_INVALID_PARAMETER DriverImageHandle is not a handle that was returned on a
42                                 previous call to GetDriver().
43 
44 **/
45 typedef
46 EFI_STATUS
47 (EFIAPI *EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER)(
48   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL              *This,
49   IN     EFI_HANDLE                                     ControllerHandle,
50   IN OUT EFI_HANDLE                                     *DriverImageHandle
51   );
52 
53 /**
54   Retrieves the device path of the platform override driver for a controller in the system.
55 
56   @param  This                  A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL instance.
57   @param  ControllerHandle      The device handle of the controller to check if a driver override
58                                 exists.
59   @param  DriverImagePath       On input, a pointer to the previous driver device path returned by
60                                 GetDriverPath(). On output, a pointer to the next driver
61                                 device path. Passing in a pointer to NULL will return the first
62                                 driver device path for ControllerHandle.
63 
64   @retval EFI_SUCCESS           The driver override for ControllerHandle was returned in
65                                 DriverImageHandle.
66   @retval EFI_UNSUPPORTED       The operation is not supported.
67   @retval EFI_NOT_FOUND         A driver override for ControllerHandle was not found.
68   @retval EFI_INVALID_PARAMETER The handle specified by ControllerHandle is NULL.
69   @retval EFI_INVALID_PARAMETER DriverImagePath is not a device path that was returned on a
70                                 previous call to GetDriverPath().
71 
72 **/
73 typedef
74 EFI_STATUS
75 (EFIAPI *EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER_PATH)(
76   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL              *This,
77   IN     EFI_HANDLE                                     ControllerHandle,
78   IN OUT EFI_DEVICE_PATH_PROTOCOL                       **DriverImagePath
79   );
80 
81 /**
82   Used to associate a driver image handle with a device path that was returned on a prior call to the
83   GetDriverPath() service. This driver image handle will then be available through the
84   GetDriver() service.
85 
86   @param  This                  A pointer to the EFI_PLATFORM_DRIVER_OVERRIDE_
87                                 PROTOCOL instance.
88   @param  ControllerHandle      The device handle of the controller.
89   @param  DriverImagePath       A pointer to the driver device path that was returned in a prior
90                                 call to GetDriverPath().
91   @param  DriverImageHandle     The driver image handle that was returned by LoadImage()
92                                 when the driver specified by DriverImagePath was loaded
93                                 into memory.
94 
95   @retval EFI_SUCCESS           The association between DriverImagePath and
96                                 DriverImageHandle was established for the controller specified
97                                 by ControllerHandle.
98   @retval EFI_UNSUPPORTED       The operation is not supported.
99   @retval EFI_NOT_FOUND         DriverImagePath is not a device path that was returned on a prior
100                                 call to GetDriverPath() for the controller specified by
101                                 ControllerHandle.
102   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
103   @retval EFI_INVALID_PARAMETER DriverImagePath is not a valid device path.
104   @retval EFI_INVALID_PARAMETER DriverImageHandle is not a valid image handle.
105 
106 **/
107 typedef
108 EFI_STATUS
109 (EFIAPI *EFI_PLATFORM_DRIVER_OVERRIDE_DRIVER_LOADED)(
110   IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL          *This,
111   IN EFI_HANDLE                                     ControllerHandle,
112   IN EFI_DEVICE_PATH_PROTOCOL                       *DriverImagePath,
113   IN EFI_HANDLE                                     DriverImageHandle
114   );
115 
116 ///
117 /// This protocol matches one or more drivers to a controller. A platform driver
118 /// produces this protocol, and it is installed on a separate handle. This protocol
119 /// is used by the ConnectController() boot service to select the best driver
120 /// for a controller. All of the drivers returned by this protocol have a higher
121 /// precedence than drivers found from an EFI Bus Specific Driver Override Protocol
122 /// or drivers found from the general UEFI driver Binding search algorithm. If more
123 /// than one driver is returned by this protocol, then the drivers are returned in
124 /// order from highest precedence to lowest precedence.
125 ///
126 struct _EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL {
127   EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER         GetDriver;
128   EFI_PLATFORM_DRIVER_OVERRIDE_GET_DRIVER_PATH    GetDriverPath;
129   EFI_PLATFORM_DRIVER_OVERRIDE_DRIVER_LOADED      DriverLoaded;
130 };
131 
132 extern EFI_GUID  gEfiPlatformDriverOverrideProtocolGuid;
133 
134 #endif
135