Allow a single InstMemAccessRecord followed by multiple InstMemContentRecords

CMakeLists.txt

@@ -11,12 +11,12 @@ if(hasParent)
     set (STF_BASE ${STF_BASE} PARENT_SCOPE)
 endif()
 
-include (${STF_BASE}/cmake/stf-config.cmake)
-
 # Boost
 find_package (Boost 1.49.0)
 include_directories (SYSTEM ${Boost_INCLUDE_DIRS})
 
+include (${STF_BASE}/cmake/stf-config.cmake)
+
 add_subdirectory(lib)
 
 if(BUILD_STF_PYTHON_LIB)

README.md

@@ -1,10 +1,12 @@
 # STF Library
 
-The acronym STF stands for Simulation Tracing Format. This is intended to be used
+The acronym STF stands for Simulation Trace Format. This is intended to be used
 with Sparta-based simulators, but that's not necessary.
+
+You can view the STF specification at [stf_spec](https://github.com/sparcians/stf_spec).
+
 This repo contains the following:
 
-1. The STF definition
 1. Trace generators (writers)
 1. Trace consumers (readers)
 

lib/stf_inst.cpp

@@ -14,22 +14,36 @@
 
 namespace stf {
     std::ostream& operator<<(std::ostream& os, const MemAccess& access) {
+        static constexpr size_t ATTR_TO_VA_PADDING = 7;
+        static constexpr size_t VA_TO_DATA_PADDING = 5;
+
         if (format_utils::showPhys()) {
             format_utils::formatSpaces(os, format_utils::PA_WIDTH + 1);
         }
         format_utils::formatOperandLabel(os, "MEM ");
         format_utils::formatLeft(os, access.getType(), format_utils::MEM_ACCESS_FIELD_WIDTH);
         format_utils::formatSpaces(os, 1);
         format_utils::formatHex(os, access.getAttr());
-        format_utils::formatSpaces(os, 7);
+        format_utils::formatSpaces(os, ATTR_TO_VA_PADDING);
         format_utils::formatVA(os, access.getAddress());
 
         if (format_utils::showPhys()) {
             os << ':';
             format_utils::formatPA(os, access.getPhysAddress());
         }
-        format_utils::formatSpaces(os, 5);
-        format_utils::formatData(os, access.getData());
+        format_utils::formatSpaces(os, VA_TO_DATA_PADDING);
+
+        const size_t num_data_spaces = (format_utils::showPhys() ? format_utils::PA_WIDTH + 1 : 0) +
+                                       format_utils::OPERAND_LABEL_WIDTH +
+                                       format_utils::MEM_ACCESS_FIELD_WIDTH +
+                                       1 + // single space
+                                       4 + // attr
+                                       ATTR_TO_VA_PADDING +
+                                       format_utils::VA_WIDTH +
+                                       (format_utils::showPhys() ? format_utils::PA_WIDTH + 1 : 0) +
+                                       VA_TO_DATA_PADDING;
+
+        access.formatContent<false>(os, num_data_spaces);
 
         return os;
     }

stf-inc/protocols/channel_protocol.hpp

@@ -174,6 +174,10 @@ namespace stf {
          */
         template<typename ChannelType>
         struct ChannelProtocol {
+            /**
+             * \class Channel
+             * Base Channel class that can be constructed from an STF
+             */
             class Channel : public STFObject<Channel, ChannelType> {
                 public:
                     /**
@@ -221,17 +225,26 @@ namespace stf {
                     }
 
                 public:
+                    /**
+                     * Constructs a FieldChannel from an STFIFstream
+                     */
                     explicit FieldChannel(STFIFstream& reader) :
                         fields_(Fields(reader)...)
                     {
                     }
 
+                    /**
+                     * Constructs a FieldChannel by specifying individual field values
+                     */
                     template<typename ... FieldArgs>
                     explicit FieldChannel(const FieldArgs&... args) :
                         fields_(args...)
                     {
                     }
 
+                    /**
+                     * Move-constructs a FieldChannel by specifying individual field values
+                     */
                     template<typename ... FieldArgs>
                     explicit FieldChannel(FieldArgs&&... args) :
                         fields_(std::forward<FieldArgs>(args)...)

stf-inc/stf_descriptor.hpp

@@ -1,3 +1,8 @@
+/**
+ * \file
+ * \brief  This file defines the descriptor values for each STF record type
+ */
+
 #ifndef __STF_DESCRIPTOR_HPP__
 #define __STF_DESCRIPTOR_HPP__
 
@@ -133,8 +138,10 @@ namespace stf {
 
                     using ArrayType = enums::EnumArray<ToDescriptor, FromDescriptor>; /**< Array that maps FromDescriptor values to ToDescriptor values */
 
+#ifndef DOXYGEN
                     #define _INIT_DESC_ARRAY_ENTRY(r, data, elem) \
                         case FromDescriptor::elem: newarr[i] = ToDescriptor::elem; continue;
+#endif
 
                     /**
                      * \def INIT_DESC_ARRAY
@@ -463,6 +470,9 @@ namespace stf {
         } // end namespace iterators
 
         namespace encoded {
+            /**
+             * Formats an encoded Descriptor to an std::ostream
+             */
             inline std::ostream& operator<<(std::ostream& os, const Descriptor desc) {
                 return os << conversion::toInternal(desc);
             }

stf-inc/stf_enum_utils.hpp

@@ -86,20 +86,32 @@
  *   STF_ENUM_VAL(name, val, str, enable_print)
  *     Defines an STF_ENUM entry with the given name, value, string representation, and print-enable setting.
  */
+#ifdef DOXYGEN
+#define STF_ENUM_VAL(name, val, ...) name = val
+#else
 #define STF_ENUM_VAL(name, ...) BOOST_PP_OVERLOAD(_STF_ENUM_VAL_, __VA_ARGS__)(name, __VA_ARGS__)
+#endif
 
 /**
  * \def STF_ENUM_ALIAS
  * Defines an STF_ENUM entry as an alias of another entry
  */
+#ifdef DOXYGEN
+#define STF_ENUM_ALIAS name = other_name
+#else
 #define STF_ENUM_ALIAS(name, other_name) STF_ENUM_VAL(name, other_name, BOOST_PP_NIL, STF_ENUM_NO_PRINT)
+#endif
 
 /**
  * \def STF_ENUM_STR
  * Defines an STF_ENUM entry with the given name and string representation. Value is auto-generated and
  * print-enable is set to 1.
  */
+#ifdef DOXYGEN
+#define STF_ENUM_STR(name, str) name
+#else
 #define STF_ENUM_STR(name, str) (name, str)
+#endif
 
 // Defines an STF_ENUM entry tuple from a name only. Allows users to use bare names in an STF_ENUM just as
 // they would with a normal enum class. String representation and value are auto-generated and print-enable
@@ -343,24 +355,35 @@
 // STF_ENUM_VAL/STF_ENUM_STR/STF_ENUM_ALIAS directives. The config is converted from an STF_ENUM_CONFIG
 // tuple to a tuple of binary flags with _FLATTEN_STF_ENUM_CONFIG before passing everything to
 // __STF_ENUM_CONFIG
+#ifdef DOXYGEN
+#define _STF_ENUM_CONFIG(config, name, type, ...) _STF_ENUM_NO_CONFIG(name, type, __VA_ARGS__)
+#else
 #define _STF_ENUM_CONFIG(config, name, type, ...)   \
     __STF_ENUM_CONFIG(                              \
             _FLATTEN_STF_ENUM_CONFIG(config),       \
             name,                                   \
             type,                                   \
             __VA_ARGS__                             \
     )
+#endif
 
 // Defines an STF_ENUM with the given name and underlying type.
 // The __VA_ARGS__ are the enum elements, which can be either bare names or tuples generated with
 // STF_ENUM_VAL/STF_ENUM_STR/STF_ENUM_ALIAS directives. Uses a default config where all flags are disabled.
+#ifdef DOXYGEN
+#define _STF_ENUM_NO_CONFIG(name, type, ...)    \
+    enum class name : type {                    \
+        __VA_ARGS__                             \
+    }
+#else
 #define _STF_ENUM_NO_CONFIG(name, type, ...)    \
     __STF_ENUM_CONFIG(                          \
         _DEFAULT_STF_CONFIG,                    \
         name,                                   \
         type,                                   \
         __VA_ARGS__                             \
     )
+#endif
 
 /**
  * \def STF_ENUM

stf-inc/stf_enums.hpp

@@ -29,36 +29,15 @@ namespace stf {
      *
      */
     STF_ENUM(
-        STF_ENUM_CONFIG(OVERRIDE_START, OVERRIDE_END),
+        STF_ENUM_CONFIG(OVERRIDE_START, OVERRIDE_END, AUTO_PRINT),
         INST_IEM,
         uint16_t,
-        STF_INST_IEM_INVALID,           /**< Invalid */
-        STF_ENUM_VAL(STF_INST_IEM_RV32, 1),
-        STF_ENUM_VAL(STF_INST_IEM_RV64, 2),
-        STF_ENUM_VAL(STF_INST_IEM_RESERVED, 0xFFFF)
+        STF_ENUM_STR(STF_INST_IEM_INVALID, "INVALID"),           /**< Invalid */
+        STF_ENUM_VAL(STF_INST_IEM_RV32, 1, "RV32"),
+        STF_ENUM_VAL(STF_INST_IEM_RV64, 2, "RV64"),
+        STF_ENUM_VAL(STF_INST_IEM_RESERVED, 0xFFFF, "RESERVED")
     );
 
-    inline std::ostream& operator<<(std::ostream& os, const INST_IEM iem)
-    {
-        switch(iem)
-        {
-            case INST_IEM::STF_INST_IEM_INVALID:
-                os << "INVALID";
-                break;
-            case INST_IEM::STF_INST_IEM_RV32:
-                os << "RV32";
-                break;
-            case INST_IEM::STF_INST_IEM_RV64:
-                os << "RV64";
-                break;
-            case INST_IEM::STF_INST_IEM_RESERVED:
-                os << "RESERVED";
-                break;
-        }
-
-        return os;
-    }
-
     /**
      * \enum BUS_MASTER
      *

stf-inc/stf_exception.hpp

@@ -115,7 +115,14 @@ namespace stf
                 reason_(std::move(reason))
             { }
 
+            /**
+             * \brief Copy constructor
+             */
             STFException(const STFException&) = default;
+
+            /**
+             * \brief Move constructor
+             */
             STFException(STFException&&) = default;
 
             /// Destroy!