Project

General

Profile

Template Description Language » History » Version 29

Andrei Tatarnikov, 05/20/2014 05:12 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 29 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 20 Alexander Kamkin
13 1 Alexander Kamkin
14 3 Artemiy Utekhin
h2. The translation process
15 1 Alexander Kamkin
16 20 Alexander Kamkin
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:
17 1 Alexander Kamkin
18 3 Artemiy Utekhin
# Receiving model metadata from the simulator;
19
# Template pre-processing;
20
# Constructing commands in the simulator;
21
# Executing commands in the simulator;
22
# Receiving the assembler code from the simulator (based on the CPU Sim-nML description);
23
# Writing the TL output to target files.
24 1 Alexander Kamkin
25 3 Artemiy Utekhin
Depending on the circumstances some of these steps may be done concurrently. 
26 1 Alexander Kamkin
27 3 Artemiy Utekhin
h2. Configuration
28 1 Alexander Kamkin
29 3 Artemiy Utekhin
_Pending..._
30 1 Alexander Kamkin
31 3 Artemiy Utekhin
h2. Execution
32 1 Alexander Kamkin
33 7 Artemiy Utekhin
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:
34 1 Alexander Kamkin
35 7 Artemiy Utekhin
<pre>generate <model package> <template file.rb> [<output file.asm>]</pre>
36
37
Example:
38
39
<pre>generate arm mytemplates\arm_template.rb myresults\executable.asm</pre>
40 1 Alexander Kamkin
41 3 Artemiy Utekhin
h2. Writing templates
42 1 Alexander Kamkin
43 3 Artemiy Utekhin
h3. Basic features
44 1 Alexander Kamkin
45 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.
46 1 Alexander Kamkin
47 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:
48 1 Alexander Kamkin
49 11 Andrei Tatarnikov
<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"
50 1 Alexander Kamkin
51 11 Andrei Tatarnikov
class MyTemplate < Template</code></pre>
52 1 Alexander Kamkin
53 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%.
54 1 Alexander Kamkin
55 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:
56 1 Alexander Kamkin
57 10 Andrei Tatarnikov
<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"
58 1 Alexander Kamkin
59 3 Artemiy Utekhin
class MyPrepost < Template
60
  def initialize
61
    super
62
    @is_executable = no
63
  end
64 1 Alexander Kamkin
65 3 Artemiy Utekhin
  def pre
66
    # Your ''startup'' code goes here
67
  end
68 1 Alexander Kamkin
69 3 Artemiy Utekhin
  def post
70
    # Your ''cleanup'' code goes here
71
  end
72 9 Andrei Tatarnikov
end</code></pre>
73 1 Alexander Kamkin
74 11 Andrei Tatarnikov
<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"
75 1 Alexander Kamkin
76 3 Artemiy Utekhin
class MyTemplate < MyPrepost
77
  def initialize
78
    super
79
    @is_executable = yes
80
  end
81
  
82
  def run
83
    # Your template code goes here
84
  end
85 11 Andrei Tatarnikov
end</code></pre>
86 1 Alexander Kamkin
87 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:
88 1 Alexander Kamkin
89 16 Andrei Tatarnikov
<pre><code class="ruby">instruction_name addr_mode1(:arg1_1 => value, :arg1_2 => value, ...), addr_mode2(:arg2_1 => value, ...), ...</code></pre>
90 1 Alexander Kamkin
91 3 Artemiy Utekhin
So, for instance, if the simulator has an ADD(MEM(i), MEM(i)|IMM(i)) instruction, it would look like:
92 1 Alexander Kamkin
93 16 Andrei Tatarnikov
<pre><code class="ruby">add mem(:i => 42), imm(:i => 128)</code></pre>
94 1 Alexander Kamkin
95 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:
96 1 Alexander Kamkin
97 16 Andrei Tatarnikov
<pre><code class="ruby">add mem(42), 128</code></pre>
98 3 Artemiy Utekhin
99 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:
100
101 16 Andrei Tatarnikov
<pre><code class="ruby">instruction_name addr_mode1(value1, value2, ...) ...</code></pre>
102 8 Artemiy Utekhin
103 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.
104
105
h3. Test situations
106
107
_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_
108
109
_Big TODO: define what is a test situation_
110
111
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):
112
113 17 Andrei Tatarnikov
<pre><code class="ruby">sub mem(42), mem(21) do overflow(:op1 => 123, :op2 => 456) end</code></pre>
114 3 Artemiy Utekhin
115
h3. Instruction blocks
116
117
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).
118
119 12 Andrei Tatarnikov
<pre><code class="ruby">p = lambda { overflow(:op1 => 123, :op2 => 456) }
120 3 Artemiy Utekhin
121
atomic p {
122
  mov mem(25), mem(26)
123
  add mem(27), 28
124
  sub mem(29), 30
125 12 Andrei Tatarnikov
}</code></pre>
126 3 Artemiy Utekhin
127 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.)_
128 3 Artemiy Utekhin
129 24 Andrei Tatarnikov
From source code comments:
130
131
<pre>
132
# VERY UNTESTED leftovers from the previous version ("V2", this is V3)
133
# Should work with the applied fixes but I''d be very careful to use these
134
135
# As things stand this is just a little discrete probability utility that
136
# may or may not find its way into the potential ruby part of the test engine
137
</pre>
138
139 3 Artemiy Utekhin
There are certain ways to group together or randomize addressing modes and instructions.
140
141
To group several addressing modes together (this only works if they have similar arguments) create a mode group like this:
142
143 17 Andrei Tatarnikov
<pre><code class="ruby">mode_group "my_group" [:mem, :imm]</code></pre>
144 3 Artemiy Utekhin
145
You can also set weights to each of the modes in the group like this:
146
147 17 Andrei Tatarnikov
<pre><code class="ruby">mode_group "my_group" {:mem => 1.5, :imm => 2.5}</code></pre>
148 3 Artemiy Utekhin
149
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:
150
151 17 Andrei Tatarnikov
<pre><code class="ruby">add mem(42), my_group.sample(21)</code></pre>
152 3 Artemiy Utekhin
153
_TODO: sampling already parametrized modes_
154
155
The first method of grouping instructions works in a similar manner with the same restrictions on arguments:
156
157 17 Andrei Tatarnikov
<pre><code class="ruby">group "i_group" [:add, :sub]</code></pre>
158 3 Artemiy Utekhin
159 17 Andrei Tatarnikov
<pre><code class="ruby">group "i_group" {:add => 0.3, :sub => 0.7]</code></pre>
160 3 Artemiy Utekhin
161 17 Andrei Tatarnikov
<pre><code class="ruby">i_group.sample mem(42), 21</code></pre>
162 3 Artemiy Utekhin
163
You can also run all of the instructions in a group at once by using the %all% method:
164
165 17 Andrei Tatarnikov
<pre><code class="ruby">i_group.all mem(42), 21</code></pre>
166 3 Artemiy Utekhin
167
The second one allows you to create a normal block of instructions, setting their arguments separately. 
168
169 17 Andrei Tatarnikov
<pre><code class="ruby">block_group "b_group" do
170 3 Artemiy Utekhin
  mov mem(25), mem(26)
171
  add mem(27), 28
172
  sub mem(29), 30
173 17 Andrei Tatarnikov
end</code></pre>
174 3 Artemiy Utekhin
175
In this case to set weights you should call a %prob% method before every instruction:
176
177 17 Andrei Tatarnikov
<pre><code class="ruby">block_group "b_group" do
178 3 Artemiy Utekhin
  prob 0.1
179
  mov mem(25), mem(26)
180
  prob 0.7
181
  add mem(27), 28
182
  prob 0.4
183
  sub mem(29), 30
184 17 Andrei Tatarnikov
end</code></pre>
185 3 Artemiy Utekhin
186
The usage is almost identical, but without providing the arguments as they are already set:
187
188 18 Andrei Tatarnikov
<pre><code class="ruby">b_group.sample
189
b_group.all</code></pre>
190 3 Artemiy Utekhin
191
_Not sure how does it work inside atomics when the group is defined outside, needs more consideration_
192
193
_TODO: Permutations_
194
195
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.
196 8 Artemiy Utekhin
197
h3. TODO: Labels
198
199
To set a label write:
200
201 18 Andrei Tatarnikov
<pre><code class="ruby">label :label_name</code></pre>
202 8 Artemiy Utekhin
203
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):
204
205 18 Andrei Tatarnikov
<pre><code class="ruby">b greaterThan, :label_name</code></pre>
206 8 Artemiy Utekhin
207
h3. TODO: Debug
208
209
To get a value from registers use:
210
211 15 Andrei Tatarnikov
<pre><code class="ruby">get_reg_value("register_name", index)</code></pre>
212 8 Artemiy Utekhin
213
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.
214
215
To print some debug in the console during the execution of the instructions use the exec_debug block:
216
217 15 Andrei Tatarnikov
<pre><code class="ruby">exec_debug {
218 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
219 15 Andrei Tatarnikov
}</code></pre>
220 8 Artemiy Utekhin
221
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:
222
223 14 Andrei Tatarnikov
<pre><code class="ruby">exec_output {
224 8 Artemiy Utekhin
  "// The result should be " + self.get_reg_value("GPR", 0).to_s
225 13 Andrei Tatarnikov
}</code></pre>