/*
 * 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/uds-releases/jasper/src/uds/volumeStore.h#2 $
 */

#ifndef VOLUME_STORE_H
#define VOLUME_STORE_H

#include "common.h"
#include "compiler.h"
#include "memoryAlloc.h"

#ifdef __KERNEL__
#include <linux/dm-bufio.h>
#else
#include "ioRegion.h"
#endif

struct geometry;
struct indexLayout;


struct volume_store {
#ifdef __KERNEL__
  struct dm_bufio_client *vs_client;
#else
  IORegion               *vs_region;
  size_t                  vs_bytesPerPage;
#endif
};


struct volume_page {
#ifdef __KERNEL__
  struct dm_buffer *vp_buffer;
#else
  byte             *vp_data;
#endif
};

/**
 * Close a volume store.
 *
 * @param volumeStore   The volume store
 **/
void closeVolumeStore(struct volume_store *volumeStore);

/**
 * Uninitialize a volume page buffer.
 *
 * @param volumePage  The volume page buffer
 **/
void destroyVolumePage(struct volume_page *volumePage);

/**
 * Get a pointer to the data contained in a volume page buffer.
 *
 * @param volumePage  The volume page buffer
 *
 * @return the address of the data
 **/
__attribute__((warn_unused_result))
static INLINE byte *getPageData(const struct volume_page *volumePage)
{
#ifdef __KERNEL__
  return dm_bufio_get_block_data(volumePage->vp_buffer);
#else
  return volumePage->vp_data;
#endif
}

/**
 * Initialize a volume page buffer.
 *
 * @param geometry    The volume geometry
 * @param volumePage  The volume page buffer
 *
 * @return UDS_SUCCESS or an error status
 **/
int initializeVolumePage(const struct geometry *geometry,
                         struct volume_page    *volumePage)
  __attribute__((warn_unused_result));

/**
 * Open a volume store.
 *
 * @param volumeStore      The volume store
 * @param layout           The index layout
 * @param reservedBuffers  The number of buffers that can be reserved
 * @param bytesPerPage     The number of bytes in a volume page
 **/
int openVolumeStore(struct volume_store *volumeStore,
                    struct indexLayout  *layout,
                    unsigned int         reservedBuffers,
                    size_t               bytesPerPage)
  __attribute__((warn_unused_result));

/**
 * Prefetch volume pages into memory.
 *
 * @param volumeStore   The volume store
 * @param physicalPage  The volume page number of the first desired page
 * @param pageCount     The number of volume pages to prefetch
 **/
void prefetchVolumePages(const struct volume_store *volumeStore,
                         unsigned int               physicalPage,
                         unsigned int               pageCount);

/**
 * Prepare a buffer to write a page to the volume.
 *
 * @param volumeStore   The volume store
 * @param physicalPage  The volume page number of the desired page
 * @param volumePage    The volume page buffer
 *
 * @return UDS_SUCCESS or an error code
 **/
int prepareToWriteVolumePage(const struct volume_store *volumeStore,
                             unsigned int               physicalPage,
                             struct volume_page        *volumePage)
  __attribute__((warn_unused_result));

/**
 * Read a page from a volume store.
 *
 * @param volumeStore   The volume store
 * @param physicalPage  The volume page number of the desired page
 * @param volumePage    The volume page buffer
 *
 * @return UDS_SUCCESS or an error code
 **/
int readVolumePage(const struct volume_store *volumeStore,
                   unsigned int               physicalPage,
                   struct volume_page        *volumePage)
  __attribute__((warn_unused_result));

/**
 * Release a volume page buffer, because it will no longer be accessed before a
 * call to readVolumePage or prepareToWriteVolumePage.
 *
 * @param volumePage  The volume page buffer
 **/
void releaseVolumePage(struct volume_page *volumePage);

/**
 * Swap volume pages.  This is used to put the contents of a newly written
 * index page (in the scratch page) into the page cache.
 *
 * @param volumePage1  The volume page buffer
 * @param volumePage2  The volume page buffer
 **/
void swapVolumePages(struct volume_page *volumePage1,
                     struct volume_page *volumePage2);

/**
 * Sync the volume store to storage.
 *
 * @param volumeStore  The volume store
 *
 * @return UDS_SUCCESS or an error code
 **/
int syncVolumeStore(const struct volume_store *volumeStore)
  __attribute__((warn_unused_result));

/**
 * Write a page to a volume store.
 *
 * @param volumeStore   The volume store
 * @param physicalPage  The volume page number of the desired page
 * @param volumePage    The volume page buffer
 *
 * @return UDS_SUCCESS or an error code
 **/
int writeVolumePage(const struct volume_store *volumeStore,
                    unsigned int               physicalPage,
                    struct volume_page        *volumePage)
  __attribute__((warn_unused_result));

#endif /* VOLUME_STORE_H */