/*

 * 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