- Generated on Tue Sep 17 2024 19:22:50 for The Sparta Modeling Framework by
1.9.8
|
The Sparta Modeling Framework
|
This page details the usage, configuration, inputs, and outputs of "sparta-based CLI(command line interface)". This term is used to refer to a simulator that uses the sparta::app framework (sparta::app::CommandLineSimulator and sparta::app::Simulation) to initialize and configure the simulator from the command line. If a simulator application is not using this part of the Sparta framework, very little of this end-user guide is applicable to an application. Some of these features will still be available interally to the simulation framework, but they may be exposed to the end-user in a different manner.
The terms "sparta simulator" and "sparta-instrumented simulator" differ in that they refer only to simulators that expose a sparta tree with instrumentation such as counter, statistics, and notifications. Such simulators may or may not be driven by a sparta CLI.
For the purpose of this page, 'user' means an invidual or script who invokes a simulator through its command line interface or needs to work with Sparta simulator output
The Sparta command line consists of a number of generic options built into the sparta application framework as well as application-specific commands that pertain to a specific simulator.
In general, the Sparta application framework attempts to provide a large set of generic commands without making any assumptions about the underlying device being simulated. The only assumptions made are that the device operates on one or more clock domains with regular frequencies and that there is some 'tick' (sparta::Scheduler::getCurrentTick) unit which can be used as a unit of absolute time in which inputs and outputs can be expressed. The tick is typically 1 picosecond, but may also be the least-common multiple of all these clock periods. All clock periods will be integer multiples of the tick period (in terms of simulated time)
Similarly, Sparta will eventually write snapshot pipeout files on error. The pipeout file prefix will be configurable
Eventually, the simulation may be able to suspend itself from within a failed memory allocation or bad file write.
The most useful of all commands are the help commands. Even if this document is out of date, full (albiet abridged) documentation will be available through the –help-verbose command line flag. The -h flag shows a limited set of the most common options with very brief descriptions. The get detailed help on all commands, use
or
A number of other built-in commands are listed in later sections.
Simulator command-lines can have any number of application-specific commands. Refer to that simulator's documentation for details.
Examples of some typical simulator-specific commands are instruction-count limits, version-printing, showing additional detailed help pages, and specifying trace files. Positional arguments are always application-specific.
Extending the sparta CLI to add application-specific events is straightforward and requires boost program_options.
The sparta CLI provides a few options that help debug the CLI and the Sparta simulation framework.
| Usage | Behavior |
|---|---|
| --debug-sim | Turn on simulator framework debugging |
| --show-options | Show all options parsed from the command line |
| --verbose-config | Sets all configuration file readers and emitters to verbose mode for easier debugging |
Sparta simulations are configured using parameters, which can be specified on the command line individually or using YAML configuration files.
| Usage | Alternate | Behavior |
|---|---|---|
| -p PATTERN VAL | --parameter | Specify an individual parameter value. Multiple parameters can be identified using '*' and '?' glob-like wildcards. Example: "\--parameter top.core0.params.foo value" |
| -c FILENAME | --config-file | Specify a YAML config file to load at the top of the simulator device tree. Example: "--config-file config.yaml" This is effectively the same as --node-config-file top params.yaml |
| -n PATTERN FILENAME | --node-config-file | Specify a YAML config file to load at aspecific node (or nodes using '*' and '?' glob-like wildcards) in the device tree. Example: "\--node-config-file top.core0 core0_params.yaml" |
Use of the -p option is straightforward. Using -c and -n require YAML-based sparta parameter configuration files, whose format is described in detail in Parameter/Configuration Format (.cfg,.yaml) .
Sparta configuration supports the` concept of architecture configuration baselines. This allows users to load configuration files that override the defaults of chosen parameters hard-coded in the simulator source code. Unlike typical configuration files or command line parameter specifications, selecting an architecture updates both the default and the value of any specified parameter such that it will show up as having a default value the final configuration of the simulator (–write-final-config) is inspected.
| Usage | Function |
|---|---|
| --arch ARCH | Searches in --arch-search-dir for a configuration file matching the given name "name" or "name.yaml" or "name.yml" or "name/name.yaml" or "name/name.yml" |
| --arch-search-dir DIR | Absolute path or relative path (to cwd) dictating where the simulator should look for --arch names to resolve them to actual configuration files |
The default values for both of these options are simulator specific. The default architecture search dir is listed in the --arch-search-dir command help string.
Afer resolving an --arch name to a config file, that configuration file is listed in the simulator output during simulator setup to show exactly what configuraration files were applied to what parts of the simulated tree and whether they were applyed as architectural baseline configuration or normal configuration.
Lexical casting of numeric literals in sparta is smart. Values being assigned to integer parameters through command line options or configuration files in the simulator can use prefixes to specify radix and suffixes to specify multipliers.
For example, 10b will be interpreted as 10000000000 (10 billion)
Note that this can be done only on parameters which EXPECT AN INTEGER. This includes any command-line options or configuration files dealing with [u]intXX_t-typed parameters. Only parts of the simulation which expect an integer will use this smart parsing mechanism. This cannot yet be used in statistic expressions because these expressions operate on doubles at all times.
The full set of features includes
These suffixes (case insensitive) can be added have the following meanings
| Suffix | Multiplier |
|---|---|
| K | 10^3 |
| M | 10^6 |
| G | 10^9 |
| B | 10^9 |
| T | 10^12 |
| P | 10^15 |
| Ki | 2^10 |
| Mi | 2^20 |
| Gi | 2^30 |
| Bi | 2^30 |
| Ti | 2^40 |
| Pi | 2^50 |
Additional Notes:
Parameter types of uint32_t, for example, will error if they encounter larger values than MAX_UINT32
The sparta CLI supports a number of output mechanisms for any sparta-instrumented simulator.
After a successful run, an automatic summary of all known counters and statistics in the simulation device tree will be written to stdout.
By default, this looks something like:
top top.foo top.foo.bar stat_x = 0 stat_y = 12324 stat_Z = 3.2491 top.foo.biz stat_a = 67
If configured to be verbose, the automatic summary looks something like:
top top.foo top.foo.bar stat_x = 0 # Number of x's that happend while doing # q while in state r or s but not t stat_y = 12324 # Time foo.bar did y stat_Z = 3.2491 # Value of z. Some of these comments can # get really long and may wrap multiple # times beacuse someone made them so very # very long. top.foo.biz stat_a = 67 # Short desciption
This behavior can be controlled using the –auto-summary command line option. Valid usages are:
| Usage | Behavior |
|---|---|
| --auto-summary off | Do not write summary |
| --auto-summary on | Write summary to stdout |
| --auto-summary normal | Write summary to stdout (same as on) |
| --auto-summary verbose | Write verbose summary to stdout including descriptions |
The Sparta Report system is capable of collecting counters and statistics from the simulation device tree and printing their names and values to an output file or stream in any of a variety of formats. This is the principal means of extracting quantitative data from a simulation.
Other than the automatic summary, all reports must be explicitly created on the command line. The --report and --report-all options configure a new report or reports.
| Usage | Behavior |
|---|---|
| --report PATTERN DEF OUT [FMT] | Create one or more reports based on the report definition file DEF at all nodes matching PATTERN and write the end-of-simulation result to OUT using the optionally-specified format FMT. If no format is given, infers it from the file extension. Use --help for more details about this command. See both the --report command details and the "Reports" section of the help output. DEF may be specified as "@" (no quotes necessary) to direct the simulator to autopopulate the report instead of using a definition file. |
| --report-all OUT [FMT] | Create one or more reports containing all counters and statistics in the simulation and write the end-of-simulation result to OUT using the optionally-specified format FMT. If no format is given, infers it from the file extension. Use --help for more details about this command. See both the --report-all command details and the "Reports" section of the help output |
Report definition files are a restricted subset of the YAML files with special semantics for YAML dictionaries based on context in the file. See Report Definition Format (.rrep,.yaml)
Often, this is used to place a simple report on the top-level node in the simulation tree
simulation --report top myreport.yaml out.txt
Node paths in myreport.yaml for the above example would be specified relative to "top".
Often, a global scope is desired so that Sparta scheduler statistics can be used (e.g. ticks) or just to allow fully qualified paths. This can be done using the "_global" keyword.
simulation --report _global myreport.yaml out.txt
Node paths in this report definition would be fully qualified and begin with "top." or "scheduler."
Each report directive can created multiple reports if the PATTERN contains multiple wildcards. For example:
simulation --report top.nodeX.* @ out%i.csv csv
It is generally a bad idea to direct mutliple reports to the same output file as the result is undefined and the files could be overwritten. If using a wildcard in the PATTERN variable in the --report command, it is usually necessary to use either of the %i (index) or %l (location) variables in the output file name. The following variables are supported (From sparta::app::computeOutputFilename).
| Wildcard | Value |
|---|---|
| %l | location (lower case L) |
| %i | index of substitution for wild-card in PATTERN (0-based). Based on construction order of found nodes |
| %p | process ID |
| %t | timestamp |
| %s | simulator name |
When using a variable in the destination, Sparta will list the instantiations both at the start of simulation and at the end.
Running... Placing report on node top.nodeX.nodeY for: Report "@" applied at "top.nodeX.*" -> "out0.csv" (format=csv) Placing report on node top.nodeX.nodeZ for: Report "@" applied at "top.nodeX.*" -> "out1.csv" (format=csv) ... later ... [out] Wrote Final Report Report "@" applied at "top.nodeX.*" -> "out%i.csv" (format=csv) (updated 13 times): Report instantiated at top.nodeX.nodeY, updated to "out0.csv" Report instantiated at top.nodeX.nodeZ, updated to "out1.csv" 2 reports written
There are several modifiers to the behavior of the reports created. These will eventually be deprecated and replaced with a more robust and flexible control system that can apply to individual reports
| Usage | Behavior |
|---|---|
| --report-warmup-count INSTRUCTIONS | Does not begin any report (including builtin reports such as the automatic summary) until INSTRUCTIONS instrutions have elapsed based on whatever counter the simulator has identified as having the 'instruction count' semantic. See sparta::app::Simulation::CounterSemantic |
| --report-update-ns NANOSECONDS | Periodically update all reports every NANOSECONDS written with formatters that support updating (see --help-topic reporting for information). CSV supports this at the least. This does not affect the automatic summary report. Exclusive to other --report-update-* options. |
| --report-update-cycles [CLOCK] CYCLES | Periodically update all reports every CYCLES cycles on the clock named CLOCK (optional) written with formatters that support updating (see --help-topic reporting for information). CSV supports this at the least. This does not affect the automatic summary report. Exclusive to other --report-update-* options. |
| --report-update-counter COUNTER COUNT | Periodically update all reports every COUNT units for a counter located in the tree at path COUNTER (e.g. top.core0.foo.stats.bar) written with formatters that support updating (see --help-topic reporting for information). This option guarantees one update to each applicable report for each multiple of COUNT reached by the counter, even if the counter is incremented as a coarse granularity such that it skips multiple instances of that target count period in a single cycle. The extra updates will show 0-deltas for all counters. CSV supports this at the least. This does not affect the automatic summary report. Exclusive to other --report-update-* options. |
When using repeating reports, be sure that the report formatter actually supports updating. Some formatters do not.
When the simulator writes its final reports, it will also indicate how many times each user-specified report has been updated. For example:
simulation <other arguments> --report-update-ns 1000 --report top.nodeX.nodeY @ out.csv csv
May generate:
[out] Wrote Final Report Report "@" applied at "top.nodeX.nodeY" -> "out.csv" (format=csv) (updated 14 times):
To periodically report based on a counter value such as intruction retierd, the following could be used in a simulator with the appropriate counter.
simulation <other arguments> --report-update-counter top.core0.retire.stats.num_insts_retired 1000 --report top.nodeX.nodeY @ out.csv csv
When writing a report that is periodically updated, it is useful to create a report definition file that includes a clock cycle counter as the first item in the report definition. Then, the report output will include that clock's value in the first column (in the case of CSV). This looks like:
After generating a periodic report in the CSV format, try plotting with the Sparta csv report plotter in sparta/tools/plot_csv_report.py
The list of available report output formats are available at Report Output Formats . Refer to this page for notes and details. Use
"--help-topic reporting"
</b
to get information
about report formatsinteractively from a Sparta simulator
For more details about the modeling side of logging, see Logging in sparta refers to a plaintext logging system for informational and diagnostic messages. Sparta includes a mechanism for generating textual messages that can be configurably directed to various output files in variou formats to generate a textual trace of the state or events inside particular components of a simulation.
| Usage | Behavior |
|---|---|
| --warn-file FILENAME | Specifies which file to which warnings should be directed (independent of --no-warn-stderr) |
| --no-warn-stderr | If set, prevents logging messages of the "error" category to the stderr stream.(independent of --warn-file) |
| Command | Functionality |
|---|---|
| -l / --log PATTERN CATEGORY DESTINATION | Creates a logging "tap" on the node(s) described by PATTERN. These taps observe log messages emitted at or below these nodes in the Sparta tree when the messages' categories match CATEGORY. If CATEGORY is "", all message categories match. ALl log output received through this tap is routed to DESTINATION, which is formatted based on the file extension. See the Logging Formats below. |
The DESTINTION field of the --log option directs the log messages from that log tap to a specific destination. These destinations are formatted based on their file extension (for now). Using 1 or 2 as a destination file directs the log output to stdout or stderr respectively.
| Format | File Extension | Description |
|---|---|---|
| Basic (stdout) | 1 | Contains message origin, category, and content |
| Basic (stderr) | 2 | Contains message origin, category, and content |
| Basic (file) | *.log.basic | Contains message origin, category, and content |
| Verbose (file) | *.log.verbose | Contains all message meta-data |
| Raw (file) | *.log.raw | Contains no message meta-data |
| Default (file) | (any other ) | Contains most message meta-data excluding thread and message sequence number |
Except raw output, each logger output places its content on a single line, beginning with a an opening '{', followed by some fileds describing the log messages, usualy including a timestamp, origin, and category, followed by a closing '}' and then the log message itself. This generally makes these log messages easily parsable.
All current logging formats can be seen near the end of the help text generated by --help or by the --help-logging command.
Pipeline collection captures a per-cycle trace of 'transactions' flowing through specially instrumented stations (e.g. buffer elements, queues, etc.) throughout the simulator when enabled. This data can be visualized in the Argos (4.1 Pipeline viewer (Argos)) viewer with customizable layouts to display and navigate pipeline snapshots and time-based pipeline crawls.
This data is written to a set of files having a common, user-specified prefix. Support for collection requires participation on the part of each model.
These files include a clock listing, a map of device tree locations to indices, a transaction data binary, a time-index, and a simulation info file
See also pipeout_format
Often, pipeline collection introduces too much performance and disk-space overhead to leave on for a multi-million cycle simulation. It becomes necessary to selectively enable collection after a certain amount of progress has been made in the simulation. Pipeline collection (and log taps) can be controlled with the --debug-on family of options.
| Usage | Behavior |
|---|---|
| --debug-on [clock] CYCLE | Defers pipeline collection and user-specified logging until cyclye=CYCLE on optional clock=path.to.clock.name |
| --debug-on-icount ICOUNT | Defers pipeline collection and user-specified logging until the instruction count has reached ICOUNT. Each simualtor defines its own instruction counter through app::Simulation::findSemanticCounter |
When the Sparta application framework encounters an exception during running or post-run validation, it attempts to dump the debug state. This behavior can be controlled to always dump or never dump using the –debug-dump command line option. Valid usages are
| Usage | Behavior |
|---|---|
| --debug-dump always | Always dump |
| --debug-dump never | Never dump |
| --debug-dump error | (default) Dump on run exception or post-run validation exception |
During this dump, the simulator will write information about itself, about the Sparta Scheduler, the exception, the device tree, the backtrace of the exception (if exception is a SpartaException) and then every known resource will be asked to write its debug state to a file. During this procedure all exceptions are suppressed and a note about any suppressed exceptions will be found in the dump.
When a debug dump occurs, the simulator will write a message such as:
[out] Debug state written to "error-dump.dbg"
If a post-run debug dump occurs, the output file used for this dump can be explicitly controlled with the --debug-dump-filenamet argument.
| Usage | Behavior |
|---|---|
| --debug-dump-filename FILENAME | Save to FILENAME. If "", auto-generates filename |
| (omitted) | Auto-generate timestamped filename |
The debug dump file contains a section for each resource in the simulation that writes any debug data to the output stream when given the chance. The file structure will look something like this
This output contains some ANSI color escape sequences that can look strange if viewed as plaintext. To see the colors represented by these sequences, either
or
When the Sparta application framework encounters a fatal signal in the following list
The simulator will attempt to print a bactrace to stderr and exit with EXIT_FAILURE (from cstdlib). No debug dump is currently written for these signals. Backtraces are also written to the error-dump.dbg (see 3.7 Post-Run Debug dumps) file when exiting the simulation due to an unhandled Exception. Other signals may eventually be handled similarly.
The device tree constructed by the simulator is visible in its entirity to a user who requests it. These are highly verbose options, but give a clear picture of the content of the simulator. When specifying parameters or creating manual report definitions, this is one way to view the structure of the simulator.
| Usage | Behavior |
|---|---|
| --show-tree | Show the entire simulation device tree between each phase of simulator startup and continues as usual |
| --show-parameters | Show all parameters in the device tree after configuration is complete and continues as usual |
| --show-ports | Show all ports in the device tree after the tree is fully bound and continues as usual |
| --show-counters | Show all counters and statistics in the device tree after the tree is fully bound and continues as usual |
| --show-notifications | Show all notification sources in the device tree after the tree is fully bound and continues as usual |
| --show-loggers | Show all log message sources in the device tree after the tree is fully bound and continues as usual |
| --show-dag | Show the Event DAG (directed acyclic graph) and continues as usual |
| --help-tree | Same as --show-tree --no-run |
| --help-parameters | Same as --show-parameters --no-run |
| --help-ports | Same as --show-ports --no-run |
| --help-counters | Same as --show-counters --no-run |
| --help-notifications | Same as --show-notifications --no-run |
| --help-loggers | Same as --show-loggers --no-run |
| --help-topic verbose | Shows verbose help then exits |
| --help-topic brief | Shows brief help then exits |
| --help-topic logging | Shows help topic on logging then exits |
| --help-topic reporting | Shows help topic on logging then exits |
| --help-topic topics | Shows all help topics |
| --help-topic pipeout | Shows all help topics |
| --help-topic parameter | Shows all help topics |
GDB 4.7 is capable of debugging the sparta infrastructure and handles the GNU ISO C++11 standard library.
The Sparta simulation framework catches and rethrows exceptions internally in order to provide debug dumps, perform proper cleanup, and potentially preserve state for user inspection once an interactive shell is built for sparta simulators. GDB breaks on uncaught exceptions by default, which is not helpful for sparta. It is more effective to break on Exception throws as seen below.
gdb --args simulator ... (gdb) catch throw (gdb) run
Alternatively, one can set a breakpoint on the sparta::SpartaException constructor to stop execution at a point very close to an exception being thrown.
(gdb) break 'sparta::SpartaException::SpartaException()'
This default construtor for SpartaException is always invoked (through delegation) regardless of how the exception is constructed, so it will reliably be hit for every SpartaException (or subclass) that is constructed.
Be sure to use other run-time debugging tools available, such as 3.3 Message Logging, 3.6 Pipeline Collection, 3.7 Post-Run Debug dumps, and 3.4 Backtraces.
Other debuggers such as Totalview have been used to debug sparta-based simulators. However, C++11 STL support in this debugger is limited and types like std::shared_ptr from the GNU ISO standard library can cause crashes in this debugger
Argos visualizes pipeline data generated from a simulator if that simulator supports sparta pipeline collection. See pipeline for instructions on using pipeline collection.
Argos is a free-form visualization tool for showing pipeline snapshots and crawls in custom layouts. Development is ongoing.
Future editions of Argos will aim to provide more dashboard-like functionality with the ability to show counters, statistics, and histograms from the simulation in addition to pipeline state.
1.9.8