/*

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

 */

#ifndef WORK_QUEUE_STATS_H

#define WORK_QUEUE_STATS_H

#include "workQueue.h"

#include "timeUtils.h"

#include "histogram.h"

#include "workItemStats.h"

// Defined in workQueueInternals.h after inclusion of workQueueStats.h.

struct simpleWorkQueue;

/*

 * Tracking statistics.

 *

 * Cache line contention issues:

 *

 * In workItemStats, there are read-only fields accessed mostly by

 * work submitters, then fields updated by the work submitters (for

 * which there will be contention), then fields rarely if ever updated

 * (more than two cache lines' worth), then fields updated only by the

 * worker thread. The trailing fields here are updated only by the

 * worker thread.

 */

typedef struct kvdoWorkQueueStats {

  // Per-work-function counters and optional nanosecond timing data

  KvdoWorkItemStats  workItemStats;

  // How often we go to sleep waiting for work

  uint64_t           waits;

  // Run time data, for monitoring utilization levels.

  // Thread start time, from which we can compute lifetime thus far.

  uint64_t           startTime;

  /*

   * Time the thread has not been blocked waiting for a new work item,

   * nor in cond_resched(). This will include time the thread has been

   * blocked by some kernel function invoked by the work functions

   * (e.g., waiting for socket buffer space).

   *

   * This is not redundant with runTimeBeforeRescheduleHistogram, as

   * the latter doesn't count run time not followed by a cond_resched

   * call.

   */

  atomic64_t         runTime;

  // Time the thread has been suspended via cond_resched().

  // (Duplicates data hidden within rescheduleTimeHistogram.)

  atomic64_t         rescheduleTime;

  // Histogram of the queue times of work items (microseconds)

  Histogram         *queueTimeHistogram;

  // How busy we are when cond_resched is called

  Histogram         *rescheduleQueueLengthHistogram;

  // Histogram of the time cond_resched makes us sleep for (microseconds)

  Histogram         *rescheduleTimeHistogram;

  // Histogram of the run time between cond_resched calls (microseconds)

  Histogram         *runTimeBeforeRescheduleHistogram;

  // Histogram of the time schedule_timeout lets us sleep for (microseconds)

  Histogram         *scheduleTimeHistogram;

  // How long from thread wakeup call to thread actually running (microseconds)

  Histogram         *wakeupLatencyHistogram;

  // How much work is pending by the time we start running

  Histogram         *wakeupQueueLengthHistogram;

} KvdoWorkQueueStats;

/**

 * Initialize the work queue's statistics tracking.

 *

 * @param stats         The statistics structure

 * @param queueKObject  The sysfs directory kobject for the work queue

 *

 * @return  0 or a kernel error code

 **/

int initializeWorkQueueStats(KvdoWorkQueueStats *stats,

                             struct kobject     *queueKObject)

  __attribute__((warn_unused_result));

/**

 * Tear down any allocated storage or objects for statistics tracking.

 *

 * @param stats  The statistics structure

 **/

void cleanupWorkQueueStats(KvdoWorkQueueStats *stats);

/**

 * Update the work queue statistics tracking to note the enqueueing of

 * a work item.

 *

 * @param stats     The statistics structure

 * @param item      The work item being enqueued

 * @param priority  The priority of the work item

 **/

static inline void updateStatsForEnqueue(KvdoWorkQueueStats *stats,

                                         KvdoWorkItem       *item,

                                         int                 priority)

{

  updateWorkItemStatsForEnqueue(&stats->workItemStats, item, priority);

  item->enqueueTime = currentTime(CLOCK_MONOTONIC);

}

/**

 * Update the work queue statistics tracking to note the dequeueing of

 * a work item.

 *

 * @param stats  The statistics structure

 * @param item   The work item being enqueued

 **/

static inline void updateStatsForDequeue(KvdoWorkQueueStats *stats,

                                         KvdoWorkItem       *item)

{

  updateWorkItemStatsForDequeue(&stats->workItemStats, item);

  enterHistogramSample(stats->queueTimeHistogram,

                       (currentTime(CLOCK_MONOTONIC) - item->enqueueTime) / 1000);

  item->enqueueTime = 0;

}

/**

 * Write the work queue's accumulated statistics to the kernel log.

 *

 * The queue pointer is needed so that its address and name can be

 * logged along with the statistics.

 *

 * @param queue  The work queue

 **/

void logWorkQueueStats(const struct simpleWorkQueue *queue);

/**

 * Format the thread lifetime, run time, and suspend time into a

 * supplied buffer for reporting via sysfs.

 *

 * @param [in]  stats   The stats structure containing the run-time info

 * @param [out] buffer  The buffer in which to report the info

 **/

ssize_t formatRunTimeStats(const KvdoWorkQueueStats *stats, char *buffer);

#endif // WORK_QUEUE_STATS_H