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

#ifndef KERNEL_VDO_H
#define KERNEL_VDO_H

#include "completion.h"
#include "kernelTypes.h"
#include "threadRegistry.h"
#include "workQueue.h"

typedef struct {
  KVDO              *kvdo;
  ThreadID           threadID;
  KvdoWorkQueue     *requestQueue;
  RegisteredThread   allocatingThread;
} KVDOThread;

struct kvdo {
  KVDOThread        *threads;
  ThreadID           initializedThreadCount;
  KvdoWorkItem       workItem;
  VDOAction         *action;
  VDOCompletion     *completion;
  // Base-code device info
  VDO               *vdo;
};

typedef enum reqQAction {
  REQ_Q_ACTION_COMPLETION,
  REQ_Q_ACTION_FLUSH,
  REQ_Q_ACTION_MAP_BIO,
  REQ_Q_ACTION_SYNC,
  REQ_Q_ACTION_VIO_CALLBACK
} ReqQAction;

/**
 * Initialize the base code interface.
 *
 * @param [in]  kvdo          The KVDO to be initialized
 * @param [in]  threadConfig  The base-code thread configuration
 * @param [out] reason        The reason for failure
 *
 * @return  VDO_SUCCESS or an error code
 **/
int initializeKVDO(KVDO                *kvdo,
                   const ThreadConfig  *threadConfig,
                   char               **reason);

/**
 * Load the VDO state from disk but don't alter the on-disk state. This method
 * is ultimately called from the constructor for devices which have not been
 * resumed.
 *
 * @param [in]  kvdo                  The KVDO to be started
 * @param [in]  common                The physical layer pointer
 * @param [in]  loadConfig            Load-time parameters for the VDO
 * @param [in]  vioTraceRecording     Debug flag to store
 * @param [out] reason                The reason for failure
 **/
int preloadKVDO(KVDO                 *kvdo,
                PhysicalLayer        *common,
                const VDOLoadConfig  *loadConfig,
                bool                  vioTraceRecording,
                char                **reason);

/**
 * Starts the base VDO instance associated with the kernel layer. This method
 * is ultimately called from preresume the first time an instance is resumed.
 *
 * @param [in]  kvdo                  The KVDO to be started
 * @param [in]  common                The physical layer pointer
 * @param [out] reason                The reason for failure
 *
 * @return VDO_SUCCESS if started, otherwise error
 */
int startKVDO(KVDO *kvdo, PhysicalLayer *common, char **reason);

/**
 * Suspend the base VDO instance associated with the kernel layer.
 *
 * @param kvdo  The KVDO to be suspended
 *
 * @return VDO_SUCCESS if stopped, otherwise error
 **/
int suspendKVDO(KVDO *kvdo);

/**
 * Resume the base VDO instance associated with the kernel layer.
 *
 * @param kvdo  The KVDO to be resumed
 *
 * @return VDO_SUCCESS or an error
 **/
int resumeKVDO(KVDO *kvdo);

/**
 * Shut down the base code interface. The kvdo object must first be
 * stopped.
 *
 * @param kvdo         The KVDO to be shut down
 **/
void finishKVDO(KVDO *kvdo);

/**
 * Free up storage of the base code interface. The KVDO object must
 * first have been "finished".
 *
 * @param kvdo         The KVDO object to be destroyed
 **/
void destroyKVDO(KVDO *kvdo);


/**
 * Dump to the kernel log any work-queue info associated with the base
 * code.
 *
 * @param kvdo     The KVDO object to be examined
 **/
void dumpKVDOWorkQueue(KVDO *kvdo);

/**
 * Get the VDO pointer for a kvdo object
 *
 * @param kvdo          The KVDO object
 *
 * @return the VDO pointer
 */
static inline VDO *getVDO(KVDO *kvdo)
{
  return kvdo->vdo;
}

/**
 * Set whether compression is enabled.
 *
 * @param kvdo               The KVDO object
 * @param enableCompression  The new compression mode
 *
 * @return state of compression before new value is set
 **/
bool setKVDOCompressing(KVDO *kvdo, bool enableCompression);

/**
 * Get the current compression mode
 *
 * @param kvdo          The KVDO object to be queried
 *
 * @return whether compression is currently enabled
 */
bool getKVDOCompressing(KVDO *kvdo);

/**
 * Gets the latest statistics gathered by the base code.
 *
 * @param kvdo  the KVDO object
 * @param stats the statistics struct to fill in
 */
void getKVDOStatistics(KVDO *kvdo, VDOStatistics *stats);

/**
 * Get the current write policy
 *
 * @param kvdo          The KVDO to be queried
 *
 * @return  the write policy in effect
 */
WritePolicy getKVDOWritePolicy(KVDO *kvdo);

/**
 * Dump base code status information to the kernel log for debugging.
 *
 * @param kvdo          The KVDO to be examined
 */
void dumpKVDOStatus(KVDO *kvdo);

/**
 * Request the base code prepare to grow the physical space.
 *
 * @param kvdo           The KVDO to be updated
 * @param physicalCount  The new size
 *
 * @return VDO_SUCCESS or error
 */
int kvdoPrepareToGrowPhysical(KVDO *kvdo, BlockCount physicalCount);

/**
 * Notify the base code of resized physical storage.
 *
 * @param kvdo           The KVDO to be updated
 * @param physicalCount  The new size
 *
 * @return VDO_SUCCESS or error
 */
int kvdoResizePhysical(KVDO *kvdo, BlockCount physicalCount);

/**
 * Request the base code prepare to grow the logical space.
 *
 * @param kvdo          The KVDO to be updated
 * @param logicalCount  The new size
 *
 * @return VDO_SUCCESS or error
 */
int kvdoPrepareToGrowLogical(KVDO *kvdo, BlockCount logicalCount);

/**
 * Request the base code grow the logical space.
 *
 * @param kvdo          The KVDO to be updated
 * @param logicalCount  The new size
 *
 * @return VDO_SUCCESS or error
 */
int kvdoResizeLogical(KVDO *kvdo, BlockCount logicalCount);

/**
 * Request the base code go read-only.
 *
 * @param kvdo          The KVDO to be updated
 * @param result        The error code causing the read only
 */
void setKVDOReadOnly(KVDO *kvdo, int result);

/**
 * Perform an extended base-code command
 *
 * @param kvdo          The KVDO upon which to perform the operation.
 * @param argc          The number of arguments to the command.
 * @param argv          The command arguments. Note that all extended
 *                        command argv[0] strings start with "x-".
 *
 * @return VDO_SUCCESS or an error code
 **/
int performKVDOExtendedCommand(KVDO *kvdo, int argc, char **argv);

/**
 * Enqueue a work item to be processed in the base code context.
 *
 * @param kvdo         The KVDO object in which to run the work item
 * @param item         The work item to be run
 * @param threadID     The thread on which to run the work item
 **/
void enqueueKVDOWork(KVDO *kvdo, KvdoWorkItem *item, ThreadID threadID);

/**
 * Set up and enqueue a VIO's work item to be processed in the base code
 * context.
 *
 * @param kvio           The VIO with the work item to be run
 * @param work           The function pointer to execute
 * @param statsFunction  A function pointer to record for stats, or NULL
 * @param action         Action code, mapping to a relative priority
 **/
void enqueueKVIO(KVIO             *kvio,
                 KvdoWorkFunction  work,
                 void             *statsFunction,
                 unsigned int      action);

/**
 * Enqueue an arbitrary completion for execution on its indicated
 * thread.
 *
 * @param enqueueable  The Enqueueable object containing the completion pointer
 **/
void kvdoEnqueue(Enqueueable *enqueueable);

/**
 * Get the base-code thread index for the current execution context.
 *
 * @return    The thread ID, or (ThreadID)-1 if the current thread is
 *            not a base-code thread, or in an interrupt context.
 **/
ThreadID kvdoGetCurrentThreadID(void);

/**
 * Do one-time initialization of kernelVDO interface.
 **/
void initKernelVDOOnce(void);

#endif // KERNEL_VDO_H