From 72ce0f03005e0a95f15c755b3faaca5a13590f46 Mon Sep 17 00:00:00 2001 From: Knute Lingaard Date: Wed, 31 Jan 2024 15:27:35 -0600 Subject: [PATCH 1/9] Updated documentation for PEvents --- sparta/doc/Doxyfile | 277 ++++++++++++++++------ sparta/doc/sparta_docs/modeling.txt | 7 + sparta/sparta/pevents/PEventHelper.hpp | 20 +- sparta/sparta/pevents/PeventCollector.hpp | 39 ++- 4 files changed, 250 insertions(+), 93 deletions(-) diff --git a/sparta/doc/Doxyfile b/sparta/doc/Doxyfile index 9cdad69f7e..29494bad64 100644 --- a/sparta/doc/Doxyfile +++ b/sparta/doc/Doxyfile @@ -1,4 +1,4 @@ -# Doxyfile 1.8.16 +# Doxyfile 1.9.1 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -217,6 +217,14 @@ QT_AUTOBRIEF = NO MULTILINE_CPP_IS_BRIEF = NO +# By default Python docstrings are displayed as preformatted text and doxygen's +# special commands cannot be used. By setting PYTHON_DOCSTRING to NO the +# doxygen's special commands can be used and the contents of the docstring +# documentation blocks is shown as doxygen documentation. +# The default value is: YES. + +PYTHON_DOCSTRING = YES + # If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the # documentation from any documented member that it re-implements. # The default value is: YES. @@ -253,12 +261,6 @@ TAB_SIZE = 8 ALIASES = -# This tag can be used to specify a number of word-keyword mappings (TCL only). -# A mapping has the form "name=value". For example adding "class=itcl::class" -# will allow you to use the command class in the itcl::class meaning. - -TCL_SUBST = - # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For # instance, some of the names that are used will be different. The list of all @@ -299,19 +301,22 @@ OPTIMIZE_OUTPUT_SLICE = NO # parses. With this tag you can assign which parser to use for a given # extension. Doxygen has a built-in mapping, but you can override or extend it # using this tag. The format is ext=language, where ext is a file extension, and -# language is one of the parsers supported by doxygen: IDL, Java, Javascript, -# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, +# language is one of the parsers supported by doxygen: IDL, Java, JavaScript, +# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, VHDL, # Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: # FortranFree, unknown formatted Fortran: Fortran. In the later case the parser # tries to guess whether the code is fixed or free formatted code, this is the -# default for Fortran type files), VHDL, tcl. For instance to make doxygen treat -# .inc files as Fortran files (default is PHP), and .f files as C (default is -# Fortran), use: inc=Fortran f=C. +# default for Fortran type files). For instance to make doxygen treat .inc files +# as Fortran files (default is PHP), and .f files as C (default is Fortran), +# use: inc=Fortran f=C. # # Note: For files without extension you can use no_extension as a placeholder. # # Note that for custom extensions you also need to set FILE_PATTERNS otherwise -# the files are not read by doxygen. +# the files are not read by doxygen. When specifying no_extension you should add +# * to the FILE_PATTERNS. +# +# Note see also the list of default file extension mappings. EXTENSION_MAPPING = @@ -445,6 +450,19 @@ TYPEDEF_HIDES_STRUCT = NO LOOKUP_CACHE_SIZE = 0 +# The NUM_PROC_THREADS specifies the number threads doxygen is allowed to use +# during processing. When set to 0 doxygen will based this on the number of +# cores available in the system. You can set it explicitly to a value larger +# than 0 to get more control over the balance between CPU load and processing +# speed. At this moment only the input processing can be done using multiple +# threads. Since this is still an experimental feature the default is set to 1, +# which efficively disables parallel processing. Please report any issues you +# encounter. Generating dot graphs in parallel is controlled by the +# DOT_NUM_THREADS setting. +# Minimum value: 0, maximum value: 32, default value: 1. + +NUM_PROC_THREADS = 1 + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- @@ -508,6 +526,13 @@ EXTRACT_LOCAL_METHODS = NO EXTRACT_ANON_NSPACES = NO +# If this flag is set to YES, the name of an unnamed parameter in a declaration +# will be determined by the corresponding definition. By default unnamed +# parameters remain unnamed in the output. +# The default value is: YES. + +RESOLVE_UNNAMED_PARAMS = YES + # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all # undocumented members inside documented classes or files. If set to NO these # members will be included in the various overviews, but no documentation @@ -525,8 +550,8 @@ HIDE_UNDOC_MEMBERS = NO HIDE_UNDOC_CLASSES = NO # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend -# (class|struct|union) declarations. If set to NO, these declarations will be -# included in the documentation. +# declarations. If set to NO, these declarations will be included in the +# documentation. # The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO @@ -545,11 +570,18 @@ HIDE_IN_BODY_DOCS = NO INTERNAL_DOCS = NO -# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file -# names in lower-case letters. If set to YES, upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# (including Cygwin) ands Mac users are advised to set this option to NO. +# With the correct setting of option CASE_SENSE_NAMES doxygen will better be +# able to match the capabilities of the underlying filesystem. In case the +# filesystem is case sensitive (i.e. it supports files in the same directory +# whose names only differ in casing), the option must be set to YES to properly +# deal with such files in case they appear in the input. For filesystems that +# are not case sensitive the option should be be set to NO to properly deal with +# output files written for symbols that only differ in casing, such as for two +# classes, one named CLASS and the other named Class, and to also support +# references to files without having to specify the exact matching casing. On +# Windows (including Cygwin) and MacOS, users should typically set this option +# to NO, whereas on Linux or other Unix flavors it should typically be set to +# YES. # The default value is: system dependent. CASE_SENSE_NAMES = YES @@ -788,7 +820,10 @@ WARN_IF_DOC_ERROR = YES WARN_NO_PARAMDOC = NO # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when -# a warning is encountered. +# a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS +# then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but +# at the end of the doxygen process doxygen will return with a non-zero status. +# Possible values are: NO, YES and FAIL_ON_WARNINGS. # The default value is: NO. WARN_AS_ERROR = NO @@ -819,28 +854,29 @@ WARN_LOGFILE = doxygen_sparta_warnings.out # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = sparta_docs \ - ../sparta/app/ \ +INPUT = sparta_docs \ + ../sparta/app/ \ ../sparta/collection/ \ - ../sparta/events/ \ - ../sparta/functional/ \ - ../sparta/kernel/ \ - ../sparta/log/ \ - ../sparta/memory/ \ - ../sparta/ports/ \ - ../sparta/resources/ \ + ../sparta/events/ \ + ../sparta/pevents/ \ + ../sparta/functional/ \ + ../sparta/kernel/ \ + ../sparta/log/ \ + ../sparta/memory/ \ + ../sparta/ports/ \ + ../sparta/resources/ \ ../sparta/simulation/ \ ../sparta/serialization/ \ ../sparta/statistics/ \ - ../sparta/utils/ \ - ../example/CoreModel \ + ../sparta/utils/ \ + ../example/CoreModel \ ../example/SkeletonPipeline # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses # libiconv (or the iconv built into libc) for the transcoding. See the libiconv -# documentation (see: https://www.gnu.org/software/libiconv/) for the list of -# possible encodings. +# documentation (see: +# https://www.gnu.org/software/libiconv/) for the list of possible encodings. # The default value is: UTF-8. INPUT_ENCODING = UTF-8 @@ -853,11 +889,15 @@ INPUT_ENCODING = UTF-8 # need to set EXTENSION_MAPPING for the extension otherwise the files are not # read by doxygen. # +# Note the list of default checked file patterns might differ from the list of +# default file extension mappings. +# # If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, # *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, # *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, -# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, -# *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice. +# *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C comment), +# *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, *.vhdl, +# *.ucf, *.qsf and *.ice. FILE_PATTERNS = *.h \ *.cpp \ @@ -1086,6 +1126,44 @@ USE_HTAGS = NO VERBATIM_HEADERS = YES +# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the +# clang parser (see: +# http://clang.llvm.org/) for more accurate parsing at the cost of reduced +# performance. This can be particularly helpful with template rich C++ code for +# which doxygen's built-in parser lacks the necessary type information. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. +# The default value is: NO. + +CLANG_ASSISTED_PARSING = NO + +# If clang assisted parsing is enabled and the CLANG_ADD_INC_PATHS tag is set to +# YES then doxygen will add the directory of each input to the include path. +# The default value is: YES. + +CLANG_ADD_INC_PATHS = YES + +# If clang assisted parsing is enabled you can provide the compiler with command +# line options that you would normally use when invoking the compiler. Note that +# the include paths will already be set by doxygen for the files and directories +# specified with INPUT and INCLUDE_PATH. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_OPTIONS = + +# If clang assisted parsing is enabled you can provide the clang parser with the +# path to the directory containing a file called compile_commands.json. This +# file is the compilation database (see: +# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the +# options used when the source files were built. This is equivalent to +# specifying the -p option to a clang tool, such as clang-check. These options +# will then be passed to the parser. Any options specified with CLANG_OPTIONS +# will be added as well. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. + +CLANG_DATABASE_PATH = + #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- @@ -1097,13 +1175,6 @@ VERBATIM_HEADERS = YES ALPHABETICAL_INDEX = YES -# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in -# which the alphabetical index list will be split. -# Minimum value: 1, maximum value: 20, default value: 5. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -COLS_IN_ALPHA_INDEX = 5 - # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag # can be used to specify a prefix (or a list of prefixes) that should be ignored @@ -1242,9 +1313,9 @@ HTML_TIMESTAMP = YES # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML # documentation will contain a main index with vertical navigation menus that -# are dynamically created via Javascript. If disabled, the navigation index will +# are dynamically created via JavaScript. If disabled, the navigation index will # consists of multiple levels of tabs that are statically embedded in every HTML -# page. Disable this option to support browsers that do not have Javascript, +# page. Disable this option to support browsers that do not have JavaScript, # like the Qt help browser. # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1274,10 +1345,11 @@ HTML_INDEX_NUM_ENTRIES = 100 # If the GENERATE_DOCSET tag is set to YES, additional index files will be # generated that can be used as input for Apple's Xcode 3 integrated development -# environment (see: https://developer.apple.com/xcode/), introduced with OSX -# 10.5 (Leopard). To create a documentation set, doxygen will generate a -# Makefile in the HTML output directory. Running make will produce the docset in -# that directory and running make install will install the docset in +# environment (see: +# https://developer.apple.com/xcode/), introduced with OSX 10.5 (Leopard). To +# create a documentation set, doxygen will generate a Makefile in the HTML +# output directory. Running make will produce the docset in that directory and +# running make install will install the docset in # ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at # startup. See https://developer.apple.com/library/archive/featuredarticles/Doxy # genXcode/_index.html for more information. @@ -1319,8 +1391,8 @@ DOCSET_PUBLISHER_NAME = Publisher # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three # additional HTML index files: index.hhp, index.hhc, and index.hhk. The # index.hhp is a project file that can be read by Microsoft's HTML Help Workshop -# (see: https://www.microsoft.com/en-us/download/details.aspx?id=21138) on -# Windows. +# (see: +# https://www.microsoft.com/en-us/download/details.aspx?id=21138) on Windows. # # The HTML Help Workshop contains a compiler that can convert all HTML output # generated by doxygen into a single compiled HTML file (.chm). Compiled HTML @@ -1350,7 +1422,7 @@ CHM_FILE = HHC_LOCATION = # The GENERATE_CHI flag controls if a separate .chi index file is generated -# (YES) or that it should be included in the master .chm file (NO). +# (YES) or that it should be included in the main .chm file (NO). # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. @@ -1395,7 +1467,8 @@ QCH_FILE = # The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help # Project output. For more information please see Qt Help Project / Namespace -# (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace). +# (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace). # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1403,8 +1476,8 @@ QHP_NAMESPACE = org.doxygen.Project # The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt # Help Project output. For more information please see Qt Help Project / Virtual -# Folders (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual- -# folders). +# Folders (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual-folders). # The default value is: doc. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1412,16 +1485,16 @@ QHP_VIRTUAL_FOLDER = doc # If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom # filter to add. For more information please see Qt Help Project / Custom -# Filters (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom- -# filters). +# Filters (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_NAME = # The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the # custom filter to add. For more information please see Qt Help Project / Custom -# Filters (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom- -# filters). +# Filters (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_ATTRS = @@ -1433,9 +1506,9 @@ QHP_CUST_FILTER_ATTRS = QHP_SECT_FILTER_ATTRS = -# The QHG_LOCATION tag can be used to specify the location of Qt's -# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the -# generated .qhp file. +# The QHG_LOCATION tag can be used to specify the location (absolute path +# including file name) of Qt's qhelpgenerator. If non-empty doxygen will try to +# run qhelpgenerator on the generated .qhp file. # This tag requires that the tag GENERATE_QHP is set to YES. QHG_LOCATION = @@ -1512,6 +1585,17 @@ TREEVIEW_WIDTH = 250 EXT_LINKS_IN_WINDOW = NO +# If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg +# tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see +# https://inkscape.org) to generate formulas as SVG images instead of PNGs for +# the HTML output. These images will generally look nicer at scaled resolutions. +# Possible values are: png (the default) and svg (looks nicer but requires the +# pdf2svg or inkscape tool). +# The default value is: png. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FORMULA_FORMAT = png + # Use this tag to change the font size of LaTeX formulas included as images in # the HTML documentation. When you change the font size after a successful # doxygen run you need to manually remove any form_*.png images from the HTML @@ -1532,8 +1616,14 @@ FORMULA_FONTSIZE = 10 FORMULA_TRANSPARENT = YES +# The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands +# to create new LaTeX commands to be used in formulas as building blocks. See +# the section "Including formulas" for details. + +FORMULA_MACROFILE = + # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see -# https://www.mathjax.org) which uses client side Javascript for the rendering +# https://www.mathjax.org) which uses client side JavaScript for the rendering # instead of using pre-rendered bitmaps. Use this if you do not have LaTeX # installed or if you want to formulas look prettier in the HTML output. When # enabled you may also need to install MathJax separately and configure the path @@ -1545,7 +1635,7 @@ USE_MATHJAX = NO # When MathJax is enabled you can set the default output format to be used for # the MathJax output. See the MathJax site (see: -# http://docs.mathjax.org/en/latest/output.html) for more details. +# http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. # Possible values are: HTML-CSS (which is slower, but has the best # compatibility), NativeMML (i.e. MathML) and SVG. # The default value is: HTML-CSS. @@ -1561,7 +1651,7 @@ MATHJAX_FORMAT = HTML-CSS # Content Delivery Network so you can quickly see the result without installing # MathJax. However, it is strongly recommended to install a local copy of # MathJax from https://www.mathjax.org before deployment. -# The default value is: https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/. +# The default value is: https://cdn.jsdelivr.net/npm/mathjax@2. # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_RELPATH = http://www.mathjax.org/mathjax @@ -1575,7 +1665,8 @@ MATHJAX_EXTENSIONS = # The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces # of code that will be used on startup of the MathJax code. See the MathJax site -# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an +# (see: +# http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. For an # example see the documentation. # This tag requires that the tag USE_MATHJAX is set to YES. @@ -1603,7 +1694,7 @@ MATHJAX_CODEFILE = SEARCHENGINE = YES # When the SERVER_BASED_SEARCH tag is enabled the search engine will be -# implemented using a web server instead of a web client using Javascript. There +# implemented using a web server instead of a web client using JavaScript. There # are two flavors of web server based searching depending on the EXTERNAL_SEARCH # setting. When disabled, doxygen will generate a PHP script for searching and # an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing @@ -1622,7 +1713,8 @@ SERVER_BASED_SEARCH = NO # # Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library -# Xapian (see: https://xapian.org/). +# Xapian (see: +# https://xapian.org/). # # See the section "External Indexing and Searching" for details. # The default value is: NO. @@ -1635,8 +1727,9 @@ EXTERNAL_SEARCH = NO # # Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library -# Xapian (see: https://xapian.org/). See the section "External Indexing and -# Searching" for details. +# Xapian (see: +# https://xapian.org/). See the section "External Indexing and Searching" for +# details. # This tag requires that the tag SEARCHENGINE is set to YES. SEARCHENGINE_URL = @@ -1800,9 +1893,11 @@ LATEX_EXTRA_FILES = PDF_HYPERLINKS = YES -# If the USE_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate -# the PDF file directly from the LaTeX files. Set this option to YES, to get a -# higher quality PDF documentation. +# If the USE_PDFLATEX tag is set to YES, doxygen will use the engine as +# specified with LATEX_CMD_NAME to generate the PDF file directly from the LaTeX +# files. Set this option to YES, to get a higher quality PDF documentation. +# +# See also section LATEX_CMD_NAME for selecting the engine. # The default value is: YES. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -2234,7 +2329,7 @@ HIDE_UNDOC_RELATIONS = YES # http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent # Bell Labs. The other options in this section have no effect if this option is # set to NO -# The default value is: NO. +# The default value is: YES. HAVE_DOT = YES @@ -2313,10 +2408,32 @@ UML_LOOK = NO # but if the number exceeds 15, the total amount of fields shown is limited to # 10. # Minimum value: 0, maximum value: 100, default value: 10. -# This tag requires that the tag HAVE_DOT is set to YES. +# This tag requires that the tag UML_LOOK is set to YES. UML_LIMIT_NUM_FIELDS = 10 +# If the DOT_UML_DETAILS tag is set to NO, doxygen will show attributes and +# methods without types and arguments in the UML graphs. If the DOT_UML_DETAILS +# tag is set to YES, doxygen will add type and arguments for attributes and +# methods in the UML graphs. If the DOT_UML_DETAILS tag is set to NONE, doxygen +# will not generate fields with class member information in the UML graphs. The +# class diagrams will look similar to the default class diagrams but using UML +# notation for the relationships. +# Possible values are: NO, YES and NONE. +# The default value is: NO. +# This tag requires that the tag UML_LOOK is set to YES. + +DOT_UML_DETAILS = NO + +# The DOT_WRAP_THRESHOLD tag can be used to set the maximum number of characters +# to display on a single line. If the actual line length exceeds this threshold +# significantly it will wrapped across multiple lines. Some heuristics are apply +# to avoid ugly line breaks. +# Minimum value: 0, maximum value: 1000, default value: 17. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_WRAP_THRESHOLD = 17 + # If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and # collaboration graphs will show the relations between templates and their # instances. @@ -2390,7 +2507,9 @@ DIRECTORY_GRAPH = YES # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order # to make the SVG files visible in IE 9+ (other browsers do not have this # requirement). -# Possible values are: png, jpg, gif, svg, png:gd, png:gd:gd, png:cairo, +# Possible values are: png, png:cairo, png:cairo:cairo, png:cairo:gd, png:gd, +# png:gd:gd, jpg, jpg:cairo, jpg:cairo:gd, jpg:gd, jpg:gd:gd, gif, gif:cairo, +# gif:cairo:gd, gif:gd, gif:gd:gd, svg, png:gd, png:gd:gd, png:cairo, # png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and # png:gdiplus:gdiplus. # The default value is: png. @@ -2506,9 +2625,11 @@ DOT_MULTI_TARGETS = YES GENERATE_LEGEND = YES -# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate dot +# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate # files that are used to generate the various graphs. +# +# Note: This setting is not only used for dot files but also for msc and +# plantuml temporary files. # The default value is: YES. -# This tag requires that the tag HAVE_DOT is set to YES. DOT_CLEANUP = YES diff --git a/sparta/doc/sparta_docs/modeling.txt b/sparta/doc/sparta_docs/modeling.txt index 1a221a11ee..dfe47d09c1 100644 --- a/sparta/doc/sparta_docs/modeling.txt +++ b/sparta/doc/sparta_docs/modeling.txt @@ -139,6 +139,13 @@ sparta::memory::TranslationIF | \copybrief sparta::memory::TranslationIF   sparta::memory::TranslationIFNode | \copybrief sparta::memory::TranslationIFNode   + ================================================================================ + \subsection pevents_overview Sparta PEvents (Performance Events) (sparta/pevents) + Class | Brief Description + --------------------------- | ------------------ + sparta::pevents::PeventCollector | \copybrief sparta::pevents::PeventCollector   + + ================================================================================ \subsection utils_overview Sparta Utilities/Tools APIs (sparta/utils) diff --git a/sparta/sparta/pevents/PEventHelper.hpp b/sparta/sparta/pevents/PEventHelper.hpp index 13d42dbaa9..5e6418f6f9 100644 --- a/sparta/sparta/pevents/PEventHelper.hpp +++ b/sparta/sparta/pevents/PEventHelper.hpp @@ -10,8 +10,8 @@ namespace sparta{ namespace pevents{ - //!A typedef for defining formatters for custom attributes. - typedef std::ios_base::fmtflags FormatFlags; +//!A typedef for defining formatters for custom attributes. +typedef std::ios_base::fmtflags FormatFlags; //we'll want a way to force that certain keys are not used else where. namespace PEventProtection @@ -29,7 +29,7 @@ namespace PEventProtection * be appending the quotes automatically. */ template - bool CheckNoQuotes(const T&, const std::string&, const std::string&) + bool CheckNoQuotes(const T&, const std::string&, const std::string&) { return true; } @@ -40,7 +40,7 @@ namespace PEventProtection * string type attribute. */ template - void AppendQuote(std::stringstream&) + void AppendQuote(std::stringstream&) {/*do nothing*/} @@ -76,8 +76,13 @@ namespace PEventProtection } - - +/*! + * \class PEvent + * \brief Defines the class base type for PEvents + * + * Do not use this class directly. Instead, use a + * sparta::pevents::PeventCollector object instead. + */ template class PEvent { @@ -354,6 +359,3 @@ class PEvent }//namespace pevents }//namespace sparta - - - diff --git a/sparta/sparta/pevents/PeventCollector.hpp b/sparta/sparta/pevents/PeventCollector.hpp index 33c4a32722..082698fcb5 100644 --- a/sparta/sparta/pevents/PeventCollector.hpp +++ b/sparta/sparta/pevents/PeventCollector.hpp @@ -19,14 +19,42 @@ namespace sparta{ namespace pevents{ - - /** * \class PeventCollector - * \brief a class that is capable of recording pevents as key value pairs, - * where a PairDefinition has been defined with the key values, and function - * pointers to where to get the data for the pairs. + * \brief Class that is capable of recording pevents as key value + * pairs, where a PairDefinition has been defined with the + * key values, and function pointers to where to get the + * data for the pairs. * \tparam the Type of PairDefinition that we want to capture a pevent from. + * + * Example usage: + * \code + * + * class MyUnit : sparta::Unit + * { + * public: + * // ... + * uint32_t getValue() const { ... }; + * // ... + * private: + * class MyEventPairs : public sparta::PairDefinition + * { + * public: + * using TypeCollected = Inst; + * MyEventPairs() : sparta::PairDefinition() + * { + * addPEventsPair("value", &MyUnit::getValue); + * } + * }; + * + * // Assumes this event is being constructed inside a sparta::Unit derived type + * sparta::pevents::PeventCollector my_pevent_{"MYEVENT", getContainer(), getClock()}; + * }; + * + * + * // Collection: + * my_event_.collect(my_unit_); + * \endcode */ template class PeventCollector @@ -218,4 +246,3 @@ namespace pevents{ } // namespace pevents } // namespace sparta - From 64e119f0321ca144b79071592513baedf028f958 Mon Sep 17 00:00:00 2001 From: Lehua Ding Date: Tue, 27 Feb 2024 20:32:26 +0800 Subject: [PATCH 2/9] Remove unused member ev_producing_event_(SkeletonPipeline) --- sparta/example/SkeletonPipeline/src/Producer.hpp | 4 ---- 1 file changed, 4 deletions(-) diff --git a/sparta/example/SkeletonPipeline/src/Producer.hpp b/sparta/example/SkeletonPipeline/src/Producer.hpp index 71a0f9f0c9..db7a1ea401 100644 --- a/sparta/example/SkeletonPipeline/src/Producer.hpp +++ b/sparta/example/SkeletonPipeline/src/Producer.hpp @@ -61,10 +61,6 @@ class Producer : public sparta::Unit // Producer's producer handler void produceData_(); - // Event to drive data, phase Tick, 1 cycle delay - sparta::UniqueEvent<> ev_producing_event_{&unit_event_set_, "ev_producing_event", - CREATE_SPARTA_HANDLER(Producer, produceData_), 1 /* delay */}; - // Internal count const uint32_t max_ints_to_send_; uint32_t current_ints_count_ = 0; From 78bc2d1fe431d33286e52435dc1080866ab6a567 Mon Sep 17 00:00:00 2001 From: littlewin-wang Date: Thu, 7 Mar 2024 14:08:54 +0800 Subject: [PATCH 3/9] [fix]: add paused check before pthread_mutex_lock. --- sparta/sparta/kernel/SleeperThread.hpp | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/sparta/sparta/kernel/SleeperThread.hpp b/sparta/sparta/kernel/SleeperThread.hpp index d0b821a7cc..ea51084636 100644 --- a/sparta/sparta/kernel/SleeperThread.hpp +++ b/sparta/sparta/kernel/SleeperThread.hpp @@ -380,8 +380,11 @@ class SleeperThread : public SleeperThreadBase void pause() override { if (thread_spawned_){ - paused_ = true; - pthread_mutex_lock(&pause_mutex_); + if(!paused_) + { + paused_ = true; + pthread_mutex_lock(&pause_mutex_); + } } } From e0406c00e2bbc2df273a07ca35a077da019b48e4 Mon Sep 17 00:00:00 2001 From: littlewin-wang Date: Mon, 11 Mar 2024 10:57:58 +0800 Subject: [PATCH 4/9] [hotfix]: make it simpler --- sparta/sparta/kernel/SleeperThread.hpp | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/sparta/sparta/kernel/SleeperThread.hpp b/sparta/sparta/kernel/SleeperThread.hpp index ea51084636..80ac77cb96 100644 --- a/sparta/sparta/kernel/SleeperThread.hpp +++ b/sparta/sparta/kernel/SleeperThread.hpp @@ -379,12 +379,10 @@ class SleeperThread : public SleeperThreadBase //! Force the sleeper thread to pause. Should be called before the Scheduler exits running void pause() override { + if(paused_) { return; } if (thread_spawned_){ - if(!paused_) - { - paused_ = true; - pthread_mutex_lock(&pause_mutex_); - } + paused_ = true; + pthread_mutex_lock(&pause_mutex_); } } From 79a35ccdf82e5dd146996ebfd868b31b39e68a88 Mon Sep 17 00:00:00 2001 From: adrenaholicgeek Date: Fri, 15 Mar 2024 15:03:39 +0000 Subject: [PATCH 5/9] Fix the syntax error warning causing error for some compilers (with -Werr) --- sparta/sparta/simulation/ClockManager.hpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sparta/sparta/simulation/ClockManager.hpp b/sparta/sparta/simulation/ClockManager.hpp index 36dfd9f4bc..c835b21837 100644 --- a/sparta/sparta/simulation/ClockManager.hpp +++ b/sparta/sparta/simulation/ClockManager.hpp @@ -19,7 +19,7 @@ #include "sparta/utils/SpartaAssert.hpp" namespace sparta { -class RootTreeNode; + class RootTreeNode; /** * \class ClockManager @@ -170,4 +170,4 @@ class RootTreeNode; }; // class ClockManager std::ostream &operator<<(std::ostream &os, const ClockManager &m); -}; +} From ee08219c9f3bf395c648720e0fdada4eb4b0c06f Mon Sep 17 00:00:00 2001 From: Knute Lingaard Date: Fri, 15 Mar 2024 09:49:32 -0500 Subject: [PATCH 6/9] Bug fix for Master scoreboard mask update --- sparta/sparta/resources/Scoreboard.hpp | 11 ++++++++++- sparta/src/Scoreboard.cpp | 7 +++++-- sparta/test/Scoreboard/Scoreboard_test.cpp | 3 +++ 3 files changed, 18 insertions(+), 3 deletions(-) diff --git a/sparta/sparta/resources/Scoreboard.hpp b/sparta/sparta/resources/Scoreboard.hpp index de40360e73..695a551b4a 100644 --- a/sparta/sparta/resources/Scoreboard.hpp +++ b/sparta/sparta/resources/Scoreboard.hpp @@ -258,6 +258,14 @@ namespace sparta return scoreboard_type_; } + /** + * \brief Get the name of this view + * \return Name of the view + */ + std::string getName() const { + return unit_name_; + } + private: // Make the Scoreboard a friend to clear bits in the view @@ -309,7 +317,8 @@ namespace sparta using ReadinessCallbacks = std::list; ReadinessCallbacks ready_callbacks_; - const sparta::Clock * clock_; + const sparta::Clock * clock_; + const std::string unit_name_; const Scoreboard::UnitID unit_id_; const std::string scoreboard_type_; }; diff --git a/sparta/src/Scoreboard.cpp b/sparta/src/Scoreboard.cpp index 9bb9fdc445..40d9061964 100644 --- a/sparta/src/Scoreboard.cpp +++ b/sparta/src/Scoreboard.cpp @@ -157,6 +157,7 @@ namespace sparta sbv->receiveScoreboardUpdate_(bits, INVALID_UNIT_ID); } } + global_reg_ready_mask_ |= bits; } void Scoreboard::set(const Scoreboard::RegisterBitMask & bits, Scoreboard::UnitID producer) @@ -173,6 +174,7 @@ namespace sparta sbv->receiveScoreboardUpdate_(bits, producer); } } + global_reg_ready_mask_ |= bits; } void Scoreboard::clearBits(const Scoreboard::RegisterBitMask & bits) @@ -232,6 +234,7 @@ namespace sparta const std::string & scoreboard_type, sparta::TreeNode * parent) : clock_(parent->getClock()), + unit_name_(unit_name), unit_id_(findMasterScoreboard_(unit_name, scoreboard_type, parent)), scoreboard_type_(scoreboard_type) { @@ -251,7 +254,7 @@ namespace sparta const Scoreboard::UnitID producer) { sparta_assert(bits.any(), - "Update should only be generated for non-empty vector"); + "Update should only be generated for non-empty vector: " << unit_name_); // Setting local ready bits local_ready_mask_ |= bits; @@ -309,7 +312,7 @@ namespace sparta // Try to find the master scoreboard, if it's available (has // been created by the Sparta framework) - + // Search for scoreboards from parent std::function findScoreboard = diff --git a/sparta/test/Scoreboard/Scoreboard_test.cpp b/sparta/test/Scoreboard/Scoreboard_test.cpp index 61b7dc4735..09dbe94a2d 100644 --- a/sparta/test/Scoreboard/Scoreboard_test.cpp +++ b/sparta/test/Scoreboard/Scoreboard_test.cpp @@ -535,16 +535,19 @@ void testScoreboardClearing() master_sb->set({0b1000}); is_set = view.isSet({0b1000}); EXPECT_TRUE(is_set); + EXPECT_TRUE(master_sb->isSet({0b1000})); master_sb->set({0b1100}); master_sb->set({0b1000}); is_set = view.isSet({0b1100}); EXPECT_TRUE(is_set); + EXPECT_TRUE(master_sb->isSet({0b1100})); master_sb->set({0b11}); master_sb->set({0b1000}); is_set = view.isSet({0b1111}); EXPECT_TRUE(is_set); + EXPECT_TRUE(master_sb->isSet({0b1111})); master_sb->clearBits({0b0100}); master_sb->set({0b1000}); From 3a668feafd9a3012ad6a1fd9618a2a6fcaebcc3e Mon Sep 17 00:00:00 2001 From: Brett Dutro Date: Mon, 8 Apr 2024 10:59:34 -0500 Subject: [PATCH 7/9] Add an implementation of a true LRU cache replacement policy --- sparta/cache/LRUReplacement.hpp | 83 +++++++++++++++++++++++++ sparta/test/cache/simple_cache/DL1.hpp | 1 + sparta/test/cache/simple_cache/main.cpp | 4 +- 3 files changed, 86 insertions(+), 2 deletions(-) create mode 100644 sparta/cache/LRUReplacement.hpp diff --git a/sparta/cache/LRUReplacement.hpp b/sparta/cache/LRUReplacement.hpp new file mode 100644 index 0000000000..c6d1796193 --- /dev/null +++ b/sparta/cache/LRUReplacement.hpp @@ -0,0 +1,83 @@ +// -*- C++ -*- + +//! +//! \file LRUReplacement.hpp +//! \brief Provides a simple true LRU implementation +//! + +#pragma once + +#include +#include + +#include "ReplacementIF.hpp" + +namespace sparta::cache +{ + // This class models true LRU with an std::list of way indices. The head of the list is LRU, and + // the tail is MRU. An std::vector of iterators to the list is used to provide constant-time + // index -> iterator lookup. A way is placed at LRU or MRU by moving its respective iterator to + // the beginning or end of the list. + class LRUReplacement : public ReplacementIF + { + public: + explicit LRUReplacement(const uint32_t num_ways) : ReplacementIF(num_ways) + { + for (uint32_t i = 0; i < num_ways; ++i) + { + way_map_.emplace_back(lru_stack_.emplace(lru_stack_.end(), i)); + } + } + + ReplacementIF* clone() const override + { + return new LRUReplacement(num_ways_); + } + + void touchLRU(uint32_t way) override + { + auto lru_it = way_map_[way]; + lru_stack_.splice(lru_stack_.begin(), lru_stack_, lru_it); + } + + void touchLRU(uint32_t way, const std::vector & way_order) override + { + sparta_assert(false, "Not implemented"); + } + + void touchMRU(uint32_t way) override + { + auto lru_it = way_map_[way]; + lru_stack_.splice(lru_stack_.end(), lru_stack_, lru_it); + } + + void touchMRU(uint32_t way, const std::vector & way_order) override + { + sparta_assert(false, "Not implemented"); + } + + uint32_t getLRUWay() const override { return lru_stack_.front(); } + + uint32_t getLRUWay(const std::vector & way_order) override + { + sparta_assert(false, "Not implemented"); + } + + uint32_t getMRUWay() const override { return lru_stack_.back(); } + + uint32_t getMRUWay(const std::vector & way_order) override + { + sparta_assert(false, "Not implemented"); + } + + void lockWay(uint32_t way) override + { + sparta_assert(way < num_ways_); + sparta_assert(false, "Not implemented"); + } + + private: + std::list lru_stack_; + std::vector::const_iterator> way_map_; + }; +} // namespace shinro diff --git a/sparta/test/cache/simple_cache/DL1.hpp b/sparta/test/cache/simple_cache/DL1.hpp index b12bb29644..6f16a66d34 100644 --- a/sparta/test/cache/simple_cache/DL1.hpp +++ b/sparta/test/cache/simple_cache/DL1.hpp @@ -2,6 +2,7 @@ #include "cache/SimpleCache.hpp" #include "cache/TreePLRUReplacement.hpp" +#include "cache/LRUReplacement.hpp" #include "cache/LineData.hpp" #include "cache/BlockingMemoryIF.hpp" diff --git a/sparta/test/cache/simple_cache/main.cpp b/sparta/test/cache/simple_cache/main.cpp index c041713a9b..5229098934 100644 --- a/sparta/test/cache/simple_cache/main.cpp +++ b/sparta/test/cache/simple_cache/main.cpp @@ -15,7 +15,7 @@ dl1_(32, // 32KB in size LINE_SIZE, // line size LINE_SIZE, // stride sparta::cache::LineData(LINE_SIZE), // line_size - sparta::cache::TreePLRUReplacement(8) ); // num_ways + sparta::cache::LRUReplacement(8) ); // num_ways sparta::cache::SimpleCache l2_(512, // 512KB @@ -31,7 +31,7 @@ btb_a_(4, // 4kb LINE_SIZE, // line size LINE_SIZE, // stride sparta::cache::LineData(LINE_SIZE), // default line copied for initialization - sparta::cache::TreePLRUReplacement(4) ); // num_ways + sparta::cache::LRUReplacement(4) ); // num_ways sparta::cache::SimpleCache2 btb_b_(4096, // 4kb From 79241b62b4342af18a3a74a348c0d48f04fc6e78 Mon Sep 17 00:00:00 2001 From: adrenaholicgeek Date: Fri, 5 Apr 2024 17:09:18 +0100 Subject: [PATCH 8/9] Fix the script to make sure user is using conda-forge channel. This resolves the further dependency issues. Co-authored-by: Arash Koohzad Mohammadi --- scripts/render_recipe_for_platform.sh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/render_recipe_for_platform.sh b/scripts/render_recipe_for_platform.sh index 3f19c517be..ffb6a18a43 100755 --- a/scripts/render_recipe_for_platform.sh +++ b/scripts/render_recipe_for_platform.sh @@ -91,7 +91,8 @@ echo "Rendering recipe in $PWD/conda.recipe" # from 'conda render' export SYSTEM_DEFAULTWORKINGDIRECTORY="$PWD" - +# Make sure to have conda-forge channel to resolve dependencies +conda config --add channels conda-forge # Render the recipe into a fully-resolved yaml file (set -x; conda render -m "$variant_file" --file "$rendered_output" conda.recipe) From 000826f860e2ed974b6ea8aea8d1183363dab0be Mon Sep 17 00:00:00 2001 From: bdutro Date: Wed, 24 Apr 2024 10:12:44 -0500 Subject: [PATCH 9/9] Define custom copy/move constructors/operators for SharedData and (#493) GlobalEvent - This fixes a segfault that can occur after a SharedData is copied --- sparta/sparta/events/GlobalEvent.hpp | 37 ++++++++++++++++++++++ sparta/sparta/resources/SharedData.hpp | 43 ++++++++++++++++++++++++++ 2 files changed, 80 insertions(+) diff --git a/sparta/sparta/events/GlobalEvent.hpp b/sparta/sparta/events/GlobalEvent.hpp index f8319ce31a..effb6d2654 100644 --- a/sparta/sparta/events/GlobalEvent.hpp +++ b/sparta/sparta/events/GlobalEvent.hpp @@ -106,6 +106,43 @@ namespace sparta ev_sched_ptr_(clk->getScheduler()->getGlobalPhasedPayloadEventPtr()) {} + GlobalEvent(const GlobalEvent& rhs) : + local_clk_(rhs.local_clk_), + event_handler_(rhs.event_handler_), + ev_handler_lifetime_(&event_handler_), + ev_sched_ptr_(rhs.ev_sched_ptr_) + { + } + + GlobalEvent(GlobalEvent&& rhs) : + local_clk_(rhs.local_clk_), + event_handler_(std::move(rhs.event_handler_)), + ev_handler_lifetime_(&event_handler_), + ev_sched_ptr_(rhs.ev_sched_ptr_) + { + rhs.ev_handler_lifetime_.reset(); + } + + GlobalEvent& operator=(const GlobalEvent& rhs) { + local_clk_ = rhs.local_clk_; + event_handler_ = rhs.event_handler_; + ev_handler_lifetime_ = utils::LifeTracker(&event_handler_); + ev_sched_ptr_ = rhs.ev_sched_ptr_; + + return *this; + } + + GlobalEvent& operator=(GlobalEvent&& rhs) { + local_clk_ = rhs.local_clk_; + event_handler_ = std::move(rhs.event_handler_); + ev_handler_lifetime_ = utils::LifeTracker(&event_handler_); + ev_sched_ptr_ = rhs.ev_sched_ptr_; + + rhs.ev_handler_lifetime_.reset(); + + return *this; + } + void schedule(const Clock::Cycle & delay, const Clock * clk) { sparta_assert(ev_sched_ptr_ != nullptr); sparta_assert(ev_sched_ptr_->getSchedulingPhase() == sched_phase_T); diff --git a/sparta/sparta/resources/SharedData.hpp b/sparta/sparta/resources/SharedData.hpp index f03de20df6..8b23e9cb26 100644 --- a/sparta/sparta/resources/SharedData.hpp +++ b/sparta/sparta/resources/SharedData.hpp @@ -49,6 +49,11 @@ namespace sparta return current_state_; } + void resetHandler_() + { + ev_update_.resetHandler(CREATE_SPARTA_HANDLER(SharedData, update_)); + } + public: /** * \brief Construct a SharedData item @@ -65,6 +70,44 @@ namespace sparta writePS(std::forward(init_val)); } + SharedData(const SharedData& rhs) : + ev_update_(rhs.ev_update_), + current_state_(rhs.current_state_), + data_(rhs.data_) + { + resetHandler_(); + } + + SharedData(SharedData&& rhs) : + ev_update_(std::move(rhs.ev_update_)), + current_state_(std::move(rhs.current_state_)), + data_(std::move(rhs.data_)) + { + resetHandler_(); + } + + SharedData& operator=(const SharedData& rhs) + { + ev_update_ = rhs.ev_update_; + resetHandler_(); + + current_state_ = rhs.current_state_; + data_ = rhs.data_; + + return *this; + } + + SharedData& operator=(SharedData&& rhs) + { + ev_update_ = std::move(rhs.ev_update_); + resetHandler_(); + + current_state_ = std::move(rhs.current_state_); + data_ = std::move(rhs.data_); + + return *this; + } + /** * \brief Write data to the current view * \param dat The data to write for visibility \b this cycle