=head1 Overview

This document contains an overview of the internals of the .NET EXE/DLL file to
PIR translator. If you are looking to use the translator rather than hack on it,
you're probably reading the wrong document; see L<contents.pod> instead.

=head2 Process Overview

This describes the steps that take place in converting a .NET EXE or DLL file
into Parrot bytecode, ready to execute natively in Parrot or write to a file
for later loading by Parrot programs.

                   +----------------------------+
                   |  .NET CLI EXE or DLL File  |
                   +------------||--------------+
                                ||
                               _||_
                               \  /
                   +------------\/--------------+
                   |    Metadata Translator     |----------+
                   +------------||--------------+          |
                                ||                      +------+
                               _||_                     | PMCs |
                               \  /                     +------+
                   +------------\/--------------+          |
                   |   Instruction Translator   |----------+
                   +------------||--------------+
                                ||
                               _||_
                               \  /
                   +------------\/--------------+
                   |    Translated PIR Code     |
                   +------------||--------------+
                                ||
                               _||_
                               \  /
                   +------------\/--------------+
                   | Translated Parrot Bytecode |
                   +----------------------------+

=head2 PMCs

These are classes implemented in C. Method calls and operations can be
performed on them from Parrot programs. In this translation system, they
are being used to enable parts of the system to be written in C.

Details of them can be found in L<pmcs.pod> and the source files are in
the "pmc" directory and have file extension ".pmc". The .c and most of
the .h files are generated, so should not be modified; "structures.h"
and "tableinfo.h" are the two exceptions to this rule.

=head2 Metadata Translator

In .NET, A lot of data about classes and their methods and fields is not
stored in the instruction stream but rather in a set of tables. This
part of the system takes the data in the tables and turns it into Parrot
intermediate code.

This module uses the PMCs extensively. It translates the class hierachy,
fields and method headers with their parameter list and local variables.
It delegates the translation of the method body to the instruction
translator.

The source for this subsystem is found in the "src" directory. It is
written in PIR.

=head2 Instruction Translator

This part of the system translates .NET method bodies into PIR. It maps
.NET instructions to Parrot instructions and maps the stack onto some
Parrot registers. This is easily the most complex part of the system.

Rules and stack to register mapping are specified in a number of files
and a build tool (located in the "build" directory) turns them into
PIR. This resultant PIR ends up in the "src" directory.

=head2 The PIR Compiler

This is a part of Parrot, not of the translation system. It simply turns
Parrot Intermediate Representation into Parrot bytecode, which the Parrot
virtual machine can execute.