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

#ifndef IOSUBMITTER_H
#define IOSUBMITTER_H

#include <linux/version.h>

#include "kernelLayer.h"
#include "kvio.h"

/**
 * Does all the appropriate accounting for bio completions
 *
 * @param bio  the bio to count
 **/
void countCompletedBios(BIO *bio);

#if LINUX_VERSION_CODE >= KERNEL_VERSION(4,4,0)
/**
 * Completes a bio relating to a kvio, causing the completion callback
 * to be invoked.
 *
 * This is used as the bi_end_io function for most of the bios created
 * within VDO and submitted to the storage device. Exceptions are the
 * flush code and the read-block code, both of which need to regain
 * control in the kernel layer after the I/O is completed.
 *
 * @param bio   The bio to complete
 **/
void completeAsyncBio(BIO *bio);
#else
/**
 * Completes a bio relating to a kvio, causing the completion callback
 * to be invoked.
 *
 * This is used as the bi_end_io function for most of the bios created
 * within VDO and submitted to the storage device. Exceptions are the
 * flush code and the read-block code, both of which need to regain
 * control in the kernel layer after the I/O is completed.
 *
 * @param bio   The bio to complete
 * @param error Possible error from underlying block device
 **/
void completeAsyncBio(BIO *bio, int error);
#endif

/**
 * Create a IOSubmitter structure for a new physical layer.
 *
 * @param [in]  threadNamePrefix  The per-device prefix to use in process names
 * @param [in]  threadCount       Number of bio-submission threads to set up
 * @param [in]  rotationInterval  Interval to use when rotating between
 *                                bio-submission threads when enqueuing work
 *                                items
 * @param [in]  maxRequestsActive Number of bios for merge tracking
 * @param [in]  layer             The kernel layer
 * @param [out] ioSubmitter       Pointer to the new data structure
 *
 * @return VDO_SUCCESS or an error
 **/
int makeIOSubmitter(const char    *threadNamePrefix,
                    unsigned int   threadCount,
                    unsigned int   rotationInterval,
                    unsigned int   maxRequestsActive,
                    KernelLayer   *layer,
                    IOSubmitter  **ioSubmitter);

/**
 * Tear down the IOSubmitter fields as needed for a physical layer.
 *
 * @param [in]  ioSubmitter    The I/O submitter data to tear down
 **/
void cleanupIOSubmitter(IOSubmitter *ioSubmitter);

/**
 * Free the IOSubmitter fields and structure as needed for a
 * physical layer. This must be called after
 * cleanupIOSubmitter(). It is used to release resources late in
 * the shutdown process to avoid or reduce the chance of race
 * conditions.
 *
 * @param [in]  ioSubmitter    The I/O submitter data to destroy
 **/
void freeIOSubmitter(IOSubmitter *ioSubmitter);

/**
 * Dump info to the kernel log about the work queue used by the
 * physical layer. For debugging only.
 *
 * @param [in]  ioSubmitter        The I/O submitter data
 **/
void dumpBioWorkQueue(IOSubmitter *ioSubmitter);


/**
 * Enqueue a work item to run in the work queue(s) used for bio
 * submissions from the physical layer.
 *
 * Outside of IOSubmitter, used only for finishing processing of empty
 * flush bios by sending them to the storage device.
 *
 * @param ioSubmitter        The I/O submitter data to update
 * @param workItem           The new work item to run
 **/
void enqueueBioWorkItem(IOSubmitter *ioSubmitter, KvdoWorkItem *workItem);

/**
 * Submit bio but don't block.
 *
 * Submits the bio to a helper work queue which sits in a loop
 * submitting bios. The worker thread may block if the target device
 * is busy, which is why we don't want to do the submission in the
 * original calling thread.
 *
 * The bi_private field of the bio must point to a KVIO associated
 * with the operation. The bi_end_io callback is invoked when the I/O
 * operation completes.
 *
 * @param bio      the block I/O operation descriptor to submit
 * @param action   the action code specifying the priority for the operation
 **/
void submitBio(BIO *bio, BioQAction action);

#endif // IOSUBMITTER_H