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

#ifndef EXTENT_H
#define EXTENT_H

#include "permassert.h"

#include "completion.h"
#include "types.h"
#include "vio.h"

/**
 * A chain of VIOs which are part of the same request. An extent contains
 * a chain of at least 'count' VIOs. The 'next' pointer of the last VIO
 * in the extent (as indicated by the count) may not be NULL, but it is not
 * part of the extent. A VIO may belong to a single extent.
 **/
struct vdoExtent {
  // The completion for asynchronous extent processing
  VDOCompletion  completion;
  // The number of VIOs in the extent
  BlockCount     count;
  // The number of completed VIOs in the extent
  BlockCount     completeCount;
  // The VIOs in the extent
  VIO           *vios[];
};

/**
 * Convert a generic VDOCompletion to a VDOExtent.
 *
 * @param completion The completion to convert
 *
 * @return The completion as an extent
 **/
static inline VDOExtent *asVDOExtent(VDOCompletion *completion)
{
  STATIC_ASSERT(offsetof(VDOExtent, completion) == 0);
  assertCompletionType(completion->type, VDO_EXTENT_COMPLETION);
  return (VDOExtent *) completion;
}

/**
 * Convert a VDOExtent to VDOCompletion.
 *
 * @param extent The extent to convert
 *
 * @return The extent as a VDOCompletion
 **/
static inline VDOCompletion *extentAsCompletion(VDOExtent *extent)
{
  return &extent->completion;
}

/**
 * Create a VDOExtent.
 *
 * @param [in]  layer       The layer
 * @param [in]  vioType     The usage type to assign to the VIOs in the extent
 *                          (data / block map / journal)
 * @param [in]  priority    The relative priority to assign to the VIOs
 * @param [in]  blockCount  The number of blocks in the buffer
 * @param [in]  data        The buffer
 * @param [out] extentPtr   A pointer to hold the new extent
 *
 * @return VDO_SUCCESS or an error
 **/
int createExtent(PhysicalLayer  *layer,
                 VIOType         vioType,
                 VIOPriority     priority,
                 BlockCount      blockCount,
                 char           *data,
                 VDOExtent     **extentPtr)
  __attribute__((warn_unused_result));

/**
 * Free an extent and null out the reference to it.
 *
 * @param [in,out] extentPtr   The reference to the extent to free
 **/
void freeExtent(VDOExtent **extentPtr);

/**
 * Read metadata from the underlying storage.
 *
 * @param extent      The extent to read
 * @param startBlock  The physical block number of the first block
 *                    in the extent
 * @param count       The number of blocks to read (must be less than or
 *                    equal to the length of the extent)
 **/
void readPartialMetadataExtent(VDOExtent           *extent,
                               PhysicalBlockNumber  startBlock,
                               BlockCount           count);

/**
 * Read metadata from the underlying storage.
 *
 * @param extent      The extent to read
 * @param startBlock  The physical block number of the first block
 *                    in the extent
 **/
static inline void readMetadataExtent(VDOExtent           *extent,
                                      PhysicalBlockNumber  startBlock)
{
  readPartialMetadataExtent(extent, startBlock, extent->count);
}

/**
 * Write metadata to the underlying storage.
 *
 * @param extent      The extent to write
 * @param startBlock  The physical block number of the first block in the
 *                    extent
 * @param count       The number of blocks to read (must be less than or
 *                    equal to the length of the extent)
 **/
void writePartialMetadataExtent(VDOExtent           *extent,
                                PhysicalBlockNumber  startBlock,
                                BlockCount           count);
/**
 * Write metadata to the underlying storage.
 *
 * @param extent      The extent to write
 * @param startBlock  The physical block number of the first block in the
 *                    extent
 **/
static inline void writeMetadataExtent(VDOExtent           *extent,
                                       PhysicalBlockNumber  startBlock)
{
  writePartialMetadataExtent(extent, startBlock, extent->count);
}

/**
 * Notify an extent that one of its VIOs has completed. If the signaling VIO
 * is the last of the extent's VIOs to complete, the extent will finish. This
 * function is set as the VIO callback in completeVIO().
 *
 * @param completion  The completion of the VIO which has just finished
 **/
void handleVIOCompletion(VDOCompletion *completion);

#endif /* EXTENT_H */