src/base/stats/storage.hh - public/gem5 - Git at Google

 /*
  * Copyright (c) 2021 Daniel R. Carvalho
  * Copyright (c) 2003-2005 The Regents of The University of Michigan
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
  * met: redistributions of source code must retain the above copyright
  * notice, this list of conditions and the following disclaimer;
  * redistributions in binary form must reproduce the above copyright
  * notice, this list of conditions and the following disclaimer in the
  * documentation and/or other materials provided with the distribution;
  * neither the name of the copyright holders nor the names of its
  * contributors may be used to endorse or promote products derived from
  * this software without specific prior written permission.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */

 #ifndef __BASE_STATS_STORAGE_HH__
 #define __BASE_STATS_STORAGE_HH__

 #include <cassert>
 #include <cmath>

 #include "base/cast.hh"
 #include "base/compiler.hh"
 #include "base/logging.hh"
 #include "base/stats/types.hh"
 #include "sim/cur_tick.hh"

 namespace gem5
 {

 namespace statistics
 {

 struct StorageParams
 {
     virtual ~StorageParams() = default;
 };

 /**
  * Templatized storage and interface for a simple scalar stat.
  */
 class StatStor
 {
   private:
     /** The statistic value. */
     Counter data;

   public:
     struct Params : public StorageParams {};

     /**
      * Builds this storage element and calls the base constructor of the
      * datatype.
      */
     StatStor(const StorageParams* const storage_params)
         : data(Counter())
     { }

     /**
      * The the stat to the given value.
      * @param val The new value.
      */
     void set(Counter val) { data = val; }

     /**
      * Increment the stat by the given value.
      * @param val The new value.
      */
     void inc(Counter val) { data += val; }

     /**
      * Decrement the stat by the given value.
      * @param val The new value.
      */
     void dec(Counter val) { data -= val; }

     /**
      * Return the value of this stat as its base type.
      * @return The value of this stat.
      */
     Counter value() const { return data; }

     /**
      * Return the value of this stat as a result type.
      * @return The value of this stat.
      */
     Result result() const { return (Result)data; }

     /**
      * Prepare stat data for dumping or serialization
      */
     void prepare(const StorageParams* const storage_params) { }

     /**
      * Reset stat value to default
      */
     void reset(const StorageParams* const storage_params) { data = Counter(); }

     /**
      * @return true if zero value
      */
     bool zero() const { return data == Counter(); }
 };

 /**
  * Templatized storage and interface to a per-tick average stat. This keeps
  * a current count and updates a total (count * ticks) when this count
  * changes. This allows the quick calculation of a per tick count of the item
  * being watched. This is good for keeping track of residencies in structures
  * among other things.
  */
 class AvgStor
 {
   private:
     /** The current count. */
     Counter current;
     /** The tick of the last reset */
     Tick lastReset;
     /** The total count for all tick. */
     mutable Result total;
     /** The tick that current last changed. */
     mutable Tick last;

   public:
     struct Params : public StorageParams {};

     /**
      * Build and initializes this stat storage.
      */
     AvgStor(const StorageParams* const storage_params)
         : current(0), lastReset(0), total(0), last(0)
     { }

     /**
      * Set the current count to the one provided, update the total and last
      * set values.
      * @param val The new count.
      */
     void
     set(Counter val)
     {
         total += current * (curTick() - last);
         last = curTick();
         current = val;
     }

     /**
      * Increment the current count by the provided value, calls set.
      * @param val The amount to increment.
      */
     void inc(Counter val) { set(current + val); }

     /**
      * Deccrement the current count by the provided value, calls set.
      * @param val The amount to decrement.
      */
     void dec(Counter val) { set(current - val); }

     /**
      * Return the current count.
      * @return The current count.
      */
     Counter value() const { return current; }

     /**
      * Return the current average.
      * @return The current average.
      */
     Result
     result() const
     {
         assert(last == curTick());
         return (Result)(total + current) / (Result)(curTick() - lastReset + 1);
     }

     /**
      * @return true if zero value
      */
     bool zero() const { return total == 0.0; }

     /**
      * Prepare stat data for dumping or serialization
      */
     void
     prepare(const StorageParams* const storage_params)
     {
         total += current * (curTick() - last);
         last = curTick();
     }

     /**
      * Reset stat value to default
      */
     void
     reset(const StorageParams* const storage_params)
     {
         total = 0.0;
         last = curTick();
         lastReset = curTick();
     }

 };

 /** The parameters for a distribution stat. */
 struct DistParams : public StorageParams
 {
     const DistType type;
     DistParams(DistType t) : type(t) {}
 };

 /**
  * Templatized storage and interface for a distribution stat. A distribution
  * uses buckets to keep track of values within a given range. All other
  * values, although accounted for on the overall calculations, are not tracked
  * in buckets themselves; two special counters, underflow and overflow store
  * the number of occurrences of such values.
  */
 class DistStor
 {
   private:
     /** The minimum value to track. */
     Counter min_track;
     /** The maximum value to track. */
     Counter max_track;
     /** The number of entries in each bucket. */
     Counter bucket_size;

     /** The smallest value sampled. */
     Counter min_val;
     /** The largest value sampled. */
     Counter max_val;
     /** The number of values sampled less than min. */
     Counter underflow;
     /** The number of values sampled more than max. */
     Counter overflow;
     /** The current sum. */
     Counter sum;
     /** The sum of squares. */
     Counter squares;
     /** The number of samples. */
     Counter samples;
     /** Counter for each bucket. */
     VCounter cvec;

   public:
     /** The parameters for a distribution stat. */
     struct Params : public DistParams
     {
         /** The minimum value to track. */
         Counter min;
         /** The maximum value to track. */
         Counter max;
         /** The number of entries in each bucket. */
         Counter bucket_size;
         /** The number of buckets. Equal to (max-min)/bucket_size. */
         size_type buckets;

         Params(Counter _min, Counter _max, Counter _bucket_size)
           : DistParams(Dist), min(_min), max(_max), bucket_size(_bucket_size),
             buckets(0)
         {
             fatal_if(bucket_size <= 0,
                 "Bucket size (%f) must be greater than zero", bucket_size);
             warn_if(std::floor((max - min + 1.0) / bucket_size) !=
                 std::ceil((max - min + 1.0) / bucket_size),
                 "Bucket size (%f) does not divide range [%f:%f] into equal-" \
                 "sized buckets. Rounding up.", bucket_size, min + 1.0, max);

             buckets = std::ceil((max - min + 1.0) / bucket_size);
         }
     };

     DistStor(const StorageParams* const storage_params)
         : cvec(safe_cast<const Params *>(storage_params)->buckets)
     {
         reset(storage_params);
     }

     /**
      * Add a value to the distribution for the given number of times.
      * @param val The value to add.
      * @param number The number of times to add the value.
      */
     void sample(Counter val, int number);

     /**
      * Return the number of buckets in this distribution.
      * @return the number of buckets.
      */
     size_type size() const { return cvec.size(); }

     /**
      * Returns true if any calls to sample have been made.
      * @return True if any values have been sampled.
      */
     bool
     zero() const
     {
         return samples == Counter();
     }

     void
     prepare(const StorageParams* const storage_params, DistData &data)
     {
         const Params *params = safe_cast<const Params *>(storage_params);

         assert(params->type == Dist);
         data.type = params->type;
         data.min = params->min;
         data.max = params->max;
         data.bucket_size = params->bucket_size;

         data.min_val = (min_val == CounterLimits::max()) ? 0 : min_val;
         data.max_val = (max_val == CounterLimits::min()) ? 0 : max_val;
         data.underflow = underflow;
         data.overflow = overflow;

         data.cvec.resize(params->buckets);
         for (off_type i = 0; i < params->buckets; ++i)
             data.cvec[i] = cvec[i];

         data.sum = sum;
         data.squares = squares;
         data.samples = samples;
     }

     /**
      * Reset stat value to default
      */
     void
     reset(const StorageParams* const storage_params)
     {
         const Params *params = safe_cast<const Params *>(storage_params);
         min_track = params->min;
         max_track = params->max;
         bucket_size = params->bucket_size;

         min_val = CounterLimits::max();
         max_val = CounterLimits::min();
         underflow = Counter();
         overflow = Counter();

         size_type size = cvec.size();
         for (off_type i = 0; i < size; ++i)
             cvec[i] = Counter();

         sum = Counter();
         squares = Counter();
         samples = Counter();
     }
 };

 /**
  * Templatized storage and interface for a histogram stat.
  *
  * The number of buckets is fixed on initialization; however, the bucket size
  * isn't. That means that when samples that are outside the current range are
  * seen, the bucket size will be increased so that each bucket can hold a
  * bigger range of values. When that happens, the bucket's contents are re-
  * located.
  *
  * The min and max bucket values can only be, respectively, decreased and
  * increased when sampling. If this wasn't true, samples that were previously
  * within the buclet range could not be anymore within the valid range, making
  * the storage's state incoherent. These values are set back to their initial
  * states on reset().
  *
  * The bucket range always is zero-centric. While the storage does not
  * contain negative values the bucket range will keep its lower bound at
  * zero, doubling the upper bound when needed; However, as soon a negative
  * value is sampled, zero becomes the lower bound of the middle (rounded up)
  * bucket. Although this means that the histogram will not be symmetric if
  * negative values are sampled, it makes it possible to grow the buckets
  * without keeping track of the individual values.
  *
  * This happens because if zero was not a lower or upper bound, when its
  * value was doubled, the lower and upper bound of the bucket containing
  * zero would intersect with middle values of the previous and next buckets.
  * For example, if the bucket containing zero has range [-2,2[, therefore
  * its neighbor buckets would have ranges at [-6,-2[ and [2,6[. When the
  * buckets are grown, the zero bucket would grow its range to [-4,4[, which
  * cannot be easily extracted from the neighor buckets.
  */
 class HistStor
 {
   private:
     /** Lower bound of the first bucket's range. */
     Counter min_bucket;
     /** Lower bound of the last bucket's range. */
     Counter max_bucket;
     /** The number of entries in each bucket. */
     Counter bucket_size;

     /** The current sum. */
     Counter sum;
     /** The sum of logarithm of each sample, used to compute geometric mean. */
     Counter logs;
     /** The sum of squares. */
     Counter squares;
     /** The number of samples. */
     Counter samples;
     /** Counter for each bucket. */
     VCounter cvec;

     /**
      * Given a bucket size B, and a range of values [0, N], this function
      * doubles the bucket size to double the range of values towards the
      * positive infinite; that is, double the upper range of this storage
      * so that the range becomes [0, 2*N].
      *
      * Because the bucket size is doubled, the buckets contents are rearranged,
      * since the original range of values is mapped to the lower half buckets.
      */
     void growUp();

     /**
      * Given a bucket size B, and a range of values [M, N], where M < 0, this
      * function doubles the bucket size to double the range of values towards
      * both positive and negative infinites; that is, it doubles both the lower
      * and the upper range of this storage so that the range becomes
      * [2*M, 2*N].
      *
      * Because the bucket size is doubled, the buckets contents are
      * rearranged, and the original range of values are redistributed to free
      * buckets for the newly appended ranges.
      */
     void growOut();

     /**
      * Given a bucket size B, and a range of values [0, N], this function
      * doubles the bucket size to double the range of values towards the
      * negative infinite; that is, it doubles the lower range of this
      * storage so that the middle buckes contaihs zero as a lower bound. As
      * such, the storage range becomes [-N, N+B] if there is an odd number
      * of buckets, and [-N-B, N+B] if there is an even number of buckets.
      *
      * Because the bucket size is doubled, the buckets contents are
      * rearranged, and the original range of values are redistributed to free
      * buckets for the newly appended ranges.
      */
     void growDown();

   public:
     /** The parameters for a distribution stat. */
     struct Params : public DistParams
     {
         /** The number of buckets. */
         size_type buckets;

         Params(size_type _buckets)
           : DistParams(Hist)
         {
             fatal_if(_buckets < 2,
                 "There must be at least two buckets in a histogram");
             buckets = _buckets;
         }
     };

     HistStor(const StorageParams* const storage_params)
         : cvec(safe_cast<const Params *>(storage_params)->buckets)
     {
         reset(storage_params);
     }

     /**
      * Adds the contents of the given storage to this storage.
      * @param other The other storage to be added.
      */
     void add(HistStor *other);

     /**
      * Add a value to the distribution for the given number of times.
      * @param val The value to add.
      * @param number The number of times to add the value.
      */
     void sample(Counter val, int number);

     /**
      * Return the number of buckets in this distribution.
      * @return the number of buckets.
      */
     size_type size() const { return cvec.size(); }

     /**
      * Returns true if any calls to sample have been made.
      * @return True if any values have been sampled.
      */
     bool
     zero() const
     {
         return samples == Counter();
     }

     void
     prepare(const StorageParams* const storage_params, DistData &data)
     {
         const Params *params = safe_cast<const Params *>(storage_params);

         assert(params->type == Hist);
         data.type = params->type;
         data.min = min_bucket;
         data.max = max_bucket + bucket_size - 1;
         data.bucket_size = bucket_size;

         data.min_val = min_bucket;
         data.max_val = max_bucket;

         int buckets = params->buckets;
         data.cvec.resize(buckets);
         for (off_type i = 0; i < buckets; ++i)
             data.cvec[i] = cvec[i];

         data.sum = sum;
         data.logs = logs;
         data.squares = squares;
         data.samples = samples;
     }

     /**
      * Reset stat value to default
      */
     void
     reset(const StorageParams* const storage_params)
     {
         const Params *params = safe_cast<const Params *>(storage_params);
         min_bucket = 0;
         max_bucket = params->buckets - 1;
         bucket_size = 1;

         size_type size = cvec.size();
         for (off_type i = 0; i < size; ++i)
             cvec[i] = Counter();

         sum = Counter();
         squares = Counter();
         samples = Counter();
         logs = Counter();
     }
 };

 /**
  * Templatized storage and interface for a distribution that calculates mean
  * and variance.
  */
 class SampleStor
 {
   private:
     /** The current sum. */
     Counter sum;
     /** The sum of squares. */
     Counter squares;
     /** The number of samples. */
     Counter samples;

   public:
     struct Params : public DistParams
     {
         Params() : DistParams(Deviation) {}
     };

     /**
      * Create and initialize this storage.
      */
     SampleStor(const StorageParams* const storage_params)
         : sum(Counter()), squares(Counter()), samples(Counter())
     { }

     /**
      * Add a value the given number of times to this running average.
      * Update the running sum and sum of squares, increment the number of
      * values seen by the given number.
      * @param val The value to add.
      * @param number The number of times to add the value.
      */
     void
     sample(Counter val, int number)
     {
         sum += val * number;
         squares += val * val * number;
         samples += number;
     }

     /**
      * Return the number of entries in this stat, 1
      * @return 1.
      */
     size_type size() const { return 1; }

     /**
      * Return true if no samples have been added.
      * @return True if no samples have been added.
      */
     bool zero() const { return samples == Counter(); }

     void
     prepare(const StorageParams* const storage_params, DistData &data)
     {
         const Params *params = safe_cast<const Params *>(storage_params);

         assert(params->type == Deviation);
         data.type = params->type;
         data.sum = sum;
         data.squares = squares;
         data.samples = samples;
     }

     /**
      * Reset stat value to default
      */
     void
     reset(const StorageParams* const storage_params)
     {
         sum = Counter();
         squares = Counter();
         samples = Counter();
     }
 };

 /**
  * Templatized storage for distribution that calculates per tick mean and
  * variance.
  */
 class AvgSampleStor
 {
   private:
     /** Current total. */
     Counter sum;
     /** Current sum of squares. */
     Counter squares;

   public:
     struct Params : public DistParams
     {
         Params() : DistParams(Deviation) {}
     };

     /**
      * Create and initialize this storage.
      */
     AvgSampleStor(const StorageParams* const storage_params)
         : sum(Counter()), squares(Counter())
     {}

     /**
      * Add a value to the distribution for the given number of times.
      * Update the running sum and sum of squares.
      * @param val The value to add.
      * @param number The number of times to add the value.
      */
     void
     sample(Counter val, int number)
     {
         sum += val * number;
         squares += val * val * number;
     }

     /**
      * Return the number of entries, in this case 1.
      * @return 1.
      */
     size_type size() const { return 1; }

     /**
      * Return true if no samples have been added.
      * @return True if the sum is zero.
      */
     bool zero() const { return sum == Counter(); }

     void
     prepare(const StorageParams* const storage_params, DistData &data)
     {
         const Params *params = safe_cast<const Params *>(storage_params);

         assert(params->type == Deviation);
         data.type = params->type;
         data.sum = sum;
         data.squares = squares;
         data.samples = curTick();
     }

     /**
      * Reset stat value to default
      */
     void
     reset(const StorageParams* const storage_params)
     {
         sum = Counter();
         squares = Counter();
     }
 };

 /**
  * Templatized storage and interface for a sparse histogram stat. There
  * is no actual limit on the number of buckets, and each of them has a size
  * of 1, meaning that samples are individually recorded, and there is no
  * need to keep track of the samples that occur in between two distant
  * sampled values.
  */
 class SparseHistStor
 {
   private:
     /** Counter for number of samples */
     Counter samples;
     /** Counter for each bucket. */
     MCounter cmap;

   public:
     /** The parameters for a sparse histogram stat. */
     struct Params : public DistParams
     {
         Params() : DistParams(Hist) {}
     };

     SparseHistStor(const StorageParams* const storage_params)
     {
         reset(storage_params);
     }

     /**
      * Add a value to the distribution for the given number of times.
      * @param val The value to add.
      * @param number The number of times to add the value.
      */
     void
     sample(Counter val, int number)
     {
         cmap[val] += number;
         samples += number;
     }

     /**
      * Return the number of buckets in this distribution.
      * @return the number of buckets.
      */
     size_type size() const { return cmap.size(); }

     /**
      * Returns true if any calls to sample have been made.
      * @return True if any values have been sampled.
      */
     bool
     zero() const
     {
         return samples == Counter();
     }

     void
     prepare(const StorageParams* const storage_params, SparseHistData &data)
     {
         MCounter::iterator it;
         data.cmap.clear();
         for (it = cmap.begin(); it != cmap.end(); it++) {
             data.cmap[(*it).first] = (*it).second;
         }

         data.samples = samples;
     }

     /**
      * Reset stat value to default
      */
     void
     reset(const StorageParams* const storage_params)
     {
         cmap.clear();
         samples = 0;
     }
 };

 } // namespace statistics
 } // namespace gem5

 #endif // __BASE_STATS_STORAGE_HH__
	/*
	* Copyright (c) 2021 Daniel R. Carvalho
	* Copyright (c) 2003-2005 The Regents of The University of Michigan
	* All rights reserved.
	*
	* Redistribution and use in source and binary forms, with or without
	* modification, are permitted provided that the following conditions are
	* met: redistributions of source code must retain the above copyright
	* notice, this list of conditions and the following disclaimer;
	* redistributions in binary form must reproduce the above copyright
	* notice, this list of conditions and the following disclaimer in the
	* documentation and/or other materials provided with the distribution;
	* neither the name of the copyright holders nor the names of its
	* contributors may be used to endorse or promote products derived from
	* this software without specific prior written permission.
	*
	* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
	* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
	* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
	* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
	* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
	* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
	* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
	* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
	* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	*/

	#ifndef __BASE_STATS_STORAGE_HH__
	#define __BASE_STATS_STORAGE_HH__

	#include <cassert>
	#include <cmath>

	#include "base/cast.hh"
	#include "base/compiler.hh"
	#include "base/logging.hh"
	#include "base/stats/types.hh"
	#include "sim/cur_tick.hh"

	namespace gem5
	{

	namespace statistics
	{

	struct StorageParams
	{
	virtual ~StorageParams() = default;
	};

	/**
	* Templatized storage and interface for a simple scalar stat.
	*/
	class StatStor
	{
	private:
	/** The statistic value. */
	Counter data;

	public:
	struct Params : public StorageParams {};

	/**
	* Builds this storage element and calls the base constructor of the
	* datatype.
	*/
	StatStor(const StorageParams* const storage_params)
	: data(Counter())
	{ }

	/**
	* The the stat to the given value.
	* @param val The new value.
	*/
	void set(Counter val) { data = val; }

	/**
	* Increment the stat by the given value.
	* @param val The new value.
	*/
	void inc(Counter val) { data += val; }

	/**
	* Decrement the stat by the given value.
	* @param val The new value.
	*/
	void dec(Counter val) { data -= val; }

	/**
	* Return the value of this stat as its base type.
	* @return The value of this stat.
	*/
	Counter value() const { return data; }

	/**
	* Return the value of this stat as a result type.
	* @return The value of this stat.
	*/
	Result result() const { return (Result)data; }

	/**
	* Prepare stat data for dumping or serialization
	*/
	void prepare(const StorageParams* const storage_params) { }

	/**
	* Reset stat value to default
	*/
	void reset(const StorageParams* const storage_params) { data = Counter(); }

	/**
	* @return true if zero value
	*/
	bool zero() const { return data == Counter(); }
	};

	/**
	* Templatized storage and interface to a per-tick average stat. This keeps
	* a current count and updates a total (count * ticks) when this count
	* changes. This allows the quick calculation of a per tick count of the item
	* being watched. This is good for keeping track of residencies in structures
	* among other things.
	*/
	class AvgStor
	{
	private:
	/** The current count. */
	Counter current;
	/** The tick of the last reset */
	Tick lastReset;
	/** The total count for all tick. */
	mutable Result total;
	/** The tick that current last changed. */
	mutable Tick last;

	public:
	struct Params : public StorageParams {};

	/**
	* Build and initializes this stat storage.
	*/
	AvgStor(const StorageParams* const storage_params)
	: current(0), lastReset(0), total(0), last(0)
	{ }

	/**
	* Set the current count to the one provided, update the total and last
	* set values.
	* @param val The new count.
	*/
	void
	set(Counter val)
	{
	total += current * (curTick() - last);
	last = curTick();
	current = val;
	}

	/**
	* Increment the current count by the provided value, calls set.
	* @param val The amount to increment.
	*/
	void inc(Counter val) { set(current + val); }

	/**
	* Deccrement the current count by the provided value, calls set.
	* @param val The amount to decrement.
	*/
	void dec(Counter val) { set(current - val); }

	/**
	* Return the current count.
	* @return The current count.
	*/
	Counter value() const { return current; }

	/**
	* Return the current average.
	* @return The current average.
	*/
	Result
	result() const
	{
	assert(last == curTick());
	return (Result)(total + current) / (Result)(curTick() - lastReset + 1);
	}

	/**
	* @return true if zero value
	*/
	bool zero() const { return total == 0.0; }

	/**
	* Prepare stat data for dumping or serialization
	*/
	void
	prepare(const StorageParams* const storage_params)
	{
	total += current * (curTick() - last);
	last = curTick();
	}

	/**
	* Reset stat value to default
	*/
	void
	reset(const StorageParams* const storage_params)
	{
	total = 0.0;
	last = curTick();
	lastReset = curTick();
	}

	};

	/** The parameters for a distribution stat. */
	struct DistParams : public StorageParams
	{
	const DistType type;
	DistParams(DistType t) : type(t) {}
	};

	/**
	* Templatized storage and interface for a distribution stat. A distribution
	* uses buckets to keep track of values within a given range. All other
	* values, although accounted for on the overall calculations, are not tracked
	* in buckets themselves; two special counters, underflow and overflow store
	* the number of occurrences of such values.
	*/
	class DistStor
	{
	private:
	/** The minimum value to track. */
	Counter min_track;
	/** The maximum value to track. */
	Counter max_track;
	/** The number of entries in each bucket. */
	Counter bucket_size;

	/** The smallest value sampled. */
	Counter min_val;
	/** The largest value sampled. */
	Counter max_val;
	/** The number of values sampled less than min. */
	Counter underflow;
	/** The number of values sampled more than max. */
	Counter overflow;
	/** The current sum. */
	Counter sum;
	/** The sum of squares. */
	Counter squares;
	/** The number of samples. */
	Counter samples;
	/** Counter for each bucket. */
	VCounter cvec;

	public:
	/** The parameters for a distribution stat. */
	struct Params : public DistParams
	{
	/** The minimum value to track. */
	Counter min;
	/** The maximum value to track. */
	Counter max;
	/** The number of entries in each bucket. */
	Counter bucket_size;
	/** The number of buckets. Equal to (max-min)/bucket_size. */
	size_type buckets;

	Params(Counter _min, Counter _max, Counter _bucket_size)
	: DistParams(Dist), min(_min), max(_max), bucket_size(_bucket_size),
	buckets(0)
	{
	fatal_if(bucket_size <= 0,
	"Bucket size (%f) must be greater than zero", bucket_size);
	warn_if(std::floor((max - min + 1.0) / bucket_size) !=
	std::ceil((max - min + 1.0) / bucket_size),
	"Bucket size (%f) does not divide range [%f:%f] into equal-" \
	"sized buckets. Rounding up.", bucket_size, min + 1.0, max);

	buckets = std::ceil((max - min + 1.0) / bucket_size);
	}
	};

	DistStor(const StorageParams* const storage_params)
	: cvec(safe_cast<const Params *>(storage_params)->buckets)
	{
	reset(storage_params);
	}

	/**
	* Add a value to the distribution for the given number of times.
	* @param val The value to add.
	* @param number The number of times to add the value.
	*/
	void sample(Counter val, int number);

	/**
	* Return the number of buckets in this distribution.
	* @return the number of buckets.
	*/
	size_type size() const { return cvec.size(); }

	/**
	* Returns true if any calls to sample have been made.
	* @return True if any values have been sampled.
	*/
	bool
	zero() const
	{
	return samples == Counter();
	}

	void
	prepare(const StorageParams* const storage_params, DistData &data)
	{
	const Params params = safe_cast<const Params >(storage_params);

	assert(params->type == Dist);
	data.type = params->type;
	data.min = params->min;
	data.max = params->max;
	data.bucket_size = params->bucket_size;

	data.min_val = (min_val == CounterLimits::max()) ? 0 : min_val;
	data.max_val = (max_val == CounterLimits::min()) ? 0 : max_val;
	data.underflow = underflow;
	data.overflow = overflow;

	data.cvec.resize(params->buckets);
	for (off_type i = 0; i < params->buckets; ++i)
	data.cvec[i] = cvec[i];

	data.sum = sum;
	data.squares = squares;
	data.samples = samples;
	}

	/**
	* Reset stat value to default
	*/
	void
	reset(const StorageParams* const storage_params)
	{
	const Params params = safe_cast<const Params >(storage_params);
	min_track = params->min;
	max_track = params->max;
	bucket_size = params->bucket_size;

	min_val = CounterLimits::max();
	max_val = CounterLimits::min();
	underflow = Counter();
	overflow = Counter();

	size_type size = cvec.size();
	for (off_type i = 0; i < size; ++i)
	cvec[i] = Counter();

	sum = Counter();
	squares = Counter();
	samples = Counter();
	}
	};

	/**
	* Templatized storage and interface for a histogram stat.
	*
	* The number of buckets is fixed on initialization; however, the bucket size
	* isn't. That means that when samples that are outside the current range are
	* seen, the bucket size will be increased so that each bucket can hold a
	* bigger range of values. When that happens, the bucket's contents are re-
	* located.
	*
	* The min and max bucket values can only be, respectively, decreased and
	* increased when sampling. If this wasn't true, samples that were previously
	* within the buclet range could not be anymore within the valid range, making
	* the storage's state incoherent. These values are set back to their initial
	* states on reset().
	*
	* The bucket range always is zero-centric. While the storage does not
	* contain negative values the bucket range will keep its lower bound at
	* zero, doubling the upper bound when needed; However, as soon a negative
	* value is sampled, zero becomes the lower bound of the middle (rounded up)
	* bucket. Although this means that the histogram will not be symmetric if
	* negative values are sampled, it makes it possible to grow the buckets
	* without keeping track of the individual values.
	*
	* This happens because if zero was not a lower or upper bound, when its
	* value was doubled, the lower and upper bound of the bucket containing
	* zero would intersect with middle values of the previous and next buckets.
	* For example, if the bucket containing zero has range [-2,2[, therefore
	* its neighbor buckets would have ranges at [-6,-2[ and [2,6[. When the
	* buckets are grown, the zero bucket would grow its range to [-4,4[, which
	* cannot be easily extracted from the neighor buckets.
	*/
	class HistStor
	{
	private:
	/** Lower bound of the first bucket's range. */
	Counter min_bucket;
	/** Lower bound of the last bucket's range. */
	Counter max_bucket;
	/** The number of entries in each bucket. */
	Counter bucket_size;

	/** The current sum. */
	Counter sum;
	/** The sum of logarithm of each sample, used to compute geometric mean. */
	Counter logs;
	/** The sum of squares. */
	Counter squares;
	/** The number of samples. */
	Counter samples;
	/** Counter for each bucket. */
	VCounter cvec;

	/**
	* Given a bucket size B, and a range of values [0, N], this function
	* doubles the bucket size to double the range of values towards the
	* positive infinite; that is, double the upper range of this storage
	* so that the range becomes [0, 2*N].
	*
	* Because the bucket size is doubled, the buckets contents are rearranged,
	* since the original range of values is mapped to the lower half buckets.
	*/
	void growUp();

	/**
	* Given a bucket size B, and a range of values [M, N], where M < 0, this
	* function doubles the bucket size to double the range of values towards
	* both positive and negative infinites; that is, it doubles both the lower
	* and the upper range of this storage so that the range becomes
	* [2M, 2N].
	*
	* Because the bucket size is doubled, the buckets contents are
	* rearranged, and the original range of values are redistributed to free
	* buckets for the newly appended ranges.
	*/
	void growOut();

	/**
	* Given a bucket size B, and a range of values [0, N], this function
	* doubles the bucket size to double the range of values towards the
	* negative infinite; that is, it doubles the lower range of this
	* storage so that the middle buckes contaihs zero as a lower bound. As
	* such, the storage range becomes [-N, N+B] if there is an odd number
	* of buckets, and [-N-B, N+B] if there is an even number of buckets.
	*
	* Because the bucket size is doubled, the buckets contents are
	* rearranged, and the original range of values are redistributed to free
	* buckets for the newly appended ranges.
	*/
	void growDown();

	public:
	/** The parameters for a distribution stat. */
	struct Params : public DistParams
	{
	/** The number of buckets. */
	size_type buckets;

	Params(size_type _buckets)
	: DistParams(Hist)
	{
	fatal_if(_buckets < 2,
	"There must be at least two buckets in a histogram");
	buckets = _buckets;
	}
	};

	HistStor(const StorageParams* const storage_params)
	: cvec(safe_cast<const Params *>(storage_params)->buckets)
	{
	reset(storage_params);
	}

	/**
	* Adds the contents of the given storage to this storage.
	* @param other The other storage to be added.
	*/
	void add(HistStor *other);

	/**
	* Add a value to the distribution for the given number of times.
	* @param val The value to add.
	* @param number The number of times to add the value.
	*/
	void sample(Counter val, int number);

	/**
	* Return the number of buckets in this distribution.
	* @return the number of buckets.
	*/
	size_type size() const { return cvec.size(); }

	/**
	* Returns true if any calls to sample have been made.
	* @return True if any values have been sampled.
	*/
	bool
	zero() const
	{
	return samples == Counter();
	}

	void
	prepare(const StorageParams* const storage_params, DistData &data)
	{
	const Params params = safe_cast<const Params >(storage_params);

	assert(params->type == Hist);
	data.type = params->type;
	data.min = min_bucket;
	data.max = max_bucket + bucket_size - 1;
	data.bucket_size = bucket_size;

	data.min_val = min_bucket;
	data.max_val = max_bucket;

	int buckets = params->buckets;
	data.cvec.resize(buckets);
	for (off_type i = 0; i < buckets; ++i)
	data.cvec[i] = cvec[i];

	data.sum = sum;
	data.logs = logs;
	data.squares = squares;
	data.samples = samples;
	}

	/**
	* Reset stat value to default
	*/
	void
	reset(const StorageParams* const storage_params)
	{
	const Params params = safe_cast<const Params >(storage_params);
	min_bucket = 0;
	max_bucket = params->buckets - 1;
	bucket_size = 1;

	size_type size = cvec.size();
	for (off_type i = 0; i < size; ++i)
	cvec[i] = Counter();

	sum = Counter();
	squares = Counter();
	samples = Counter();
	logs = Counter();
	}
	};

	/**
	* Templatized storage and interface for a distribution that calculates mean
	* and variance.
	*/
	class SampleStor
	{
	private:
	/** The current sum. */
	Counter sum;
	/** The sum of squares. */
	Counter squares;
	/** The number of samples. */
	Counter samples;

	public:
	struct Params : public DistParams
	{
	Params() : DistParams(Deviation) {}
	};

	/**
	* Create and initialize this storage.
	*/
	SampleStor(const StorageParams* const storage_params)
	: sum(Counter()), squares(Counter()), samples(Counter())
	{ }

	/**
	* Add a value the given number of times to this running average.
	* Update the running sum and sum of squares, increment the number of
	* values seen by the given number.
	* @param val The value to add.
	* @param number The number of times to add the value.
	*/
	void
	sample(Counter val, int number)
	{
	sum += val * number;
	squares += val * val * number;
	samples += number;
	}

	/**
	* Return the number of entries in this stat, 1
	* @return 1.
	*/
	size_type size() const { return 1; }

	/**
	* Return true if no samples have been added.
	* @return True if no samples have been added.
	*/
	bool zero() const { return samples == Counter(); }

	void
	prepare(const StorageParams* const storage_params, DistData &data)
	{
	const Params params = safe_cast<const Params >(storage_params);

	assert(params->type == Deviation);
	data.type = params->type;
	data.sum = sum;
	data.squares = squares;
	data.samples = samples;
	}

	/**
	* Reset stat value to default
	*/
	void
	reset(const StorageParams* const storage_params)
	{
	sum = Counter();
	squares = Counter();
	samples = Counter();
	}
	};

	/**
	* Templatized storage for distribution that calculates per tick mean and
	* variance.
	*/
	class AvgSampleStor
	{
	private:
	/** Current total. */
	Counter sum;
	/** Current sum of squares. */
	Counter squares;

	public:
	struct Params : public DistParams
	{
	Params() : DistParams(Deviation) {}
	};

	/**
	* Create and initialize this storage.
	*/
	AvgSampleStor(const StorageParams* const storage_params)
	: sum(Counter()), squares(Counter())
	{}

	/**
	* Add a value to the distribution for the given number of times.
	* Update the running sum and sum of squares.
	* @param val The value to add.
	* @param number The number of times to add the value.
	*/
	void
	sample(Counter val, int number)
	{
	sum += val * number;
	squares += val * val * number;
	}

	/**
	* Return the number of entries, in this case 1.
	* @return 1.
	*/
	size_type size() const { return 1; }

	/**
	* Return true if no samples have been added.
	* @return True if the sum is zero.
	*/
	bool zero() const { return sum == Counter(); }

	void
	prepare(const StorageParams* const storage_params, DistData &data)
	{
	const Params params = safe_cast<const Params >(storage_params);

	assert(params->type == Deviation);
	data.type = params->type;
	data.sum = sum;
	data.squares = squares;
	data.samples = curTick();
	}

	/**
	* Reset stat value to default
	*/
	void
	reset(const StorageParams* const storage_params)
	{
	sum = Counter();
	squares = Counter();
	}
	};

	/**
	* Templatized storage and interface for a sparse histogram stat. There
	* is no actual limit on the number of buckets, and each of them has a size
	* of 1, meaning that samples are individually recorded, and there is no
	* need to keep track of the samples that occur in between two distant
	* sampled values.
	*/
	class SparseHistStor
	{
	private:
	/** Counter for number of samples */
	Counter samples;
	/** Counter for each bucket. */
	MCounter cmap;

	public:
	/** The parameters for a sparse histogram stat. */
	struct Params : public DistParams
	{
	Params() : DistParams(Hist) {}
	};

	SparseHistStor(const StorageParams* const storage_params)
	{
	reset(storage_params);
	}

	/**
	* Add a value to the distribution for the given number of times.
	* @param val The value to add.
	* @param number The number of times to add the value.
	*/
	void
	sample(Counter val, int number)
	{
	cmap[val] += number;
	samples += number;
	}

	/**
	* Return the number of buckets in this distribution.
	* @return the number of buckets.
	*/
	size_type size() const { return cmap.size(); }

	/**
	* Returns true if any calls to sample have been made.
	* @return True if any values have been sampled.
	*/
	bool
	zero() const
	{
	return samples == Counter();
	}

	void
	prepare(const StorageParams* const storage_params, SparseHistData &data)
	{
	MCounter::iterator it;
	data.cmap.clear();
	for (it = cmap.begin(); it != cmap.end(); it++) {
	data.cmap[(it).first] = (it).second;
	}

	data.samples = samples;
	}

	/**
	* Reset stat value to default
	*/
	void
	reset(const StorageParams* const storage_params)
	{
	cmap.clear();
	samples = 0;
	}
	};

	} // namespace statistics
	} // namespace gem5

	#endif // __BASE_STATS_STORAGE_HH__