Template Description Language¶

_{By Artemiy Utekhin}

UNDER CONSTRUCTION

• Table of contents
• Template Description Language
  • The translation process
  • Configuration
  • Execution
  • Writing templates
    • Basic features
    • Test situations
    • Instruction blocks
    • Groups and random selections
    • TODO: Labels
    • TODO: Debug
    • TODO: Pipelines

Ruby-TDL (Ruby-Based Template Description Language) is a Ruby-based domain specific language geared towards writing compact and reusable tests for microprocessors and other programmable devices. The language intends to look similar to the assembler of the target CPU (TL, Target Language) complemented by higher level features consisting of both standard Ruby and features specific to the Ruby-TDL implementation (ML, Meta Language). Ruby-TDL, in a sense, is similar to a macro processor - it generates code in the target language based on the provided meta language.

Since Ruby-TDL is built as a Ruby library providing an internal DSL no additional parsers are required. Currently, because of the extensive use of Java, Ruby-TDL templates can only be executed by the JRuby interpreter. CRuby will probably be supported at a later stage.

The translation process¶

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:

1. Receiving model metadata from the simulator;
2. Template pre-processing;
3. Constructing commands in the simulator;
4. Executing commands in the simulator;
5. Receiving the assembler code from the simulator (based on the CPU Sim-nML description);
6. Writing the TL output to target files.

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

Configuration¶

Pending...

Execution¶

Right now there is a simple execution script that requires the name of a package containing the CPU model (which is responsible for simulating the target processor and is generated by the Sim-nML Translator), a template file and an optional output file (if it''s not provided the library uses the standard output to print out the results). To run a template, execute the following command:

generate <model package> <template file.rb> [<output file.asm>]

Example:

generate arm mytemplates\arm_template.rb myresults\executable.asm

Writing templates¶

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:

require_relative "_path-to-the-rubymt-library_/mtruby" 

class MyTemplate < Template

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:

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

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

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

instruction_name addr_mode1(:arg1_1 => value, :arg1_2 => value, ...), addr_mode2(:arg2_1 => value, ...), ...

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

add mem(:i => 42), imm(:i => 128)

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:

add mem(42), 128

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:

instruction_name addr_mode1(value1, value2, ...) ...

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.

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):

sub mem(42), mem(21) do overflow(:op1 => 123, :op2 => 456) end

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).

p = lambda { overflow(:op1 => 123, :op2 => 456) }

atomic p {
  mov mem(25), mem(26)
  add mem(27), 28
  sub mem(29), 30
}

Groups and random selections¶

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:

mode_group "my_group" [:mem, :imm]

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

mode_group "my_group" {:mem => 1.5, :imm => 2.5}

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:

add mem(42), my_group.sample(21)

TODO: sampling already parametrized modes

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

group "i_group" [:add, :sub]

group "i_group" {:add => 0.3, :sub => 0.7]

i_group.sample mem(42), 21

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

i_group.all mem(42), 21

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

block_group "b_group" do
  mov mem(25), mem(26)
  add mem(27), 28
  sub mem(29), 30
end

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

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

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

b_group.sample
b_group.all

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.

TODO: Labels¶

To set a label write:

label :label_name

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):

b greaterThan, :label_name

TODO: Debug¶

To get a value from registers use:

get_reg_value("register_name", index)

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:

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
}

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:

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

TODO: Pipelines¶

TODO in code first