Project

General

Profile

Template Description Language » History » Version 48

Andrei Tatarnikov, 05/21/2014 05:06 PM

1 5 Alexander Kamkin
h1. Template Description Language
2 4 Alexander Kamkin
3
_~By Artemiy Utekhin~_
4 1 Alexander Kamkin
5 21 Alexander Kamkin
*UNDER CONSTRUCTION*
6
7 6 Alexander Kamkin
{{toc}}
8
9 27 Andrei Tatarnikov
h2. Introduction
10
11 30 Andrei Tatarnikov
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.
12 1 Alexander Kamkin
13 45 Andrei Tatarnikov
h2. How It Works
14 1 Alexander Kamkin
15 48 Andrei Tatarnikov
A test template in Ruby describes a test program in terms of the model of the target microprocessor. The structure of the test program is described using built-in features of Ruby (conditions, loops, etc.) and facilities provided by MicroTESK libraries (instruction blocks that help organize instruction sequences). To provide access to such elements of the model as instructions, their addressing modes and test situations, corresponding methods are created at runtime on the basis on the meta-information provided by the model. The test template subsystem interacts with the model and the testing library of MicroTESK to create a symbolic test program, simulate it on the model and generate its textual representation. Generally speaking, processing of a test template is performed in the following steps:
16 46 Andrei Tatarnikov
17
# The model of the microprocessor is loaded;
18
# Runtime methods to access architecture-specific elements are created on the basis of the model''s meta-information;
19
# The code of the test template is executed to build a hierarchy of instruction call blocks;
20 47 Andrei Tatarnikov
# Instruction call blocks are processed bottom-up to produce sequences of abstract instruction calls (at this step, instruction call arguments can be described as a set of conditions instead of being assigned concrete values);
21
# A symbolic test program is built on the basis of abstract instruction call sequences by applying corresponding algorithms to produce values satisfying the specified conditions;
22
# The symbolic test program is simulated on the microprocessor model;
23
# The code of test program is generated and saved to the output file.
24 1 Alexander Kamkin
25 3 Artemiy Utekhin
h2. Configuration
26 1 Alexander Kamkin
27 43 Andrei Tatarnikov
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.
28 1 Alexander Kamkin
29 35 Andrei Tatarnikov
h2. Running Test Program Generation
30 1 Alexander Kamkin
31 33 Andrei Tatarnikov
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: 
32 1 Alexander Kamkin
33
<pre>generate <model name> <template file.rb> [<output file.asm>]</pre>
34 7 Artemiy Utekhin
35 34 Andrei Tatarnikov
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:
36 7 Artemiy Utekhin
37 31 Andrei Tatarnikov
<pre>sh bin/generate.sh demo arch/demo/templates/demo_template.rb test.asm</pre>
38 1 Alexander Kamkin
39 39 Andrei Tatarnikov
h2. Writing templates (TODO: rewrite)
40 1 Alexander Kamkin
41 3 Artemiy Utekhin
h3. Basic features
42 1 Alexander Kamkin
43 20 Alexander Kamkin
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.
44 1 Alexander Kamkin
45 20 Alexander Kamkin
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:
46 1 Alexander Kamkin
47 11 Andrei Tatarnikov
<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"
48 1 Alexander Kamkin
49 11 Andrei Tatarnikov
class MyTemplate < Template</code></pre>
50 1 Alexander Kamkin
51 20 Alexander Kamkin
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%.
52 1 Alexander Kamkin
53 3 Artemiy Utekhin
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:
54 1 Alexander Kamkin
55 10 Andrei Tatarnikov
<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"
56 1 Alexander Kamkin
57 3 Artemiy Utekhin
class MyPrepost < Template
58
  def initialize
59
    super
60
    @is_executable = no
61
  end
62 1 Alexander Kamkin
63 3 Artemiy Utekhin
  def pre
64
    # Your ''startup'' code goes here
65
  end
66 1 Alexander Kamkin
67 3 Artemiy Utekhin
  def post
68
    # Your ''cleanup'' code goes here
69
  end
70 9 Andrei Tatarnikov
end</code></pre>
71 1 Alexander Kamkin
72 11 Andrei Tatarnikov
<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"
73 1 Alexander Kamkin
74 3 Artemiy Utekhin
class MyTemplate < MyPrepost
75
  def initialize
76
    super
77
    @is_executable = yes
78
  end
79
  
80
  def run
81
    # Your template code goes here
82
  end
83 11 Andrei Tatarnikov
end</code></pre>
84 1 Alexander Kamkin
85 3 Artemiy Utekhin
These methods essentially contain the instructions. The general instruction format is slightly more intimidating than the native assembler and looks like this:
86 1 Alexander Kamkin
87 16 Andrei Tatarnikov
<pre><code class="ruby">instruction_name addr_mode1(:arg1_1 => value, :arg1_2 => value, ...), addr_mode2(:arg2_1 => value, ...), ...</code></pre>
88 1 Alexander Kamkin
89 3 Artemiy Utekhin
So, for instance, if the simulator has an ADD(MEM(i), MEM(i)|IMM(i)) instruction, it would look like:
90 1 Alexander Kamkin
91 16 Andrei Tatarnikov
<pre><code class="ruby">add mem(:i => 42), imm(:i => 128)</code></pre>
92 1 Alexander Kamkin
93 3 Artemiy Utekhin
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:
94 1 Alexander Kamkin
95 16 Andrei Tatarnikov
<pre><code class="ruby">add mem(42), 128</code></pre>
96 3 Artemiy Utekhin
97 8 Artemiy Utekhin
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:
98
99 16 Andrei Tatarnikov
<pre><code class="ruby">instruction_name addr_mode1(value1, value2, ...) ...</code></pre>
100 8 Artemiy Utekhin
101 3 Artemiy Utekhin
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.
102
103
h3. Test situations
104
105
_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_
106
107
_Big TODO: define what is a test situation_
108
109
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):
110
111 17 Andrei Tatarnikov
<pre><code class="ruby">sub mem(42), mem(21) do overflow(:op1 => 123, :op2 => 456) end</code></pre>
112 3 Artemiy Utekhin
113
h3. Instruction blocks
114
115
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).
116
117 12 Andrei Tatarnikov
<pre><code class="ruby">p = lambda { overflow(:op1 => 123, :op2 => 456) }
118 3 Artemiy Utekhin
119
atomic p {
120
  mov mem(25), mem(26)
121
  add mem(27), 28
122
  sub mem(29), 30
123 12 Andrei Tatarnikov
}</code></pre>
124 3 Artemiy Utekhin
125 25 Andrei Tatarnikov
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.)_
126 3 Artemiy Utekhin
127 24 Andrei Tatarnikov
From source code comments:
128
129
<pre>
130
# VERY UNTESTED leftovers from the previous version ("V2", this is V3)
131
# Should work with the applied fixes but I''d be very careful to use these
132
133
# As things stand this is just a little discrete probability utility that
134
# may or may not find its way into the potential ruby part of the test engine
135
</pre>
136
137 3 Artemiy Utekhin
There are certain ways to group together or randomize addressing modes and instructions.
138
139
To group several addressing modes together (this only works if they have similar arguments) create a mode group like this:
140
141 17 Andrei Tatarnikov
<pre><code class="ruby">mode_group "my_group" [:mem, :imm]</code></pre>
142 3 Artemiy Utekhin
143
You can also set weights to each of the modes in the group like this:
144
145 17 Andrei Tatarnikov
<pre><code class="ruby">mode_group "my_group" {:mem => 1.5, :imm => 2.5}</code></pre>
146 3 Artemiy Utekhin
147
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:
148
149 17 Andrei Tatarnikov
<pre><code class="ruby">add mem(42), my_group.sample(21)</code></pre>
150 3 Artemiy Utekhin
151
_TODO: sampling already parametrized modes_
152
153
The first method of grouping instructions works in a similar manner with the same restrictions on arguments:
154
155 17 Andrei Tatarnikov
<pre><code class="ruby">group "i_group" [:add, :sub]</code></pre>
156 3 Artemiy Utekhin
157 17 Andrei Tatarnikov
<pre><code class="ruby">group "i_group" {:add => 0.3, :sub => 0.7]</code></pre>
158 3 Artemiy Utekhin
159 17 Andrei Tatarnikov
<pre><code class="ruby">i_group.sample mem(42), 21</code></pre>
160 3 Artemiy Utekhin
161
You can also run all of the instructions in a group at once by using the %all% method:
162
163 17 Andrei Tatarnikov
<pre><code class="ruby">i_group.all mem(42), 21</code></pre>
164 3 Artemiy Utekhin
165
The second one allows you to create a normal block of instructions, setting their arguments separately. 
166
167 17 Andrei Tatarnikov
<pre><code class="ruby">block_group "b_group" do
168 3 Artemiy Utekhin
  mov mem(25), mem(26)
169
  add mem(27), 28
170
  sub mem(29), 30
171 17 Andrei Tatarnikov
end</code></pre>
172 3 Artemiy Utekhin
173
In this case to set weights you should call a %prob% method before every instruction:
174
175 17 Andrei Tatarnikov
<pre><code class="ruby">block_group "b_group" do
176 3 Artemiy Utekhin
  prob 0.1
177
  mov mem(25), mem(26)
178
  prob 0.7
179
  add mem(27), 28
180
  prob 0.4
181
  sub mem(29), 30
182 17 Andrei Tatarnikov
end</code></pre>
183 3 Artemiy Utekhin
184
The usage is almost identical, but without providing the arguments as they are already set:
185
186 18 Andrei Tatarnikov
<pre><code class="ruby">b_group.sample
187
b_group.all</code></pre>
188 3 Artemiy Utekhin
189
_Not sure how does it work inside atomics when the group is defined outside, needs more consideration_
190
191
_TODO: Permutations_
192
193
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.
194 8 Artemiy Utekhin
195
h3. TODO: Labels
196
197
To set a label write:
198
199 18 Andrei Tatarnikov
<pre><code class="ruby">label :label_name</code></pre>
200 8 Artemiy Utekhin
201
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):
202
203 18 Andrei Tatarnikov
<pre><code class="ruby">b greaterThan, :label_name</code></pre>
204 8 Artemiy Utekhin
205
h3. TODO: Debug
206
207
To get a value from registers use:
208
209 15 Andrei Tatarnikov
<pre><code class="ruby">get_reg_value("register_name", index)</code></pre>
210 8 Artemiy Utekhin
211
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.
212
213
To print some debug in the console during the execution of the instructions use the exec_debug block:
214
215 15 Andrei Tatarnikov
<pre><code class="ruby">exec_debug {
216 8 Artemiy Utekhin
  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
217 15 Andrei Tatarnikov
}</code></pre>
218 8 Artemiy Utekhin
219
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:
220
221 14 Andrei Tatarnikov
<pre><code class="ruby">exec_output {
222 8 Artemiy Utekhin
  "// The result should be " + self.get_reg_value("GPR", 0).to_s
223 13 Andrei Tatarnikov
}</code></pre>