Project

General

Profile

Template Description Language » History » Version 14

Andrei Tatarnikov, 06/17/2013 06:47 PM

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