3 This is a simple fault tolerant write driver that is intended to use in the SMM environment.
5 This boot service protocol only provides fault tolerant write capability for
6 block devices. The protocol has internal non-volatile intermediate storage
7 of the data and private information. It should be able to recover
8 automatically from a critical fault, such as power failure.
10 The implementation uses an FTW (Fault Tolerant Write) Work Space.
11 This work space is a memory copy of the work space on the Working Block,
12 the size of the work space is the FTW_WORK_SPACE_SIZE bytes.
14 The work space stores each write record as EFI_FTW_RECORD structure.
15 The spare block stores the write buffer before write to the target block.
17 The write record has three states to specify the different phase of write operation.
18 1) WRITE_ALLOCATED is that the record is allocated in write space.
19 The information of write operation is stored in write record structure.
20 2) SPARE_COMPLETED is that the data from write buffer is writed into the spare block as the backup.
21 3) WRITE_COMPLETED is that the data is copied from the spare block to the target block.
23 This driver operates the data as the whole size of spare block.
24 It first read the SpareAreaLength data from the target block into the spare memory buffer.
25 Then copy the write buffer data into the spare memory buffer.
26 Then write the spare memory buffer into the spare block.
27 Final copy the data from the spare block to the target block.
29 To make this drive work well, the following conditions must be satisfied:
30 1. The write NumBytes data must be fit within Spare area.
31 Offset + NumBytes <= SpareAreaLength
32 2. The whole flash range has the same block size.
33 3. Working block is an area which contains working space in its last block and has the same size as spare block.
34 4. Working Block area must be in the single one Firmware Volume Block range which FVB protocol is produced on.
35 5. Spare area must be in the single one Firmware Volume Block range which FVB protocol is produced on.
36 6. Any write data area (SpareAreaLength Area) which the data will be written into must be
37 in the single one Firmware Volume Block range which FVB protocol is produced on.
38 7. If write data area (such as Variable range) is enlarged, the spare area range must be enlarged.
39 The spare area must be enough large to store the write data before write them into the target range.
40 If one of them is not satisfied, FtwWrite may fail.
41 Usually, Spare area only takes one block. That's SpareAreaLength = BlockSize, NumberOfSpareBlock = 1.
43 Caution: This module requires additional review when modified.
44 This driver need to make sure the CommBuffer is not in the SMRAM range.
46 Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved.<BR>
47 SPDX-License-Identifier: BSD-2-Clause-Patent
52 #include <Library/MmServicesTableLib.h>
53 #include <Library/BaseLib.h>
54 #include <Protocol/SmmSwapAddressRange.h>
55 #include "FaultTolerantWrite.h"
56 #include "FaultTolerantWriteSmmCommon.h"
57 #include <Protocol/MmEndOfDxe.h>
59 EFI_EVENT mFvbRegistration
= NULL
;
60 EFI_FTW_DEVICE
*mFtwDevice
= NULL
;
63 /// The flag to indicate whether the platform has left the DXE phase of execution.
65 BOOLEAN mEndOfDxe
= FALSE
;
68 Retrieve the SMM FVB protocol interface by HANDLE.
70 @param[in] FvBlockHandle The handle of SMM FVB protocol that provides services for
71 reading, writing, and erasing the target block.
72 @param[out] FvBlock The interface of SMM FVB protocol
74 @retval EFI_SUCCESS The interface information for the specified protocol was returned.
75 @retval EFI_UNSUPPORTED The device does not support the SMM FVB protocol.
76 @retval EFI_INVALID_PARAMETER FvBlockHandle is not a valid EFI_HANDLE or FvBlock is NULL.
81 IN EFI_HANDLE FvBlockHandle
,
82 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
**FvBlock
86 // To get the SMM FVB protocol interface on the handle
88 return gMmst
->MmHandleProtocol (
90 &gEfiSmmFirmwareVolumeBlockProtocolGuid
,
96 Retrieve the SMM Swap Address Range protocol interface.
98 @param[out] SarProtocol The interface of SMM SAR protocol
100 @retval EFI_SUCCESS The SMM SAR protocol instance was found and returned in SarProtocol.
101 @retval EFI_NOT_FOUND The SMM SAR protocol instance was not found.
102 @retval EFI_INVALID_PARAMETER SarProtocol is NULL.
107 OUT VOID
**SarProtocol
113 // Locate Smm Swap Address Range protocol
115 Status
= gMmst
->MmLocateProtocol (
116 &gEfiSmmSwapAddressRangeProtocolGuid
,
124 Function returns an array of handles that support the SMM FVB protocol
125 in a buffer allocated from pool.
127 @param[out] NumberHandles The number of handles returned in Buffer.
128 @param[out] Buffer A pointer to the buffer to return the requested
129 array of handles that support SMM FVB protocol.
131 @retval EFI_SUCCESS The array of handles was returned in Buffer, and the number of
132 handles in Buffer was returned in NumberHandles.
133 @retval EFI_NOT_FOUND No SMM FVB handle was found.
134 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the matching results.
135 @retval EFI_INVALID_PARAMETER NumberHandles is NULL or Buffer is NULL.
139 GetFvbCountAndBuffer (
140 OUT UINTN
*NumberHandles
,
141 OUT EFI_HANDLE
**Buffer
147 if ((NumberHandles
== NULL
) || (Buffer
== NULL
)) {
148 return EFI_INVALID_PARAMETER
;
154 Status
= gMmst
->MmLocateHandle (
156 &gEfiSmmFirmwareVolumeBlockProtocolGuid
,
161 if (EFI_ERROR(Status
) && Status
!= EFI_BUFFER_TOO_SMALL
) {
162 return EFI_NOT_FOUND
;
165 *Buffer
= AllocatePool (BufferSize
);
166 if (*Buffer
== NULL
) {
167 return EFI_OUT_OF_RESOURCES
;
170 Status
= gMmst
->MmLocateHandle (
172 &gEfiSmmFirmwareVolumeBlockProtocolGuid
,
178 *NumberHandles
= BufferSize
/ sizeof(EFI_HANDLE
);
179 if (EFI_ERROR(Status
)) {
190 Get the handle of the SMM FVB protocol by the FVB base address and attributes.
192 @param[in] Address The base address of SMM FVB protocol.
193 @param[in] Attributes The attributes of the SMM FVB protocol.
194 @param[out] SmmFvbHandle The handle of the SMM FVB protocol.
196 @retval EFI_SUCCESS The FVB handle is found.
197 @retval EFI_ABORTED The FVB protocol is not found.
201 GetFvbByAddressAndAttribute (
202 IN EFI_PHYSICAL_ADDRESS Address
,
203 IN EFI_FVB_ATTRIBUTES_2 Attributes
,
204 OUT EFI_HANDLE
*SmmFvbHandle
208 EFI_HANDLE
*HandleBuffer
;
211 EFI_PHYSICAL_ADDRESS FvbBaseAddress
;
212 EFI_FVB_ATTRIBUTES_2 FvbAttributes
;
213 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
;
218 // Locate all handles of SMM Fvb protocol.
220 Status
= GetFvbCountAndBuffer (&HandleCount
, &HandleBuffer
);
221 if (EFI_ERROR (Status
)) {
226 // Find the proper SMM Fvb handle by the address and attributes.
228 for (Index
= 0; Index
< HandleCount
; Index
++) {
229 Status
= FtwGetFvbByHandle (HandleBuffer
[Index
], &Fvb
);
230 if (EFI_ERROR (Status
)) {
234 // Compare the address.
236 Status
= Fvb
->GetPhysicalAddress (Fvb
, &FvbBaseAddress
);
237 if (EFI_ERROR (Status
)) {
240 if (Address
!= FvbBaseAddress
) {
245 // Compare the attribute.
247 Status
= Fvb
->GetAttributes (Fvb
, &FvbAttributes
);
248 if (EFI_ERROR (Status
)) {
251 if (Attributes
!= FvbAttributes
) {
256 // Found the proper FVB handle.
258 *SmmFvbHandle
= HandleBuffer
[Index
];
259 FreePool (HandleBuffer
);
263 FreePool (HandleBuffer
);
268 Communication service SMI Handler entry.
270 This SMI handler provides services for the fault tolerant write wrapper driver.
272 Caution: This function requires additional review when modified.
273 This driver need to make sure the CommBuffer is not in the SMRAM range.
274 Also in FTW_FUNCTION_GET_LAST_WRITE case, check SmmFtwGetLastWriteHeader->Data +
275 SmmFtwGetLastWriteHeader->PrivateDataSize within communication buffer.
277 @param[in] DispatchHandle The unique handle assigned to this handler by SmiHandlerRegister().
278 @param[in] RegisterContext Points to an optional handler context which was specified when the
279 handler was registered.
280 @param[in, out] CommBuffer A pointer to a collection of data in memory that will be conveyed
281 from a non-SMM environment into an SMM environment.
282 @param[in, out] CommBufferSize The size of the CommBuffer.
284 @retval EFI_SUCCESS The interrupt was handled and quiesced. No other handlers
285 should still be called.
286 @retval EFI_WARN_INTERRUPT_SOURCE_QUIESCED The interrupt has been quiesced but other handlers should
288 @retval EFI_WARN_INTERRUPT_SOURCE_PENDING The interrupt is still pending and other handlers should still
290 @retval EFI_INTERRUPT_PENDING The interrupt could not be quiesced.
295 SmmFaultTolerantWriteHandler (
296 IN EFI_HANDLE DispatchHandle
,
297 IN CONST VOID
*RegisterContext
,
298 IN OUT VOID
*CommBuffer
,
299 IN OUT UINTN
*CommBufferSize
303 SMM_FTW_COMMUNICATE_FUNCTION_HEADER
*SmmFtwFunctionHeader
;
304 SMM_FTW_GET_MAX_BLOCK_SIZE_HEADER
*SmmGetMaxBlockSizeHeader
;
305 SMM_FTW_ALLOCATE_HEADER
*SmmFtwAllocateHeader
;
306 SMM_FTW_WRITE_HEADER
*SmmFtwWriteHeader
;
307 SMM_FTW_RESTART_HEADER
*SmmFtwRestartHeader
;
308 SMM_FTW_GET_LAST_WRITE_HEADER
*SmmFtwGetLastWriteHeader
;
310 EFI_HANDLE SmmFvbHandle
;
312 UINTN CommBufferPayloadSize
;
313 UINTN PrivateDataSize
;
315 UINTN TempCommBufferSize
;
318 // If input is invalid, stop processing this SMI
320 if (CommBuffer
== NULL
|| CommBufferSize
== NULL
) {
324 TempCommBufferSize
= *CommBufferSize
;
326 if (TempCommBufferSize
< SMM_FTW_COMMUNICATE_HEADER_SIZE
) {
327 DEBUG ((EFI_D_ERROR
, "SmmFtwHandler: SMM communication buffer size invalid!\n"));
330 CommBufferPayloadSize
= TempCommBufferSize
- SMM_FTW_COMMUNICATE_HEADER_SIZE
;
332 if (!FtwSmmIsBufferOutsideSmmValid ((UINTN
)CommBuffer
, TempCommBufferSize
)) {
333 DEBUG ((EFI_D_ERROR
, "SmmFtwHandler: SMM communication buffer in SMRAM or overflow!\n"));
337 SmmFtwFunctionHeader
= (SMM_FTW_COMMUNICATE_FUNCTION_HEADER
*)CommBuffer
;
341 // It will be not safe to expose the operations after End Of Dxe.
343 DEBUG ((EFI_D_ERROR
, "SmmFtwHandler: Not safe to do the operation: %x after End Of Dxe, so access denied!\n", SmmFtwFunctionHeader
->Function
));
344 SmmFtwFunctionHeader
->ReturnStatus
= EFI_ACCESS_DENIED
;
348 switch (SmmFtwFunctionHeader
->Function
) {
349 case FTW_FUNCTION_GET_MAX_BLOCK_SIZE
:
350 if (CommBufferPayloadSize
< sizeof (SMM_FTW_GET_MAX_BLOCK_SIZE_HEADER
)) {
351 DEBUG ((EFI_D_ERROR
, "GetMaxBlockSize: SMM communication buffer size invalid!\n"));
354 SmmGetMaxBlockSizeHeader
= (SMM_FTW_GET_MAX_BLOCK_SIZE_HEADER
*) SmmFtwFunctionHeader
->Data
;
356 Status
= FtwGetMaxBlockSize (
357 &mFtwDevice
->FtwInstance
,
358 &SmmGetMaxBlockSizeHeader
->BlockSize
362 case FTW_FUNCTION_ALLOCATE
:
363 if (CommBufferPayloadSize
< sizeof (SMM_FTW_ALLOCATE_HEADER
)) {
364 DEBUG ((EFI_D_ERROR
, "Allocate: SMM communication buffer size invalid!\n"));
367 SmmFtwAllocateHeader
= (SMM_FTW_ALLOCATE_HEADER
*) SmmFtwFunctionHeader
->Data
;
368 Status
= FtwAllocate (
369 &mFtwDevice
->FtwInstance
,
370 &SmmFtwAllocateHeader
->CallerId
,
371 SmmFtwAllocateHeader
->PrivateDataSize
,
372 SmmFtwAllocateHeader
->NumberOfWrites
376 case FTW_FUNCTION_WRITE
:
377 if (CommBufferPayloadSize
< OFFSET_OF (SMM_FTW_WRITE_HEADER
, Data
)) {
378 DEBUG ((EFI_D_ERROR
, "Write: SMM communication buffer size invalid!\n"));
381 SmmFtwWriteHeader
= (SMM_FTW_WRITE_HEADER
*) SmmFtwFunctionHeader
->Data
;
382 Length
= SmmFtwWriteHeader
->Length
;
383 PrivateDataSize
= SmmFtwWriteHeader
->PrivateDataSize
;
384 if (((UINTN
)(~0) - Length
< OFFSET_OF (SMM_FTW_WRITE_HEADER
, Data
)) ||
385 ((UINTN
)(~0) - PrivateDataSize
< OFFSET_OF (SMM_FTW_WRITE_HEADER
, Data
) + Length
)) {
387 // Prevent InfoSize overflow
389 Status
= EFI_ACCESS_DENIED
;
392 InfoSize
= OFFSET_OF (SMM_FTW_WRITE_HEADER
, Data
) + Length
+ PrivateDataSize
;
395 // SMRAM range check already covered before
397 if (InfoSize
> CommBufferPayloadSize
) {
398 DEBUG ((EFI_D_ERROR
, "Write: Data size exceed communication buffer size limit!\n"));
399 Status
= EFI_ACCESS_DENIED
;
403 if (PrivateDataSize
== 0) {
406 PrivateData
= (VOID
*)&SmmFtwWriteHeader
->Data
[Length
];
408 Status
= GetFvbByAddressAndAttribute (
409 SmmFtwWriteHeader
->FvbBaseAddress
,
410 SmmFtwWriteHeader
->FvbAttributes
,
413 if (!EFI_ERROR (Status
)) {
415 // The SpeculationBarrier() call here is to ensure the previous
416 // range/content checks for the CommBuffer have been completed before
417 // calling into FtwWrite().
419 SpeculationBarrier ();
421 &mFtwDevice
->FtwInstance
,
422 SmmFtwWriteHeader
->Lba
,
423 SmmFtwWriteHeader
->Offset
,
427 SmmFtwWriteHeader
->Data
432 case FTW_FUNCTION_RESTART
:
433 if (CommBufferPayloadSize
< sizeof (SMM_FTW_RESTART_HEADER
)) {
434 DEBUG ((EFI_D_ERROR
, "Restart: SMM communication buffer size invalid!\n"));
437 SmmFtwRestartHeader
= (SMM_FTW_RESTART_HEADER
*) SmmFtwFunctionHeader
->Data
;
438 Status
= GetFvbByAddressAndAttribute (
439 SmmFtwRestartHeader
->FvbBaseAddress
,
440 SmmFtwRestartHeader
->FvbAttributes
,
443 if (!EFI_ERROR (Status
)) {
444 Status
= FtwRestart (&mFtwDevice
->FtwInstance
, SmmFvbHandle
);
448 case FTW_FUNCTION_ABORT
:
449 Status
= FtwAbort (&mFtwDevice
->FtwInstance
);
452 case FTW_FUNCTION_GET_LAST_WRITE
:
453 if (CommBufferPayloadSize
< OFFSET_OF (SMM_FTW_GET_LAST_WRITE_HEADER
, Data
)) {
454 DEBUG ((EFI_D_ERROR
, "GetLastWrite: SMM communication buffer size invalid!\n"));
457 SmmFtwGetLastWriteHeader
= (SMM_FTW_GET_LAST_WRITE_HEADER
*) SmmFtwFunctionHeader
->Data
;
458 PrivateDataSize
= SmmFtwGetLastWriteHeader
->PrivateDataSize
;
459 if ((UINTN
)(~0) - PrivateDataSize
< OFFSET_OF (SMM_FTW_GET_LAST_WRITE_HEADER
, Data
)){
461 // Prevent InfoSize overflow
463 Status
= EFI_ACCESS_DENIED
;
466 InfoSize
= OFFSET_OF (SMM_FTW_GET_LAST_WRITE_HEADER
, Data
) + PrivateDataSize
;
469 // SMRAM range check already covered before
471 if (InfoSize
> CommBufferPayloadSize
) {
472 DEBUG ((EFI_D_ERROR
, "Data size exceed communication buffer size limit!\n"));
473 Status
= EFI_ACCESS_DENIED
;
477 Status
= FtwGetLastWrite (
478 &mFtwDevice
->FtwInstance
,
479 &SmmFtwGetLastWriteHeader
->CallerId
,
480 &SmmFtwGetLastWriteHeader
->Lba
,
481 &SmmFtwGetLastWriteHeader
->Offset
,
482 &SmmFtwGetLastWriteHeader
->Length
,
484 (VOID
*)SmmFtwGetLastWriteHeader
->Data
,
485 &SmmFtwGetLastWriteHeader
->Complete
487 SmmFtwGetLastWriteHeader
->PrivateDataSize
= PrivateDataSize
;
491 Status
= EFI_UNSUPPORTED
;
494 SmmFtwFunctionHeader
->ReturnStatus
= Status
;
501 SMM Firmware Volume Block Protocol notification event handler.
503 @param[in] Protocol Points to the protocol's unique identifier
504 @param[in] Interface Points to the interface instance
505 @param[in] Handle The handle on which the interface was installed
507 @retval EFI_SUCCESS SmmEventCallback runs successfully
512 FvbNotificationEvent (
513 IN CONST EFI_GUID
*Protocol
,
519 EFI_SMM_FAULT_TOLERANT_WRITE_PROTOCOL
*FtwProtocol
;
520 EFI_HANDLE SmmFtwHandle
;
523 // Just return to avoid install SMM FaultTolerantWriteProtocol again
524 // if SMM Fault Tolerant Write protocol had been installed.
526 Status
= gMmst
->MmLocateProtocol (
527 &gEfiSmmFaultTolerantWriteProtocolGuid
,
529 (VOID
**) &FtwProtocol
531 if (!EFI_ERROR (Status
)) {
536 // Found proper FVB protocol and initialize FtwDevice for protocol installation
538 Status
= InitFtwProtocol (mFtwDevice
);
539 if (EFI_ERROR(Status
)) {
544 // Install protocol interface
546 Status
= gMmst
->MmInstallProtocolInterface (
548 &gEfiSmmFaultTolerantWriteProtocolGuid
,
549 EFI_NATIVE_INTERFACE
,
550 &mFtwDevice
->FtwInstance
552 ASSERT_EFI_ERROR (Status
);
555 /// Register SMM FTW SMI handler
557 Status
= gMmst
->MmiHandlerRegister (SmmFaultTolerantWriteHandler
, &gEfiSmmFaultTolerantWriteProtocolGuid
, &SmmFtwHandle
);
558 ASSERT_EFI_ERROR (Status
);
561 // Notify the Ftw wrapper driver SMM Ftw is ready
563 FtwNotifySmmReady ();
569 SMM END_OF_DXE protocol notification event handler.
571 @param Protocol Points to the protocol's unique identifier
572 @param Interface Points to the interface instance
573 @param Handle The handle on which the interface was installed
575 @retval EFI_SUCCESS SmmEndOfDxeCallback runs successfully
581 IN CONST EFI_GUID
*Protocol
,
591 Shared entry point of the module
593 @retval EFI_SUCCESS The initialization finished successfully.
594 @retval EFI_OUT_OF_RESOURCES Allocate memory error
595 @retval EFI_INVALID_PARAMETER Workspace or Spare block does not exist
598 MmFaultTolerantWriteInitialize (
603 VOID
*MmEndOfDxeRegistration
;
606 // Allocate private data structure for SMM FTW protocol and do some initialization
608 Status
= InitFtwDevice (&mFtwDevice
);
609 if (EFI_ERROR(Status
)) {
614 // Register EFI_SMM_END_OF_DXE_PROTOCOL_GUID notify function.
616 Status
= gMmst
->MmRegisterProtocolNotify (
617 &gEfiMmEndOfDxeProtocolGuid
,
619 &MmEndOfDxeRegistration
621 ASSERT_EFI_ERROR (Status
);
624 // Register FvbNotificationEvent () notify function.
626 Status
= gMmst
->MmRegisterProtocolNotify (
627 &gEfiSmmFirmwareVolumeBlockProtocolGuid
,
628 FvbNotificationEvent
,
631 ASSERT_EFI_ERROR (Status
);
633 FvbNotificationEvent (NULL
, NULL
, NULL
);