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

#ifndef ALBIREO_WORK_QUEUE_H
#define ALBIREO_WORK_QUEUE_H

#include <linux/kobject.h>
#include <linux/sched.h>        /* for TASK_COMM_LEN */

#include "kernelTypes.h"
#include "util/funnelQueue.h"

enum {
  MAX_QUEUE_NAME_LEN        = TASK_COMM_LEN,
  /** Maximum number of action definitions per work queue type */
  WORK_QUEUE_ACTION_COUNT   = 8,
  /** Number of priority values available */
  WORK_QUEUE_PRIORITY_COUNT = 4,
};

struct kvdoWorkItem {
  /** Entry link for lock-free work queue */
  FunnelQueueEntry  workQueueEntryLink;
  /** Function to be called */
  KvdoWorkFunction  work;
  /** Optional alternate function for display in queue stats */
  void             *statsFunction;
  /** An index into the statistics table; filled in by workQueueStats code */
  unsigned int      statTableIndex;
  /**
   * The action code given to setupWorkItem, from which a priority will be
   * determined.
   **/
  unsigned int      action;
  /** The work queue in which the item is enqueued, or NULL if not enqueued. */
  KvdoWorkQueue    *myQueue;
  /**
   * Time at which to execute in jiffies for a delayed work item, or zero to
   * queue for execution ASAP.
   **/
  Jiffies           executionTime;
  /** List management for delayed or expired work items */
  KvdoWorkItem     *next;
  /** Time of enqueueing, in ns, for recording queue (waiting) time stats */
  uint64_t          enqueueTime;
};

/**
 * Table entries defining an action.
 *
 * Actions are intended to distinguish general classes of activity for
 * prioritization purposes, but not necessarily to indicate specific work
 * functions. They are indicated to setupWorkItem numerically, using an
 * enumerator defined per kind of work queue -- bio submission work queue
 * actions use BioQAction, cpu actions use CPUQAction, etc. For example, for
 * the CPU work queues, data compression can be prioritized separately from
 * final cleanup processing of a KVIO or from dedupe verification; base code
 * threads prioritize all VIO callback invocation the same, but separate from
 * sync or heartbeat operations. The bio acknowledgement work queue, on the
 * other hand, only does one thing, so it only defines one action code.
 *
 * Action codes values must be small integers, 0 through
 * WORK_QUEUE_ACTION_COUNT-1, and should not be duplicated for a queue type.
 *
 * A table of KvdoWorkQueueAction entries embedded in KvdoWorkQueueType
 * specifies the name, code, and priority for each type of action in the work
 * queue. The table can have at most WORK_QUEUE_ACTION_COUNT entries, but a
 * NULL name indicates an earlier end to the table.
 *
 * Priorities may be specified as values from 0 through
 * WORK_QUEUE_PRIORITY_COUNT-1, higher values indicating higher priority.
 * Priorities are just strong suggestions; it's possible for a lower-priority
 * work item scheduled right after a high-priority one to be run first, if the
 * worker thread happens to be scanning its queues at just the wrong moment,
 * but the high-priority item will be picked up next.
 *
 * Internally, the priorities in this table are used to initialize another
 * table in the constructed work queue object, and in internal builds,
 * device-mapper messages can be sent to change the priority for an action,
 * identified by name, in a running VDO device. Doing so does not affect the
 * priorities for other devices, or for future VDO device creation.
 **/
typedef struct kvdoWorkQueueAction {
  /** Name of the action */
  char         *name;

  /** The action code (per-type enum) */
  unsigned int  code;

  /** The initial priority for this action */
  unsigned int  priority;
} KvdoWorkQueueAction;

typedef void (*KvdoWorkQueueFunction)(void *);

/**
 * Static attributes of a work queue that are fixed at compile time
 * for a given call site. (Attributes that may be computed at run time
 * are passed as separate arguments.)
 **/
typedef struct kvdoWorkQueueType {
  /** A function to call in the new thread before servicing requests */
  KvdoWorkQueueFunction start;

  /** A function to call in the new thread when shutting down */
  KvdoWorkQueueFunction finish;

  /** A function to call in the new thread after running out of work */
  KvdoWorkQueueFunction suspend;

  /** Table of actions for this work queue */
  KvdoWorkQueueAction   actionTable[WORK_QUEUE_ACTION_COUNT];
} KvdoWorkQueueType;

/**
 * Create a work queue.
 *
 * If multiple threads are requested, work items will be distributed to them in
 * round-robin fashion.
 *
 * @param [in]  threadNamePrefix The per-device prefix to use in thread names
 * @param [in]  name             The queue name
 * @param [in]  parentKobject    The parent sysfs node
 * @param [in]  owner            The kernel layer owning the work queue
 * @param [in]  private          Private data of the queue for use by work
 *                               items or other queue-specific functions
 * @param [in]  type             The work queue type defining the lifecycle
 *                               functions, queue actions, priorities, and
 *                               timeout behavior
 * @param [in]  threadCount      Number of service threads to set up
 * @param [out] queuePtr         Where to store the queue handle
 *
 * @return VDO_SUCCESS or an error code
 **/
int makeWorkQueue(const char               *threadNamePrefix,
                  const char               *name,
                  struct kobject           *parentKobject,
                  KernelLayer              *owner,
                  void                     *private,
                  const KvdoWorkQueueType  *type,
                  unsigned int              threadCount,
                  KvdoWorkQueue           **queuePtr);

/**
 * Set up the fields of a work queue item.
 *
 * Before the first setup call (setupWorkItem or setupWorkItemWithTimeout), the
 * work item must have been initialized to all-zero. Resetting a
 * previously-used work item does not require another memset.
 *
 * The action code is typically defined in a work-queue-type-specific
 * enumeration; see the description of KvdoWorkQueueAction.
 *
 * @param item           The work item to initialize
 * @param work           The function pointer to execute
 * @param statsFunction  A function pointer to record for stats, or NULL
 * @param action         Action code, for determination of priority
 **/
void setupWorkItem(KvdoWorkItem     *item,
                   KvdoWorkFunction  work,
                   void             *statsFunction,
                   unsigned int      action);

/**
 * Add a work item to a work queue.
 *
 * If the work item has a timeout that has already passed, the timeout
 * handler function may be invoked at this time.
 *
 * @param queue      The queue handle
 * @param item       The work item to be processed
 **/
void enqueueWorkQueue(KvdoWorkQueue *queue, KvdoWorkItem *item);

/**
 * Add a work item to a work queue, to be run at a later point in time.
 *
 * Currently delayed work items are used only in a very limited fashion -- at
 * most one at a time for any of the work queue types that use them -- and some
 * shortcuts have been taken that assume that that's the case. Multiple delayed
 * work items should work, but they will execute in the order they were
 * enqueued.
 *
 * @param queue           The queue handle
 * @param item            The work item to be processed
 * @param executionTime   When to run the work item (jiffies)
 **/
void enqueueWorkQueueDelayed(KvdoWorkQueue *queue,
                             KvdoWorkItem  *item,
                             Jiffies        executionTime);

/**
 * Shut down a work queue's worker thread.
 *
 * Alerts the worker thread that it should shut down, and then waits
 * for it to do so.
 *
 * There should not be any new enqueueing of work items done once this
 * function is called. Any pending delayed work items will be
 * processed, as scheduled, before the worker thread shuts down, but
 * they must not re-queue themselves to run again.
 *
 * @param queue  The work queue to shut down
 **/
void finishWorkQueue(KvdoWorkQueue *queue);

/**
 * Free a work queue and null out the reference to it.
 *
 * @param queuePtr  Where the queue handle is found
 **/
void freeWorkQueue(KvdoWorkQueue **queuePtr);

/**
 * Print work queue state and statistics to the kernel log.
 *
 * @param queue  The work queue to examine
 **/
void dumpWorkQueue(KvdoWorkQueue *queue);

/**
 * Write to the buffer some info about the work item, for logging.
 * Since the common use case is dumping info about a lot of work items
 * to syslog all at once, the format favors brevity over readability.
 *
 * @param item    The work item
 * @param buffer  The message buffer to fill in
 * @param length  The length of the message buffer
 **/
void dumpWorkItemToBuffer(KvdoWorkItem *item, char *buffer, size_t length);


/**
 * Initialize work queue internals at module load time.
 **/
void initWorkQueueOnce(void);

/**
 * Checks whether two work items have the same action codes
 *
 * @param item1 The first item
 * @param item2 The second item
 *
 * @return TRUE if the actions are the same, FALSE otherwise
 */
static inline bool areWorkItemActionsEqual(KvdoWorkItem *item1,
                                           KvdoWorkItem *item2)
{
  return item1->action == item2->action;
}

/**
 * Returns the private data for the current thread's work queue.
 *
 * @return  The private data pointer, or NULL if none or if the current
 *          thread is not a work queue thread.
 **/
void *getWorkQueuePrivateData(void);

/**
 * Updates the private data pointer for the current thread's work queue.
 *
 * @param newData  The new private data pointer
 **/
void setWorkQueuePrivateData(void *newData);

/**
 * Returns the work queue pointer for the current thread, if any.
 *
 * @return   The work queue pointer or NULL
 **/
KvdoWorkQueue *getCurrentWorkQueue(void);

/**
 * Returns the kernel layer that owns the work queue.
 *
 * @param queue  The work queue
 *
 * @return   The owner pointer supplied at work queue creation
 **/
KernelLayer *getWorkQueueOwner(KvdoWorkQueue *queue);

#endif /* ALBIREO_WORK_QUEUE_H */