MdePkg/Include/Guid/Btt.h

   1 /** @file
   2   Block Translation Table (BTT) metadata layout definition.
   3
   4   BTT is a layout and set of rules for doing block I/O that provide powerfail
   5   write atomicity of a single block.
   6
   7 Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
   8 SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10   @par Revision Reference:
  11   This metadata layout definition was introduced in UEFI Specification 2.7.
  12
  13 **/
  14
  15 #ifndef _BTT_H_
  16 #define _BTT_H_
  17
  18 ///
  19 /// The BTT layout and behavior is described by the GUID as below.
  20 ///
  21 #define EFI_BTT_ABSTRACTION_GUID \
  22   { \
  23     0x18633bfc, 0x1735, 0x4217, { 0x8a, 0xc9, 0x17, 0x23, 0x92, 0x82, 0xd3, 0xf8 } \
  24   }
  25
  26 //
  27 // Alignment of all BTT structures
  28 //
  29 #define EFI_BTT_ALIGNMENT                4096
  30
  31 #define EFI_BTT_INFO_UNUSED_LEN          3968
  32
  33 #define EFI_BTT_INFO_BLOCK_SIG_LEN       16
  34
  35 ///
  36 /// Indicate inconsistent metadata or lost metadata due to unrecoverable media errors.
  37 ///
  38 #define EFI_BTT_INFO_BLOCK_FLAGS_ERROR   0x00000001
  39
  40 #define EFI_BTT_INFO_BLOCK_MAJOR_VERSION 2
  41 #define EFI_BTT_INFO_BLOCK_MINOR_VERSION 0
  42
  43 ///
  44 /// Block Translation Table (BTT) Info Block
  45 ///
  46 typedef struct _EFI_BTT_INFO_BLOCK {
  47   ///
  48   /// Signature of the BTT Index Block data structure.
  49   /// Shall be "BTT_ARENA_INFO\0\0".
  50   ///
  51   CHAR8    Sig[EFI_BTT_INFO_BLOCK_SIG_LEN];
  52
  53   ///
  54   /// UUID identifying this BTT instance.
  55   ///
  56   GUID Uuid;
  57
  58   ///
  59   /// UUID of containing namespace.
  60   ///
  61   GUID ParentUuid;
  62
  63   ///
  64   /// Attributes of this BTT Info Block.
  65   ///
  66   UINT32   Flags;
  67
  68   ///
  69   /// Major version number. Currently at version 2.
  70   ///
  71   UINT16   Major;
  72
  73   ///
  74   /// Minor version number. Currently at version 0.
  75   ///
  76   UINT16   Minor;
  77
  78   ///
  79   /// Advertised LBA size in bytes. I/O requests shall be in this size chunk.
  80   ///
  81   UINT32   ExternalLbaSize;
  82
  83   ///
  84   /// Advertised number of LBAs in this arena.
  85   ///
  86   UINT32   ExternalNLba;
  87
  88   ///
  89   /// Internal LBA size shall be greater than or equal to ExternalLbaSize and shall not be smaller than 512 bytes.
  90   ///
  91   UINT32   InternalLbaSize;
  92
  93   ///
  94   /// Number of internal blocks in the arena data area.
  95   ///
  96   UINT32   InternalNLba;
  97
  98   ///
  99   /// Number of free blocks maintained for writes to this arena.
 100   ///
 101   UINT32   NFree;
 102
 103   ///
 104   /// The size of this info block in bytes.
 105   ///
 106   UINT32   InfoSize;
 107
 108   ///
 109   /// Offset of next arena, relative to the beginning of this arena.
 110   ///
 111   UINT64   NextOff;
 112
 113   ///
 114   /// Offset of the data area for this arena, relative to the beginning of this arena.
 115   ///
 116   UINT64   DataOff;
 117
 118   ///
 119   /// Offset of the map for this arena, relative to the beginning of this arena.
 120   ///
 121   UINT64   MapOff;
 122
 123   ///
 124   /// Offset of the flog for this arena, relative to the beginning of this arena.
 125   ///
 126   UINT64   FlogOff;
 127
 128   ///
 129   /// Offset of the backup copy of this arena's info block, relative to the beginning of this arena.
 130   ///
 131   UINT64   InfoOff;
 132
 133   ///
 134   /// Shall be zero.
 135   ///
 136   CHAR8    Unused[EFI_BTT_INFO_UNUSED_LEN];
 137
 138   ///
 139   /// 64-bit Fletcher64 checksum of all fields.
 140   ///
 141   UINT64   Checksum;
 142 } EFI_BTT_INFO_BLOCK;
 143
 144 ///
 145 /// BTT Map entry maps an LBA that indexes into the arena, to its actual location.
 146 ///
 147 typedef struct _EFI_BTT_MAP_ENTRY {
 148   ///
 149   /// Post-map LBA number (block number in this arena's data area)
 150   ///
 151   UINT32 PostMapLba : 30;
 152
 153   ///
 154   /// When set and Zero is not set, reads on this block return an error.
 155   /// When set and Zero is set, indicate a map entry in its normal, non-error state.
 156   ///
 157   UINT32 Error : 1;
 158
 159   ///
 160   /// When set and Error is not set, reads on this block return a full block of zeros.
 161   /// When set and Error is set, indicate a map entry in its normal, non-error state.
 162   ///
 163   UINT32 Zero : 1;
 164 } EFI_BTT_MAP_ENTRY;
 165
 166 ///
 167 /// Alignment of each flog structure
 168 ///
 169 #define EFI_BTT_FLOG_ENTRY_ALIGNMENT 64
 170
 171 ///
 172 /// The BTT Flog is both a free list and a log.
 173 /// The Flog size is determined by the EFI_BTT_INFO_BLOCK.NFree which determines how many of these flog
 174 /// entries there are.
 175 /// The Flog location is the highest aligned address in the arena after space for the backup info block.
 176 ///
 177 typedef struct _EFI_BTT_FLOG {
 178   ///
 179   /// Last pre-map LBA written using this flog entry.
 180   ///
 181   UINT32 Lba0;
 182
 183   ///
 184   /// Old post-map LBA.
 185   ///
 186   UINT32 OldMap0;
 187
 188   ///
 189   /// New post-map LBA.
 190   ///
 191   UINT32 NewMap0;
 192
 193   ///
 194   /// The Seq0 field in each flog entry is used to determine which set of fields is newer between the two sets
 195   /// (Lba0, OldMap0, NewMpa0, Seq0 vs Lba1, Oldmap1, NewMap1, Seq1).
 196   ///
 197   UINT32 Seq0;
 198
 199   ///
 200   /// Alternate lba entry.
 201   ///
 202   UINT32 Lba1;
 203
 204   ///
 205   /// Alternate old entry.
 206   ///
 207   UINT32 OldMap1;
 208
 209   ///
 210   /// Alternate new entry.
 211   ///
 212   UINT32 NewMap1;
 213
 214   ///
 215   /// Alternate Seq entry.
 216   ///
 217   UINT32 Seq1;
 218 } EFI_BTT_FLOG;
 219
 220 extern GUID gEfiBttAbstractionGuid;
 221
 222 #endif //_BTT_H_