Port PlatformDriOverrideDxe into R9.
[mirror_edk2.git] / MdeModulePkg / Include / Library / PlatDriOverLib.h
1 /** @file
2
3 Copyright (c) 2007, Intel Corporation
4 All rights reserved. This program and the accompanying materials
5 are licensed and made available under the terms and conditions of the BSD License
6 which accompanies this distribution. The full text of the license may be found at
7 http://opensource.org/licenses/bsd-license.php
8
9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
11
12 Module Name:
13
14 PlatDriOverLib.h
15
16 Abstract:
17
18
19 **/
20
21 #ifndef _PLAT_DRI_OVER_LIB_H_
22 #define _PLAT_DRI_OVER_LIB_H_
23
24 #include <PiDxe.h>
25 #include <Protocol/PlatformDriverOverride.h>
26 #include <Protocol/DevicePath.h>
27 #include <Library/BaseLib.h>
28
29 #include <VariableFormat.h>
30
31 /**
32 Install the Platform Driver Override Protocol, and ensure there is only one Platform Driver Override Protocol
33 in the system.
34
35 @param gPlatformDriverOverride PlatformDriverOverride protocol interface which
36 needs to be installed
37
38 @retval EFI_ALREADY_STARTED There has been a Platform Driver Override
39 Protocol in the system, cannot install it again.
40 @retval Other Returned by InstallProtocolInterface
41
42 **/
43 EFI_STATUS
44 EFIAPI
45 InstallPlatformDriverOverrideProtocol (
46 EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL *gPlatformDriverOverride
47 );
48
49 /**
50 Free all the mapping database memory resource and initialize the mapping list entry
51
52 @param MappingDataBase Mapping database list entry pointer
53
54 @retval EFI_INVALID_PARAMETER mapping database list entry is NULL
55 @retval EFI_SUCCESS Free success
56
57 **/
58 EFI_STATUS
59 EFIAPI
60 FreeMappingDatabase (
61 IN OUT LIST_ENTRY *MappingDataBase
62 );
63
64 /**
65 Read the environment variable(s) that contain the override mappings from Controller Device Path to
66 a set of Driver Device Paths, and create the mapping database in memory with those variable info.
67 VariableLayout{
68 //
69 // NotEnd indicate whether the variable is the last one, and has no subsequent variable need to load.
70 // Each variable has MaximumVariableSize limitation, so we maybe need multi variables to store
71 // large mapping infos.
72 // The variable(s) name rule is PlatDriOver, PlatDriOver1, PlatDriOver2, ....
73 //
74 UINT32 NotEnd;
75 //
76 // The entry which contains the mapping that Controller Device Path to a set of Driver Device Paths
77 // There are often multi mapping entries in a variable.
78 //
79 UINT32 SIGNATURE; //EFI_SIGNATURE_32('p','d','o','i')
80 UINT32 DriverNum;
81 EFI_DEVICE_PATH_PROTOCOL ControllerDevicePath[];
82 EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[];
83 EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[];
84 EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[];
85 ......
86 UINT32 SIGNATURE;
87 UINT32 DriverNum;
88 EFI_DEVICE_PATH_PROTOCOL ControllerDevicePath[];
89 EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[];
90 EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[];
91 EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[];
92 ......
93 }
94 typedef struct _PLATFORM_OVERRIDE_ITEM{
95 UINTN Signature; //EFI_SIGNATURE_32('p','d','o','i')
96 LIST_ENTRY Link;
97 UINT32 DriverInfoNum;
98 EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath;
99 LIST_ENTRY DriverInfoList; //DRIVER_IMAGE_INFO List
100 } PLATFORM_OVERRIDE_ITEM;
101 typedef struct _DRIVER_IMAGE_INFO{
102 UINTN Signature; //EFI_SIGNATURE_32('p','d','i','i')
103 LIST_ENTRY Link;
104 EFI_HANDLE ImageHandle;
105 EFI_DEVICE_PATH_PROTOCOL *DriverImagePath;
106 BOOLEAN UnLoadable;
107 BOOLEAN UnStartable;
108 } DRIVER_IMAGE_INFO;
109
110 @param MappingDataBase Mapping database list entry pointer
111
112 @retval EFI_INVALID_PARAMETER MappingDataBase pointer is null
113 @retval EFI_NOT_FOUND Cannot find the 'PlatDriOver' NV variable
114 @retval EFI_VOLUME_CORRUPTED The found NV variable is corrupted
115 @retval EFI_SUCCESS Create the mapping database in memory
116 successfully
117
118 **/
119 EFI_STATUS
120 EFIAPI
121 InitOverridesMapping (
122 OUT LIST_ENTRY *MappingDataBase
123 );
124
125 /**
126 Save the memory mapping database into NV environment variable(s)
127
128 @param MappingDataBase Mapping database list entry pointer
129
130 @retval EFI_INVALID_PARAMETER MappingDataBase pointer is null
131 @retval EFI_SUCCESS Save memory mapping database successfully
132
133 **/
134 EFI_STATUS
135 EFIAPI
136 SaveOverridesMapping (
137 IN LIST_ENTRY *MappingDataBase
138 );
139
140 /**
141 Retrieves the image handle of the platform override driver for a controller in the system from the memory mapping database.
142
143 @param This A pointer to the
144 EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL instance.
145 @param ControllerHandle The device handle of the controller to check if
146 a driver override exists.
147 @param DriverImageHandle On output, a pointer to the next driver handle.
148 Passing in a pointer to NULL, will return the
149 first driver handle for ControllerHandle.
150 @param MappingDataBase MappingDataBase - Mapping database list entry
151 pointer
152 @param CallerImageHandle The caller driver's image handle, for
153 UpdateFvFileDevicePath use.
154
155 @retval EFI_INVALID_PARAMETER The handle specified by ControllerHandle is not
156 a valid handle. Or DriverImagePath is not a
157 device path that was returned on a previous call
158 to GetDriverPath().
159 @retval EFI_NOT_FOUND A driver override for ControllerHandle was not
160 found.
161 @retval EFI_UNSUPPORTED The operation is not supported.
162 @retval EFI_SUCCESS The driver override for ControllerHandle was
163 returned in DriverImagePath.
164
165 **/
166 EFI_STATUS
167 EFIAPI
168 GetDriverFromMapping (
169 IN EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL * This,
170 IN EFI_HANDLE ControllerHandle,
171 IN OUT EFI_HANDLE * DriverImageHandle,
172 IN LIST_ENTRY * MappingDataBase,
173 IN EFI_HANDLE CallerImageHandle
174 );
175
176 EFI_STATUS
177 EFIAPI
178 DeleteOverridesVariables (
179 VOID
180 );
181
182 /**
183 Check mapping database whether already has the mapping info which
184 records the input Controller to input DriverImage.
185 If has, the controller's total override driver number and input DriverImage's order number is return.
186
187 @param ControllerDevicePath The controller device path need to add a
188 override driver image item
189 @param DriverImageDevicePath The driver image device path need to be insert
190 @param MappingDataBase Mapping database list entry pointer
191 @param DriverInfoNum the controller's total override driver number
192 @param DriverImageNO The inserted order number
193
194 @return EFI_INVALID_PARAMETER
195 @return EFI_NOT_FOUND
196 @return EFI_SUCCESS
197
198 **/
199 EFI_STATUS
200 EFIAPI
201 CheckMapping (
202 IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath,
203 IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath,
204 IN LIST_ENTRY * MappingDataBase,
205 OUT UINT32 *DriverInfoNum,
206 OUT UINT32 *DriverImageNO
207 );
208
209 /**
210 Insert a driver image as a controller's override driver into the mapping database.
211 The driver image's order number is indicated by DriverImageNO.
212
213 @param ControllerDevicePath The controller device path need to add a
214 override driver image item
215 @param DriverImageDevicePath The driver image device path need to be insert
216 @param MappingDataBase Mapping database list entry pointer
217 @param DriverImageNO The inserted order number
218
219 @return EFI_INVALID_PARAMETER
220 @return EFI_ALREADY_STARTED
221 @return EFI_SUCCESS
222
223 **/
224 EFI_STATUS
225 EFIAPI
226 InsertDriverImage (
227 IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath,
228 IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath,
229 IN LIST_ENTRY *MappingDataBase,
230 IN UINT32 DriverImageNO
231 );
232
233 /**
234 Delete a controller's override driver from the mapping database.
235
236 @param ControllerDevicePath The controller device path need to add a
237 override driver image item
238 @param DriverImageDevicePath The driver image device path need to be insert
239 @param MappingDataBase Mapping database list entry pointer
240 @param DriverImageNO The inserted order number
241
242 @return EFI_INVALID_PARAMETER
243 @return EFI_NOT_FOUND
244 @return EFI_SUCCESS
245
246 **/
247 EFI_STATUS
248 EFIAPI
249 DeleteDriverImage (
250 IN EFI_DEVICE_PATH_PROTOCOL *ControllerDevicePath,
251 IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath,
252 IN LIST_ENTRY *MappingDataBase
253 );
254
255 #endif