Project

General

Profile

Template Description Language » History » Version 117

Andrei Tatarnikov, 02/25/2015 05:40 PM

1 5 Alexander Kamkin
h1. Template Description Language
2 4 Alexander Kamkin
3 97 Andrei Tatarnikov
_~By Artemiy Utekhin and Andrei Tatarnikov~_
4 1 Alexander Kamkin
5 21 Alexander Kamkin
*UNDER CONSTRUCTION*
6 21 Alexander Kamkin
7 6 Alexander Kamkin
{{toc}}
8 6 Alexander Kamkin
9 27 Andrei Tatarnikov
h2. Introduction
10 27 Andrei Tatarnikov
11 116 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 test cases 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 further processing these test templates to produce a test program. MicroTESK uses the JRuby interpreter to process Ruby files. This allows Ruby libraries to interact with other components of MicroTESK written in Java.
12 1 Alexander Kamkin
13 45 Andrei Tatarnikov
h2. How It Works
14 1 Alexander Kamkin
15 102 Andrei Tatarnikov
A test template in Ruby describes a test program in terms of the model of the target microprocessor ISA. 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 elements of the model such as instructions and their addressing modes, 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 101 Andrei Tatarnikov
* The model of the microprocessor is loaded;
18 101 Andrei Tatarnikov
* Runtime methods to access architecture-specific elements are created on the basis of the model''s meta-information;
19 101 Andrei Tatarnikov
* The code of the test template is executed to build the internal representation of the template described as a hierarchy of instruction call blocks;
20 101 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 101 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 101 Andrei Tatarnikov
* The symbolic test program is simulated on the microprocessor model;
23 101 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 1 Alexander Kamkin
<pre>generate <model name> <template file.rb> [<output file.asm>]</pre>
34 7 Artemiy Utekhin
35 104 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>example.rb</code> test template and saves the generated test program to the <code>test.asm</code> file:
36 7 Artemiy Utekhin
37 99 Andrei Tatarnikov
<pre>sh bin/generate.sh cpu arch/demo/cpu/templates/example.rb test.asm</pre>
38 1 Alexander Kamkin
39 56 Andrei Tatarnikov
h2. Writing Test Templates
40 56 Andrei Tatarnikov
41 57 Andrei Tatarnikov
h3. Test Template Structure
42 57 Andrei Tatarnikov
43 95 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. Information on the location of the <code>Template</code> class is stored in the <code>TEMPLATE</code> environment variable. So, the definition of a test template class looks like this:
44 57 Andrei Tatarnikov
45 57 Andrei Tatarnikov
<pre><code class="ruby">
46 57 Andrei Tatarnikov
require ENV[''TEMPLATE'']
47 57 Andrei Tatarnikov
48 57 Andrei Tatarnikov
class MyTemplate < Template</code></pre>
49 1 Alexander Kamkin
50 96 Andrei Tatarnikov
Test template classes should contain implementations of the following methods:
51 58 Andrei Tatarnikov
52 109 Andrei Tatarnikov
# <code>initialize</code> (optional) - specifies settings for the given test template;
53 105 Andrei Tatarnikov
# <code>pre</code> (optional) - specifies the initialization code for the test program;
54 105 Andrei Tatarnikov
# <code>post</code> (optional) - specifies the finalization code for the test program;
55 105 Andrei Tatarnikov
# <code>run</code> - specifies the main code of the test program (test cases).
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 63 Andrei Tatarnikov
59 64 Andrei Tatarnikov
The full interface of a test template looks as follows:
60 60 Andrei Tatarnikov
61 60 Andrei Tatarnikov
<pre><code class="ruby">require ENV[''TEMPLATE'']
62 60 Andrei Tatarnikov
63 60 Andrei Tatarnikov
class MyTemplate < Template
64 60 Andrei Tatarnikov
65 60 Andrei Tatarnikov
  def initialize
66 60 Andrei Tatarnikov
    super
67 60 Andrei Tatarnikov
    # Initialize settings here 
68 60 Andrei Tatarnikov
  end
69 60 Andrei Tatarnikov
70 60 Andrei Tatarnikov
  def pre
71 60 Andrei Tatarnikov
    # Place your initialization code here
72 60 Andrei Tatarnikov
  end
73 60 Andrei Tatarnikov
74 60 Andrei Tatarnikov
  def post
75 60 Andrei Tatarnikov
    # Place your finalization code here
76 60 Andrei Tatarnikov
  end
77 60 Andrei Tatarnikov
78 60 Andrei Tatarnikov
  def run
79 60 Andrei Tatarnikov
    # Place your test problem description here
80 60 Andrei Tatarnikov
  end
81 60 Andrei Tatarnikov
82 61 Andrei Tatarnikov
end</code></pre>
83 57 Andrei Tatarnikov
84 65 Andrei Tatarnikov
h3. Reusing Test Templates
85 65 Andrei Tatarnikov
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 68 Andrei Tatarnikov
<pre><code class="ruby">require ENV[''TEMPLATE'']
89 68 Andrei Tatarnikov
require_relative ''MyPrepost''
90 68 Andrei Tatarnikov
91 71 Andrei Tatarnikov
class MyTemplate < MyPrepost
92 71 Andrei Tatarnikov
93 71 Andrei Tatarnikov
  def run
94 71 Andrei Tatarnikov
  ... 
95 71 Andrei Tatarnikov
  end
96 71 Andrei Tatarnikov
97 71 Andrei Tatarnikov
end</code></pre>
98 68 Andrei Tatarnikov
99 74 Andrei Tatarnikov
h3. Test Template Settings
100 74 Andrei Tatarnikov
101 78 Andrei Tatarnikov
Test templates use the following settings:
102 78 Andrei Tatarnikov
103 78 Andrei Tatarnikov
# Use the standard output to print the generated test program (in addition to the output file);
104 78 Andrei Tatarnikov
# Enable logging information on the simulated instruction calls;
105 78 Andrei Tatarnikov
# Starting characters for single-line comments in the test program;
106 1 Alexander Kamkin
# Starting characters for multi-line comments in the test program;
107 107 Andrei Tatarnikov
# Terminating characters for multi-line comments in the test program;
108 107 Andrei Tatarnikov
# Seed for the randomizer.
109 78 Andrei Tatarnikov
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 106 Andrei Tatarnikov
<pre><code class="ruby">
113 106 Andrei Tatarnikov
@use_stdout    = true
114 106 Andrei Tatarnikov
@log_execution = true
115 106 Andrei Tatarnikov
116 1 Alexander Kamkin
@sl_comment_starts_with = "// "
117 1 Alexander Kamkin
@ml_comment_starts_with = "/*"
118 106 Andrei Tatarnikov
@ml_comment_ends_with   = "*/"
119 106 Andrei Tatarnikov
120 106 Andrei Tatarnikov
@random_seed = 0
121 106 Andrei Tatarnikov
</code></pre>
122 72 Andrei Tatarnikov
123 107 Andrei Tatarnikov
The settings can be overridden in the <code>initialize</code> method of a test template. For example:
124 80 Andrei Tatarnikov
125 80 Andrei Tatarnikov
<pre><code class="ruby">class MyTemplate < Template
126 80 Andrei Tatarnikov
127 80 Andrei Tatarnikov
  def initialize
128 80 Andrei Tatarnikov
    super
129 80 Andrei Tatarnikov
    @sl_comment_starts_with = ";" 
130 80 Andrei Tatarnikov
    @ml_comment_starts_with = "/="
131 80 Andrei Tatarnikov
    @ml_comment_ends_with   = "=/" 
132 80 Andrei Tatarnikov
  end
133 80 Andrei Tatarnikov
  ...
134 80 Andrei Tatarnikov
end</code></pre>
135 80 Andrei Tatarnikov
136 111 Andrei Tatarnikov
h3. Data Definitions
137 1 Alexander Kamkin
138 117 Andrei Tatarnikov
Describing data requires the use of assembler-related directives. These directives should be configured in the <code>data_config</code> block of a test template. Configuration information includes textual format of directives and mappings between nML and assembler data types used by directives. The <code>data_config</code> block is usually placed in the <code>pre</code> method and only one such block per template is allowed. Here is an example:
139 111 Andrei Tatarnikov
140 110 Andrei Tatarnikov
<pre><code class="ruby">
141 110 Andrei Tatarnikov
data_config(:text => ''.data'', :target => ''M'', :addressableSize => 8) {
142 110 Andrei Tatarnikov
  define_type :id => :byte, :text => ''.byte'', :type => type(''card'', 8)
143 110 Andrei Tatarnikov
  define_type :id => :half, :text => ''.half'', :type => type(''card'', 16)
144 110 Andrei Tatarnikov
  define_type :id => :word, :text => ''.word'', :type => type(''card'', 32)
145 110 Andrei Tatarnikov
146 110 Andrei Tatarnikov
  define_space :id => :space, :text => ''.space'', :fillWith => 0
147 110 Andrei Tatarnikov
  define_ascii_string :id => :ascii, :text => ''.ascii'', :zeroTerm => false
148 110 Andrei Tatarnikov
  define_ascii_string :id => :asciiz, :text => ''.asciiz'', :zeroTerm => true
149 110 Andrei Tatarnikov
}
150 1 Alexander Kamkin
</code></pre>
151 111 Andrei Tatarnikov
152 117 Andrei Tatarnikov
The block takes the following parameters (compulsory):
153 1 Alexander Kamkin
154 117 Andrei Tatarnikov
# _text_ - specifies the keyword that marks the beginning of the data section of the generated test program;
155 117 Andrei Tatarnikov
# _target_ - specifies the memory array defined in the nML specification to which data will be placed during simulation;
156 117 Andrei Tatarnikov
# _addressableSize_ - specifies the size (in bits) of addressable memory locations.
157 117 Andrei Tatarnikov
158 117 Andrei Tatarnikov
To set up particular directives the special methods that must be called inside the block are provided. All methods share two parameters: _id_ and _text_. The first specifies the keyword to be used in a test template to address the directive and the second specifies how it will be printed in the test program. The current version of MicroTESK provides the following methods:
159 117 Andrei Tatarnikov
160 117 Andrei Tatarnikov
# _define_type_
161 117 Andrei Tatarnikov
# _define_space_
162 117 Andrei Tatarnikov
# _define_ascii_string_ 
163 117 Andrei Tatarnikov
164 117 Andrei Tatarnikov
After all data directives are configured, data can be defined using the <code>data</code> block:
165 110 Andrei Tatarnikov
166 110 Andrei Tatarnikov
<pre><code class="ruby">
167 110 Andrei Tatarnikov
data {
168 110 Andrei Tatarnikov
  label :data1
169 110 Andrei Tatarnikov
  word 1, 2, 3, 4
170 110 Andrei Tatarnikov
171 110 Andrei Tatarnikov
  label :data2
172 110 Andrei Tatarnikov
  half 0xDEAD, 0xBEEF
173 110 Andrei Tatarnikov
174 110 Andrei Tatarnikov
  label :hello
175 110 Andrei Tatarnikov
  ascii  ''Hello''
176 110 Andrei Tatarnikov
177 110 Andrei Tatarnikov
  label :world
178 110 Andrei Tatarnikov
  asciiz ''World''
179 110 Andrei Tatarnikov
180 110 Andrei Tatarnikov
  space 8
181 110 Andrei Tatarnikov
}
182 110 Andrei Tatarnikov
</code></pre>
183 110 Andrei Tatarnikov
184 1 Alexander Kamkin
TODO
185 110 Andrei Tatarnikov
186 110 Andrei Tatarnikov
-------------------
187 108 Andrei Tatarnikov
188 91 Andrei Tatarnikov
h3. Instruction Calls
189 1 Alexander Kamkin
190 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:
191 85 Andrei Tatarnikov
192 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>
193 1 Alexander Kamkin
194 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:
195 89 Andrei Tatarnikov
196 89 Andrei Tatarnikov
<pre><code class="ruby">instruction addr_mode1(value1_1, value1_2, ...), addr_mode2(value2_1, ...), ...</code></pre>
197 89 Andrei Tatarnikov
198 90 Andrei Tatarnikov
The code below demonstrates both approaches:
199 90 Andrei Tatarnikov
200 90 Andrei Tatarnikov
<pre><code class="ruby">
201 90 Andrei Tatarnikov
mov reg(:i => 0), imm(:i => 0xFF) # The use of hash maps
202 90 Andrei Tatarnikov
mov reg(0), imm(0xFF)             # The use of variable numbers of arguments
203 1 Alexander Kamkin
</code></pre>
204 91 Andrei Tatarnikov
205 91 Andrei Tatarnikov
h3. Instruction Call Blocks
206 91 Andrei Tatarnikov
207 91 Andrei Tatarnikov
208 90 Andrei Tatarnikov
209 20 Alexander Kamkin
h2. *TODO: REWRITE*
210 1 Alexander Kamkin
211 20 Alexander Kamkin
h3. Basic features
212 1 Alexander Kamkin
213 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.
214 1 Alexander Kamkin
215 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:
216 1 Alexander Kamkin
217 20 Alexander Kamkin
<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"
218 1 Alexander Kamkin
219 3 Artemiy Utekhin
class MyTemplate < Template</code></pre>
220 1 Alexander Kamkin
221 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%.
222 1 Alexander Kamkin
223 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:
224 3 Artemiy Utekhin
225 3 Artemiy Utekhin
<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"
226 3 Artemiy Utekhin
227 3 Artemiy Utekhin
class MyPrepost < Template
228 1 Alexander Kamkin
  def initialize
229 3 Artemiy Utekhin
    super
230 3 Artemiy Utekhin
    @is_executable = no
231 3 Artemiy Utekhin
  end
232 1 Alexander Kamkin
233 3 Artemiy Utekhin
  def pre
234 3 Artemiy Utekhin
    # Your ''startup'' code goes here
235 3 Artemiy Utekhin
  end
236 9 Andrei Tatarnikov
237 1 Alexander Kamkin
  def post
238 11 Andrei Tatarnikov
    # Your ''cleanup'' code goes here
239 1 Alexander Kamkin
  end
240 3 Artemiy Utekhin
end</code></pre>
241 3 Artemiy Utekhin
242 3 Artemiy Utekhin
<pre><code class="ruby">require_relative "_path-to-the-rubymt-library_/mtruby"
243 3 Artemiy Utekhin
244 3 Artemiy Utekhin
class MyTemplate < MyPrepost
245 3 Artemiy Utekhin
  def initialize
246 3 Artemiy Utekhin
    super
247 3 Artemiy Utekhin
    @is_executable = yes
248 3 Artemiy Utekhin
  end
249 11 Andrei Tatarnikov
  
250 1 Alexander Kamkin
  def run
251 3 Artemiy Utekhin
    # Your template code goes here
252 1 Alexander Kamkin
  end
253 16 Andrei Tatarnikov
end</code></pre>
254 1 Alexander Kamkin
255 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:
256 1 Alexander Kamkin
257 16 Andrei Tatarnikov
<pre><code class="ruby">instruction_name addr_mode1(:arg1_1 => value, :arg1_2 => value, ...), addr_mode2(:arg2_1 => value, ...), ...</code></pre>
258 1 Alexander Kamkin
259 3 Artemiy Utekhin
So, for instance, if the simulator has an ADD(MEM(i), MEM(i)|IMM(i)) instruction, it would look like:
260 1 Alexander Kamkin
261 16 Andrei Tatarnikov
<pre><code class="ruby">add mem(:i => 42), imm(:i => 128)</code></pre>
262 3 Artemiy Utekhin
263 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:
264 8 Artemiy Utekhin
265 16 Andrei Tatarnikov
<pre><code class="ruby">add mem(42), 128</code></pre>
266 8 Artemiy Utekhin
267 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:
268 3 Artemiy Utekhin
269 3 Artemiy Utekhin
<pre><code class="ruby">instruction_name addr_mode1(value1, value2, ...) ...</code></pre>
270 3 Artemiy Utekhin
271 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.
272 3 Artemiy Utekhin
273 3 Artemiy Utekhin
h3. Test situations
274 3 Artemiy Utekhin
275 3 Artemiy Utekhin
_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_
276 3 Artemiy Utekhin
277 17 Andrei Tatarnikov
_Big TODO: define what is a test situation_
278 3 Artemiy Utekhin
279 3 Artemiy Utekhin
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):
280 3 Artemiy Utekhin
281 3 Artemiy Utekhin
<pre><code class="ruby">sub mem(42), mem(21) do overflow(:op1 => 123, :op2 => 456) end</code></pre>
282 3 Artemiy Utekhin
283 12 Andrei Tatarnikov
h3. Instruction blocks
284 3 Artemiy Utekhin
285 3 Artemiy Utekhin
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).
286 3 Artemiy Utekhin
287 3 Artemiy Utekhin
<pre><code class="ruby">p = lambda { overflow(:op1 => 123, :op2 => 456) }
288 3 Artemiy Utekhin
289 12 Andrei Tatarnikov
atomic p {
290 3 Artemiy Utekhin
  mov mem(25), mem(26)
291 25 Andrei Tatarnikov
  add mem(27), 28
292 3 Artemiy Utekhin
  sub mem(29), 30
293 24 Andrei Tatarnikov
}</code></pre>
294 24 Andrei Tatarnikov
295 24 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.)_
296 24 Andrei Tatarnikov
297 24 Andrei Tatarnikov
From source code comments:
298 24 Andrei Tatarnikov
299 24 Andrei Tatarnikov
<pre>
300 24 Andrei Tatarnikov
# VERY UNTESTED leftovers from the previous version ("V2", this is V3)
301 24 Andrei Tatarnikov
# Should work with the applied fixes but I''d be very careful to use these
302 24 Andrei Tatarnikov
303 3 Artemiy Utekhin
# As things stand this is just a little discrete probability utility that
304 3 Artemiy Utekhin
# may or may not find its way into the potential ruby part of the test engine
305 3 Artemiy Utekhin
</pre>
306 3 Artemiy Utekhin
307 17 Andrei Tatarnikov
There are certain ways to group together or randomize addressing modes and instructions.
308 3 Artemiy Utekhin
309 3 Artemiy Utekhin
To group several addressing modes together (this only works if they have similar arguments) create a mode group like this:
310 3 Artemiy Utekhin
311 17 Andrei Tatarnikov
<pre><code class="ruby">mode_group "my_group" [:mem, :imm]</code></pre>
312 3 Artemiy Utekhin
313 3 Artemiy Utekhin
You can also set weights to each of the modes in the group like this:
314 3 Artemiy Utekhin
315 17 Andrei Tatarnikov
<pre><code class="ruby">mode_group "my_group" {:mem => 1.5, :imm => 2.5}</code></pre>
316 3 Artemiy Utekhin
317 3 Artemiy Utekhin
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:
318 3 Artemiy Utekhin
319 3 Artemiy Utekhin
<pre><code class="ruby">add mem(42), my_group.sample(21)</code></pre>
320 3 Artemiy Utekhin
321 17 Andrei Tatarnikov
_TODO: sampling already parametrized modes_
322 3 Artemiy Utekhin
323 17 Andrei Tatarnikov
The first method of grouping instructions works in a similar manner with the same restrictions on arguments:
324 3 Artemiy Utekhin
325 17 Andrei Tatarnikov
<pre><code class="ruby">group "i_group" [:add, :sub]</code></pre>
326 3 Artemiy Utekhin
327 3 Artemiy Utekhin
<pre><code class="ruby">group "i_group" {:add => 0.3, :sub => 0.7]</code></pre>
328 3 Artemiy Utekhin
329 17 Andrei Tatarnikov
<pre><code class="ruby">i_group.sample mem(42), 21</code></pre>
330 3 Artemiy Utekhin
331 3 Artemiy Utekhin
You can also run all of the instructions in a group at once by using the %all% method:
332 3 Artemiy Utekhin
333 17 Andrei Tatarnikov
<pre><code class="ruby">i_group.all mem(42), 21</code></pre>
334 3 Artemiy Utekhin
335 3 Artemiy Utekhin
The second one allows you to create a normal block of instructions, setting their arguments separately. 
336 3 Artemiy Utekhin
337 17 Andrei Tatarnikov
<pre><code class="ruby">block_group "b_group" do
338 3 Artemiy Utekhin
  mov mem(25), mem(26)
339 3 Artemiy Utekhin
  add mem(27), 28
340 3 Artemiy Utekhin
  sub mem(29), 30
341 17 Andrei Tatarnikov
end</code></pre>
342 3 Artemiy Utekhin
343 3 Artemiy Utekhin
In this case to set weights you should call a %prob% method before every instruction:
344 3 Artemiy Utekhin
345 3 Artemiy Utekhin
<pre><code class="ruby">block_group "b_group" do
346 3 Artemiy Utekhin
  prob 0.1
347 3 Artemiy Utekhin
  mov mem(25), mem(26)
348 17 Andrei Tatarnikov
  prob 0.7
349 3 Artemiy Utekhin
  add mem(27), 28
350 3 Artemiy Utekhin
  prob 0.4
351 3 Artemiy Utekhin
  sub mem(29), 30
352 18 Andrei Tatarnikov
end</code></pre>
353 18 Andrei Tatarnikov
354 3 Artemiy Utekhin
The usage is almost identical, but without providing the arguments as they are already set:
355 3 Artemiy Utekhin
356 3 Artemiy Utekhin
<pre><code class="ruby">b_group.sample
357 3 Artemiy Utekhin
b_group.all</code></pre>
358 3 Artemiy Utekhin
359 3 Artemiy Utekhin
_Not sure how does it work inside atomics when the group is defined outside, needs more consideration_
360 8 Artemiy Utekhin
361 8 Artemiy Utekhin
_TODO: Permutations_
362 8 Artemiy Utekhin
363 8 Artemiy Utekhin
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.
364 8 Artemiy Utekhin
365 18 Andrei Tatarnikov
h3. TODO: Labels
366 8 Artemiy Utekhin
367 8 Artemiy Utekhin
To set a label write:
368 8 Artemiy Utekhin
369 18 Andrei Tatarnikov
<pre><code class="ruby">label :label_name</code></pre>
370 8 Artemiy Utekhin
371 8 Artemiy Utekhin
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):
372 8 Artemiy Utekhin
373 8 Artemiy Utekhin
<pre><code class="ruby">b greaterThan, :label_name</code></pre>
374 8 Artemiy Utekhin
375 15 Andrei Tatarnikov
h3. TODO: Debug
376 8 Artemiy Utekhin
377 8 Artemiy Utekhin
To get a value from registers use:
378 8 Artemiy Utekhin
379 8 Artemiy Utekhin
<pre><code class="ruby">get_reg_value("register_name", index)</code></pre>
380 8 Artemiy Utekhin
381 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.
382 8 Artemiy Utekhin
383 15 Andrei Tatarnikov
To print some debug in the console during the execution of the instructions use the exec_debug block:
384 8 Artemiy Utekhin
385 8 Artemiy Utekhin
<pre><code class="ruby">exec_debug {
386 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
387 14 Andrei Tatarnikov
}</code></pre>
388 8 Artemiy Utekhin
389 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:
390 1 Alexander Kamkin
391 1 Alexander Kamkin
<pre><code class="ruby">exec_output {
392 1 Alexander Kamkin
  "// The result should be " + self.get_reg_value("GPR", 0).to_s
393 1 Alexander Kamkin
}</code></pre>