/*

 * 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/vdoPageCacheInternals.h#8 $

 */

#ifndef VDO_PAGE_CACHE_INTERNALS_H

#define VDO_PAGE_CACHE_INTERNALS_H

#include "vdoPageCache.h"

#ifndef __KERNEL__

# include <stdint.h>

#endif

#include "blockMapInternals.h"

#include "completion.h"

#include "dirtyLists.h"

#include "intMap.h"

#include "physicalLayer.h"

#include "ringNode.h"

enum {

  MAX_PAGE_CONTEXT_SIZE = 8,

};

static const PhysicalBlockNumber NO_PAGE = 0xFFFFFFFFFFFFFFFF;

/**

 * A PageInfoNode is a ring node.

 **/

typedef RingNode PageInfoNode;

/**

 * The VDO Page Cache abstraction.

 **/

struct vdoPageCache {

  /** the physical layer to page to */

  PhysicalLayer             *layer;

  /** number of pages in cache */

  PageCount                  pageCount;

  /** function to call on page read */

  VDOPageReadFunction       *readHook;

  /** function to call on page write */

  VDOPageWriteFunction      *writeHook;

  /** number of pages to write in the current batch */

  PageCount                  pagesInBatch;

  /** Whether the VDO is doing a read-only rebuild */

  bool                       rebuilding;

  /** array of page information entries */

  PageInfo                  *infos;

  /** raw memory for pages */

  char                      *pages;

  /** cache last found page info */

  PageInfo                  *lastFound;

  /** map of page number to info */

  IntMap                    *pageMap;

  /** master LRU list (all infos) */

  PageInfoNode               lruList;

  /** dirty pages by period */

  DirtyLists                *dirtyLists;

  /** free page list (oldest first) */

  PageInfoNode               freeList;

  /** outgoing page list */

  PageInfoNode               outgoingList;

  /** number of read I/O operations pending */

  PageCount                  outstandingReads;

  /** number of write I/O operations pending */

  PageCount                  outstandingWrites;

  /** number of pages covered by the current flush */

  PageCount                  pagesInFlush;

  /** number of pages waiting to be included in the next flush */

  PageCount                  pagesToFlush;

  /** number of discards in progress */

  unsigned int               discardCount;

  /** how many VPCs waiting for free page */

  unsigned int               waiterCount;

  /** queue of waiters who want a free page */

  WaitQueue                  freeWaiters;

  /** statistics */

  AtomicPageCacheStatistics  stats;

  /** counter for pressure reports */

  uint32_t                   pressureReport;

  /** the block map zone to which this cache belongs */

  BlockMapZone              *zone;

};

/**

 * The state of a page buffer. If the page buffer is free no particular page is

 * bound to it, otherwise the page buffer is bound to particular page whose

 * absolute pbn is in the pbn field. If the page is resident or dirty the page

 * data is stable and may be accessed. Otherwise the page is in flight

 * (incoming or outgoing) and its data should not be accessed.

 *

 * @note Update the static data in vpcPageStateName() and vpcPageStateFlag()

 *       if you change this enumeration.

 **/

typedef enum __attribute__((packed)) pageState {

  /* this page buffer is not being used */

  PS_FREE,

  /* this page is being read from store */

  PS_INCOMING,

  /* attempt to load this page failed */

  PS_FAILED,

  /* this page is valid and un-modified */

  PS_RESIDENT,

  /* this page is valid and modified */

  PS_DIRTY,

  /* this page is being written and should not be used */

  PS_OUTGOING,

  /* not a state */

  PAGE_STATE_COUNT,

} PageState;

/**

 * The write status of page

 **/

typedef enum __attribute__((packed)) {

  WRITE_STATUS_NORMAL,

  WRITE_STATUS_DISCARD,

  WRITE_STATUS_DEFERRED,

} WriteStatus;

/**

 * Per-page-slot information.

 **/

struct pageInfo {

  /** Preallocated page VIO */

  VIO                 *vio;

  /** back-link for references */

  VDOPageCache        *cache;

  /** the pbn of the page */

  PhysicalBlockNumber  pbn;

  /** page is busy (temporarily locked) */

  uint16_t             busy;

  /** the write status the page */

  WriteStatus          writeStatus;

  /** page state */

  PageState            state;

  /** queue of completions awaiting this item */

  WaitQueue            waiting;

  /** state linked list node */

  PageInfoNode         listNode;

  /** LRU node */

  PageInfoNode         lruNode;

  /** Space for per-page client data */

  byte                 context[MAX_PAGE_CONTEXT_SIZE];

};

// PAGE INFO LIST OPERATIONS

/**********************************************************************/

static inline PageInfo *pageInfoFromListNode(PageInfoNode *node)

{

  if (node == NULL) {

    return NULL;

  }

  return (PageInfo *) ((uintptr_t) node - offsetof(PageInfo, listNode));

}

/**********************************************************************/

static inline PageInfo *pageInfoFromLRUNode(PageInfoNode *node)

{

  if (node == NULL) {

    return NULL;

  }

  return (PageInfo *) ((uintptr_t) node - offsetof(PageInfo, lruNode));

}

// PAGE INFO STATE ACCESSOR FUNCTIONS

/**********************************************************************/

static inline bool isFree(const PageInfo *info)

{

  return info->state == PS_FREE;

}

/**********************************************************************/

static inline bool isAvailable(const PageInfo *info)

{

  return (info->state == PS_FREE) || (info->state == PS_FAILED);

}

/**********************************************************************/

static inline bool isPresent(const PageInfo *info)

{

  return (info->state == PS_RESIDENT) || (info->state == PS_DIRTY);

}

/**********************************************************************/

static inline bool isDirty(const PageInfo *info)

{

  return info->state == PS_DIRTY;

}

/**********************************************************************/

static inline bool isResident(const PageInfo *info)

{

  return info->state == PS_RESIDENT;

}

/**********************************************************************/

static inline bool isInFlight(const PageInfo *info)

{

  return (info->state == PS_INCOMING) || (info->state == PS_OUTGOING);

}

/**********************************************************************/

static inline bool isIncoming(const PageInfo *info)

{

  return info->state == PS_INCOMING;

}

/**********************************************************************/

static inline bool isOutgoing(const PageInfo *info)

{

  return info->state == PS_OUTGOING;

}

/**********************************************************************/

static inline bool isValid(const PageInfo *info)

{

  return isPresent(info) || isOutgoing(info);

}

// COMPLETION CONVERSIONS

/**********************************************************************/

static inline VDOPageCompletion *asVDOPageCompletion(VDOCompletion *completion)

{

  assertCompletionType(completion->type, VDO_PAGE_COMPLETION);

  return (VDOPageCompletion *) ((uintptr_t) completion

                                - offsetof(VDOPageCompletion, completion));

}

/**********************************************************************/

static inline

VDOPageCompletion *pageCompletionFromWaiter(Waiter *waiter)

{

  if (waiter == NULL) {

    return NULL;

  }

  VDOPageCompletion *completion = (VDOPageCompletion *)

    ((uintptr_t) waiter - offsetof(VDOPageCompletion, waiter));

  assertCompletionType(completion->completion.type, VDO_PAGE_COMPLETION);

  return completion;

}

// COMMONLY USED FUNCTIONS

// All of these functions are prefixed "vpc" in order to prevent namespace

// issues (ordinarily they would be static).

/**

 * Find the page info (if any) associated with a given pbn.

 *

 * @param cache  the page cache

 * @param pbn    the absolute physical block number of the page

 *

 * @return the page info for the page if available, or NULL if not

 **/

PageInfo *vpcFindPage(VDOPageCache *cache, PhysicalBlockNumber pbn)

  __attribute__((warn_unused_result));

/**

 * Return the name of a page state.

 *

 * @param state     a page state

 *

 * @return a pointer to a static page state name

 *

 * @note If the page state is invalid a static string is returned and the

 *       invalid state is logged.

 **/

const char *vpcPageStateName(PageState state)

  __attribute__((warn_unused_result));

#endif // VDO_PAGE_CACHE_INTERNALS_H