Project

General

Profile

Ruby-MT » History » Version 1

Artemiy Utekhin, 03/04/2013 07:01 AM

1 1 Artemiy Utekhin
h1. Ruby-MT - MicroTESK Template Description Language
2
3
*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.
4
5
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.
6
7
h2. The translation process
8
9
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:
10
11
# Receiving model metadata from the simulator;
12
# Template pre-processing;
13
# Constructing commands in the simulator;
14
# Executing commands in the simulator;
15
# Receiving the assembler code from the simulator (based on the CPU Sim-nML description);
16
# Writing the TL output to target files.
17
18
Depending on the circumstances some of these steps may be done concurrently. 
19
20
h2. Configuration
21
22
_Pending..._
23
24
h2. Execution
25
26
Right now there is a simple execution script that requires 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:
27
28
<pre>jruby parse_templates.rb <template file.rb> [<output file.asm>]</pre>
29
30
h2. Writing templates
31
32
h3. Basic features
33
34
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.
35
36
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:
37
38
<pre>require_relative "_path-to-the-rubymt-library_/mtruby"
39
40
class MyTemplate < Template</pre>
41
42
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%.
43
44
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:
45
46
<pre>require_relative "_path-to-the-rubymt-library_/mtruby"
47
48
class MyPrepost < Template
49
  def initialize
50
    super
51
    @is_executable = no
52
  end
53
54
  def pre
55
    # Your ''startup'' code goes here
56
  end
57
58
  def post
59
    # Your ''cleanup'' code goes here
60
  end
61
end</pre>
62
63
<pre>require_relative "_path-to-the-rubymt-library_/mtruby"
64
65
class MyTemplate < MyPrepost
66
  def initialize
67
    super
68
    @is_executable = yes
69
  end
70
  
71
  def run
72
    # Your template code goes here
73
  end
74
end</pre>
75
76
These methods essentially contain the instructions. The general instruction format is slightly more intimidating than the native assembler and looks like this:
77
78
<pre> instruction_name addr_mode1(:arg1_1 => value, :arg1_2 => value, ...), addr_mode2(:arg2_1 => value, ...), ...</pre>
79
80
So, for instance, if the simulator has an ADD(MEM(i), MEM(i)|IMM(i)) instruction, it would look like:
81
82
<pre> add mem(:i => 42), imm(:i => 128) </pre>
83
84
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:
85
86
<pre> add mem(42), 128 </pre>
87
88
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.
89
90
h3. Test situations
91
92
_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_
93
94
_Big TODO: define what is a test situation_
95
96
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):
97
98
<pre> sub mem(42), mem(21) do overflow(:op1 => 123, :op2 => 456) end</pre>
99
100
h3. Instruction blocks
101
102
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).
103
104
<pre>p = lambda { overflow(:op1 => 123, :op2 => 456) }
105
106
atomic p {
107
  mov mem(25), mem(26)
108
  add mem(27), 28
109
  sub mem(29), 30
110
}</pre>
111
112
h3. Groups and random selections
113
114
There are certain ways to group together or randomize addressing modes and instructions.
115
116
To group several addressing modes together (this only works if they have similar arguments) create a mode group like this:
117
118
<pre> mode_group "my_group" [:mem, :imm] </pre>
119
120
You can also set weights to each of the modes in the group like this:
121
122
<pre> mode_group "my_group" {:mem => 1.5, :imm => 2.5} </pre>
123
124
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:
125
126
<pre> add mem(42), my_group.sample(21) </pre>
127
128
_TODO: sampling already parametrized modes_
129
130
The first method of grouping instructions works in a similar manner with the same restrictions on arguments:
131
132
<pre> group "i_group" [:add, :sub]</pre>
133
<pre> group "i_group" {:add => 0.3, :sub => 0.7]</pre>
134
135
<pre>i_group.sample mem(42), 21</pre>
136
137
You can also run all of the instructions in a group at once by using the %all% method:
138
139
<pre>i_group.all mem(42), 21</pre>
140
141
The second one allows you to create a normal block of instructions, setting their arguments separately. 
142
143
<pre> block_group "b_group" do
144
  mov mem(25), mem(26)
145
  add mem(27), 28
146
  sub mem(29), 30
147
end</pre>
148
149
In this case to set weights you should call a %prob% method before every instruction:
150
151
<pre> block_group "b_group" do
152
  prob 0.1
153
  mov mem(25), mem(26)
154
  prob 0.7
155
  add mem(27), 28
156
  prob 0.4
157
  sub mem(29), 30
158
end</pre>
159
160
The usage is almost identical, but without providing the arguments as they are already set:
161
162
<pre>b_group.sample
163
b_group.all</pre>
164
165
_Not sure how does it work inside atomics when the group is defined outside, needs more consideration_
166
167
_TODO: Permutations_
168
169
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.