/*
* 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 */