====== ELF Loader Capability ======

The **ELF Loader Capability** allows to load a binary or a kernel prior to the simulator start simulating it.

A loader is closely tied to the ISA. A PowerPC loader can therefore be reused across different implementation of the same ISA (in-order, superscalar, ...)

===== Instruction: Role of the loader =====

The role of the loader is to load the program into the memory and set various registers such as the stack pointer and the program counter. It can also load the
symbol table of the simulated program if it was compiled with "-g" to provide additional information to a plugged debugger.




===== Interface =====

The loader affects the register bank and the main memory. It requires to be able to write in some registers (stack pointer, PC) and to write the binary to the main memory, as shown on the picture below:

{{ elf_loader_itf.png }}

To to so, the loader will use the **MemoryInterface** provided by the memory and the **RegisterInterface** provided by the CPU.




===== 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 **Loader File Capability** let's plug a loader to a dram memory. To do so let's consider a simulator with the following modules defined:

<code c>
  CpuPPC405<...> cpu;
  DRAM<...> dram;
  ... other modules ...
</code>

First, we shoould add a PowerPC Loader to the simulator:

<code c>
  CpuPPC405<...> cpu;
  DRAM<...> dram;
  ... other modules ...
  StandalonePowerPCLoader loader("loader",NULL);
</code>

Second, we should paramereize the PowerPC loader to provide the elf binary.

<code c>
  loader["elf32-loader.filename"] = filename;
  loader["linux-loader.endianess"] = E_BIG_ENDIAN;
  loader["linux-loader.stack-base"] = 0xc0000000;
  loader["linux-loader.max-environ"] = 16 * 1024;
  loader["linux-loader.argc"] = sim_argc;          // Pass the extra arguments of the simulator 
  for(j = 0; j < sim_argc; j++)                    // on the command line as the command line
  { loader["linux-loader.argv"][j] = sim_argv[j];  // of the simulated program
  }
  loader["linux-loader.envc"] = 0;
</code>

Last we need to connect the loader to the CPU and the DRAM:

<code>
  loader.memory_import >> dram.loader_exp;
  loader.cpu_import >> cpu.loader_exp;
</code>

Now, at the initialization of the Loader capability, the binary provided on the command line will be loaded in the 
simulator and the register bank will be initialized.


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

  * [[http://unisim.org/website/refman/capabilities/loader/refman.pdf|Loader Capability reference manual]]