CycleHistogram.hpp

Go to the documentation of this file.

// <CycleHistogram.h> -*- C++ -*-
 
 
#pragma once
 
#include <iostream>
#include <string>
#include <vector>
#include <numeric>
#include "sparta/utils/MathUtils.hpp"
#include "sparta/simulation/TreeNode.hpp"
#include "sparta/utils/SpartaAssert.hpp"
#include "sparta/statistics/Counter.hpp"
#include "sparta/statistics/CycleCounter.hpp"
#include "sparta/statistics/StatisticDef.hpp"
#include "sparta/statistics/StatisticSet.hpp"
#include "sparta/simulation/Resource.hpp"
#include "sparta/utils/ValidValue.hpp"
 
namespace sparta
{
    class CycleHistogramBase
    {
    public:
 
        CycleHistogramBase() = delete;
 
        CycleHistogramBase(const CycleHistogramBase&) = delete;
 
        CycleHistogramBase(CycleHistogramBase&&) = delete;
 
        void operator=(const CycleHistogramBase&) = delete;
 
 
 
        void addValue(uint64_t val)
        {
            stopCounting_(last_value_);
            startCounting_(val);
            stopCounting_(val, 1);
            startCounting_(idle_value_, 1);
 
            updateMaxValues_(val);
        }
 
        double getStandardDeviation() const {
 
            // Summation of counts in normal bins plus underflow bin and
            // overflow bin.
            const double sum = std::accumulate(bin_.begin(), bin_.end(), 0.0)
                + (*underflow_bin_) + (*overflow_bin_);
 
            // Total number of bins is number of regular bins
            // plus one for underflow bin and plus one for
            // overflow bin.
            const std::size_t total_num_bins = bin_.size() + 2;
 
            const double mean = sum / total_num_bins;
            double accum = 0.0;
            std::for_each(bin_.begin(), bin_.end(), [&](const sparta::CycleCounter& c) {
                auto c_get = c.get();
                accum += pow(c_get - mean, 2);
            });
            accum += pow((*underflow_bin_ - mean), 2);
            accum += pow((*overflow_bin_ - mean), 2);
            return std::sqrt(accum / (total_num_bins - 1));
        }
 
        double getMeanBinCount() const {
 
            // Summation of counts in normal bins plus underflow bin and
            // overflow bin.
            const double sum = std::accumulate(bin_.begin(), bin_.end(), 0.0)
                + (*underflow_bin_) + (*overflow_bin_);
 
            // Total number of bins is number of regular bins
            // plus one for underflow bin and plus one for
            // overflow bin.
            const std::size_t total_num_bins = bin_.size() + 2;
 
            return  sum / total_num_bins;
        }
 
        const sparta::CycleCounter& getAggCycles() const{
            return *total_;
        }
 
        const std::vector<sparta::CycleCounter>& getRegularBin() const{
            return bin_;
        }
 
        const sparta::CycleCounter& getUnderflowBin() const{
            return *underflow_bin_;
        }
 
        const sparta::CycleCounter& getOverflowBin() const{
            return *overflow_bin_;
        }
 
        double getUnderflowProbability() const{
            return ((static_cast<double>(*underflow_bin_))/(static_cast<double>(*total_)));
        }
 
        double getOverflowProbability() const{
            return ((static_cast<double>(*overflow_bin_))/(static_cast<double>(*total_)));
        }
 
        const std::vector<double>& recomputeRegularBinProbabilities() const{
            bin_prob_vector_.clear();
            for(const auto& b : bin_){
                bin_prob_vector_.emplace_back(((static_cast<double>(b))/(static_cast<double>(*total_))));
            }
            return bin_prob_vector_;
        }
 
        void setValue(uint64_t val)
        {
            if (last_value_ != val) {
                stopCounting_(last_value_);
                startCounting_(val);
 
                updateMaxValues_(val);
            }
        }
 
 
        uint64_t getHistogramUpperValue() const { return upper_val_; }
        uint64_t getHistogramLowerValue() const { return lower_val_; }
        uint64_t getNumBins() const { return num_bins_; }
        uint64_t getNumValuesPerBin() const { return num_vals_per_bin_; }
 
    protected:
 
        CycleHistogramBase(const uint64_t lower_val,
                           const uint64_t upper_val,
                           const uint64_t num_vals_per_bin,
                           const uint64_t idle_value = 0) :
            lower_val_(lower_val),
            upper_val_(upper_val),
            num_vals_per_bin_(num_vals_per_bin),
            idle_value_(idle_value)
        {
            sparta_assert_context(upper_val > lower_val,
                                "CycleHistogramBase: upper value must be greater than lower value");
            sparta_assert_context(utils::is_power_of_2(num_vals_per_bin),
                                "CycleHistogramBase: num_vals_per_bin must be power of 2");
            idx_shift_amount_ = utils::floor_log2(num_vals_per_bin);  // for quick divide
            double actual_num_bins = (upper_val - lower_val)/num_vals_per_bin + 1;
            num_bins_ = (uint64_t) actual_num_bins;
            sparta_assert_context(actual_num_bins == num_bins_,
                                "CycleHistogramBase: Actual number of bins (" << actual_num_bins
                                << ") is not an integer");
        }
 
        std::string getDisplayStringCumulative_(const std::string &name) const
        {
            std::stringstream str;
            str << std::dec;
            uint64_t running_sum = *underflow_bin_;
            str << "\t" <<  name << "[ UF ] = " << running_sum << std::endl;
            uint64_t start_val = lower_val_;
            uint64_t end_val  = start_val + num_vals_per_bin_ - 1;
            for (uint64_t i = 0; i < num_bins_; ++i) {
                if (end_val > upper_val_) {
                    end_val = upper_val_;
                }
                running_sum +=  (bin_[i]);
                str << "\t" << name
                    << "[ " << start_val << "-" << end_val << " ] = "
                    << running_sum << '\n';
                end_val  += num_vals_per_bin_;
            }
            running_sum += *overflow_bin_;
            str << "\t" << name << "[ OF ] = " << running_sum << std::endl;
            return str.str();
        }
 
        void startCounting_(uint64_t val, uint64_t delay = 0)
        {
            if (val < lower_val_) {
                (*underflow_bin_).startCounting(delay);
            }
            else if (val > upper_val_) {
                (*overflow_bin_).startCounting(delay);
            }
            else {
                uint64_t idx = (val - lower_val_) >> idx_shift_amount_;
                (bin_.at(idx)).startCounting(delay);
            }
 
            last_value_ = val;
        }
 
        void stopCounting_(uint64_t val, uint64_t delay = 0)
        {
            if (val < lower_val_) {
                (*underflow_bin_).stopCounting(delay);
            }
            else if (val > upper_val_) {
                (*overflow_bin_).stopCounting(delay);
            }
            else {
                const uint64_t idx = (val - lower_val_) >> idx_shift_amount_;
                (bin_.at(idx)).stopCounting(delay);
            }
        }
 
        void updateMaxValues_(uint64_t val)
        {
            if (val > max_value_->get()) {
                max_value_->set(val);
            }
        }
 
        void initializeStats_(StatisticSet* sset,
                              const Clock* clk,
                              const std::string &name,
                              const std::string &description,
                              const InstrumentationNode::visibility_t stat_vis_general = InstrumentationNode::AUTO_VISIBILITY,
                              const InstrumentationNode::visibility_t stat_vis_detailed = InstrumentationNode::AUTO_VISIBILITY,
                              InstrumentationNode::visibility_t stat_vis_max = InstrumentationNode::AUTO_VISIBILITY,
                              InstrumentationNode::visibility_t stat_vis_avg = InstrumentationNode::AUTO_VISIBILITY,
                              const std::vector<std::string>& histogram_state_names = {})
        {
            // Reserve to use emplacement without tree child reordering
            bin_.reserve(num_bins_);
 
            const std::string name_total = name.empty() ? std::string("total") : (name + "_total");
 
            // Setup the underflow bins
            const std::string name_uf = name.empty() ? std::string("UF") : (name + "_UF");
            underflow_bin_ = &sset->createCounter<sparta::CycleCounter>(name_uf,
                                                                      "underflow bin",
                                                                      Counter::COUNT_NORMAL,
                                                                      clk);
            underflow_probability_.reset(new StatisticDef(sset,
                                                          name_uf + "_probability",
                                                          "Probability of underflow",
                                                          sset,
                                                          name_uf + " / " + name_total));
 
            utils::ValidValue<InstrumentationNode::visibility_t> count_visibility;
 
            // Setup the normal bins
            uint64_t start_val = lower_val_;
            uint64_t end_val   = start_val + num_vals_per_bin_ - 1;
            std::string weighted_total_str = "( " + std::to_string(lower_val_) + " * " + underflow_bin_->getName() + " )";
            std::string weighted_total_nonzero_str;
            std::string count0_statistic_str;
            for (uint64_t i = 0; i < num_bins_; ++i)
            {
                if (end_val > upper_val_) {
                    end_val = upper_val_;
                }
                std::ostringstream str(name, std::ios_base::ate);
                if (!name.empty()) {
                    str << "_";
                }
                if (SPARTA_EXPECT_TRUE(start_val == end_val)) {
                    if (str.str().empty()) {
                        str << "cycle_";
                    }
 
                    // This vector could be passed to this method from derived EnumCycleHistogram.
                    // If this container is not empty, then we put actual enum constant names in
                    // statistic definition strings, instead of the generic 0, 1, 2, ..., n.
                    if(histogram_state_names.empty()){
                        str << "count" << start_val;
                    }
                    else{
 
                        // Here we are looping over the range of the regular bins of the histogram.
                        // The loop index is stored in variable i.
                        // histogram_state_names[0] will have the the stringified name of the enum constant
                        // with value 0.
                        // histogram_state_names[1] will have the the stringified name of the enum constant
                        // with value 1.
                        // Same goes for when i = 1, 2, 3, ..., n.
                        // So, instead of publishing numbers like 0, 1, 2, we publish names like
                        // UOPSTATE::READY, UOPSTATE::WAIT, UOPSTATE::RETIRE etc.
                        str << "count" << histogram_state_names[i];
                    }
                } else {
                    str << "bin_"  << start_val << "_" << end_val;
                }
                if (count0_statistic_str.empty() && start_val == 0) {
                    count0_statistic_str = str.str();
                }
 
                InstrumentationNode::visibility_t visibility = stat_vis_detailed;
                if (i == 0 || i == (num_bins_ - 1)) {
                    if(stat_vis_general == InstrumentationNode::AUTO_VISIBILITY) {
                        visibility = InstrumentationNode::CONTAINER_DEFAULT_VISIBILITY;
                    } else {
                        visibility = stat_vis_general;
                    }
                } else { // we are internal counts for different levels of utilization.
                    if (stat_vis_detailed == InstrumentationNode::AUTO_VISIBILITY) {
                        visibility = InstrumentationNode::CONTAINER_DEFAULT_VISIBILITY;
                    } else {
                        visibility = stat_vis_detailed;
                    }
                }
                if (i == num_bins_ - 1) {
                    count_visibility = visibility;
                }
 
                bin_.emplace_back(sparta::CycleCounter(sset,
                                                       str.str(),
                                                       name.empty() ? std::string("cycle_count") : name, i,
                                                       description + " histogram bin",
                                                       sparta::Counter::COUNT_NORMAL,
                                                       clk, visibility));
                probabilities_.emplace_back(new StatisticDef(sset,
                                                             str.str() + "_probability",
                                                             str.str() + " bin probability",
                                                             sset,
                                                             str.str() + "/ " + name_total,
                                                             sparta::StatisticDef::VS_FRACTIONAL,
                                                             visibility));
 
                if (SPARTA_EXPECT_TRUE(num_vals_per_bin_ == 1)) {
                    weighted_total_str += "+ ( " + std::to_string(start_val) + " * " + str.str() + " )";
                    if (!count0_statistic_str.empty()) {
                        if (i == 1) {
                            weighted_total_nonzero_str = "( " + std::to_string(start_val) + " * " + str.str() + " )";
                        } else if (i > 1) {
                            weighted_total_nonzero_str += "+ ( " + std::to_string(start_val) + " * " + str.str() + " )";
                        }
                    }
                }
 
                start_val = end_val + 1;
                end_val += num_vals_per_bin_;
            }
 
            // Setup the overflow bins
            const std::string name_of = name.empty() ? std::string("OF") : (name + "_OF");
            overflow_bin_ = &sset->createCounter<sparta::CycleCounter>(name_of,
                                                                     "overflow bin",
                                                                     Counter::COUNT_NORMAL,
                                                                     clk);
            overflow_probability_.reset(new StatisticDef(sset,
                                                         name_of + "_probability",
                                                         "Probability of overflow",
                                                         sset,
                                                         name_of + " / " + name_total));
 
            weighted_total_str += " + ( " + std::to_string(upper_val_) + " * " + overflow_bin_->getName() + " )";
            if (!count0_statistic_str.empty()) {
                weighted_total_nonzero_str += " + ( " + std::to_string(upper_val_) + " * " + overflow_bin_->getName() + " )";
            }
 
            if(stat_vis_avg == InstrumentationNode::AUTO_VISIBILITY) {
                stat_vis_avg = InstrumentationNode::DEFAULT_VISIBILITY;
            }
            // Compute the total of all bins
            total_.reset(new CycleCounter(sset,
                                          name_total,
                                          description,
                                          sparta::Counter::COUNT_NORMAL,
                                          clk, InstrumentationNode::VIS_SUPPORT));
 
            // Setup to collect the maximum value
            if(stat_vis_max == InstrumentationNode::AUTO_VISIBILITY) {
                stat_vis_max = InstrumentationNode::DEFAULT_VISIBILITY;
            }
            max_value_.reset(new Counter(sset,
                                         name.empty() ? std::string("max_value") : (name + "_max"),
                                         "The maximum value in the histogram",
                                         CounterBase::COUNT_LATEST,
                                         stat_vis_max));
 
            // Compute weighted average if single value per bin
            if (SPARTA_EXPECT_TRUE(num_vals_per_bin_ == 1)) {
                weighted_average_.reset(new StatisticDef(sset,
                                                         name.empty() ? std::string("weighted_avg") : (name + "_weighted_avg"),
                                                         "Weighted average",
                                                         sset,
                                                         "( " + weighted_total_str + " ) / " + name_total,
                                                         sparta::StatisticDef::VS_ABSOLUTE,
                                                         stat_vis_avg));
 
                if (!count0_statistic_str.empty()) {
                    const std::string nonzero_weighted_avg_stat_def_name =
                        name.empty() ? std::string("weighted_nonzero_avg") : (name + "_weighted_nonzero_avg");
 
                    const std::string nonzero_weighted_avg_stat_def_equation =
                        "( " +         weighted_total_nonzero_str             + " ) " +
                        "                          /                                " +
                        "( " +    name_total  + " - " +  count0_statistic_str + " )";
 
                    weighted_non_zero_average_.reset(new StatisticDef(sset,
                                                                      nonzero_weighted_avg_stat_def_name,
                                                                      "Weighted nonzero average",
                                                                      sset,
                                                                      nonzero_weighted_avg_stat_def_equation,
                                                                      sparta::StatisticDef::VS_ABSOLUTE,
                                                                      stat_vis_avg));
                } else {
                    const std::string nonzero_weighted_avg_stat_def_name =
                        name.empty() ? std::string("weighted_nonzero_avg") : (name + "_weighted_nonzero_avg");
 
                    weighted_non_zero_average_.reset(new StatisticDef(
                                                                      sset,
                                                                      nonzero_weighted_avg_stat_def_name,
                                                                      "Weighted nonzero average",
                                                                      sset,
                                                                      weighted_average_->getExpression(),
                                                                      sparta::StatisticDef::VS_ABSOLUTE,
                                                                      stat_vis_avg));
                }
            }
 
            if (!bin_.empty()) {
                std::ostringstream fullness_equation;
                fullness_equation << bin_.back().getName() + " + " + name_of;
                const std::string fullness_equation_str = fullness_equation.str();
 
                const std::string full_name = name.empty() ? std::string("full") : (name + "_full");
                fullness_.reset(new StatisticDef(sset,
                                                 full_name,
                                                 "Fullness",
                                                 sset,
                                                 fullness_equation_str,
                                                 sparta::StatisticDef::VS_ABSOLUTE,
                                                 count_visibility.getValue()));
 
                const std::string full_prob_name = full_name + "_probability";
                fullness_probability_.reset(new StatisticDef(sset,
                                                             full_prob_name,
                                                             "Fullness probability",
                                                             sset,
                                                             full_name + " / " + name_total,
                                                             sparta::StatisticDef::VS_FRACTIONAL,
                                                             count_visibility.getValue()));
            }
        }
 
        const uint64_t lower_val_; 
        const uint64_t upper_val_; 
        const uint64_t num_vals_per_bin_; 
        const uint64_t idle_value_; 
 
        std::unique_ptr<sparta::CycleCounter> total_; 
        sparta::CycleCounter* underflow_bin_; 
        sparta::CycleCounter* overflow_bin_; 
        std::vector<sparta::CycleCounter> bin_; 
        std::unique_ptr<sparta::StatisticDef> underflow_probability_; 
        std::unique_ptr<sparta::StatisticDef> overflow_probability_; 
        std::vector<std::unique_ptr<sparta::StatisticDef>> probabilities_; 
        std::unique_ptr<sparta::StatisticDef> weighted_non_zero_average_;
        std::unique_ptr<sparta::Counter> max_value_; 
        std::unique_ptr<sparta::StatisticDef> weighted_average_; 
        std::unique_ptr<sparta::StatisticDef> fullness_; 
        std::unique_ptr<sparta::StatisticDef> fullness_probability_; 
 
        uint64_t num_bins_; 
        uint64_t idx_shift_amount_; 
        uint64_t last_value_ = 0; 
        mutable std::vector<double> bin_prob_vector_;
    }; // class CycleHistogramBase
 
    class CycleHistogramStandalone final : public CycleHistogramBase
    {
    public:
 
        CycleHistogramStandalone() = delete;
 
        CycleHistogramStandalone(const CycleHistogramStandalone&) = delete;
 
        CycleHistogramStandalone(CycleHistogramStandalone&&) = delete;
 
        void operator=(const CycleHistogramStandalone&) = delete;
 
        CycleHistogramStandalone(StatisticSet * sset,
                                 const Clock *  clk,
                                 const std::string &name,
                                 const std::string &description,
                                 const uint64_t lower_val,
                                 const uint64_t upper_val,
                                 const uint64_t num_vals_per_bin,
                                 const uint64_t idle_value = 0,
                                 const InstrumentationNode::visibility_t stat_vis_general = InstrumentationNode::AUTO_VISIBILITY,
                                 const InstrumentationNode::visibility_t stat_vis_detailed = InstrumentationNode::AUTO_VISIBILITY,
                                 const InstrumentationNode::visibility_t stat_vis_max = InstrumentationNode::AUTO_VISIBILITY,
                                 const InstrumentationNode::visibility_t stat_vis_avg = InstrumentationNode::AUTO_VISIBILITY) :
            CycleHistogramBase(lower_val, upper_val, num_vals_per_bin, idle_value),
            name_(name)
            {
                initializeStats_ (sset, clk, name, description, stat_vis_general, stat_vis_detailed, stat_vis_max, stat_vis_avg);
 
                total_->startCounting();
                // Start capturing the idle value
                startCounting_(idle_value_);
                updateMaxValues_(idle_value_);
            }
 
        std::string getDisplayStringCumulative() const
        {
            return getDisplayStringCumulative_(name_);
        }
 
    private:
 
        const std::string name_;
 
    }; // class CycleHistogramStandalone
 
    class CycleHistogramTreeNode final : public TreeNode, public CycleHistogramBase
    {
    public:
 
        CycleHistogramTreeNode() = delete;
 
        CycleHistogramTreeNode(const CycleHistogramTreeNode&) = delete;
 
        CycleHistogramTreeNode(CycleHistogramTreeNode&&) = delete;
 
        void operator=(const CycleHistogramTreeNode&) = delete;
 
        CycleHistogramTreeNode(TreeNode* parent_treenode,
                               const std::string &histogram_name,
                               const std::string &description,
                               const uint64_t lower_val,
                               const uint64_t upper_val,
                               const uint64_t num_vals_per_bin,
                               const uint64_t idle_value = 0,
                               const InstrumentationNode::visibility_t stat_vis_general = InstrumentationNode::AUTO_VISIBILITY,
                               const InstrumentationNode::visibility_t stat_vis_detailed = InstrumentationNode::AUTO_VISIBILITY,
                               const InstrumentationNode::visibility_t stat_vis_max = InstrumentationNode::AUTO_VISIBILITY,
                               const InstrumentationNode::visibility_t stat_vis_avg = InstrumentationNode::AUTO_VISIBILITY) :
            TreeNode(histogram_name, description),
            CycleHistogramBase(lower_val, upper_val, num_vals_per_bin, idle_value),
            stats_(this)
            {
                sparta_assert(parent_treenode && parent_treenode->getClock());
                setExpectedParent_(parent_treenode);
 
                initializeStats_ (&stats_, parent_treenode->getClock(), std::string(), description,
                                  stat_vis_general, stat_vis_detailed, stat_vis_max, stat_vis_avg);
 
                parent_treenode->addChild(this);
 
                total_->startCounting();
                // Start capturing the idle value
                startCounting_(idle_value_);
                updateMaxValues_(idle_value_);
            }
 
        std::string getDisplayStringCumulative() const
        {
            return getDisplayStringCumulative_(getName());
        }
 
    private:
 
        sparta::StatisticSet stats_; 
 
    }; // class CycleHistogramTreeNode
 
    using CycleHistogram = CycleHistogramTreeNode;
 
} // namespace sparta