/*
 * 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/vdoLayout.h#2 $
 */

/**
 * VDOLayout is an object which manages the layout of a VDO. It wraps
 * FixedLayout, but includes the knowledge of exactly which partitions a VDO is
 * expected to have. Because of this knowledge, the VDOLayout validates the
 * FixedLayout encoded in the super block at load time, obviating the need for
 * subsequent error checking when other modules need to get partitions from the
 * layout.
 *
 * The VDOLayout also manages the preparation and growth of the layout for grow
 * physical operations.
 **/

#ifndef VDO_LAYOUT_H
#define VDO_LAYOUT_H

#include "fixedLayout.h"
#include "types.h"

/**
 * Make a VDO layout with the specified parameters.
 *
 * @param [in]  physicalBlocks  The number of physical blocks in the VDO
 * @param [in]  startingOffset  The starting offset of the layout
 * @param [in]  blockMapBlocks  The size of the block map partition
 * @param [in]  journalBlocks   The size of the journal partition
 * @param [in]  summaryBlocks   The size of the slab summary partition
 * @param [out] vdoLayoutPtr    A pointer to hold the new VDOLayout
 *
 * @return VDO_SUCCESS or an error
 **/
int makeVDOLayout(BlockCount            physicalBlocks,
                  PhysicalBlockNumber   startingOffset,
                  BlockCount            blockMapBlocks,
                  BlockCount            journalBlocks,
                  BlockCount            summaryBlocks,
                  VDOLayout           **vdoLayoutPtr)
  __attribute__((warn_unused_result));

/**
 * Decode a VDOLayout from a buffer.
 *
 * @param [in]  buffer        The buffer from which to decode
 * @param [out] vdoLayoutPtr  A pointer to hold the VDOLayout
 *
 * @return VDO_SUCCESS or an error
 **/
int decodeVDOLayout(Buffer *buffer, VDOLayout **vdoLayoutPtr)
  __attribute__((warn_unused_result));

/**
 * Free a VDOLayout and NULL out the reference to it.
 *
 * @param vdoLayoutPtr  The pointer to a VDOLayout to free
 **/
void freeVDOLayout(VDOLayout **vdoLayoutPtr);

/**
 * Get a partition from a VDOLayout. Because the layout's FixedLayout has
 * already been validated, this can not fail.
 *
 * @param vdoLayout  The VDOLayout from which to get the partition
 * @param id         The ID of the desired partition
 *
 * @return The requested partition
 **/
Partition *getVDOPartition(VDOLayout *vdoLayout, PartitionID id)
  __attribute__((warn_unused_result));

/**
 * Prepare the layout to be grown.
 *
 * @param vdoLayout          The layout to grow
 * @param oldPhysicalBlocks  The current size of the VDO
 * @param newPhysicalBlocks  The size to which the VDO will be grown
 * @param layer              The layer being grown
 *
 * @return VDO_SUCCESS or an error code
 **/
int prepareToGrowVDOLayout(VDOLayout     *vdoLayout,
                           BlockCount     oldPhysicalBlocks,
                           BlockCount     newPhysicalBlocks,
                           PhysicalLayer *layer)
  __attribute__((warn_unused_result));

/**
 * Get the size of the next layout.
 *
 * @param vdoLayout  The layout to check
 *
 * @return The size which was specified when the layout was prepared for growth
 *         or 0 if the layout is not prepared to grow
 **/
BlockCount getNextVDOLayoutSize(VDOLayout *vdoLayout)
  __attribute__((warn_unused_result));

/**
 * Get the size of the next block allocator partition.
 *
 * @param vdoLayout  The VDOLayout which has been prepared to grow
 *
 * @return The size of the block allocator partition in the next layout or 0
 *         if the layout is not prepared to grow
 **/
BlockCount getNextBlockAllocatorPartitionSize(VDOLayout *vdoLayout)
  __attribute__((warn_unused_result));

/**
 * Grow the layout by swapping in the prepared layout.
 *
 * @param vdoLayout  The layout to grow
 *
 * @return The new size of the VDO
 **/
BlockCount growVDOLayout(VDOLayout *vdoLayout)
  __attribute__((warn_unused_result));

/**
 * Revert the last growth attempt.
 *
 * @param vdoLayout  The layout to revert
 *
 * @return The reverted size (in blocks) of the VDO
 **/
BlockCount revertVDOLayout(VDOLayout *vdoLayout)
  __attribute__((warn_unused_result));

/**
 * Clean up any unused resources once an attempt to grow has completed.
 *
 * @param vdoLayout  The layout
 **/
void finishVDOLayoutGrowth(VDOLayout *vdoLayout);

/**
 * Copy a partition from the location specified in the current layout to that in
 * the next layout.
 *
 * @param layout       The VDOLayout which is prepared to grow
 * @param partitionID  The ID of the partition to copy
 * @param parent       The completion to notify when the copy is complete
 **/
void copyPartition(VDOLayout     *layout,
                   PartitionID    partitionID,
                   VDOCompletion *parent);

/**
 * Get the size of an encoded VDOLayout.
 *
 * @param vdoLayout  The VDOLayout
 *
 * @return The encoded size of the VDOLayout
 **/
size_t getVDOLayoutEncodedSize(const VDOLayout *vdoLayout)
  __attribute__((warn_unused_result));

/**
 * Encode a VDOLayout into a buffer.
 *
 * @param vdoLayout  The VDOLayout to encode
 * @param buffer     The buffer to encode into
 *
 * @return UDS_SUCCESS or an error
 **/
int encodeVDOLayout(const VDOLayout *vdoLayout, Buffer *buffer)
  __attribute__((warn_unused_result));

#endif // VDO_LAYOUT_H