/*

 * Copyright (c) 2020 Red Hat, Inc.

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or (at your option) any later version.

 * 

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 * 

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA

 * 02110-1301, USA. 

 *

 * $Id: //eng/uds-releases/jasper/src/uds/indexLayout.c#19 $

 */

#include "indexLayout.h"

#include "buffer.h"

#include "compiler.h"

#include "config.h"

#include "indexConfig.h"

#include "layoutRegion.h"

#include "logger.h"

#include "masterIndexOps.h"

#include "memoryAlloc.h"

#include "nonce.h"

#include "openChapter.h"

/*

 * Overall layout of an index on disk:

 *

 * The layout is divided into a number of fixed-size regions, the sizes of

 * which are computed when the index is created. Every header and region

 * begins on 4K block boundary. Save regions are further sub-divided into

 * regions of their own.

 *

 * Each region has a kind and an instance number. Some kinds only have one

 * instance and therefore use RL_SOLE_INSTANCE (-1) as the instance number.

 * The RL_KIND_INDEX uses instances to represent sub-indices, where used.

 * A save region can either hold a checkpoint or a clean shutdown (determined

 * by the type). The instances determine which available save slot is used.

 * The RL_KIND_MASTER_INDEX uses instances to record which zone is being saved.

 *

 *     +-+-+--------+--------+--------+-----+---  -+-+

 *     | | |   I N D E X   0      101, 0    | ...  | |

 *     |H|C+--------+--------+--------+-----+---  -+S|

 *     |D|f| Volume | Save   | Save   |     |      |e|

 *     |R|g| Region | Region | Region | ... | ...  |a|

 *     | | | 201 -1 | 202  0 | 202  1 |     |      |l|

 *     +-+-+--------+--------+--------+-----+---  -+-+

 *

 * The header contains the encoded regional layout table as well as

 * the saved index configuration record. The sub-index regions and their

 * subdivisions are maintained in the same table.

 *

 * There are at least two save regions per sub-index to preserve the old

 * state should the saving of a state be incomplete. They are used in

 * a round-robin fashion.

 *

 * Anatomy of a save region:

 *

 *     +-+-----+------+------+-----+   -+-----+

 *     |H| IPM | MI   | MI   |     |    | OC  |

 *     |D|     | zone | zone | ... |    |     |

 *     |R| 301 | 302  | 302  |     |    | 303 |

 *     | | -1  | 0    | 1    |     |    | -1  |

 *     +-+-----+------+------+-----+   -+-----+

 *

 * Every region header has a type (and version). In save regions,

 * the open chapter only appears in RL_TYPE_SAVE not RL_TYPE_CHECKPOINT,

 * although the same space is reserved for both.

 *

 * The header contains the encoded regional layout table as well as the

 * index state record for that save or checkpoint. Each save or checkpoint

 * has a unique generation number and nonce which is used to seed the

 * checksums of those regions.

 */

typedef struct indexSaveData_v1 {

  uint64_t timestamp;           // ms since epoch...

  uint64_t nonce;

  uint32_t version;             // 1

  uint32_t unused__; 

} IndexSaveData;

typedef struct indexSaveLayout {

  LayoutRegion     indexSave;

  LayoutRegion     header;

  unsigned int     numZones;

  LayoutRegion     indexPageMap;

  LayoutRegion     freeSpace;

  LayoutRegion    *masterIndexZones;

  LayoutRegion    *openChapter;

  IndexSaveType    saveType;

  IndexSaveData    saveData;

  Buffer          *indexStateBuffer;

  bool             read;

  bool             written;

} IndexSaveLayout;

typedef struct subIndexLayout {

  LayoutRegion     subIndex;

  uint64_t         nonce;

  LayoutRegion     volume;

  IndexSaveLayout *saves;

} SubIndexLayout;

typedef struct superBlockData_v1 {

  byte     magicLabel[32];

  byte     nonceInfo[32];

  uint64_t nonce;

  uint32_t version;             // 2

  uint32_t blockSize;           // for verification

  uint16_t numIndexes;          // 1

  uint16_t maxSaves;

  uint64_t openChapterBlocks;

  uint64_t pageMapBlocks;

} SuperBlockData;

struct indexLayout {

  IOFactory            *factory;

  off_t                 offset;

  struct index_version  indexVersion;

  SuperBlockData        super;

  LayoutRegion          header;

  LayoutRegion          config;

  SubIndexLayout        index;

  LayoutRegion          seal;

  uint64_t              totalBlocks;

  int                   refCount;

};

/**

 * Structure used to compute single file layout sizes.

 *

 * Note that the masterIndexBlocks represent all zones and are sized for

 * the maximum number of blocks that would be needed regardless of the number

 * of zones (up to the maximum value) that are used at run time.

 *

 * Similarly, the number of saves is sized for the minimum safe value

 * assuming checkpointing is enabled, since that is also a run-time parameter.

 **/

typedef struct saveLayoutSizes {

  Configuration config;                 // this is a captive copy

  Geometry      geometry;               // this is a captive copy

  unsigned int  numSaves;               // per sub-index

  size_t        blockSize;              // in bytes

  uint64_t      volumeBlocks;           // per sub-index

  uint64_t      masterIndexBlocks;      // per save

  uint64_t      pageMapBlocks;          // per save

  uint64_t      openChapterBlocks;      // per save

  uint64_t      saveBlocks;             // per sub-index

  uint64_t      subIndexBlocks;         // per sub-index

  uint64_t      totalBlocks;            // for whole layout

} SaveLayoutSizes;

enum {

  INDEX_STATE_BUFFER_SIZE =  512,

  MAX_SAVES               =    5,

};

static const byte SINGLE_FILE_MAGIC_1[32] = "*ALBIREO*SINGLE*FILE*LAYOUT*001*";

enum {

  SINGLE_FILE_MAGIC_1_LENGTH = sizeof(SINGLE_FILE_MAGIC_1),

};

static int reconstituteSingleFileLayout(IndexLayout    *layout,

                                        SuperBlockData *super,

                                        RegionTable    *table,

                                        uint64_t        firstBlock)

  __attribute__((warn_unused_result));

static int writeIndexSaveLayout(IndexLayout *layout, IndexSaveLayout *isl)

  __attribute__((warn_unused_result));

/*****************************************************************************/

static INLINE uint64_t blockCount(uint64_t bytes, uint32_t blockSize)

{

  uint64_t blocks = bytes / blockSize;

  if (bytes % blockSize > 0) {

    ++blocks;

  }

  return blocks;

}

/*****************************************************************************/

__attribute__((warn_unused_result))

static int computeSizes(SaveLayoutSizes        *sls,

                        const UdsConfiguration  config,

                        size_t                  blockSize,

                        unsigned int            numCheckpoints)

{

  if (config->bytesPerPage % blockSize != 0) {

    return logErrorWithStringError(UDS_INCORRECT_ALIGNMENT,

                                   "page size not a multiple of block size");

  }

  Configuration *cfg = NULL;

  int result = makeConfiguration(config, &cfg;;

  if (result != UDS_SUCCESS) {

    return logErrorWithStringError(result, "cannot compute layout size");

  }

  memset(sls, 0, sizeof(*sls));

  // internalize the configuration and geometry...

  sls->geometry        = *cfg->geometry;

  sls->config          = *cfg;

  sls->config.geometry = &sls->geometry;

  freeConfiguration(cfg);

  sls->numSaves         = 2 + numCheckpoints;

  sls->blockSize        = blockSize;

  sls->volumeBlocks     = sls->geometry.bytesPerVolume / blockSize;

  result = computeMasterIndexSaveBlocks(&sls->config, blockSize,

                                        &sls->masterIndexBlocks);

  if (result != UDS_SUCCESS) {

    return logErrorWithStringError(result, "cannot compute index save size");

  }

  sls->pageMapBlocks =

    blockCount(computeIndexPageMapSaveSize(&sls->geometry), blockSize);

  sls->openChapterBlocks =

    blockCount(computeSavedOpenChapterSize(&sls->geometry), blockSize);

  sls->saveBlocks = 1 + (sls->masterIndexBlocks +

                         sls->pageMapBlocks + sls->openChapterBlocks);

  sls->subIndexBlocks = sls->volumeBlocks + (sls->numSaves * sls->saveBlocks);

  sls->totalBlocks = 3 + sls->subIndexBlocks;

  return UDS_SUCCESS;

}

/*****************************************************************************/

int udsComputeIndexSize(const UdsConfiguration  config,

                        unsigned int            numCheckpoints,

                        uint64_t               *indexSize)

{

  SaveLayoutSizes sizes;

  int result = computeSizes(&sizes, config, UDS_BLOCK_SIZE, numCheckpoints);

  if (result != UDS_SUCCESS) {

    return result;

  }

  if (indexSize != NULL) {

    *indexSize = sizes.totalBlocks * sizes.blockSize;

  }

  return UDS_SUCCESS;

}

/*****************************************************************************/

__attribute__((warn_unused_result))

static int openLayoutReader(IndexLayout     *layout,

                            LayoutRegion    *lr,

                            BufferedReader **readerPtr)

{

  off_t start = lr->startBlock * layout->super.blockSize;

  size_t size = lr->numBlocks * layout->super.blockSize;

  return openBufferedReader(layout->factory, start, size, readerPtr);

}

/*****************************************************************************/

__attribute__((warn_unused_result))

static int openLayoutWriter(IndexLayout     *layout,

                            LayoutRegion    *lr,

                            BufferedWriter **writerPtr)

{

  off_t start = lr->startBlock * layout->super.blockSize;

  size_t size = lr->numBlocks * layout->super.blockSize;

  return openBufferedWriter(layout->factory, start, size, writerPtr);

}

/*****************************************************************************/

__attribute__((warn_unused_result))

static int decodeIndexSaveData(Buffer *buffer, IndexSaveData *saveData)

{

  int result = getUInt64LEFromBuffer(buffer, &saveData->timestamp);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt64LEFromBuffer(buffer, &saveData->nonce);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt32LEFromBuffer(buffer, &saveData->version);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt32LEFromBuffer(buffer, &saveData->unused__);

  if (result != UDS_SUCCESS) {

    return result;

  }

  // The unused padding has to be zeroed for correct nonce calculation

  if (saveData->unused__ != 0) {

    return UDS_CORRUPT_COMPONENT;

  }

  result = ASSERT_LOG_ONLY(contentLength(buffer) == 0,

                           "%zu bytes decoded of %zu expected",

                           bufferLength(buffer), sizeof(*saveData));

  if (result != UDS_SUCCESS) {

    return UDS_CORRUPT_COMPONENT;

  }

  return result;

}

/*****************************************************************************/

__attribute__((warn_unused_result))

static int decodeRegionHeader(Buffer *buffer, RegionHeader *header)

{

  int result = getUInt64LEFromBuffer(buffer, &header->magic);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt64LEFromBuffer(buffer, &header->regionBlocks);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt16LEFromBuffer(buffer, &header->type);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt16LEFromBuffer(buffer, &header->version);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt16LEFromBuffer(buffer, &header->numRegions);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt16LEFromBuffer(buffer, &header->payload);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = ASSERT_LOG_ONLY(contentLength(buffer) == 0,

                           "%zu bytes decoded of %zu expected",

                           bufferLength(buffer), sizeof(*header));

  if (result != UDS_SUCCESS) {

    return UDS_CORRUPT_COMPONENT;

  }

  return result;

}

/*****************************************************************************/

__attribute__((warn_unused_result))

static int decodeLayoutRegion(Buffer *buffer, LayoutRegion *region)

{

  size_t cl1 = contentLength(buffer);

  int result = getUInt64LEFromBuffer(buffer, &region->startBlock);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt64LEFromBuffer(buffer, &region->numBlocks);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt32LEFromBuffer(buffer, &region->checksum);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt16LEFromBuffer(buffer, &region->kind);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt16LEFromBuffer(buffer, &region->instance);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = ASSERT_LOG_ONLY(cl1 - contentLength(buffer) == sizeof(*region),

                           "%zu bytes decoded, of %zu expected",

                           cl1 - contentLength(buffer), sizeof(*region));

  if (result != UDS_SUCCESS) {

    return UDS_CORRUPT_COMPONENT;

  }

  return result;

}

/*****************************************************************************/

__attribute__((warn_unused_result))

static int loadRegionTable(BufferedReader *reader, RegionTable **tablePtr)

{

  Buffer *buffer;

  int result = makeBuffer(sizeof(RegionHeader), &buffer);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = readFromBufferedReader(reader, getBufferContents(buffer),

                                  bufferLength(buffer));

  if (result != UDS_SUCCESS) {

    freeBuffer(&buffer);

    return logErrorWithStringError(result, "cannot read region table header");

  }

  result = resetBufferEnd(buffer, bufferLength(buffer));

  if (result != UDS_SUCCESS) {

    freeBuffer(&buffer);

    return result;

  }

  RegionHeader header;

  result = decodeRegionHeader(buffer, &header);

  freeBuffer(&buffer);

  if (result != UDS_SUCCESS) {

    return result;

  }

  if (header.magic != REGION_MAGIC) {

    return UDS_NO_INDEX;

  }

  if (header.version != 1) {

    return logErrorWithStringError(UDS_UNSUPPORTED_VERSION,

                                   "unknown region table version %" PRIu16,

                                   header.version);

  }

  RegionTable *table;

  result = ALLOCATE_EXTENDED(RegionTable, header.numRegions, LayoutRegion,

                             "single file layout region table", &table);

  if (result != UDS_SUCCESS) {

    return result;

  }

  table->header = header;

  result = makeBuffer(header.numRegions * sizeof(LayoutRegion), &buffer);

  if (result != UDS_SUCCESS) {

    FREE(table);

    return result;

  }

  result = readFromBufferedReader(reader, getBufferContents(buffer),

                                  bufferLength(buffer));

  if (result != UDS_SUCCESS) {

    FREE(table);

    freeBuffer(&buffer);

    return logErrorWithStringError(UDS_CORRUPT_COMPONENT,

                                   "cannot read region table layouts");

  }

  result = resetBufferEnd(buffer, bufferLength(buffer));

  if (result != UDS_SUCCESS) {

    FREE(table);

    freeBuffer(&buffer);

    return result;

  }

  unsigned int i;

  for (i = 0; i < header.numRegions; i++){

    result = decodeLayoutRegion(buffer, &table->regions[i]);

    if (result != UDS_SUCCESS) {

      FREE(table);

      freeBuffer(&buffer);

      return result;

    }

  }

  freeBuffer(&buffer);

  *tablePtr = table;

  return UDS_SUCCESS;

}

/*****************************************************************************/

__attribute__((warn_unused_result))

static int decodeSuperBlockData(Buffer *buffer, SuperBlockData *super)

{

  int result = getBytesFromBuffer(buffer, 32, super->magicLabel);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getBytesFromBuffer(buffer, 32, super->nonceInfo);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt64LEFromBuffer(buffer, &super->nonce);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt32LEFromBuffer(buffer, &super->version);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt32LEFromBuffer(buffer, &super->blockSize);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt16LEFromBuffer(buffer, &super->numIndexes);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt16LEFromBuffer(buffer, &super->maxSaves);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = skipForward(buffer, 4);      // aligment

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt64LEFromBuffer(buffer, &super->openChapterBlocks);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = getUInt64LEFromBuffer(buffer, &super->pageMapBlocks);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = ASSERT_LOG_ONLY(contentLength(buffer) == 0,

                           "%zu bytes decoded of %zu expected",

                           bufferLength(buffer), sizeof(*super));

  if (result != UDS_SUCCESS) {

    return UDS_CORRUPT_COMPONENT;

  }

  return result;

}

/*****************************************************************************/

__attribute__((warn_unused_result))

static int readSuperBlockData(BufferedReader *reader,

                              SuperBlockData *super,

                              size_t          savedSize)

{

  if (savedSize != sizeof(SuperBlockData)) {

    return logErrorWithStringError(UDS_CORRUPT_COMPONENT,

                                   "unexpected super block data size %zu",

                                   savedSize);

  }

  if (sizeof(super->magicLabel) != SINGLE_FILE_MAGIC_1_LENGTH) {

    return logErrorWithStringError(UDS_CORRUPT_COMPONENT,

                                   "super block magic label size incorrect");

  }

  Buffer *buffer;

  int result = makeBuffer(savedSize, &buffer);

  if (result != UDS_SUCCESS) {

    return result;

  }

  result = readFromBufferedReader(reader, getBufferContents(buffer),

                                  bufferLength(buffer));

  if (result != UDS_SUCCESS) {

    freeBuffer(&buffer);

    return logErrorWithStringError(result, "cannot read region table header");

  }

  result = resetBufferEnd(buffer, bufferLength(buffer));

  if (result != UDS_SUCCESS) {

    freeBuffer(&buffer);

    return result;

  }

  result = decodeSuperBlockData(buffer, super);

  freeBuffer(&buffer);

  if (result != UDS_SUCCESS) {

    return logErrorWithStringError(result, "cannot read super block data");

  }

  if (memcmp(super->magicLabel, SINGLE_FILE_MAGIC_1,

             SINGLE_FILE_MAGIC_1_LENGTH) != 0) {

    return logErrorWithStringError(UDS_CORRUPT_COMPONENT,

                                   "unknown superblock magic label");

  }

  if ((super->version < SUPER_VERSION_MINIMUM)

      || (super->version > SUPER_VERSION_MAXIMUM)) {

    return logErrorWithStringError(UDS_UNSUPPORTED_VERSION,

                                   "unknown superblock version number %"

                                   PRIu32,

                                   super->version);

  }

  // We dropped the usage of multiple subindices before we ever ran UDS code in

  // the kernel.  We do not have code that will handle multiple subindices.

  if (super->numIndexes != 1) {

    return logErrorWithStringError(UDS_CORRUPT_COMPONENT,

                                   "invalid subindex count %" PRIu32,

                                   super->numIndexes);

  }

  if (generateMasterNonce(super->nonceInfo, sizeof(super->nonceInfo)) !=

      super->nonce)

  {

    return logErrorWithStringError(UDS_CORRUPT_COMPONENT,

                                   "inconsistent superblock nonce");

  }

  return UDS_SUCCESS;

}

/*****************************************************************************/

__attribute__((warn_unused_result))

static int allocateSingleFileParts(IndexLayout    *layout,

                                   SuperBlockData *super)

{

  int result = ALLOCATE(super->maxSaves, IndexSaveLayout, __func__,

                        &layout->index.saves);

  if (result != UDS_SUCCESS) {

    return result;

  }

  return UDS_SUCCESS;

}

/*****************************************************************************/

__attribute__((warn_unused_result))

static int loadSuperBlock(IndexLayout    *layout,

                          size_t          blockSize,

                          uint64_t        firstBlock,

                          BufferedReader *reader)

{

  RegionTable *table = NULL;

  int result = loadRegionTable(reader, &table);

  if (result != UDS_SUCCESS) {

    return result;

  }

  if (table->header.type != RH_TYPE_SUPER) {

    FREE(table);

    return logErrorWithStringError(UDS_CORRUPT_COMPONENT,

                                   "not a superblock region table");

  }

  SuperBlockData superBlockData;

  result = readSuperBlockData(reader, &superBlockData, table->header.payload);

  if (result != UDS_SUCCESS) {

    FREE(table);

    return logErrorWithStringError(result, "unknown superblock format");

  }

  if (superBlockData.blockSize != blockSize) {

    FREE(table);

    return logErrorWithStringError(UDS_WRONG_INDEX_CONFIG,

                                   "superblock saved blockSize %" PRIu32

                                   " differs from supplied blockSize %zu",

                                   superBlockData.blockSize, blockSize);

  }

  initializeIndexVersion(&layout->indexVersion, superBlockData.version);

  result = allocateSingleFileParts(layout, &superBlockData);

  if (result != UDS_SUCCESS) {

    FREE(table);

    return result;

  }

  result = reconstituteSingleFileLayout(layout, &superBlockData, table,

                                        firstBlock);

  FREE(table);

  return result;

}

/*****************************************************************************/

__attribute__((warn_unused_result))

static int readIndexSaveData(BufferedReader  *reader,

                             IndexSaveData   *saveData,

                             size_t           savedSize,

                             Buffer         **bufferPtr)

{

  int result = UDS_SUCCESS;

  if (savedSize == 0) {

    memset(saveData, 0, sizeof(*saveData));

  } else {

    if (savedSize < sizeof(IndexSaveData)) {

      return logErrorWithStringError(UDS_CORRUPT_COMPONENT,

                                     "unexpected index save data size %zu",

                                     savedSize);

    }

    Buffer *buffer;

    result = makeBuffer(sizeof(*saveData), &buffer);

    if (result != UDS_SUCCESS) {

      return result;

    }

    result = readFromBufferedReader(reader, getBufferContents(buffer),

                                    bufferLength(buffer));

    if (result != UDS_SUCCESS) {

      freeBuffer(&buffer);

      return logErrorWithStringError(result, "cannot read index save data");

    }

    result = resetBufferEnd(buffer, bufferLength(buffer));

    if (result != UDS_SUCCESS) {

      freeBuffer(&buffer);

      return result;

    }

    result = decodeIndexSaveData(buffer, saveData);

    freeBuffer(&buffer);

    if (result != UDS_SUCCESS) {

      return result;

    }

    savedSize -= sizeof(IndexSaveData);

    if (saveData->version > 1) {

      return logErrorWithStringError(UDS_UNSUPPORTED_VERSION,

                                     "unkown index save verion number %"

                                     PRIu32,

                                     saveData->version);

    }

    if (savedSize > INDEX_STATE_BUFFER_SIZE) {

      return logErrorWithStringError(UDS_CORRUPT_COMPONENT,

                                     "unexpected index state buffer size %zu",

                                     savedSize);

    }

  }

  Buffer *buffer = NULL;

  if (saveData->version != 0) {

    result = makeBuffer(INDEX_STATE_BUFFER_SIZE, &buffer);

    if (result != UDS_SUCCESS) {

      return result;

    }

    if (savedSize > 0) {

      result = readFromBufferedReader(reader, getBufferContents(buffer),

                                      savedSize);

      if (result != UDS_SUCCESS) {

        freeBuffer(&buffer);

        return result;

      }

      result = resetBufferEnd(buffer, savedSize);

      if (result != UDS_SUCCESS) {

        freeBuffer(&buffer);

        return result;

      }

    }

  }

  *bufferPtr = buffer;

  return UDS_SUCCESS;

}

/*****************************************************************************/

typedef struct {

  LayoutRegion  *nextRegion;

  LayoutRegion  *lastRegion;

  uint64_t       nextBlock;

  int            result;

} RegionIterator;

/*****************************************************************************/

__attribute__((format(printf, 2, 3)))

static void iterError(RegionIterator *iter, const char *fmt, ...)

{

  va_list args;

  va_start(args, fmt);

  int r = vLogWithStringError(LOG_ERR, UDS_UNEXPECTED_RESULT, fmt, args);

  va_end(args);

  if (iter->result == UDS_SUCCESS) {

    iter->result = r;

  }

}

/**

 * Set the next layout region in the layout according to a region table

 * iterator, unless the iterator already contains an error

 *

 * @param expect        whether to record an error or return false

 * @param lr            the layout region field to set

 * @param iter          the region iterator, which also holds the cumulative

 *                        result

 * @param numBlocks     if non-zero, the expected number of blocks

 * @param kind          the expected kind of the region

 * @param instance      the expected instance number of the region

 *

 * @return true if we meet expectations, false if we do not

 **/

static bool expectLayout(bool            expect,

                         LayoutRegion   *lr,

                         RegionIterator *iter,

                         uint64_t        numBlocks,

                         RegionKind      kind,

                         unsigned int    instance)

{

  if (iter->result != UDS_SUCCESS) {

    return false;

  }

  if (iter->nextRegion == iter->lastRegion) {

    if (expect) {

      iterError(iter, "ran out of layout regions in region table");

    }

    return false;

  }

  if (iter->nextRegion->startBlock != iter->nextBlock) {

    iterError(iter, "layout region not at expected offset");

    return false;

  }

  if (iter->nextRegion->kind != kind) {

    if (expect) {

      iterError(iter, "layout region has incorrect kind");

    }

    return false;

  }

  if (iter->nextRegion->instance != instance) {

    iterError(iter, "layout region has incorrect instance");

    return false;

  }

  if (numBlocks > 0 && iter->nextRegion->numBlocks != numBlocks) {

    iterError(iter, "layout region size is incorrect");

    return false;

  }

  if (lr != NULL) {

    *lr = *iter->nextRegion;

  }

  iter->nextBlock += iter->nextRegion->numBlocks;

  iter->nextRegion++;

  return true;

}

/*****************************************************************************/

static void setupLayout(LayoutRegion *lr,

                        uint64_t     *nextAddrPtr,

                        uint64_t      regionSize,

                        unsigned int  kind,

                        unsigned int  instance)

{

  *lr = (LayoutRegion) {

    .startBlock = *nextAddrPtr,

    .numBlocks  = regionSize,

    .checksum   = 0,

    .kind       = kind,

    .instance   = instance,

  };

  *nextAddrPtr += regionSize;

}

/*****************************************************************************/

static void populateIndexSaveLayout(IndexSaveLayout *isl,

                                    SuperBlockData  *super,

                                    unsigned int     numZones,

                                    IndexSaveType    saveType)

{

  uint64_t nextBlock = isl->indexSave.startBlock;

  setupLayout(&isl->header, &nextBlock, 1, RL_KIND_HEADER, RL_SOLE_INSTANCE);

  setupLayout(&isl->indexPageMap, &nextBlock, super->pageMapBlocks,

              RL_KIND_INDEX_PAGE_MAP, RL_SOLE_INSTANCE);

  uint64_t blocksAvail = (isl->indexSave.numBlocks -

                          (nextBlock - isl->indexSave.startBlock) -

                          super->openChapterBlocks);

  if (numZones > 0) {

    uint64_t miBlockCount = blocksAvail / numZones;

    unsigned int z;

    for (z = 0; z < numZones; ++z) {

      LayoutRegion *miz = &isl->masterIndexZones[z];

      setupLayout(miz, &nextBlock, miBlockCount, RL_KIND_MASTER_INDEX, z);

    }

  }

  if (saveType == IS_SAVE && isl->openChapter != NULL) {

    setupLayout(isl->openChapter, &nextBlock, super->openChapterBlocks,

                RL_KIND_OPEN_CHAPTER, RL_SOLE_INSTANCE);

  }

  setupLayout(&isl->freeSpace, &nextBlock,

              (isl->indexSave.numBlocks -

               (nextBlock - isl->indexSave.startBlock)),

               RL_KIND_SCRATCH, RL_SOLE_INSTANCE);

}

/*****************************************************************************/

__attribute__((warn_unused_result))

static int reconstructIndexSave(IndexSaveLayout *isl,

                                IndexSaveData   *saveData,

                                SuperBlockData  *super,

                                RegionTable     *table)

{

  isl->numZones = 0;

  isl->saveData = *saveData;

  isl->read     = false;

  isl->written  = false;

  if (table->header.type == RH_TYPE_SAVE) {

    isl->saveType = IS_SAVE;

  } else if (table->header.type == RH_TYPE_CHECKPOINT) {

    isl->saveType = IS_CHECKPOINT;