/*

 * 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/slabSummary.h#5 $

 */

#ifndef SLAB_SUMMARY_H

#define SLAB_SUMMARY_H

#include "completion.h"

#include "fixedLayout.h"

#include "slab.h"

#include "statistics.h"

#include "types.h"

#include "waitQueue.h"

/**

 * The SlabSummary provides hints during load and recovery about the state

 * of the slabs in order to avoid the need to read the slab journals in their

 * entirety before a VDO can come online.

 *

 * The information in the summary for each slab includes the rough number of

 * free blocks (which is used to prioritize scrubbing), the cleanliness of a

 * slab (so that clean slabs containing free space will be used on restart),

 * and the location of the tail block of the slab's journal.

 *

 * The SlabSummary has its own partition at the end of the volume which is

 * sized to allow for a complete copy of the summary for each of up to 16

 * physical zones.

 *

 * During resize, the SlabSummary moves its backing partition and is saved once

 * moved; the SlabSummary is not permitted to overwrite the previous recovery

 * journal space.

 *

 * The SlabSummary does not have its own version information, but relies on the

 * master version number.

 **/

/**

 * The offset of a slab journal tail block.

 **/

typedef uint8_t TailBlockOffset;

/**

 * A slab status is a very small structure for use in determining the ordering

 * of slabs in the scrubbing process.

 **/

typedef struct slabStatus {

  SlabCount slabNumber;

  bool      isClean;

  uint8_t   emptiness;

} SlabStatus;

/**

 * Returns the size on disk of the SlabSummary structure.

 *

 * @param blockSize  The block size of the physical layer

 *

 * @return the blocks required to store the SlabSummary on disk

 **/

BlockCount getSlabSummarySize(BlockSize blockSize)

__attribute__((warn_unused_result));

/**

 * Create a slab summary.

 *

 * @param [in]  layer                     The layer

 * @param [in]  partition                 The partition to hold the summary

 * @param [in]  threadConfig              The thread config of the VDO

 * @param [in]  slabSizeShift             The number of bits in the slab size

 * @param [in]  maximumFreeBlocksPerSlab  The maximum number of free blocks a

 *                                        slab can have

 * @param [in]  readOnlyNotifier          The context for entering read-only

 *                                        mode

 * @param [out] slabSummaryPtr            A pointer to hold the summary

 *

 * @return VDO_SUCCESS or an error

 **/

int makeSlabSummary(PhysicalLayer       *layer,

                    Partition           *partition,

                    const ThreadConfig  *threadConfig,

                    unsigned int         slabSizeShift,

                    BlockCount           maximumFreeBlocksPerSlab,

                    ReadOnlyNotifier    *readOnlyNotifier,

                    SlabSummary        **slabSummaryPtr)

  __attribute__((warn_unused_result));

/**

 * Destroy a SlabSummary and NULL out the reference to it.

 *

 * @param [in,out] slabSummaryPtr A pointer to the SlabSummary to free

 **/

void freeSlabSummary(SlabSummary **slabSummaryPtr);

/**

 * Get the portion of the slab summary for a specified zone.

 *

 * @param summary  The slab summary

 * @param zone     The zone

 *

 * @return The portion of the slab summary for the specified zone

 **/

SlabSummaryZone *getSummaryForZone(SlabSummary *summary, ZoneCount zone)

  __attribute__((warn_unused_result));

/**

 * Drain a zone of the slab summary.

 *

 * @param summaryZone  The zone to drain

 * @param operation    The type of drain to perform

 * @param parent       The object to notify when the suspend is complete

 **/

void drainSlabSummaryZone(SlabSummaryZone *summaryZone,

                          AdminStateCode   operation,

                          VDOCompletion   *parent);

/**

 * Resume a zone of the slab summary.

 *

 * @param summaryZone  The zone to resume

 * @param parent       The object to notify when the zone is resumed

 **/

void resumeSlabSummaryZone(SlabSummaryZone *summaryZone,

                           VDOCompletion   *parent);

/**

 * Update the entry for a slab.

 *

 * @param summaryZone     The SlabSummaryZone for the zone of the slab

 * @param waiter          The waiter that is updating the summary

 * @param slabNumber      The slab number to update

 * @param tailBlockOffset The offset of slab journal's tail block

 * @param loadRefCounts   Whether the refCounts must be loaded from the layer

 *                        on the next load

 * @param isClean         Whether the slab is clean

 * @param freeBlocks      The number of free blocks

 **/

void updateSlabSummaryEntry(SlabSummaryZone *summaryZone,

                            Waiter          *waiter,

                            SlabCount        slabNumber,

                            TailBlockOffset  tailBlockOffset,

                            bool             loadRefCounts,

                            bool             isClean,

                            BlockCount       freeBlocks);

/**

 * Get the stored tail block offset for a slab.

 *

 * @param summaryZone       The SlabSummaryZone to use

 * @param slabNumber        The slab number to get the offset for

 *

 * @return The tail block offset for the slab

 **/

TailBlockOffset getSummarizedTailBlockOffset(SlabSummaryZone *summaryZone,

                                             SlabCount        slabNumber)

  __attribute__((warn_unused_result));

/**

 * Whether refCounts must be loaded from the layer.

 *

 * @param summaryZone   The SlabSummaryZone to use

 * @param slabNumber    The slab number to get information for

 *

 * @return Whether refCounts must be loaded

 **/

bool mustLoadRefCounts(SlabSummaryZone *summaryZone, SlabCount slabNumber)

  __attribute__((warn_unused_result));

/**

 * Get the stored cleanliness information for a single slab.

 *

 * @param summaryZone   The SlabSummaryZone to use

 * @param slabNumber    The slab number to get information for

 *

 * @return Whether the slab is clean

 **/

bool getSummarizedCleanliness(SlabSummaryZone *summaryZone,

                              SlabCount        slabNumber)

  __attribute__((warn_unused_result));

/**

 * Get the stored emptiness information for a single slab.

 *

 * @param summaryZone    The SlabSummaryZone to use

 * @param slabNumber     The slab number to get information for

 *

 * @return An approximation to the free blocks in the slab

 **/

BlockCount getSummarizedFreeBlockCount(SlabSummaryZone *summaryZone,

                                       SlabCount        slabNumber)

  __attribute__((warn_unused_result));

/**

 * Get the stored RefCounts state information for a single slab. Used

 * in testing only.

 *

 * @param [in]  summaryZone     The SlabSummaryZone to use

 * @param [in]  slabNumber      The slab number to get information for

 * @param [out] freeBlockHint   The approximate number of free blocks

 * @param [out] isClean         Whether the slab is clean

 **/

void getSummarizedRefCountsState(SlabSummaryZone *summaryZone,

                                 SlabCount        slabNumber,

                                 size_t          *freeBlockHint,

                                 bool            *isClean);

/**

 * Get the stored slab statuses for all slabs in a zone.

 *

 * @param [in]     summaryZone   The SlabSummaryZone to use

 * @param [in]     slabCount     The number of slabs to fetch

 * @param [in,out] statuses      An array of SlabStatuses to populate

 **/

void getSummarizedSlabStatuses(SlabSummaryZone *summaryZone,

                               SlabCount        slabCount,

                               SlabStatus      *statuses);

/**

 * Set the origin of the slab summary relative to the physical layer.

 *

 * @param summary    The SlabSummary to update

 * @param partition  The slab summary partition

 **/

void setSlabSummaryOrigin(SlabSummary *summary, Partition *partition);

/**

 * Read in all the slab summary data from the slab summary partition,

 * combine all the previously used zones into a single zone, and then

 * write the combined summary back out to each possible zones' summary

 * region.

 *

 * @param summary         The summary to load

 * @param operation       The type of load to perform

 * @param zonesToCombine  The number of zones to be combined; if set to 0,

 *                        all of the summary will be initialized as new.

 * @param parent          The parent of this operation

 **/

void loadSlabSummary(SlabSummary    *summary,

                     AdminStateCode  operation,

                     ZoneCount       zonesToCombine,

                     VDOCompletion  *parent);

/**

 * Fetch the cumulative statistics for all slab summary zones in a summary.

 *

 * @param summary       The summary in question

 *

 * @return the cumulative slab summary statistics for the summary

 **/

SlabSummaryStatistics getSlabSummaryStatistics(const SlabSummary *summary)

  __attribute__((warn_unused_result));

#endif // SLAB_SUMMARY_H