MicroTESK

h1. Template Description Language

_~By Artemiy Utekhin~_

*UNDER CONSTRUCTION*

{{toc}}

h2. Introduction

MicroTESK generates test programs on the basis of _*test templates*_ that provide an abstract description of scenarios to be reproduced by the generated programs. Test templates are created using the _*test template description language*_. It is a Ruby-based domain-specific language that provides facilities to describe tests in terms of the target microprocessor''s ISA and to manage the structure of the generated test programs. The language is implemented as a library that includes functionality for describing test templates and for processing these test templates to produce a test program. MicroTESK uses the JRuby interpreter to process test templates, which allows interaction between Ruby libraries and other parts of MicroTESK written in Java.

h2. How It Works (TODO: rewrite)

Ruby-TDL code describes a template of a test program which is then translated into TL code using the API of the MicroTESK CPU model parser and simulator (and, by extension, the constraint solver and other MicroTESK components). The process can be described as follows:

# Receiving model metadata from the simulator;

# Template pre-processing;

# Constructing commands in the simulator;

# Executing commands in the simulator;

# Receiving the assembler code from the simulator (based on the CPU Sim-nML description);

# Writing the TL output to target files.

Depending on the circumstances some of these steps may be done concurrently.

h2. Configuration

Global settings for the test template subsystem are specified in the <code>config.rb</code> file. These settings are related to the package structure and dependencies of the subsystem. They are predefined and rarely need to be modified. Also, there are local settings that control processing of individual test templates. They are specified as member variables of the <code>Template</code> class. Test templates can override these settings to customize the behavior of the subsystem. The settings will be discussed in more detail in the Writing Test Templates section.

h2. Running Test Program Generation

To start test program generation, a user needs to run the <code>generate.sh</code> script (Unix, Linux, OS X) or the <code>generate.bat</code> script (Windows) located in the <code>bin</code> folder. The script launches a Ruby program that processes the specified test template and produces a test program. The command to run the script has the following format: 

<pre>generate <model name> <template file.rb> [<output file.asm>]</pre>

There are three parameters: (1) the name of the microprocessor model (generated by the [[Sim-nML Translator]] on the basis of Sim-nML specifications), (2) the name of the test template file to be processed and (3) the name of the test program file to be generated (optional, if it is skipped the program is printed to the console). For example, the following command processes the <code>demo_template.rb</code> test template and saves the generated test program to the <code>test.asm</code> file:

<pre>sh bin/generate.sh demo arch/demo/templates/demo_template.rb test.asm</pre>

h2. Writing templates (TODO: rewrite)

h3. Basic features

The two core abstractions used by MicroTESK parser/simulator and Ruby-TDL are an *instruction* and an *addressing mode*. An instruction is rather self-explanatory, it simply represents a target assembler instruction. Every argument of an instruction is a parametrized *addressing mode* that explains the meaning of the provided values to the simulator. The mode could point to the registers, for instance, or to a specific memory location. It can also denote an immediate value - e.g. a simple integer or a string. Thus, a basic template is effectively a sequence of instructions with parametrized addressing modes as their arguments.

Each template is a class that inherits a basic Template class that provides most of the core Ruby-TDL functionality. So, to write a template you need to subclass Template first:

<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"

class MyTemplate < Template</code></pre>

While processing a template Ruby-TDL calls its %pre%, %run% and %post% methods, loosely meaning the pre-conditions, the main body and the post-conditions. The %pre% method is mostly useful for setup common to many templates, the %post% method will be more important once sequential testing is introduced. Most of the template code is supposed to be in the %run% method. Thus, a template needs to override one or more of these methods, most commonly %run%.

To get %pre% and %post% over with, the most common usage of these is to make a special non-executable class and then subclass it with the actual templates:

<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"

class MyPrepost < Template

  def initialize

    super

    @is_executable = no

  end

  def pre

    # Your ''startup'' code goes here

  end

  def post

    # Your ''cleanup'' code goes here

  end

end</code></pre>

<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"

class MyTemplate < MyPrepost

  def initialize

    super

    @is_executable = yes

  end

  def run

    # Your template code goes here

  end

end</code></pre>

These methods essentially contain the instructions. The general instruction format is slightly more intimidating than the native assembler and looks like this:

<pre><code class="ruby">instruction_name addr_mode1(:arg1_1 => value, :arg1_2 => value, ...), addr_mode2(:arg2_1 => value, ...), ...</code></pre>

So, for instance, if the simulator has an ADD(MEM(i), MEM(i)|IMM(i)) instruction, it would look like:

<pre><code class="ruby">add mem(:i => 42), imm(:i => 128)</code></pre>

Thankfully, there are shortcuts. If there''s only one argument expected in the addressing mode, you can simply write its value and never have to worry about the argument name. And, by convention, the immediate values are always denoted in the simulator as the IMM addressing mode, so the template parser automatically accepts numbers and strings as such. Thus, in this case, the instruction can be simplified to:

<pre><code class="ruby">add mem(42), 128</code></pre>

As a matter of fact, if you''re sure about the order of addressing mode arguments, you can omit the names altogether and simply provide the values:

<pre><code class="ruby">instruction_name addr_mode1(value1, value2, ...) ...</code></pre>

If the name of the instruction conflicts with an already existing Ruby method, the instruction will be available with an %op_% prefix before its name.

h3. Test situations

_This section is to be taken with a grain of salt because the logic and the interface behind the situations is not yet finalized and mostly missing from the templates and shouldn''t be used yet_

_Big TODO: define what is a test situation_

To denote a test situation, add a Ruby block that describes situations to an instruction, this will loosely look like this (likely similar to the way the addressing modes are denoted):

<pre><code class="ruby">sub mem(42), mem(21) do overflow(:op1 => 123, :op2 => 456) end</code></pre>

h3. Instruction blocks

Sometimes a certain test situation should influence more than just one instruction. In that case, you can pass the instructions in an atomic block that can optionally accept a Proc of situations as its argument (because Ruby doesn''t want to be nice and allow multiple blocks for a method, and passing a Hash of Proc can hardly be called comfortable).

<pre><code class="ruby">p = lambda { overflow(:op1 => 123, :op2 => 456) }

atomic p {

  mov mem(25), mem(26)

  add mem(27), 28

  sub mem(29), 30

}</code></pre>

h3. Groups and random selections _(N.B. REMOVED in r1923. The implementation does not work in the current build and, therefore, was removed. The described features must be reviewed and reimplemented if required.)_

From source code comments:

<pre>

# VERY UNTESTED leftovers from the previous version ("V2", this is V3)

# Should work with the applied fixes but I''d be very careful to use these

# As things stand this is just a little discrete probability utility that

# may or may not find its way into the potential ruby part of the test engine

</pre>

There are certain ways to group together or randomize addressing modes and instructions.

To group several addressing modes together (this only works if they have similar arguments) create a mode group like this:

<pre><code class="ruby">mode_group "my_group" [:mem, :imm]</code></pre>

You can also set weights to each of the modes in the group like this:

<pre><code class="ruby">mode_group "my_group" {:mem => 1.5, :imm => 2.5}</code></pre>

The name of the group is converted into a method in the Template class. To select a random mode from a group, use %sample% on this generated method:

<pre><code class="ruby">add mem(42), my_group.sample(21)</code></pre>

_TODO: sampling already parametrized modes_

The first method of grouping instructions works in a similar manner with the same restrictions on arguments:

<pre><code class="ruby">group "i_group" [:add, :sub]</code></pre>

<pre><code class="ruby">group "i_group" {:add => 0.3, :sub => 0.7]</code></pre>

<pre><code class="ruby">i_group.sample mem(42), 21</code></pre>

You can also run all of the instructions in a group at once by using the %all% method:

<pre><code class="ruby">i_group.all mem(42), 21</code></pre>

The second one allows you to create a normal block of instructions, setting their arguments separately. 

<pre><code class="ruby">block_group "b_group" do

  mov mem(25), mem(26)

  add mem(27), 28

  sub mem(29), 30

end</code></pre>

In this case to set weights you should call a %prob% method before every instruction:

<pre><code class="ruby">block_group "b_group" do

  prob 0.1

  mov mem(25), mem(26)

  prob 0.7

  add mem(27), 28

  prob 0.4

  sub mem(29), 30

end</code></pre>

The usage is almost identical, but without providing the arguments as they are already set:

<pre><code class="ruby">b_group.sample

b_group.all</code></pre>

_Not sure how does it work inside atomics when the group is defined outside, needs more consideration_

_TODO: Permutations_

Any normal Ruby code is allowed inside the blocks as well as the %run%-type methods, letting you write more complex or inter-dependent templates.

h3. TODO: Labels

To set a label write:

<pre><code class="ruby">label :label_name</code></pre>

To use a label in an instruction that accepts one (under the hood it''s just a simple immediate #IMM value - just not a pre-defined one until it''s actually defined):

<pre><code class="ruby">b greaterThan, :label_name</code></pre>

h3. TODO: Debug

To get a value from registers use:

<pre><code class="ruby">get_reg_value("register_name", index)</code></pre>

Right now the pre-processing and the execution of instructions are separated due to ambiguous logic regarding labels and various blocks and atomics. This may be changed later, so these special debugging blocks might become unnecessary. By default what''s written in the template is run during pre-processing so you have to use special blocks if you want to run some Ruby code during the execution stage, most likely some debugging.

To print some debug in the console during the execution of the instructions use the exec_debug block:

<pre><code class="ruby">exec_debug {

  puts "R0: " + get_reg_value("GPR", 0).to_s + ", R1: " + get_reg_value("GPR", 1).to_s# + ", label code: " + self.send("cycle" + ind.to_s).to_s

}</code></pre>

To save something that depends on the current state of the simulator to the resulting assembler code use exec_output that should return a string:

<pre><code class="ruby">exec_output {

  "// The result should be " + self.get_reg_value("GPR", 0).to_s

}</code></pre>