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