====== Statistic File Capability ======

The [[services:Statistics:|Statistic Capability]] allow to generate various statistics tied to the simulation such as the cache miss rate, number of instruction executed and so on.

The **Statistic File Capability** allows to save some of the statistics computed during the simulation to an output file, and to reload those statistics for future simulations.

Such a capability enable different uses:
  * It allows to validate different runs of the simulator comparing the statistics for those different runs.
  * It also allow to pass some statistics from an higher level simulation to a lower level one, to either:
    * compare the accuracy on some specific metrics of the level of abstraction
    * to estimate the running time of the lower level simulator (knowing the total number of instructions)



















===== Interface =====

The **Statistic File Interface** is very simple, just providing a method to either create a new statistic file or reload an existing one, then some methods to add new statistics and to save the statistic repository to a file.

The interface for the Statistic File Capability is defined by the ''StatisticFile'' class presented below:
<code c>
class StatisticFile
{public:
  StatisticFile ()                        // Creates a new empty Statistic File
  StatisticFile (const string &name)      // Creates a Statistic File by reading an input file
  void add (const string &name, T value)  // Add a new statistic of type T to the repository
  const T operator[ ] (const string&)     // Access a statistic from the repository
  void save (const string &name)          // Save the statistic repository to an output file.
}
</code>

The next section describes how to use the statistic file capability within your own simulators.







===== How To use the Statistic File Capability in your simulator =====

To illustrate the use of the **Statistic File Capability** we'll add:
  * the ability to a Powerpc instruction set simulator to dump the number of executed insturctions at the end of the run
  * the ability to a cycle level simulator to relaod such a satistic file to be able to build some sort of progress bar during the simulation.

=== Modification to the ISS simulator ===

Adding the following code at the end of your ISS will allow it to dump statistics:

<code c>
 StatisticFile f;
 double speed = cpu->GetInstructionCounter() / spent_time;
 f.add("instruction_count",cpu->GetInstructionCounter());
 f.add("emulation_time",spent_time);
 f.add("speed",speed);
 f.save("dump-statistics");
</code>

The statistics consisting of:
  * the number of instruction executed
  * the total emulation time
  * the average emulation speed

The first one will allow us to compute the estimated ETA in the cycle-level simulator, the last two ones could be used to compute the cycle-level over ISS slowdown.

=== Modification to the cycle-level simulator ===

Then the cycle level simulator needs to be modified to reload the ISS statistic before the main simulation loop, adding the following source code:

<code c>
  StatisticFile statfile("dump-statistics");
  predicted_total_instructions = statfile["instruction_count"];
</code>

Last, we can add our "progress indicator" to the main simulation loop, even if it is not the most efficent way to do so, as it will slow the simulator a lot:

<code c>
  cerr << commited_instructions << "/" << predicted_total_instructions << endl;
</code>

A more efficient way would be to do this in a separated thread refreshing the indicator every few seconds or so.


===== Reference Manual =====

  * [[http://unisim.org/website/refman/capabilities/stat_file/refman.pdf|Statistic File Capability reference manual]]