/*

 * 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/indexLayout.h#13 $

 */

#ifndef INDEX_LAYOUT_H

#define INDEX_LAYOUT_H

#include "buffer.h"

#include "indexState.h"

#include "indexVersion.h"

#include "ioFactory.h"

#include "uds.h"

typedef struct indexLayout IndexLayout;

/**

 * Construct an index layout.  This is a platform specific function that uses

 * the name string, a flag that indicates old vs. new indices, and a

 * UDSConfiguration (for new indices) to make an IOFactory and invoke

 * makeIndexLayoutFromFactory.

 *

 * @param name       String naming the index.  Each platform will use its own

 *                   conventions to interpret the string, but in general it is

 *                   a space-separated sequence of param=value settings.  For

 *                   backward compatibility a string without an equals is

 *                   treated as a platform-specific default parameter value.

 * @param newLayout  Whether this is a new layout.

 * @param config     The UdsConfiguration required for a new layout.

 * @param layoutPtr  Where to store the new index layout

 *

 * @return UDS_SUCCESS or an error code.

 **/

int makeIndexLayout(const char              *name,

                    bool                     newLayout,

                    const UdsConfiguration   config,

                    IndexLayout            **layoutPtr)

  __attribute__((warn_unused_result));

/**

 * Construct an index layout using an IOFactory.  This method is common to all

 * platforms.

 *

 * @param factory    The IOFactory for the block storage containing the index.

 * @param offset     The offset of the start of the index within the block

 *                   storage address space.

 * @param namedSize  The size in bytes of the space within the block storage

 *                   address space, as specified in the name string.

 * @param newLayout  Whether this is a new layout.

 * @param config     The UdsConfiguration required for a new layout.

 * @param layoutPtr  Where to store the new index layout

 *

 * @return UDS_SUCCESS or an error code.

 **/

int makeIndexLayoutFromFactory(IOFactory               *factory,

                               off_t                    offset,

                               uint64_t                 namedSize,

                               bool                     newLayout,

                               const UdsConfiguration   config,

                               IndexLayout            **layoutPtr)

  __attribute__((warn_unused_result));

/**

 * Decrement the use count of an index layout.  If the count goes to zero, free

 * the index layout.

 *

 * @param layoutPtr  Where the layout is being stored.  Always reset to NULL.

 **/

void putIndexLayout(IndexLayout **layoutPtr);

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

int cancelIndexSave(IndexLayout *layout, unsigned int saveSlot)

  __attribute__((warn_unused_result));

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

int commitIndexSave(IndexLayout *layout, unsigned int saveSlot)

  __attribute__((warn_unused_result));

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

int discardIndexSaves(IndexLayout *layout, bool all)

  __attribute__((warn_unused_result));

/**

 * Find the latest index save slot.

 *

 * @param [in]  layout          The single file layout.

 * @param [out] numZonesPtr     Where to store the actual number of zones

 *                                that were saved.

 * @param [out] slotPtr         Where to store the slot number we found.

 *

 * @return UDS_SUCCESS or an error code.

 **/

int findLatestIndexSaveSlot(IndexLayout  *layout,

                            unsigned int *numZonesPtr,

                            unsigned int *slotPtr)

  __attribute__((warn_unused_result));

/**

 * Get another reference to an index layout, incrementing it's use count.

 *

 * @param layout     The index layout.

 * @param layoutPtr  Where the new layout pointer is being stored.

 **/

void getIndexLayout(IndexLayout *layout, IndexLayout **layoutPtr);

/**

 * Open a BufferedReader for a specified state, kind, and zone.

 *

 * @param layout     The index layout

 * @param slot       The save slot

 * @param kind       The kind if index save region to open.

 * @param zone       The zone number for the region.

 * @param readerPtr  Where to store the BufferedReader.

 *

 * @return UDS_SUCCESS or an error code.

 **/

int openIndexBufferedReader(IndexLayout     *layout,

                            unsigned int     slot,

                            RegionKind       kind,

                            unsigned int     zone,

                            BufferedReader **readerPtr)

  __attribute__((warn_unused_result));

/**

 * Open a BufferedWriter for a specified state, kind, and zone.

 *

 * @param layout     The index layout

 * @param slot       The save slot

 * @param kind       The kind if index save region to open.

 * @param zone       The zone number for the region.

 * @param writerPtr  Where to store the BufferedWriter.

 *

 * @return UDS_SUCCESS or an error code.

 **/

int openIndexBufferedWriter(IndexLayout     *layout,

                            unsigned int     slot,

                            RegionKind       kind,

                            unsigned int     zone,

                            BufferedWriter **writerPtr)

  __attribute__((warn_unused_result));

/**

 * Obtain the nonce to be used to store or validate the loading of volume index

 * pages.

 *

 * @param [in]  layout   The index layout.

 *

 * @return The nonce to use.

 **/

uint64_t getVolumeNonce(IndexLayout *layout)

  __attribute__((warn_unused_result));

#ifdef __KERNEL__

/**

 * Obtain a dm_bufio_client for the specified index volume.

 *

 * @param [in]  layout           The index layout.

 * @param [in]  blockSize        The size of a volume page

 * @param [in]  reservedBuffers  The count of reserved buffers

 * @param [out] clientPtr        Where to put the new dm_bufio_client

 *

 * @return UDS_SUCCESS or an error code.

 **/

int openVolumeBufio(IndexLayout             *layout,

                    size_t                   blockSize,

                    unsigned int             reservedBuffers,

                    struct dm_bufio_client **clientPtr)

  __attribute__((warn_unused_result));

#else

/**

 * Obtain an IORegion for the specified index volume.

 *

 * @param [in]  layout     The index layout.

 * @param [out] regionPtr  Where to put the new region.

 *

 * @return UDS_SUCCESS or an error code.

 **/

int openVolumeRegion(IndexLayout *layout, struct ioRegion **regionPtr)

  __attribute__((warn_unused_result));

#endif

/**

 * Read the index configuration, and verify that it matches the given

 * configuration.

 *

 * @param layout  the generic index layout

 * @param config  the index configuration

 *

 * @return UDS_SUCCESS or an error code

 **/

int verifyIndexConfig(IndexLayout *layout, UdsConfiguration config)

  __attribute__((warn_unused_result));

/**

 * Determine which index save slot to use for a new index save.

 *

 * Also allocates the masterIndex regions and, if needed, the openChapter

 * region.

 *

 * @param [in]  layout          The index layout.

 * @param [in]  numZones        Actual number of zones currently in use.

 * @param [in]  saveType        The index save type.

 * @param [out] saveSlotPtr     Where to store the save slot number.

 *

 * @return UDS_SUCCESS or an error code

 **/

int setupIndexSaveSlot(IndexLayout   *layout,

                       unsigned int   numZones,

                       IndexSaveType  saveType,

                       unsigned int  *saveSlotPtr)

  __attribute__((warn_unused_result));

/**

 * Write the index configuration.

 *

 * @param layout  the generic index layout

 * @param config  the index configuration to write

 *

 * @return UDS_SUCCESS or an error code

 **/

int writeIndexConfig(IndexLayout *layout, UdsConfiguration config)

  __attribute__((warn_unused_result));

/**

 * Get the index state buffer

 *

 * @param layout  the index layout

 * @param slot    the save slot

 *

 * @return UDS_SUCCESS or an error code

 **/

Buffer *getIndexStateBuffer(IndexLayout *layout, unsigned int slot)

  __attribute__((warn_unused_result));

/**

 * Get the index version parameters.

 *

 * @param layout  the index layout

 *

 * @return the index version parameters.

 **/

const struct index_version *getIndexVersion(IndexLayout *layout)

  __attribute__((warn_unused_result));

#endif // INDEX_LAYOUT_H