/*

 * 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/histogram.h#1 $

 */

#ifndef HISTOGRAM_H

#define HISTOGRAM_H

#include <linux/types.h>

typedef struct histogram Histogram;

/**

 * Allocate and initialize a histogram that uses linearly sized buckets.

 *

 * The histogram label reported via /sys is constructed from several of the

 * values passed here; it will be something like "Init Label Histogram - number

 * of countedItems grouped by metric (sampleUnits)", e.g., "Flush Forwarding

 * Histogram - number of flushes grouped by latency (milliseconds)". Thus

 * countedItems and sampleUnits should be plural.

 *

 * The sampleUnits string will also be reported separately via another /sys

 * entry to aid in programmatic processing of the results, so the strings used

 * should be consistent (e.g., always "milliseconds" and not "ms" for

 * milliseconds).

 *

 * @param parent       The parent kobject.

 * @param name         The short name of the histogram.  This label is used

 *                     for the sysfs node.

 * @param initLabel    The label for the sampled data.  This label is used

 *                     when we plot the data.

 * @param countedItems A name (plural) for the things being counted.

 * @param metric       The measure being used to divide samples into buckets.

 * @param sampleUnits  The unit (plural) for the metric, or NULL if it's a

 *                     simple counter.

 * @param size         The number of buckets.  There are buckets for every

 *                     value from 0 up to size (but not including) size.

 *                     There is an extra bucket for larger samples.

 *

 * @return the histogram

 **/

Histogram *makeLinearHistogram(struct kobject *parent,

                               const char     *name,

                               const char     *initLabel,

                               const char     *countedItems,

                               const char     *metric,

                               const char     *sampleUnits,

                               int             size);

/**

 * Allocate and initialize a histogram that uses logarithmically sized

 * buckets.

 *

 * @param parent       The parent kobject.

 * @param name         The short name of the histogram.  This label is used

 *                     for the sysfs node.

 * @param initLabel    The label for the sampled data.  This label is used

 *                     when we plot the data.

 * @param countedItems A name (plural) for the things being counted.

 * @param metric       The measure being used to divide samples into buckets.

 * @param sampleUnits  The unit (plural) for the metric, or NULL if it's a

 *                     simple counter.

 * @param logSize      The number of buckets.  There are buckets for a range

 *                     of sizes up to 10^logSize, and an extra bucket for

 *                     larger samples.

 *

 * @return the histogram

 **/

Histogram *makeLogarithmicHistogram(struct kobject *parent,

                                    const char     *name,

                                    const char     *initLabel,

                                    const char     *countedItems,

                                    const char     *metric,

                                    const char     *sampleUnits,

                                    int             logSize);

/**

 * Allocate and initialize a histogram that uses logarithmically sized

 * buckets. Values are entered that count in jiffies, and they are

 * reported in milliseconds.

 *

 * @param parent       The parent kobject.

 * @param name         The short name of the histogram.  This label is used

 *                     for the sysfs node.

 * @param initLabel    The label for the sampled data.  This label is used

 *                     when we plot the data.

 * @param countedItems A name (plural) for the things being counted.

 * @param metric       The measure being used to divide samples into buckets.

 * @param logSize      The number of buckets.  There are buckets for a range

 *                     of sizes up to 10^logSize, and an extra bucket for

 *                     larger samples.

 *

 * @return the histogram

 **/

Histogram *makeLogarithmicJiffiesHistogram(struct kobject *parent,

                                           const char     *name,

                                           const char     *initLabel,

                                           const char     *countedItems,

                                           const char     *metric,

                                           int             logSize);

/**

 * Enter a sample into a histogram

 *

 * @param h       The histogram

 * @param sample  The sample

 **/

void enterHistogramSample(Histogram *h, uint64_t sample);

/**

 * Free a histogram and null out the reference to it.

 *

 * @param hp  The reference to the histogram.

 **/

void freeHistogram(Histogram **hp);

#endif /* HISTOGRAM_H */