b59726f19ea80944554dd8b40e00687339cbf293
[mirror_edk2.git] / IntelFrameworkPkg / Include / Ppi / DeviceRecoveryModule.h
1 /** @file
2 This file declares the Device Recovery Module PPI.
3
4 The interface of this PPI does the following:
5 - Reports the number of recovery DXE capsules that exist on the associated device(s)
6 - Finds the requested firmware binary capsule
7 - Loads that capsule into memory
8
9 A device can be either a group of devices, such as a block device, or an individual device.
10 The module determines the internal search order, with capsule number 1 as the highest load
11 priority and number N as the lowest priority.
12
13 Copyright (c) 2007 - 2009, Intel Corporation
14 All rights reserved. This program and the accompanying materials
15 are licensed and made available under the terms and conditions of the BSD License
16 which accompanies this distribution. The full text of the license may be found at
17 http://opensource.org/licenses/bsd-license.php
18
19 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
20 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
21
22 @par Revision Reference:
23 This PPI is defined in the "EFI Recovery" Framework spec.
24 Version 0.9
25
26 **/
27
28 #ifndef _PEI_DEVICE_RECOVERY_MODULE_PPI_H_
29 #define _PEI_DEVICE_RECOVERY_MODULE_PPI_H_
30
31 #define EFI_PEI_DEVICE_RECOVERY_MODULE_PPI_GUID \
32 { \
33 0x0DE2CE25, 0x446A, 0x45a7, {0xBF, 0xC9, 0x37, 0xDA, 0x26, 0x34, 0x4B, 0x37 } \
34 }
35
36 typedef struct _EFI_PEI_DEVICE_RECOVERY_MODULE_PPI EFI_PEI_DEVICE_RECOVERY_MODULE_PPI;
37
38 /**
39 Returns the number of DXE capsules residing on the device.
40
41 This function searches for DXE capsules from the associated device and returns the number
42 and maximum size in bytes of the capsules discovered. Entry 1 is assumed to be the
43 highest load priority and entry N is assumed to be the lowest priority.
44
45 @param[in] PeiServices General-purpose services that are available to every PEIM
46 @param[in] This Indicates the EFI_PEI_DEVICE_RECOVERY_MODULE_PPI instance.
47 @param[out] NumberRecoveryCapsules Pointer to a caller-allocated UINTN. On output,
48 *NumberRecoveryCapsules contains the number of recovery capsule
49 images available for retrieval from this PEIM instance.
50
51 @retval EFI_SUCCESS One or more capsules were discovered.
52 @retval EFI_DEVICE_ERROR A device error occurred.
53 @retval EFI_NOT_FOUND A recovery DXE capsule cannot be found.
54
55 **/
56 typedef
57 EFI_STATUS
58 (EFIAPI *EFI_PEI_DEVICE_GET_NUMBER_RECOVERY_CAPSULE)(
59 IN EFI_PEI_SERVICES **PeiServices,
60 IN EFI_PEI_DEVICE_RECOVERY_MODULE_PPI *This,
61 OUT UINTN *NumberRecoveryCapsules
62 );
63
64 /**
65 Returns the size and type of the requested recovery capsule.
66
67 This function gets the size and type of the requested recovery capsule.
68
69 @param[in] PeiServices General-purpose services that are available to every PEIM
70 @param[in] This Indicates the EFI_PEI_DEVICE_RECOVERY_MODULE_PPI instance.
71 @param[in] CapsuleInstance Specifies for which capsule instance to retrieve the information.
72 This parameter must be between one and the value returned by
73 GetNumberRecoveryCapsules() in NumberRecoveryCapsules.
74 @param[out] Size A pointer to a caller-allocated UINTN in which the size of
75 the requested recovery module is returned.
76 @param[out] CapsuleType A pointer to a caller-allocated EFI_GUID in
77 which the type of the requested recovery capsule is returned.
78
79 @retval EFI_SUCCESS One or more capsules were discovered.
80 @retval EFI_DEVICE_ERROR A device error occurred.
81 @retval EFI_NOT_FOUND A recovery DXE capsule cannot be found.
82
83 **/
84 typedef
85 EFI_STATUS
86 (EFIAPI *EFI_PEI_DEVICE_GET_RECOVERY_CAPSULE_INFO)(
87 IN EFI_PEI_SERVICES **PeiServices,
88 IN EFI_PEI_DEVICE_RECOVERY_MODULE_PPI *This,
89 IN UINTN CapsuleInstance,
90 OUT UINTN *Size,
91 OUT EFI_GUID *CapsuleType
92 );
93
94 /**
95 Loads a DXE capsule from some media into memory.
96
97 This function retrieves a DXE capsule from some device and loads it into memory.
98 Note that the published interface is device neutral.
99
100 @param[in, out] PeiServices General-purpose services that are available to every PEIM
101 @param[in] This Indicates the EFI_PEI_DEVICE_RECOVERY_MODULE_PPI instance.
102 @param[in] CapsuleInstance Specifies which capsule instance to retrieve.
103 This parameter must be between one and the value returned by
104 GetNumberRecoveryCapsules() in NumberRecoveryCapsules.
105 @param[out] Buffer Specifies a caller-allocated buffer in which the requested
106 recovery capsule will be returned.
107
108 @retval EFI_SUCCESS One or more capsules were discovered.
109 @retval EFI_DEVICE_ERROR A device error occurred.
110 @retval EFI_NOT_FOUND A recovery DXE capsule cannot be found.
111
112 **/
113 typedef
114 EFI_STATUS
115 (EFIAPI *EFI_PEI_DEVICE_LOAD_RECOVERY_CAPSULE)(
116 IN OUT EFI_PEI_SERVICES **PeiServices,
117 IN EFI_PEI_DEVICE_RECOVERY_MODULE_PPI *This,
118 IN UINTN CapsuleInstance,
119 OUT VOID *Buffer
120 );
121
122 ///
123 /// Presents a standard interface to EFI_PEI_DEVICE_RECOVERY_MODULE_PPI,
124 /// regardless of the underlying device(s).
125 ///
126 struct _EFI_PEI_DEVICE_RECOVERY_MODULE_PPI {
127 EFI_PEI_DEVICE_GET_NUMBER_RECOVERY_CAPSULE GetNumberRecoveryCapsules; ///< Returns the number of DXE capsules residing on the device.
128 EFI_PEI_DEVICE_GET_RECOVERY_CAPSULE_INFO GetRecoveryCapsuleInfo; ///< Returns the size and type of the requested recovery capsule.
129 EFI_PEI_DEVICE_LOAD_RECOVERY_CAPSULE LoadRecoveryCapsule; ///< Loads a DXE capsule from some media into memory.
130 };
131
132 extern EFI_GUID gEfiPeiDeviceRecoveryModulePpiGuid;
133
134 #endif /* _PEI_DEVICE_RECOVERY_MODULE_PPI_H_ */