/*

 * 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/refCountsInternals.h#4 $

 */

#ifndef REF_COUNTS_INTERNALS_H

#define REF_COUNTS_INTERNALS_H

#include "refCounts.h"

#include "journalPoint.h"

#include "referenceBlock.h"

#include "slab.h"

#include "blockAllocatorInternals.h"

#include "waitQueue.h"

/**

 * Represents the possible status of a block.

 **/

typedef enum referenceStatus {

  RS_FREE,        // this block is free

  RS_SINGLE,      // this block is singly-referenced

  RS_SHARED,      // this block is shared

  RS_PROVISIONAL  // this block is provisionally allocated

} ReferenceStatus;

/**

 * The SearchCursor represents the saved position of a free block search.

 **/

typedef struct searchCursor {

  /** The reference block containing the current search index */

  ReferenceBlock      *block;

  /** The position at which to start searching for the next free counter */

  SlabBlockNumber      index;

  /** The position just past the last valid counter in the current block */

  SlabBlockNumber      endIndex;

  /** A pointer to the first reference block in the slab */

  ReferenceBlock      *firstBlock;

  /** A pointer to the last reference block in the slab */

  ReferenceBlock      *lastBlock;

} SearchCursor;

/*

 * RefCounts structure

 *

 * A reference count is maintained for each PhysicalBlockNumber.  The vast

 * majority of blocks have a very small reference count (usually 0 or 1).

 * For references less than or equal to MAXIMUM_REFS (254) the reference count

 * is stored in counters[pbn].

 *

 */

struct refCounts {

  /** The slab of this reference block */

  Slab                     *slab;

  /** The size of the counters array */

  uint32_t                  blockCount;

  /** The number of free blocks */

  uint32_t                  freeBlocks;

  /** The array of reference counts */

  ReferenceCount           *counters; // use ALLOCATE to align data ptr

  /** The saved block pointer and array indexes for the free block search */

  SearchCursor              searchCursor;

  /** A list of the dirty blocks waiting to be written out */

  WaitQueue                 dirtyBlocks;

  /** The number of blocks which are currently writing */

  size_t                    activeCount;

  /** A waiter object for updating the slab summary */

  Waiter                    slabSummaryWaiter;

  /** Whether slab summary update is in progress */

  bool                      updatingSlabSummary;

  /** The notifier for read-only mode */

  ReadOnlyNotifier         *readOnlyNotifier;

  /** The refcount statistics, shared by all refcounts in our physical zone */

  AtomicRefCountStatistics *statistics;

  /** The layer PBN for the first ReferenceBlock */

  PhysicalBlockNumber       origin;

  /** The latest slab journal entry this RefCounts has been updated with */

  JournalPoint              slabJournalPoint;

  /** The number of reference count blocks */

  uint32_t                  referenceBlockCount;

  /** reference count block array */

  ReferenceBlock            blocks[];

};

/**

 * Convert a reference count to a reference status.

 *

 * @param count The count to convert

 *

 * @return  The appropriate reference status

 **/

__attribute__((warn_unused_result))

ReferenceStatus referenceCountToStatus(ReferenceCount count);

/**

 * Convert a generic VDOCompletion to a RefCounts.

 *

 * @param completion The completion to convert

 *

 * @return The completion as a RefCounts

 **/

RefCounts *asRefCounts(VDOCompletion *completion)

  __attribute__((warn_unused_result));

/**

 * Get the reference block that covers the given block index (exposed for

 * testing).

 *

 * @param refCounts  The refcounts object

 * @param index      The block index

 **/

ReferenceBlock *getReferenceBlock(RefCounts *refCounts, SlabBlockNumber index)

  __attribute__((warn_unused_result));

/**

 * Find the reference counters for a given block (exposed for testing).

 *

 * @param block  The ReferenceBlock in question

 *

 * @return A pointer to the reference counters for this block

 **/

ReferenceCount *getReferenceCountersForBlock(ReferenceBlock *block)

  __attribute__((warn_unused_result));

/**

 * Copy data from a reference block to a buffer ready to be written out

 * (exposed for testing).

 *

 * @param block   The block to copy

 * @param buffer  The char buffer to fill with the packed block

 **/

void packReferenceBlock(ReferenceBlock *block, void *buffer);

/**

 * Get the reference status of a block. Exposed only for unit testing.

 *

 * @param [in]  refCounts   The refcounts object

 * @param [in]  pbn         The physical block number

 * @param [out] statusPtr   Where to put the status of the block

 *

 * @return                  A success or error code, specifically:

 *                          VDO_OUT_OF_RANGE if the pbn is out of range.

 **/

int getReferenceStatus(RefCounts           *refCounts,

                       PhysicalBlockNumber  pbn,

                       ReferenceStatus     *statusPtr)

  __attribute__((warn_unused_result));

/**

 * Find the first block with a reference count of zero in the specified range

 * of reference counter indexes. Exposed for unit testing.

 *

 * @param [in]  refCounts   The reference counters to scan

 * @param [in]  startIndex  The array index at which to start scanning

 *                          (included in the scan)

 * @param [in]  endIndex    The array index at which to stop scanning

 *                          (excluded from the scan)

 * @param [out] indexPtr    A pointer to hold the array index of the free block

 *

 * @return true if a free block was found in the specified range

 **/

bool findFreeBlock(const RefCounts *refCounts,

                   SlabBlockNumber  startIndex,

                   SlabBlockNumber  endIndex,

                   SlabBlockNumber *indexPtr)

  __attribute__((warn_unused_result));

/**

 * Request a RefCounts save its oldest dirty block asynchronously.

 *

 * @param refCounts  The RefCounts object to notify

 **/

void saveOldestReferenceBlock(RefCounts *refCounts);

/**

 * Reset all reference counts back to RS_FREE.

 *

 * @param refCounts   The reference counters to reset

 **/

void resetReferenceCounts(RefCounts *refCounts);

#endif // REF_COUNTS_INTERNALS_H