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 VOID
*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
)) {
189 Get the handle of the SMM FVB protocol by the FVB base address and attributes.
191 @param[in] Address The base address of SMM FVB protocol.
192 @param[in] Attributes The attributes of the SMM FVB protocol.
193 @param[out] SmmFvbHandle The handle of the SMM FVB protocol.
195 @retval EFI_SUCCESS The FVB handle is found.
196 @retval EFI_ABORTED The FVB protocol is not found.
200 GetFvbByAddressAndAttribute (
201 IN EFI_PHYSICAL_ADDRESS Address
,
202 IN EFI_FVB_ATTRIBUTES_2 Attributes
,
203 OUT EFI_HANDLE
*SmmFvbHandle
207 EFI_HANDLE
*HandleBuffer
;
210 EFI_PHYSICAL_ADDRESS FvbBaseAddress
;
211 EFI_FVB_ATTRIBUTES_2 FvbAttributes
;
212 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
;
217 // Locate all handles of SMM Fvb protocol.
219 Status
= GetFvbCountAndBuffer (&HandleCount
, &HandleBuffer
);
220 if (EFI_ERROR (Status
)) {
225 // Find the proper SMM Fvb handle by the address and attributes.
227 for (Index
= 0; Index
< HandleCount
; Index
++) {
228 Status
= FtwGetFvbByHandle (HandleBuffer
[Index
], &Fvb
);
229 if (EFI_ERROR (Status
)) {
234 // Compare the address.
236 Status
= Fvb
->GetPhysicalAddress (Fvb
, &FvbBaseAddress
);
237 if (EFI_ERROR (Status
)) {
241 if (Address
!= FvbBaseAddress
) {
246 // Compare the attribute.
248 Status
= Fvb
->GetAttributes (Fvb
, &FvbAttributes
);
249 if (EFI_ERROR (Status
)) {
253 if (Attributes
!= FvbAttributes
) {
258 // Found the proper FVB handle.
260 *SmmFvbHandle
= HandleBuffer
[Index
];
261 FreePool (HandleBuffer
);
265 FreePool (HandleBuffer
);
270 Communication service SMI Handler entry.
272 This SMI handler provides services for the fault tolerant write wrapper driver.
274 Caution: This function requires additional review when modified.
275 This driver need to make sure the CommBuffer is not in the SMRAM range.
276 Also in FTW_FUNCTION_GET_LAST_WRITE case, check SmmFtwGetLastWriteHeader->Data +
277 SmmFtwGetLastWriteHeader->PrivateDataSize within communication buffer.
279 @param[in] DispatchHandle The unique handle assigned to this handler by SmiHandlerRegister().
280 @param[in] RegisterContext Points to an optional handler context which was specified when the
281 handler was registered.
282 @param[in, out] CommBuffer A pointer to a collection of data in memory that will be conveyed
283 from a non-SMM environment into an SMM environment.
284 @param[in, out] CommBufferSize The size of the CommBuffer.
286 @retval EFI_SUCCESS The interrupt was handled and quiesced. No other handlers
287 should still be called.
288 @retval EFI_WARN_INTERRUPT_SOURCE_QUIESCED The interrupt has been quiesced but other handlers should
290 @retval EFI_WARN_INTERRUPT_SOURCE_PENDING The interrupt is still pending and other handlers should still
292 @retval EFI_INTERRUPT_PENDING The interrupt could not be quiesced.
297 SmmFaultTolerantWriteHandler (
298 IN EFI_HANDLE DispatchHandle
,
299 IN CONST VOID
*RegisterContext
,
300 IN OUT VOID
*CommBuffer
,
301 IN OUT UINTN
*CommBufferSize
305 SMM_FTW_COMMUNICATE_FUNCTION_HEADER
*SmmFtwFunctionHeader
;
306 SMM_FTW_GET_MAX_BLOCK_SIZE_HEADER
*SmmGetMaxBlockSizeHeader
;
307 SMM_FTW_ALLOCATE_HEADER
*SmmFtwAllocateHeader
;
308 SMM_FTW_WRITE_HEADER
*SmmFtwWriteHeader
;
309 SMM_FTW_RESTART_HEADER
*SmmFtwRestartHeader
;
310 SMM_FTW_GET_LAST_WRITE_HEADER
*SmmFtwGetLastWriteHeader
;
312 EFI_HANDLE SmmFvbHandle
;
314 UINTN CommBufferPayloadSize
;
315 UINTN PrivateDataSize
;
317 UINTN TempCommBufferSize
;
320 // If input is invalid, stop processing this SMI
322 if ((CommBuffer
== NULL
) || (CommBufferSize
== NULL
)) {
326 TempCommBufferSize
= *CommBufferSize
;
328 if (TempCommBufferSize
< SMM_FTW_COMMUNICATE_HEADER_SIZE
) {
329 DEBUG ((DEBUG_ERROR
, "SmmFtwHandler: SMM communication buffer size invalid!\n"));
333 CommBufferPayloadSize
= TempCommBufferSize
- SMM_FTW_COMMUNICATE_HEADER_SIZE
;
335 if (!FtwSmmIsBufferOutsideSmmValid ((UINTN
)CommBuffer
, TempCommBufferSize
)) {
336 DEBUG ((DEBUG_ERROR
, "SmmFtwHandler: SMM communication buffer in SMRAM or overflow!\n"));
340 SmmFtwFunctionHeader
= (SMM_FTW_COMMUNICATE_FUNCTION_HEADER
*)CommBuffer
;
344 // It will be not safe to expose the operations after End Of Dxe.
346 DEBUG ((DEBUG_ERROR
, "SmmFtwHandler: Not safe to do the operation: %x after End Of Dxe, so access denied!\n", SmmFtwFunctionHeader
->Function
));
347 SmmFtwFunctionHeader
->ReturnStatus
= EFI_ACCESS_DENIED
;
351 switch (SmmFtwFunctionHeader
->Function
) {
352 case FTW_FUNCTION_GET_MAX_BLOCK_SIZE
:
353 if (CommBufferPayloadSize
< sizeof (SMM_FTW_GET_MAX_BLOCK_SIZE_HEADER
)) {
354 DEBUG ((DEBUG_ERROR
, "GetMaxBlockSize: SMM communication buffer size invalid!\n"));
358 SmmGetMaxBlockSizeHeader
= (SMM_FTW_GET_MAX_BLOCK_SIZE_HEADER
*)SmmFtwFunctionHeader
->Data
;
360 Status
= FtwGetMaxBlockSize (
361 &mFtwDevice
->FtwInstance
,
362 &SmmGetMaxBlockSizeHeader
->BlockSize
366 case FTW_FUNCTION_ALLOCATE
:
367 if (CommBufferPayloadSize
< sizeof (SMM_FTW_ALLOCATE_HEADER
)) {
368 DEBUG ((DEBUG_ERROR
, "Allocate: SMM communication buffer size invalid!\n"));
372 SmmFtwAllocateHeader
= (SMM_FTW_ALLOCATE_HEADER
*)SmmFtwFunctionHeader
->Data
;
373 Status
= FtwAllocate (
374 &mFtwDevice
->FtwInstance
,
375 &SmmFtwAllocateHeader
->CallerId
,
376 SmmFtwAllocateHeader
->PrivateDataSize
,
377 SmmFtwAllocateHeader
->NumberOfWrites
381 case FTW_FUNCTION_WRITE
:
382 if (CommBufferPayloadSize
< OFFSET_OF (SMM_FTW_WRITE_HEADER
, Data
)) {
383 DEBUG ((DEBUG_ERROR
, "Write: SMM communication buffer size invalid!\n"));
387 SmmFtwWriteHeader
= (SMM_FTW_WRITE_HEADER
*)SmmFtwFunctionHeader
->Data
;
388 Length
= SmmFtwWriteHeader
->Length
;
389 PrivateDataSize
= SmmFtwWriteHeader
->PrivateDataSize
;
390 if (((UINTN
)(~0) - Length
< OFFSET_OF (SMM_FTW_WRITE_HEADER
, Data
)) ||
391 ((UINTN
)(~0) - PrivateDataSize
< OFFSET_OF (SMM_FTW_WRITE_HEADER
, Data
) + Length
))
394 // Prevent InfoSize overflow
396 Status
= EFI_ACCESS_DENIED
;
400 InfoSize
= OFFSET_OF (SMM_FTW_WRITE_HEADER
, Data
) + Length
+ PrivateDataSize
;
403 // SMRAM range check already covered before
405 if (InfoSize
> CommBufferPayloadSize
) {
406 DEBUG ((DEBUG_ERROR
, "Write: Data size exceed communication buffer size limit!\n"));
407 Status
= EFI_ACCESS_DENIED
;
411 if (PrivateDataSize
== 0) {
414 PrivateData
= (VOID
*)&SmmFtwWriteHeader
->Data
[Length
];
417 Status
= GetFvbByAddressAndAttribute (
418 SmmFtwWriteHeader
->FvbBaseAddress
,
419 SmmFtwWriteHeader
->FvbAttributes
,
422 if (!EFI_ERROR (Status
)) {
424 // The SpeculationBarrier() call here is to ensure the previous
425 // range/content checks for the CommBuffer have been completed before
426 // calling into FtwWrite().
428 SpeculationBarrier ();
430 &mFtwDevice
->FtwInstance
,
431 SmmFtwWriteHeader
->Lba
,
432 SmmFtwWriteHeader
->Offset
,
436 SmmFtwWriteHeader
->Data
442 case FTW_FUNCTION_RESTART
:
443 if (CommBufferPayloadSize
< sizeof (SMM_FTW_RESTART_HEADER
)) {
444 DEBUG ((DEBUG_ERROR
, "Restart: SMM communication buffer size invalid!\n"));
448 SmmFtwRestartHeader
= (SMM_FTW_RESTART_HEADER
*)SmmFtwFunctionHeader
->Data
;
449 Status
= GetFvbByAddressAndAttribute (
450 SmmFtwRestartHeader
->FvbBaseAddress
,
451 SmmFtwRestartHeader
->FvbAttributes
,
454 if (!EFI_ERROR (Status
)) {
455 Status
= FtwRestart (&mFtwDevice
->FtwInstance
, SmmFvbHandle
);
460 case FTW_FUNCTION_ABORT
:
461 Status
= FtwAbort (&mFtwDevice
->FtwInstance
);
464 case FTW_FUNCTION_GET_LAST_WRITE
:
465 if (CommBufferPayloadSize
< OFFSET_OF (SMM_FTW_GET_LAST_WRITE_HEADER
, Data
)) {
466 DEBUG ((DEBUG_ERROR
, "GetLastWrite: SMM communication buffer size invalid!\n"));
470 SmmFtwGetLastWriteHeader
= (SMM_FTW_GET_LAST_WRITE_HEADER
*)SmmFtwFunctionHeader
->Data
;
471 PrivateDataSize
= SmmFtwGetLastWriteHeader
->PrivateDataSize
;
472 if ((UINTN
)(~0) - PrivateDataSize
< OFFSET_OF (SMM_FTW_GET_LAST_WRITE_HEADER
, Data
)) {
474 // Prevent InfoSize overflow
476 Status
= EFI_ACCESS_DENIED
;
480 InfoSize
= OFFSET_OF (SMM_FTW_GET_LAST_WRITE_HEADER
, Data
) + PrivateDataSize
;
483 // SMRAM range check already covered before
485 if (InfoSize
> CommBufferPayloadSize
) {
486 DEBUG ((DEBUG_ERROR
, "Data size exceed communication buffer size limit!\n"));
487 Status
= EFI_ACCESS_DENIED
;
491 Status
= FtwGetLastWrite (
492 &mFtwDevice
->FtwInstance
,
493 &SmmFtwGetLastWriteHeader
->CallerId
,
494 &SmmFtwGetLastWriteHeader
->Lba
,
495 &SmmFtwGetLastWriteHeader
->Offset
,
496 &SmmFtwGetLastWriteHeader
->Length
,
498 (VOID
*)SmmFtwGetLastWriteHeader
->Data
,
499 &SmmFtwGetLastWriteHeader
->Complete
501 SmmFtwGetLastWriteHeader
->PrivateDataSize
= PrivateDataSize
;
505 Status
= EFI_UNSUPPORTED
;
508 SmmFtwFunctionHeader
->ReturnStatus
= Status
;
514 SMM Firmware Volume Block Protocol notification event handler.
516 @param[in] Protocol Points to the protocol's unique identifier
517 @param[in] Interface Points to the interface instance
518 @param[in] Handle The handle on which the interface was installed
520 @retval EFI_SUCCESS SmmEventCallback runs successfully
525 FvbNotificationEvent (
526 IN CONST EFI_GUID
*Protocol
,
532 EFI_SMM_FAULT_TOLERANT_WRITE_PROTOCOL
*FtwProtocol
;
533 EFI_HANDLE SmmFtwHandle
;
536 // Just return to avoid install SMM FaultTolerantWriteProtocol again
537 // if SMM Fault Tolerant Write protocol had been installed.
539 Status
= gMmst
->MmLocateProtocol (
540 &gEfiSmmFaultTolerantWriteProtocolGuid
,
542 (VOID
**)&FtwProtocol
544 if (!EFI_ERROR (Status
)) {
549 // Found proper FVB protocol and initialize FtwDevice for protocol installation
551 Status
= InitFtwProtocol (mFtwDevice
);
552 if (EFI_ERROR (Status
)) {
557 // Install protocol interface
559 Status
= gMmst
->MmInstallProtocolInterface (
561 &gEfiSmmFaultTolerantWriteProtocolGuid
,
562 EFI_NATIVE_INTERFACE
,
563 &mFtwDevice
->FtwInstance
565 ASSERT_EFI_ERROR (Status
);
568 /// Register SMM FTW SMI handler
570 Status
= gMmst
->MmiHandlerRegister (SmmFaultTolerantWriteHandler
, &gEfiSmmFaultTolerantWriteProtocolGuid
, &SmmFtwHandle
);
571 ASSERT_EFI_ERROR (Status
);
574 // Notify the Ftw wrapper driver SMM Ftw is ready
576 FtwNotifySmmReady ();
582 SMM END_OF_DXE protocol notification event handler.
584 @param Protocol Points to the protocol's unique identifier
585 @param Interface Points to the interface instance
586 @param Handle The handle on which the interface was installed
588 @retval EFI_SUCCESS SmmEndOfDxeCallback runs successfully
594 IN CONST EFI_GUID
*Protocol
,
604 Shared entry point of the module
606 @retval EFI_SUCCESS The initialization finished successfully.
607 @retval EFI_OUT_OF_RESOURCES Allocate memory error
608 @retval EFI_INVALID_PARAMETER Workspace or Spare block does not exist
611 MmFaultTolerantWriteInitialize (
616 VOID
*MmEndOfDxeRegistration
;
619 // Allocate private data structure for SMM FTW protocol and do some initialization
621 Status
= InitFtwDevice (&mFtwDevice
);
622 if (EFI_ERROR (Status
)) {
627 // Register EFI_SMM_END_OF_DXE_PROTOCOL_GUID notify function.
629 Status
= gMmst
->MmRegisterProtocolNotify (
630 &gEfiMmEndOfDxeProtocolGuid
,
632 &MmEndOfDxeRegistration
634 ASSERT_EFI_ERROR (Status
);
637 // Register FvbNotificationEvent () notify function.
639 Status
= gMmst
->MmRegisterProtocolNotify (
640 &gEfiSmmFirmwareVolumeBlockProtocolGuid
,
641 FvbNotificationEvent
,
644 ASSERT_EFI_ERROR (Status
);
646 FvbNotificationEvent (NULL
, NULL
, NULL
);