Resolve issue 668: add support for counter/stat meta data

sparta/example/CoreModel/src/ROB.cpp

@@ -16,7 +16,15 @@ namespace core_example
                   "ipc",
                   "Instructions retired per cycle",
                   &unit_stat_set_,
-                  "total_number_retired/cycles"),
+                  "total_number_retired/cycles",
+                  {
+                      sparta::StatisticDef::VS_ABSOLUTE,
+                      {
+                          {"low", "0"},
+                          {"high", std::to_string(uint32_t(p->num_to_retire))},
+                          {"semantic", "higher"}
+                      }
+                  }),
         num_retired_(&unit_stat_set_,
                      "total_number_retired",
                      "The total number of instructions retired by this core",

sparta/example/SkeletonPipeline/src/Consumer.hpp

@@ -55,10 +55,10 @@ class Consumer : public sparta::Unit
 
     // Stats
     sparta::Counter num_consumed_{&unit_stat_set_, "num_consumed",
-                                  "Number of items consumed", sparta::Counter::COUNT_NORMAL};
+                                  "Number of items consumed",
+                                  sparta::Counter::COUNT_NORMAL};
 
     //! Loggers
     sparta::log::MessageSource consumer_log_;
 
 };
-

sparta/sparta/report/format/JSON_detail.hpp

@@ -221,10 +221,7 @@ class JSON_detail : public BaseOstreamFormatter
             tmp.desc = desc;
             tmp.vis = si.second->getVisibility();
             tmp.n_class = si.second->getClass();
-            const StatisticDef * stat_defn = si.second->getStatisticDef();
-            if (stat_defn != nullptr) {
-                tmp.metadata = stat_defn->getMetadata();
-            }
+            tmp.metadata = si.second->getMetadata();
             return tmp;
         };
 

sparta/sparta/statistics/ContextCounter.hpp

@@ -380,8 +380,11 @@ namespace sparta
                 ++sub_stat_index;
             }
 
-            addMetadata_("context_name", context_name);
-            addMetadata_("num_contexts", std::to_string(num_contexts));
+            meta_data_.insert(meta_data_.begin(),
+                              {
+                                  {"context_name", context_name},
+                                  {"num_contexts", std::to_string(num_contexts)}
+                              });
 
             begin_counter_ = &internal_counters_.front();
             end_counter_ = &internal_counters_.back();
@@ -483,4 +486,3 @@ namespace sparta
     sparta::trigger::ContextCounterTrigger:: \
         registerContextCounterAggregateFcn(handler, this, #method, aggregated_value); \
     }
-

sparta/sparta/statistics/Counter.hpp

@@ -52,7 +52,7 @@ namespace sparta
                 const std::string& group,
                 TreeNode::group_idx_type group_idx,
                 const std::string& desc,
-                CounterBehavior behave,
+                CounterBase::CounterBehaviorDetailed behave,
                 visibility_t visibility) :
             CounterBase(parent,
                         name,
@@ -70,7 +70,7 @@ namespace sparta
                 const std::string& group,
                 TreeNode::group_idx_type group_idx,
                 const std::string& desc,
-                CounterBehavior behave) :
+                CounterBase::CounterBehaviorDetailed behave) :
             Counter(parent,
                     name,
                     group,
@@ -86,7 +86,7 @@ namespace sparta
         Counter(TreeNode* parent,
                 const std::string& name,
                 const std::string& desc,
-                CounterBehavior behave,
+                CounterBase::CounterBehaviorDetailed behave,
                 visibility_t visibility) :
             Counter(parent,
                     name,
@@ -103,7 +103,7 @@ namespace sparta
         Counter(TreeNode* parent,
                 const std::string& name,
                 const std::string& desc,
-                CounterBehavior behave) :
+                CounterBase::CounterBehaviorDetailed behave) :
             Counter(parent,
                     name,
                     TreeNode::GROUP_NAME_NONE,
@@ -304,4 +304,3 @@ namespace sparta
     };
 
 } // namespace sparta
-

sparta/sparta/statistics/CounterBase.hpp

@@ -104,6 +104,82 @@ namespace sparta
 
     public:
 
+        /*!
+         * \class CounterBehaviorDetailed
+         * \brief Wrapper class to add meta information to a counter definition
+         *
+         * When defining the counter's behavior, this class enables
+         * the modeler to extend that behavior with meta information.
+         * During report generation to data serialization formats
+         * (like json, yaml, or SimDB) this information is included
+         * with the counter.
+         *
+         * Usage:
+         * \code
+         *     new sparta::Counter(getContainer(),
+         *                         "my_counter_name",
+         *                         "my_counter_group_name,
+         *                         0,                                     // group idx
+         *                         "This is my fancy counter definition", // desc
+         *                         // CounterBehaviorDetailed
+         *                         {
+         *                             sparta::CounterBase::CounterBehavior::COUNT_NORMAL,
+         *                             {
+         *                                 {"lowest_value" : "0" },
+         *                                 {"highest_value" : "100" },
+         *                                 {"polarity" : "positive" }  // Positive polarity, higher is better
+         *                             }
+         *                         });
+         * \endcode
+         *
+         * The modeler is not required to provide any meta data
+         * information.  As an example, the following works as well:
+         *
+         * \code
+         *     new sparta::Counter(getContainer(),
+         *                         "my_counter_name",
+         *                         "my_counter_group_name,
+         *                         0,                                      // group idx
+         *                         "This is my simple counter definition", // desc
+         *                         sparta::CounterBase::CounterBehavior::COUNT_NORMAL);
+         * \endcode
+         */
+        class CounterBehaviorDetailed
+        {
+        public:
+            /*!
+             * \brief Construct a CounterBehaviorDetailed without meta data
+             * \param behavior The CounterBehavior
+             * \note Do not make this explicit
+             */
+            CounterBehaviorDetailed(CounterBehavior behavior) :
+                CounterBehaviorDetailed(behavior, {})
+            {}
+
+            /*!
+             * \brief Construct a CounterBehaviorDetailed without meta data
+             * \param behavior The CounterBehavior
+             * \param meta_data MetadataPairs to assign `{("name", "value"}}`
+             */
+            CounterBehaviorDetailed(CounterBehavior behavior,
+                                    const InstrumentationNode::MetadataPairs & meta_data) :
+                behavior_(behavior),
+                meta_data_(meta_data)
+            {}
+
+            //! Casting operator to obtain the original behavior
+            operator CounterBehavior() const { return behavior_; }
+
+            //! Get the meta data provided by the user
+            const InstrumentationNode::MetadataPairs & getMetadata() const {
+                return meta_data_;
+            }
+
+        private:
+            const CounterBehavior behavior_;
+            const InstrumentationNode::MetadataPairs meta_data_;
+        };
+
         //! \name Construction & Initialization
         //! @{
         ////////////////////////////////////////////////////////////////////////
@@ -127,7 +203,7 @@ namespace sparta
                     const std::string& group,
                     TreeNode::group_idx_type group_idx,
                     const std::string& desc,
-                    CounterBehavior behave,
+                    CounterBehaviorDetailed behave,
                     visibility_t visibility) :
             InstrumentationNode(nullptr,
                                 name,
@@ -144,6 +220,12 @@ namespace sparta
             ensureParentIsValid_(parent);
 
             parent->addChild(this);
+
+            // Copy over the meta data to the InstrumentationNode.
+            meta_data_.insert(meta_data_.begin(),
+                              behave.getMetadata().begin(),
+                              behave.getMetadata().end());
+
         }
 
         // Alternate constructor
@@ -152,7 +234,7 @@ namespace sparta
                     const std::string& group,
                     TreeNode::group_idx_type group_idx,
                     const std::string& desc,
-                    CounterBehavior behave) :
+                    CounterBehaviorDetailed behave) :
             CounterBase(parent,
                         name,
                         group,
@@ -168,7 +250,7 @@ namespace sparta
         CounterBase(TreeNode* parent,
                     const std::string& name,
                     const std::string& desc,
-                    CounterBehavior behave) :
+                    CounterBehaviorDetailed behave) :
             CounterBase(parent,
                         name,
                         TreeNode::GROUP_NAME_NONE,
@@ -254,7 +336,7 @@ namespace sparta
         /*!
          * \brief Returns a string containing the name of the given behavior
          */
-        static std::string getBehaviorName(CounterBehavior behave) {
+        static std::string getBehaviorName(CounterBehaviorDetailed behave) {
             switch(behave){
             case COUNT_NORMAL:
                 return "normal";
@@ -295,7 +377,7 @@ namespace sparta
         /*!
          * \brief Behavior of this counter
          */
-        const CounterBehavior behave_;
+        const CounterBehaviorDetailed behave_;
 
     }; // class CounterBase
 

sparta/sparta/statistics/InstrumentationNode.hpp

@@ -8,6 +8,9 @@
 
 #pragma once
 
+#include <vector>
+#include <utility>
+
 #include "sparta/simulation/TreeNode.hpp"
 #include "sparta/utils/SpartaException.hpp"
 #include "sparta/utils/SpartaAssert.hpp"
@@ -194,6 +197,14 @@ class InstrumentationNode : public TreeNode
 
     };
 
+    //! MetadataPairs are name/value pairs appended to an
+    //! object/derived type in report generation.  This information
+    //! can be used for communicating relevant information about an
+    //! InstrumentationNode like value ranges, big numbers good/bad,
+    //! etc.
+    using StringPair = std::pair<std::string, std::string>;
+    using MetadataPairs = std::vector<StringPair>;
+
     ////////////////////////////////////////////////////////////////////////
     //! @}
 
@@ -220,6 +231,7 @@ class InstrumentationNode : public TreeNode
      */
     InstrumentationNode(InstrumentationNode&& rhp) :
         TreeNode::TreeNode(std::move(rhp)),
+        meta_data_(std::move(rhp.meta_data_)),
         visibility_(rhp.visibility_),
         class_(rhp.class_),
         instrument_type_(rhp.instrument_type_)
@@ -548,9 +560,8 @@ class InstrumentationNode : public TreeNode
         return false;
     }
 
-    using StringPair = std::pair<std::string, std::string>;
-    const std::vector<StringPair> & getMetadata() const {
-        return metadata_;
+    const MetadataPairs & getMetadata() const {
+        return meta_data_;
     }
 
     ////////////////////////////////////////////////////////////////////////
@@ -562,9 +573,7 @@ class InstrumentationNode : public TreeNode
      * \brief Add any arbitrary metadata as strings to this object. Used to
      * add extra information to statistics reports (json, etc.)
      */
-    void addMetadata_(const std::string & key, const std::string & value){
-        metadata_.emplace_back(std::make_pair(key, value));
-    }
+    MetadataPairs meta_data_;
 
 private:
 
@@ -582,11 +591,6 @@ class InstrumentationNode : public TreeNode
      * \brief Type hint for this node
      */
     Type instrument_type_;
-
-    /*!
-     * \brief
-     */
-    std::vector<StringPair> metadata_;
 };
 
 } // namespace sparta