1. Sync the latest network stack. Add NetLibCreateIPv4DPathNode () in netlib library.
[mirror_edk2.git] / MdeModulePkg / Universal / FirmwareVolume / FaultTolerantWriteDxe / FtwLite.h
1 /*++
2
3 Copyright (c) 2006, 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
13 Module Name:
14
15 FtwLite.h
16
17 Abstract:
18
19 This is a simple fault tolerant write driver, based on PlatformFd library.
20 And it only supports write BufferSize <= SpareAreaLength.
21
22 This boot service only protocol provides fault tolerant write capability for
23 block devices. The protocol has internal non-volatile intermediate storage
24 of the data and private information. It should be able to recover
25 automatically from a critical fault, such as power failure.
26
27 --*/
28
29 #ifndef _EFI_FAULT_TOLERANT_WRITE_LITE_H_
30 #define _EFI_FAULT_TOLERANT_WRITE_LITE_H_
31
32
33 #include <PiDxe.h>
34
35 #include <Protocol/PciRootBridgeIo.h>
36 #include <Guid/SystemNvDataGuid.h>
37 #include <Protocol/FaultTolerantWriteLite.h>
38 #include <Protocol/FirmwareVolumeBlock.h>
39
40 #include <Library/PcdLib.h>
41 #include <Library/DebugLib.h>
42 #include <Library/UefiDriverEntryPoint.h>
43 #include <Library/BaseMemoryLib.h>
44 #include <Library/MemoryAllocationLib.h>
45 #include <Library/UefiBootServicesTableLib.h>
46
47 #include <WorkingBlockHeader.h>
48
49 #define EFI_D_FTW_LITE EFI_D_ERROR
50 #define EFI_D_FTW_INFO EFI_D_INFO
51
52 //
53 // Flash erase polarity is 1
54 //
55 #define FTW_ERASE_POLARITY 1
56
57 #define FTW_VALID_STATE 0
58 #define FTW_INVALID_STATE 1
59
60 #define FTW_ERASED_BYTE ((UINT8) (255))
61 #define FTW_POLARITY_REVERT ((UINT8) (255))
62
63 typedef struct {
64 UINT8 WriteAllocated : 1;
65 UINT8 SpareCompleted : 1;
66 UINT8 WriteCompleted : 1;
67 UINT8 Reserved : 5;
68 #define WRITE_ALLOCATED 0x1
69 #define SPARE_COMPLETED 0x2
70 #define WRITE_COMPLETED 0x4
71
72 EFI_DEV_PATH DevPath;
73 EFI_LBA Lba;
74 UINTN Offset;
75 UINTN NumBytes;
76 //
77 // UINTN SpareAreaOffset;
78 //
79 } EFI_FTW_LITE_RECORD;
80
81 #define FTW_LITE_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('F', 'T', 'W', 'L')
82
83 //
84 // MACRO for Block size.
85 // Flash Erasing will do in block granularity.
86 //
87 #ifdef FV_BLOCK_SIZE
88 #define FTW_BLOCK_SIZE FV_BLOCK_SIZE
89 #else
90 #define FV_BLOCK_SIZE 0x10000
91 #define FTW_BLOCK_SIZE FV_BLOCK_SIZE
92 #endif
93 //
94 // MACRO for FTW WORK SPACE Base & Size
95 //
96 #ifdef EFI_FTW_WORKING_OFFSET
97 #define FTW_WORK_SPACE_BASE EFI_FTW_WORKING_OFFSET
98 #else
99 #define FTW_WORK_SPACE_BASE 0x00E000
100 #endif
101
102 #ifdef EFI_FTW_WORKING_LENGTH
103 #define FTW_WORK_SPACE_SIZE EFI_FTW_WORKING_LENGTH
104 #else
105 #define FTW_WORK_SPACE_SIZE 0x002000
106 #endif
107 //
108 // MACRO for FTW header and record
109 //
110 #define FTW_WORKING_QUEUE_SIZE (FTW_WORK_SPACE_SIZE - sizeof (EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER))
111 #define FTW_LITE_RECORD_SIZE (sizeof (EFI_FTW_LITE_RECORD))
112 #define WRITE_TOTAL_SIZE FTW_LITE_RECORD_SIZE
113
114 //
115 // EFI Fault tolerant protocol private data structure
116 //
117 typedef struct {
118 UINTN Signature;
119 EFI_HANDLE Handle;
120 EFI_FTW_LITE_PROTOCOL FtwLiteInstance;
121 EFI_PHYSICAL_ADDRESS WorkSpaceAddress;
122 UINTN WorkSpaceLength;
123 EFI_PHYSICAL_ADDRESS SpareAreaAddress;
124 UINTN SpareAreaLength;
125 UINTN NumberOfSpareBlock; // Number of the blocks in spare block
126 UINTN SizeOfSpareBlock; // Block size in bytes of the blocks in spare block
127 EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *FtwWorkSpaceHeader;
128 EFI_FTW_LITE_RECORD *FtwLastRecord;
129 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FtwFvBlock; // FVB of working block
130 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FtwBackupFvb; // FVB of spare block
131 EFI_LBA FtwSpareLba;
132 EFI_LBA FtwWorkBlockLba; // Start LBA of working block
133 EFI_LBA FtwWorkSpaceLba; // Start LBA of working space
134 UINTN FtwWorkSpaceBase; // Offset from LBA start addr
135 UINTN FtwWorkSpaceSize;
136 UINT8 *FtwWorkSpace;
137 //
138 // Following a buffer of FtwWorkSpace[FTW_WORK_SPACE_SIZE],
139 // Allocated with EFI_FTW_LITE_DEVICE.
140 //
141 } EFI_FTW_LITE_DEVICE;
142
143 #define FTW_LITE_CONTEXT_FROM_THIS(a) CR (a, EFI_FTW_LITE_DEVICE, FtwLiteInstance, FTW_LITE_DEVICE_SIGNATURE)
144
145 //
146 // Driver entry point
147 //
148 EFI_STATUS
149 EFIAPI
150 InitializeFtwLite (
151 IN EFI_HANDLE ImageHandle,
152 IN EFI_SYSTEM_TABLE *SystemTable
153 )
154 /*++
155
156 Routine Description:
157 This function is the entry point of the Fault Tolerant Write driver.
158
159 Arguments:
160 ImageHandle - EFI_HANDLE: A handle for the image that is initializing
161 this driver
162 SystemTable - EFI_SYSTEM_TABLE: A pointer to the EFI system table
163
164 Returns:
165 EFI_SUCCESS - FTW has finished the initialization
166 EFI_ABORTED - FTW initialization error
167
168 --*/
169 ;
170
171 //
172 // Fault Tolerant Write Protocol API
173 //
174 EFI_STATUS
175 EFIAPI
176 FtwLiteWrite (
177 IN EFI_FTW_LITE_PROTOCOL *This,
178 IN EFI_HANDLE FvbHandle,
179 IN EFI_LBA Lba,
180 IN UINTN Offset,
181 IN UINTN *NumBytes,
182 IN VOID *Buffer
183 )
184 /*++
185
186 Routine Description:
187 Starts a target block update. This function will record data about write
188 in fault tolerant storage and will complete the write in a recoverable
189 manner, ensuring at all times that either the original contents or
190 the modified contents are available.
191
192 Arguments:
193 This - Calling context
194 FvbHandle - The handle of FVB protocol that provides services for
195 reading, writing, and erasing the target block.
196 Lba - The logical block address of the target block.
197 Offset - The offset within the target block to place the data.
198 NumBytes - The number of bytes to write to the target block.
199 Buffer - The data to write.
200
201 Returns:
202 EFI_SUCCESS - The function completed successfully
203 EFI_BAD_BUFFER_SIZE - The write would span a target block, which is not
204 a valid action.
205 EFI_ACCESS_DENIED - No writes have been allocated.
206 EFI_NOT_FOUND - Cannot find FVB by handle.
207 EFI_OUT_OF_RESOURCES - Cannot allocate memory.
208 EFI_ABORTED - The function could not complete successfully.
209
210 --*/
211 ;
212
213 //
214 // Internal functions
215 //
216 EFI_STATUS
217 FtwRestart (
218 IN EFI_FTW_LITE_DEVICE *FtwLiteDevice
219 )
220 /*++
221
222 Routine Description:
223 Restarts a previously interrupted write. The caller must provide the
224 block protocol needed to complete the interrupted write.
225
226 Arguments:
227 FtwLiteDevice - The private data of FTW_LITE driver
228 FvbHandle - The handle of FVB protocol that provides services for
229 reading, writing, and erasing the target block.
230
231 Returns:
232 EFI_SUCCESS - The function completed successfully
233 EFI_ACCESS_DENIED - No pending writes exist
234 EFI_NOT_FOUND - FVB protocol not found by the handle
235 EFI_ABORTED - The function could not complete successfully
236
237 --*/
238 ;
239
240 EFI_STATUS
241 FtwAbort (
242 IN EFI_FTW_LITE_DEVICE *FtwLiteDevice
243 )
244 /*++
245
246 Routine Description:
247 Aborts all previous allocated writes.
248
249 Arguments:
250 FtwLiteDevice - The private data of FTW_LITE driver
251
252 Returns:
253 EFI_SUCCESS - The function completed successfully
254 EFI_ABORTED - The function could not complete successfully.
255 EFI_NOT_FOUND - No allocated writes exist.
256
257 --*/
258 ;
259
260
261 EFI_STATUS
262 FtwWriteRecord (
263 IN EFI_FTW_LITE_DEVICE *FtwLiteDevice,
264 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb
265 )
266 /*++
267
268 Routine Description:
269 Write a record with fault tolerant mannaer.
270 Since the content has already backuped in spare block, the write is
271 guaranteed to be completed with fault tolerant manner.
272
273 Arguments:
274 FtwLiteDevice - The private data of FTW_LITE driver
275 Fvb - The FVB protocol that provides services for
276 reading, writing, and erasing the target block.
277
278 Returns:
279 EFI_SUCCESS - The function completed successfully
280 EFI_ABORTED - The function could not complete successfully
281
282 --*/
283 ;
284
285 EFI_STATUS
286 FtwEraseBlock (
287 IN EFI_FTW_LITE_DEVICE *FtwLiteDevice,
288 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock,
289 EFI_LBA Lba
290 )
291 /*++
292
293 Routine Description:
294 To Erase one block. The size is FTW_BLOCK_SIZE
295
296 Arguments:
297 FtwLiteDevice - Calling context
298 FvBlock - FVB Protocol interface
299 Lba - Lba of the firmware block
300
301 Returns:
302 EFI_SUCCESS - Block LBA is Erased successfully
303 Others - Error occurs
304
305 --*/
306 ;
307
308 EFI_STATUS
309 FtwEraseSpareBlock (
310 IN EFI_FTW_LITE_DEVICE *FtwLiteDevice
311 )
312 /*++
313
314 Routine Description:
315
316 Erase spare block.
317
318 Arguments:
319
320 FtwLiteDevice - Calling context
321
322 Returns:
323
324 Status code
325
326 --*/
327 ;
328
329 EFI_STATUS
330 FtwGetFvbByHandle (
331 IN EFI_HANDLE FvBlockHandle,
332 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock
333 )
334 /*++
335
336 Routine Description:
337 Retrive the proper FVB protocol interface by HANDLE.
338
339 Arguments:
340 FvBlockHandle - The handle of FVB protocol that provides services for
341 reading, writing, and erasing the target block.
342 FvBlock - The interface of FVB protocol
343
344 Returns:
345 EFI_SUCCESS - The function completed successfully
346 EFI_ABORTED - The function could not complete successfully
347 --*/
348 ;
349
350 EFI_STATUS
351 GetFvbByAddress (
352 IN EFI_PHYSICAL_ADDRESS Address,
353 OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL **FvBlock
354 )
355 /*++
356
357 Routine Description:
358
359 Get firmware block by address.
360
361 Arguments:
362
363 Address - Address specified the block
364 FvBlock - The block caller wanted
365
366 Returns:
367
368 Status code
369
370 EFI_NOT_FOUND - Block not found
371
372 --*/
373 ;
374
375 BOOLEAN
376 IsInWorkingBlock (
377 EFI_FTW_LITE_DEVICE *FtwLiteDevice,
378 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock,
379 EFI_LBA Lba
380 )
381 /*++
382
383 Routine Description:
384
385 Is it in working block?
386
387 Arguments:
388
389 FtwLiteDevice - Calling context
390 FvBlock - Fvb protocol instance
391 Lba - The block specified
392
393 Returns:
394
395 In working block or not
396
397 --*/
398 ;
399
400 BOOLEAN
401 IsBootBlock (
402 EFI_FTW_LITE_DEVICE *FtwLiteDevice,
403 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock,
404 EFI_LBA Lba
405 )
406 /*++
407
408 Routine Description:
409
410 Check whether the block is a boot block.
411
412 Arguments:
413
414 FtwLiteDevice - Calling context
415 FvBlock - Fvb protocol instance
416 Lba - Lba value
417
418 Returns:
419
420 Is a boot block or not
421
422 --*/
423 ;
424
425 EFI_STATUS
426 FlushSpareBlockToTargetBlock (
427 EFI_FTW_LITE_DEVICE *FtwLiteDevice,
428 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock,
429 EFI_LBA Lba
430 )
431 /*++
432
433 Routine Description:
434 Copy the content of spare block to a target block. Size is FTW_BLOCK_SIZE.
435 Spare block is accessed by FTW backup FVB protocol interface. LBA is
436 FtwLiteDevice->FtwSpareLba.
437 Target block is accessed by FvBlock protocol interface. LBA is Lba.
438
439 Arguments:
440 FtwLiteDevice - The private data of FTW_LITE driver
441 FvBlock - FVB Protocol interface to access target block
442 Lba - Lba of the target block
443
444 Returns:
445 EFI_SUCCESS - Spare block content is copied to target block
446 EFI_INVALID_PARAMETER - Input parameter error
447 EFI_OUT_OF_RESOURCES - Allocate memory error
448 EFI_ABORTED - The function could not complete successfully
449
450 --*/
451 ;
452
453 EFI_STATUS
454 FlushSpareBlockToWorkingBlock (
455 EFI_FTW_LITE_DEVICE *FtwLiteDevice
456 )
457 /*++
458
459 Routine Description:
460 Copy the content of spare block to working block. Size is FTW_BLOCK_SIZE.
461 Spare block is accessed by FTW backup FVB protocol interface. LBA is
462 FtwLiteDevice->FtwSpareLba.
463 Working block is accessed by FTW working FVB protocol interface. LBA is
464 FtwLiteDevice->FtwWorkBlockLba.
465
466 Arguments:
467 FtwLiteDevice - The private data of FTW_LITE driver
468
469 Returns:
470 EFI_SUCCESS - Spare block content is copied to target block
471 EFI_OUT_OF_RESOURCES - Allocate memory error
472 EFI_ABORTED - The function could not complete successfully
473
474 Notes:
475 Since the working block header is important when FTW initializes, the
476 state of the operation should be handled carefully. The Crc value is
477 calculated without STATE element.
478
479 --*/
480 ;
481
482 EFI_STATUS
483 FlushSpareBlockToBootBlock (
484 EFI_FTW_LITE_DEVICE *FtwLiteDevice
485 )
486 /*++
487
488 Routine Description:
489 Copy the content of spare block to a boot block. Size is FTW_BLOCK_SIZE.
490 Spare block is accessed by FTW backup FVB protocol interface. LBA is
491 FtwLiteDevice->FtwSpareLba.
492 Boot block is accessed by BootFvb protocol interface. LBA is 0.
493
494 Arguments:
495 FtwLiteDevice - The private data of FTW_LITE driver
496
497 Returns:
498 EFI_SUCCESS - Spare block content is copied to boot block
499 EFI_INVALID_PARAMETER - Input parameter error
500 EFI_OUT_OF_RESOURCES - Allocate memory error
501 EFI_ABORTED - The function could not complete successfully
502
503 Notes:
504
505 --*/
506 ;
507
508 EFI_STATUS
509 FtwUpdateFvState (
510 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvBlock,
511 IN EFI_LBA Lba,
512 IN UINTN Offset,
513 IN UINT8 NewBit
514 )
515 /*++
516
517 Routine Description:
518 Update a bit of state on a block device. The location of the bit is
519 calculated by the (Lba, Offset, bit). Here bit is determined by the
520 the name of a certain bit.
521
522 Arguments:
523 FvBlock - FVB Protocol interface to access SrcBlock and DestBlock
524 Lba - Lba of a block
525 Offset - Offset on the Lba
526 NewBit - New value that will override the old value if it can be change
527
528 Returns:
529 EFI_SUCCESS - A state bit has been updated successfully
530 Others - Access block device error.
531
532 Notes:
533 Assume all bits of State are inside the same BYTE.
534
535 EFI_ABORTED - Read block fail
536 --*/
537 ;
538
539 EFI_STATUS
540 FtwGetLastRecord (
541 IN EFI_FTW_LITE_DEVICE *FtwLiteDevice,
542 OUT EFI_FTW_LITE_RECORD **FtwLastRecord
543 )
544 /*++
545
546 Routine Description:
547 Get the last Write record pointer.
548 The last record is the record whose 'complete' state hasn't been set.
549 After all, this header may be a EMPTY header entry for next Allocate.
550
551 Arguments:
552 FtwLiteDevice - Private data of this driver
553 FtwLastRecord - Pointer to retrieve the last write record
554
555 Returns:
556 EFI_SUCCESS - Get the last write record successfully
557 EFI_ABORTED - The FTW work space is damaged
558
559 --*/
560 ;
561
562 BOOLEAN
563 IsErasedFlashBuffer (
564 IN BOOLEAN Polarity,
565 IN UINT8 *Buffer,
566 IN UINTN BufferSize
567 )
568 /*++
569
570 Routine Description:
571
572 Check whether a flash buffer is erased.
573
574 Arguments:
575
576 Polarity - All 1 or all 0
577 Buffer - Buffer to check
578 BufferSize - Size of the buffer
579
580 Returns:
581
582 Erased or not.
583
584 --*/
585 ;
586
587 EFI_STATUS
588 InitWorkSpaceHeader (
589 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader
590 )
591 /*++
592
593 Routine Description:
594 Initialize a work space when there is no work space.
595
596 Arguments:
597 WorkingHeader - Pointer of working block header
598
599 Returns:
600 EFI_SUCCESS - The function completed successfully
601 EFI_ABORTED - The function could not complete successfully.
602
603 --*/
604 ;
605
606 EFI_STATUS
607 WorkSpaceRefresh (
608 IN EFI_FTW_LITE_DEVICE *FtwLiteDevice
609 )
610 /*++
611
612 Routine Description:
613 Read from working block to refresh the work space in memory.
614
615 Arguments:
616 FtwLiteDevice - Point to private data of FTW driver
617
618 Returns:
619 EFI_SUCCESS - The function completed successfully
620 EFI_ABORTED - The function could not complete successfully.
621
622 --*/
623 ;
624
625 BOOLEAN
626 IsValidWorkSpace (
627 IN EFI_FAULT_TOLERANT_WORKING_BLOCK_HEADER *WorkingHeader
628 )
629 /*++
630
631 Routine Description:
632 Check to see if it is a valid work space.
633
634 Arguments:
635 WorkingHeader - Pointer of working block header
636
637 Returns:
638 EFI_SUCCESS - The function completed successfully
639 EFI_ABORTED - The function could not complete successfully.
640
641 --*/
642 ;
643
644 EFI_STATUS
645 CleanupWorkSpace (
646 IN EFI_FTW_LITE_DEVICE *FtwLiteDevice,
647 IN OUT UINT8 *BlockBuffer,
648 IN UINTN BufferSize
649 )
650 /*++
651
652 Routine Description:
653 Reclaim the work space. Get rid of all the completed write records
654 and write records in the Fault Tolerant work space.
655
656 Arguments:
657 FtwLiteDevice - Point to private data of FTW driver
658 FtwSpaceBuffer - Buffer to contain the reclaimed clean data
659 BufferSize - Size of the FtwSpaceBuffer
660
661 Returns:
662 EFI_SUCCESS - The function completed successfully
663 EFI_BUFFER_TOO_SMALL - The FtwSpaceBuffer is too small
664 EFI_ABORTED - The function could not complete successfully.
665
666 --*/
667 ;
668
669 EFI_STATUS
670 FtwReclaimWorkSpace (
671 IN EFI_FTW_LITE_DEVICE *FtwLiteDevice
672 )
673 /*++
674
675 Routine Description:
676 Reclaim the work space on the working block.
677
678 Arguments:
679 FtwLiteDevice - Point to private data of FTW driver
680
681 Returns:
682 EFI_SUCCESS - The function completed successfully
683 EFI_OUT_OF_RESOURCES - Allocate memory error
684 EFI_ABORTED - The function could not complete successfully
685
686 --*/
687 ;
688
689 #endif