MicroTESK

h1. Getting Started with x86

{{toc}}

h2. Prerequisite

MicroTESK should be [[Installation Guide|installed]].

h2. Demo Specifications

Specifications of the x86 (8086) instruction set architecture (ISA) can be found in "$MICROTESK_HOME/arch/demo/x86/model/x86.nml":http://forge.ispras.ru/projects/microtesk/repository/entry/trunk/microtesk/src/main/arch/demo/x86/model/x86.nml.

Instruction are described in [[nML Language Reference|nML]] by means of the following constructs (_move r16/r16_ is taken as an example):

## the signature

<pre><code class="c">op mov_r16r16 (dst: R16, src: R16)</code></pre>

## the assembly format

<pre><code class="c">syntax = format("mov %s, %s", dst.syntax, src.syntax)</code></pre>

## the binary encoding

<pre><code class="c">image = format("1000101111%s%s", dst.image, src.image)</code></pre>

## the semantics

<pre><code class="c">

  action = {

    dst = src;

    ...

  }

</code></pre>

To compile the ISA model, run the following command:

<pre>sh $MICROTESK_HOME/bin/compile.sh x86.nml</pre>

h2. Demo Templates

Test templates for the x86 (8086) ISA can be found in "$MICROTESK_HOME/arch/demo/x86/templates":http://forge.ispras.ru/projects/microtesk/repository/entry/trunk/microtesk/src/main/arch/demo/x86/templates.

The directory contains a number of demo templates including the following ones:

{background:#f6fcff}. | "block.rb":http://forge.ispras.ru/projects/microtesk/repository/entry/trunk/microtesk/src/main/arch/demo/x86/templates/block.rb | demonstrates how to use block constructs |

                      | "block_random.rb":http://forge.ispras.ru/projects/microtesk/repository/entry/trunk/microtesk/src/main/arch/demo/x86/templates/block_random.rb | demonstrates how to create randomized instruction sequences using block constructs |

{background:#f6fcff}. | "euclid.rb":http://forge.ispras.ru/projects/microtesk/repository/entry/trunk/microtesk/src/main/arch/demo/x86/templates/euclid.rb | demonstrates test program simulation to predict the resulting microprocessor state |

                      | "random.rb":http://forge.ispras.ru/projects/microtesk/repository/entry/trunk/microtesk/src/main/arch/demo/x86/templates/random.rb | demonstrates how to randomize tests by using biases and distributions |

{background:#f6fcff}. | "random_immediate.rb":http://forge.ispras.ru/projects/microtesk/repository/entry/trunk/microtesk/src/main/arch/demo/x86/templates/random_immediate.rb | demonstrates how to randomize immediate values |

                      | "random_registers.rb":http://forge.ispras.ru/projects/microtesk/repository/entry/trunk/microtesk/src/main/arch/demo/x86/templates/random_registers.rb | demonstrates how to randomize registers (dependencies) |

Test templates are written in "Ruby":http://www.ruby-lang.org extended with specific [[Template_Description_Language|constructs]] (let us look at "block.rb":http://forge.ispras.ru/projects/microtesk/repository/entry/trunk/microtesk/src/main/arch/demo/x86/templates/block.rb):

# the code in the beginning includes the "x86_base.rb":http://forge.ispras.ru/projects/microtesk/repository/entry/trunk/microtesk/src/main/arch/demo/x86/templates/x86_base.rb file where a base template @X86BaseTemplate@ is defined and declares a @BlockTemplate@ template:

<pre><code class="ruby">

require_relative ''x86_base''

class BlockTemplate < X86BaseTemplate  # BlockTemplate is a heir of @X86BaseTemplate@

</code></pre>

# here is a template entry point:

<pre><code class="ruby"> def run</code></pre>

# this block produces a sequence consisting of three instructions:

<pre><code class="ruby">

  sequence { # {{mov, sub, add}}

    mov_r16r16 ax, bx

    sub_r16r16 cx, dx

    add_r16r16 r16(_), r16(_)

  }.run

</code></pre>

# this block produces an atomic sequence consisting of three instructions (atomic sequences are not interrupted while being merged with other ones):

<pre><code class="ruby">

  atomic { # {{mov, add, sub}}

    mov_r16r16 ax, bx

    add_r16r16 cx, dx

    sub_r16r16 r16(_), r16(_)

  }.run

</code></pre>

# this block produces three sequences each consisting of one instruction:

<pre><code class="ruby">

  iterate { # {{mov}, {sub}, {add}}

    mov_r16r16 ax, bx

    sub_r16r16 cx, dx

    add_r16r16 r16(_), r16(_)

  }.run

</code></pre>

# this block produces four sequences each consisting of two instructions

~the combinator constructs the Cartesian product of the nested sets of sequences; the compositor randomly merges each tuple of the product into one sequence:~

<pre><code class="ruby">

  block(:combinator => ''product'',  # {({sub}, {mov}), ({sub}, {sub}), ({add}, {mov}), ({add}, {sub})}

        :compositor => ''random'') { # {  {mov, sub},     {sub, sub},     {add, mov},     {add, sub}  }

    iterate { # {{sub}, {add}}

      sub_r16r16 cx, dx

      add_r16r16 ax, bx

    }

    iterate { # {{mov}, {sub}}

      mov_r16r16 ax, bx

      sub_r16r16 r16(_), r16(_)

    }

  }.run

</code></pre>

# this block merges two sequences in a random fashion

~the combinator constructs the diagonal of the Cartesian product; the compositor randomly merges the tuples into sequences; the obfuscator reorders the sequences:~

<pre><code class="ruby">

  block(:combinator => ''diagonal'', # {({sub, or}, {start, and, end})}

        :compositor => ''random'',   # {  {sub, start, and, end, or}  }

        :obfuscator => ''random'') { # {  {or, start, and, end, sub}  }

    sequence { # {sub, or}

      sub_r16r16 bx, ax

      or_r16r16 cx, dx

    }

    atomic {   # {start, add, end}

      prologue { comment ''Atomic starts'' }

      epilogue { comment ''Atomic ends'' }

      and_r16r16 r16(_), r16(_)

    }

  }.run

</code></pre>

To generate a test program from a test template (in our case, from @block.rb@), run the following command:

<pre>sh $MICROTESK_HOME/bin/generate.sh x86 block.rb --code-file-prefix block --code-file-extension s -v</pre>

When generation is finished, the resulting "assembly code":http://forge.ispras.ru/attachments/download/5127/block_0000.s can be found in @$MICROTESK_HOME@.

To compile the test program, run the following commands:

<pre>

nasm -f elf block_0000.s

ld -m i386pe -s -o block_0000 block_0000.o

</pre>

The test program can be executed in the "simulator":https://www.tutorialspoint.com/compile_assembly_online.php

p=. !Example_block.png!