Project

General

Profile

Template Description Language » History » Version 93

Andrei Tatarnikov, 05/22/2014 03:38 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 92 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, addressing modes and test situations, corresponding Ruby 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 51 Andrei Tatarnikov
# Instruction call blocks are processed bottom-up to produce sequences of abstract instruction calls (at this step, their arguments can be described as a set of conditions instead of being assigned concrete values);
21 53 Andrei Tatarnikov
# A symbolic test program is built on the basis of the produced abstract instruction call sequences by applying corresponding algorithms to find values satisfying the specified conditions;
22 47 Andrei Tatarnikov
# The symbolic test program is simulated on the microprocessor model;
23 54 Andrei Tatarnikov
# The code of the 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 93 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 them 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 56 Andrei Tatarnikov
h2. Writing Test Templates
40
41 57 Andrei Tatarnikov
h3. Test Template Structure
42
43 58 Andrei Tatarnikov
A test template is a class inherited from the <code>Template</code> library class that provides access to all features of the library. In other words, you need to start with creating a class that would subclass <code>Template</code>. MicroTESK stores information on the location of the <code>Template</code> class in the <code>TEMPLATE</code> environment variable. So, the definition of your test template class will look like this:
44 57 Andrei Tatarnikov
45
<pre><code class="ruby">
46
require ENV[''TEMPLATE'']
47
48
class MyTemplate < Template</code></pre>
49 1 Alexander Kamkin
50 58 Andrei Tatarnikov
The test template class should contain the implementations of the following methods:
51
52 59 Andrei Tatarnikov
# <code>initialize</code> (optional) - Configure settings for the given test template;
53
# <code>pre</code> (optional) - Holds the initialization code for the test program;
54
# <code>post</code> (optional) - Holds the finalization code for the test program;
55
# <code>run</code> (optional) - Holds the main code of the test program (testing problem description).
56 58 Andrei Tatarnikov
57 63 Andrei Tatarnikov
The definitions of optional methods can be skipped. In this case, the default implementations provided by the parent class will be used. The default implementation of the <code>initialize</code> method initializes the settings with default values. The default implementations of the <code>pre</code> and <code>post</code> methods do nothing.
58
59 64 Andrei Tatarnikov
The full interface of a test template looks as follows:
60 60 Andrei Tatarnikov
61
<pre><code class="ruby">require ENV[''TEMPLATE'']
62
63
class MyTemplate < Template
64
65
  def initialize
66
    super
67
    # Initialize settings here 
68
  end
69
70
  def pre
71
    # Place your initialization code here
72
  end
73
74
  def post
75
    # Place your finalization code here
76
  end
77
78
  def run
79
    # Place your test problem description here
80
  end
81
82 61 Andrei Tatarnikov
end</code></pre>
83 57 Andrei Tatarnikov
84 65 Andrei Tatarnikov
h3. Reusing Test Templates
85
86 70 Andrei Tatarnikov
It is possible to reuse code of existing test templates in other test templates. To do this, you need to subclass the template you want to reuse instead of the <code>Template</code> class. For example, the <code>MyTemplate</code> class below reuses code from the <code>MyPrepost</code> class that provides initialization and finalization code for similar test templates.
87 68 Andrei Tatarnikov
88
<pre><code class="ruby">require ENV[''TEMPLATE'']
89
require_relative ''MyPrepost''
90
91 71 Andrei Tatarnikov
class MyTemplate < MyPrepost
92
93
  def run
94
  ... 
95
  end
96
97
end</code></pre>
98 68 Andrei Tatarnikov
99 74 Andrei Tatarnikov
h3. Test Template Settings
100
101 78 Andrei Tatarnikov
Test templates use the following settings:
102
103
# Enable using the test template to generate a test program (some templates are designed to be used as base classes only);
104
# Use the standard output to print the generated test program (in addition to the output file);
105
# Enable logging information on the simulated instruction calls;
106
# Starting characters for single-line comments in the test program;
107
# Starting characters for multi-line comments in the test program;
108
# Terminating characters for multi-line comments in the test program.
109
110 79 Andrei Tatarnikov
Here is how these settings are initialized with default values in the <code>Template</code> class:
111 75 Andrei Tatarnikov
112 79 Andrei Tatarnikov
<pre><code class="ruby">@is_executable          = true
113 1 Alexander Kamkin
@use_stdout             = true
114 78 Andrei Tatarnikov
@log_execution          = true
115
@sl_comment_starts_with = "// "
116
@ml_comment_starts_with = "/*"
117 79 Andrei Tatarnikov
@ml_comment_ends_with   = "*/"</code></pre>
118 72 Andrei Tatarnikov
119 81 Andrei Tatarnikov
The settings can be overridden in the <code>Initialize</code> method of a test template. For example:
120 80 Andrei Tatarnikov
121
<pre><code class="ruby">class MyTemplate < Template
122
123
  def initialize
124
    super
125
    @sl_comment_starts_with = ";" 
126
    @ml_comment_starts_with = "/="
127
    @ml_comment_ends_with   = "=/" 
128
  end
129
  ...
130
end</code></pre>
131
132 91 Andrei Tatarnikov
h3. Instruction Calls
133 1 Alexander Kamkin
134 86 Andrei Tatarnikov
The <code>pre</code>, <code>post</code> and <code>run</code> methods of a test template class contain specifications of instruction call sequences. Instruction calls are specified using the *_instruction_* and *_addressing mode_* abstractions. Instructions are self-explanatory, they simply represent target assembler instructions. Every instruction argument is a parameterized addressing mode that explains the meaning of the provided values. For example, an addressing mode can refer to a register, a memory location or hold an immediate value. In other words, an instruction call is an instruction that uses appropriate addressing modes initialized with appropriate values. The format of an instruction call description looks like this:
135 85 Andrei Tatarnikov
136 88 Andrei Tatarnikov
<pre><code class="ruby">instruction addr_mode1(:arg1_1 => value1_1, :arg1_2 => value1_2, ...), addr_mode2(:arg2_1 => value2_1, ...), ...</code></pre>
137 1 Alexander Kamkin
138 89 Andrei Tatarnikov
This format implies that addressing modes are parameterized with hash tables where they key is in the name of the addressing mode parameter and the value is the value to be assigned to this parameter. Also, there is a shorter format based on methods with a variable number of arguments. In this case, values are expected to come in the same order as corresponding parameter definitions. The shorter format looks like this:
139
140
<pre><code class="ruby">instruction addr_mode1(value1_1, value1_2, ...), addr_mode2(value2_1, ...), ...</code></pre>
141
142 90 Andrei Tatarnikov
The code below demonstrates both approaches:
143
144
<pre><code class="ruby">
145
mov reg(:i => 0), imm(:i => 0xFF) # The use of hash maps
146
mov reg(0), imm(0xFF)             # The use of variable numbers of arguments
147 1 Alexander Kamkin
</code></pre>
148 91 Andrei Tatarnikov
149
h3. Instruction Call Blocks
150
151
152 90 Andrei Tatarnikov
153 20 Alexander Kamkin
h2. *TODO: REWRITE*
154 1 Alexander Kamkin
155 20 Alexander Kamkin
h3. Basic features
156 1 Alexander Kamkin
157 11 Andrei Tatarnikov
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.
158 1 Alexander Kamkin
159 11 Andrei Tatarnikov
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:
160 1 Alexander Kamkin
161 20 Alexander Kamkin
<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"
162 1 Alexander Kamkin
163 3 Artemiy Utekhin
class MyTemplate < Template</code></pre>
164 1 Alexander Kamkin
165 10 Andrei Tatarnikov
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%.
166 1 Alexander Kamkin
167 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:
168
169
<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"
170
171
class MyPrepost < Template
172 1 Alexander Kamkin
  def initialize
173 3 Artemiy Utekhin
    super
174
    @is_executable = no
175
  end
176 1 Alexander Kamkin
177 3 Artemiy Utekhin
  def pre
178
    # Your ''startup'' code goes here
179
  end
180 9 Andrei Tatarnikov
181 1 Alexander Kamkin
  def post
182 11 Andrei Tatarnikov
    # Your ''cleanup'' code goes here
183 1 Alexander Kamkin
  end
184 3 Artemiy Utekhin
end</code></pre>
185
186
<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"
187
188
class MyTemplate < MyPrepost
189
  def initialize
190
    super
191
    @is_executable = yes
192
  end
193 11 Andrei Tatarnikov
  
194 1 Alexander Kamkin
  def run
195 3 Artemiy Utekhin
    # Your template code goes here
196 1 Alexander Kamkin
  end
197 16 Andrei Tatarnikov
end</code></pre>
198 1 Alexander Kamkin
199 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:
200 1 Alexander Kamkin
201 16 Andrei Tatarnikov
<pre><code class="ruby">instruction_name addr_mode1(:arg1_1 => value, :arg1_2 => value, ...), addr_mode2(:arg2_1 => value, ...), ...</code></pre>
202 1 Alexander Kamkin
203 3 Artemiy Utekhin
So, for instance, if the simulator has an ADD(MEM(i), MEM(i)|IMM(i)) instruction, it would look like:
204 1 Alexander Kamkin
205 16 Andrei Tatarnikov
<pre><code class="ruby">add mem(:i => 42), imm(:i => 128)</code></pre>
206 3 Artemiy Utekhin
207 8 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:
208
209 16 Andrei Tatarnikov
<pre><code class="ruby">add mem(42), 128</code></pre>
210 8 Artemiy Utekhin
211 3 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:
212
213
<pre><code class="ruby">instruction_name addr_mode1(value1, value2, ...) ...</code></pre>
214
215
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.
216
217
h3. Test situations
218
219
_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_
220
221 17 Andrei Tatarnikov
_Big TODO: define what is a test situation_
222 3 Artemiy Utekhin
223
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):
224
225
<pre><code class="ruby">sub mem(42), mem(21) do overflow(:op1 => 123, :op2 => 456) end</code></pre>
226
227 12 Andrei Tatarnikov
h3. Instruction blocks
228 3 Artemiy Utekhin
229
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).
230
231
<pre><code class="ruby">p = lambda { overflow(:op1 => 123, :op2 => 456) }
232
233 12 Andrei Tatarnikov
atomic p {
234 3 Artemiy Utekhin
  mov mem(25), mem(26)
235 25 Andrei Tatarnikov
  add mem(27), 28
236 3 Artemiy Utekhin
  sub mem(29), 30
237 24 Andrei Tatarnikov
}</code></pre>
238
239
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.)_
240
241
From source code comments:
242
243
<pre>
244
# VERY UNTESTED leftovers from the previous version ("V2", this is V3)
245
# Should work with the applied fixes but I''d be very careful to use these
246
247 3 Artemiy Utekhin
# As things stand this is just a little discrete probability utility that
248
# may or may not find its way into the potential ruby part of the test engine
249
</pre>
250
251 17 Andrei Tatarnikov
There are certain ways to group together or randomize addressing modes and instructions.
252 3 Artemiy Utekhin
253
To group several addressing modes together (this only works if they have similar arguments) create a mode group like this:
254
255 17 Andrei Tatarnikov
<pre><code class="ruby">mode_group "my_group" [:mem, :imm]</code></pre>
256 3 Artemiy Utekhin
257
You can also set weights to each of the modes in the group like this:
258
259 17 Andrei Tatarnikov
<pre><code class="ruby">mode_group "my_group" {:mem => 1.5, :imm => 2.5}</code></pre>
260 3 Artemiy Utekhin
261
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:
262
263
<pre><code class="ruby">add mem(42), my_group.sample(21)</code></pre>
264
265 17 Andrei Tatarnikov
_TODO: sampling already parametrized modes_
266 3 Artemiy Utekhin
267 17 Andrei Tatarnikov
The first method of grouping instructions works in a similar manner with the same restrictions on arguments:
268 3 Artemiy Utekhin
269 17 Andrei Tatarnikov
<pre><code class="ruby">group "i_group" [:add, :sub]</code></pre>
270 3 Artemiy Utekhin
271
<pre><code class="ruby">group "i_group" {:add => 0.3, :sub => 0.7]</code></pre>
272
273 17 Andrei Tatarnikov
<pre><code class="ruby">i_group.sample mem(42), 21</code></pre>
274 3 Artemiy Utekhin
275
You can also run all of the instructions in a group at once by using the %all% method:
276
277 17 Andrei Tatarnikov
<pre><code class="ruby">i_group.all mem(42), 21</code></pre>
278 3 Artemiy Utekhin
279
The second one allows you to create a normal block of instructions, setting their arguments separately. 
280
281 17 Andrei Tatarnikov
<pre><code class="ruby">block_group "b_group" do
282 3 Artemiy Utekhin
  mov mem(25), mem(26)
283
  add mem(27), 28
284
  sub mem(29), 30
285 17 Andrei Tatarnikov
end</code></pre>
286 3 Artemiy Utekhin
287
In this case to set weights you should call a %prob% method before every instruction:
288
289
<pre><code class="ruby">block_group "b_group" do
290
  prob 0.1
291
  mov mem(25), mem(26)
292 17 Andrei Tatarnikov
  prob 0.7
293 3 Artemiy Utekhin
  add mem(27), 28
294
  prob 0.4
295
  sub mem(29), 30
296 18 Andrei Tatarnikov
end</code></pre>
297
298 3 Artemiy Utekhin
The usage is almost identical, but without providing the arguments as they are already set:
299
300
<pre><code class="ruby">b_group.sample
301
b_group.all</code></pre>
302
303
_Not sure how does it work inside atomics when the group is defined outside, needs more consideration_
304 8 Artemiy Utekhin
305
_TODO: Permutations_
306
307
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.
308
309 18 Andrei Tatarnikov
h3. TODO: Labels
310 8 Artemiy Utekhin
311
To set a label write:
312
313 18 Andrei Tatarnikov
<pre><code class="ruby">label :label_name</code></pre>
314 8 Artemiy Utekhin
315
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):
316
317
<pre><code class="ruby">b greaterThan, :label_name</code></pre>
318
319 15 Andrei Tatarnikov
h3. TODO: Debug
320 8 Artemiy Utekhin
321
To get a value from registers use:
322
323
<pre><code class="ruby">get_reg_value("register_name", index)</code></pre>
324
325 15 Andrei Tatarnikov
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.
326 8 Artemiy Utekhin
327 15 Andrei Tatarnikov
To print some debug in the console during the execution of the instructions use the exec_debug block:
328 8 Artemiy Utekhin
329
<pre><code class="ruby">exec_debug {
330
  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
331 14 Andrei Tatarnikov
}</code></pre>
332 8 Artemiy Utekhin
333 13 Andrei Tatarnikov
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:
334 1 Alexander Kamkin
335
<pre><code class="ruby">exec_output {
336
  "// The result should be " + self.get_reg_value("GPR", 0).to_s
337
}</code></pre>