/*
 * 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/vdo-releases/aluminum/src/c++/vdo/base/blockMap.h#4 $
 */

#ifndef BLOCK_MAP_H
#define BLOCK_MAP_H

#include "adminState.h"
#include "blockMapEntry.h"
#include "completion.h"
#include "fixedLayout.h"
#include "statistics.h"
#include "types.h"

/**
 * Create a block map.
 *
 * @param [in]  logicalBlocks    The number of logical blocks for the VDO
 * @param [in]  threadConfig     The thread configuration of the VDO
 * @param [in]  flatPageCount    The number of flat pages
 * @param [in]  rootOrigin       The absolute PBN of the first root page
 * @param [in]  rootCount        The number of tree roots
 * @param [out] mapPtr           The pointer to hold the new block map
 *
 * @return VDO_SUCCESS or an error code
 **/
int makeBlockMap(BlockCount           logicalBlocks,
                 const ThreadConfig  *threadConfig,
                 BlockCount           flatPageCount,
                 PhysicalBlockNumber  rootOrigin,
                 BlockCount           rootCount,
                 BlockMap           **mapPtr)
  __attribute__((warn_unused_result));

/**
 * Quiesce all block map I/O, possibly writing out all dirty metadata.
 *
 * @param map        The block map to drain
 * @param operation  The type of drain to perform
 * @param parent     The completion to notify when the drain is complete
 **/
void drainBlockMap(BlockMap       *map,
                   AdminStateCode  operation,
                   VDOCompletion  *parent);

/**
 * Resume I/O for a quiescent block map.
 *
 * @param map     The block map to resume
 * @param parent  The completion to notify when the resume is complete
 **/
void resumeBlockMap(BlockMap *map, VDOCompletion *parent);

/**
 * Prepare to grow the block map by allocating an expanded collection of trees.
 *
 * @param map               The block map to grow
 * @param newLogicalBlocks  The new logical size of the VDO
 *
 * @return VDO_SUCCESS or an error
 **/
int prepareToGrowBlockMap(BlockMap *map, BlockCount newLogicalBlocks)
  __attribute__((warn_unused_result));

/**
 * Get the logical size to which this block map is prepared to grow.
 *
 * @param map  The block map
 *
 * @return The new number of entries the block map will be grown to or 0 if
 *         the block map is not prepared to grow
 **/
BlockCount getNewEntryCount(BlockMap *map)
  __attribute__((warn_unused_result));

/**
 * Grow a block map on which prepareToGrowBlockMap() has already been called.
 *
 * @param map     The block map to grow
 * @param parent  The object to notify when the growth is complete
 **/
void growBlockMap(BlockMap *map, VDOCompletion *parent);

/**
 * Abandon any preparations which were made to grow this block map.
 *
 * @param map  The map which won't be grown
 **/
void abandonBlockMapGrowth(BlockMap *map);

/**
 * Decode the state of a block map saved in a buffer, without creating page
 * caches.
 *
 * @param [in]  buffer         A buffer containing the super block state
 * @param [in]  logicalBlocks  The number of logical blocks for the VDO
 * @param [in]  threadConfig   The thread configuration of the VDO
 * @param [out] mapPtr         The pointer to hold the new block map
 *
 * @return VDO_SUCCESS or an error code
 **/
int decodeBlockMap(Buffer              *buffer,
                   BlockCount           logicalBlocks,
                   const ThreadConfig  *threadConfig,
                   BlockMap           **mapPtr)
  __attribute__((warn_unused_result));

/**
 * Create a block map from the saved state of a Sodium block map, and do any
 * necessary upgrade work.
 *
 * @param [in]  buffer         A buffer containing the super block state
 * @param [in]  logicalBlocks  The number of logical blocks for the VDO
 * @param [in]  threadConfig   The thread configuration of the VDO
 * @param [out] mapPtr         The pointer to hold the new block map
 *
 * @return VDO_SUCCESS or an error code
 **/
int decodeSodiumBlockMap(Buffer              *buffer,
                         BlockCount           logicalBlocks,
                         const ThreadConfig  *threadConfig,
                         BlockMap           **mapPtr)
  __attribute__((warn_unused_result));

/**
 * Allocate the page caches for a block map.
 *
 * @param map               The block map needing caches.
 * @param layer             The physical layer for the cache
 * @param readOnlyNotifier  The read only mode context
 * @param journal           The recovery journal (may be NULL)
 * @param nonce             The nonce to distinguish initialized pages
 * @param cacheSize         The block map cache size, in pages
 * @param maximumAge        The number of journal blocks before a dirtied page
 *                          is considered old and must be written out
 *
 * @return VDO_SUCCESS or an error code
 **/
int makeBlockMapCaches(BlockMap         *map,
                       PhysicalLayer    *layer,
                       ReadOnlyNotifier *readOnlyNotifier,
                       RecoveryJournal  *journal,
                       Nonce             nonce,
                       PageCount         cacheSize,
                       BlockCount        maximumAge)
  __attribute__((warn_unused_result));

/**
 * Free a block map and null out the reference to it.
 *
 * @param mapPtr  A pointer to the block map to free
 **/
void freeBlockMap(BlockMap **mapPtr);

/**
 * Get the size of the encoded state of a block map.
 *
 * @return The encoded size of the map's state
 **/
size_t getBlockMapEncodedSize(void)
  __attribute__((warn_unused_result));

/**
 * Encode the state of a block map into a buffer.
 *
 * @param map     The block map to encode
 * @param buffer  The buffer to encode into
 *
 * @return UDS_SUCCESS or an error
 **/
int encodeBlockMap(const BlockMap *map, Buffer *buffer)
  __attribute__((warn_unused_result));

/**
 * Obtain any necessary state from the recovery journal that is needed for
 * normal block map operation.
 *
 * @param map      The map in question
 * @param journal  The journal to initialize from
 **/
void initializeBlockMapFromJournal(BlockMap *map, RecoveryJournal *journal);

/**
 * Get the portion of the block map for a given logical zone.
 *
 * @param map         The map
 * @param zoneNumber  The number of the zone
 *
 * @return The requested block map zone
 **/
BlockMapZone *getBlockMapZone(BlockMap *map, ZoneCount zoneNumber)
  __attribute__((warn_unused_result));

/**
 * Compute the logical zone on which the entry for a DataVIO
 * resides
 *
 * @param dataVIO  The DataVIO
 *
 * @return The logical zone number for the DataVIO
 **/
ZoneCount computeLogicalZone(DataVIO *dataVIO);

/**
 * Compute the block map slot in which the block map entry for a DataVIO
 * resides, and cache that number in the DataVIO.
 *
 * @param dataVIO  The DataVIO
 * @param callback The function to call once the slot has been found
 * @param threadID The thread on which to run the callback
 **/
void findBlockMapSlotAsync(DataVIO   *dataVIO,
                           VDOAction *callback,
                           ThreadID   threadID);

/**
 * Get number of block map pages at predetermined locations.
 *
 * @param map  The block map
 *
 * @return The number of fixed pages used by the map
 **/
PageCount getNumberOfFixedBlockMapPages(const BlockMap *map)
  __attribute__((warn_unused_result));

/**
 * Get number of block map entries.
 *
 * @param map  The block map
 *
 * @return The number of entries stored in the map
 **/
BlockCount getNumberOfBlockMapEntries(const BlockMap *map)
  __attribute__((warn_unused_result));

/**
 * Notify the block map that the recovery journal has finished a new block.
 * This method must be called from the journal zone thread.
 *
 * @param map                  The block map
 * @param recoveryBlockNumber  The sequence number of the finished recovery
 *                             journal block
 **/
void advanceBlockMapEra(BlockMap *map, SequenceNumber recoveryBlockNumber);

/**
 * Get the block number of the physical block containing the data for the
 * specified logical block number. All blocks are mapped to physical block
 * zero by default, which is conventionally the zero block.
 *
 * @param dataVIO  The DataVIO of the block to map
 **/
void getMappedBlockAsync(DataVIO *dataVIO);

/**
 * Associate the logical block number for a block represented by a DataVIO
 * with the physical block number in its newMapped field.
 *
 * @param dataVIO  The DataVIO of the block to map
 **/
void putMappedBlockAsync(DataVIO *dataVIO);

/**
 * Get the stats for the block map page cache.
 *
 * @param map  The block map containing the cache
 *
 * @return The block map statistics
 **/
BlockMapStatistics getBlockMapStatistics(BlockMap *map)
  __attribute__((warn_unused_result));

#endif // BLOCK_MAP_H