diff --git a/docs/source/prog8compiler.odg b/docs/source/prog8compiler.odg new file mode 100644 index 000000000..afc1d19f8 Binary files /dev/null and b/docs/source/prog8compiler.odg differ diff --git a/docs/source/prog8compiler.svg b/docs/source/prog8compiler.svg new file mode 100644 index 000000000..9923a781f --- /dev/null +++ b/docs/source/prog8compiler.svg @@ -0,0 +1,490 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + antlr + + + + + + + + Read module.p8 + + + + + + + + Tokenize + + + + + + + + Convert to AST + + + + + + + + Semantic and Type checking + + + + + + + + Preprocess AST + + + + + + + + + + + + + + + + + + + + + + + + + + + + + importmodule + + + + + + + + + + + + + + + + + + + + + + Optimize + + + + + + + + Postprocess AST + + + + + + + + + + + + + + + + + + + + + + Parse + + + + + + + + + + + + + (optional step) + + + + + + + + Select CodeGenfor target + + + + + + + + + + + + + + (if assembly generation is selected) + + + + + + + + Make Intermediate AST + + + + + + + + + + + + + + + Generate IR + + + + + + + + + + + + + + + Optimize IR + + + + + + + + + + + + + + + Generate 6502 Asm + + + + + + + + + + + + + (depends on codegen) + + + + + + + + Assemble (64tass) + + + + + + + + + + + + + + + hello.p8 + + + + + + + + + + + + + + + hello.prg + + + + + + + + + + + + + + + Generate VM code + + + + + + + + hello.p8virt + + + + + + + + + + + + + + + + + + + + + + + + + + + (future) + + + + + + + + \ No newline at end of file diff --git a/docs/source/technical.rst b/docs/source/technical.rst index 7dc83755d..ea2295792 100644 --- a/docs/source/technical.rst +++ b/docs/source/technical.rst @@ -119,3 +119,29 @@ Prog8 also provides some help to deal with this: - you should use a ``clobbers(X)`` specification for asmsub routines that modify the X register; the compiler will preserve it for you automatically when such a routine is called - the ``rsavex()`` and ``rrestorex()`` builtin functions can preserve and restore the X register - the ``rsave()`` and ``rrestore()`` builtin functions can preserve and restore *all* registers (but this is very slow and overkill if you only need to save X) + + +Compiler Internals +------------------ + +Here is a diagram of how the compiler translates your program source code into a binary program: + +.. image:: prog8compiler.svg + +Some notes and references into the compiler's source code modules: + +#. The ``compileProgram()`` function (in the ``compiler`` module) does all the coordination and basically drives all of the flow shown in the diagram. +#. ANTLR is a Java parser generator and is used for initial parsing of the source code. (``parser`` module) +#. Most of the compiler and the optimizer operate on the *Compiler AST*. These are complicated + syntax nodes closely representing the Prog8 program structure. (``compilerAst`` module) +#. For code generation, a much simpler *intermediate AST* has been defined that replaces the *Compiler AST*. + Most notably, node type information is now baked in. (``codeCore`` module) +#. An *Intermediate Representation* has been defined that is generated from the intermediate AST. This IR + is more or less a machine code language for a virtual machine - and indeed this is what the built-in + prog8 VM will execute if you use the 'virtual' compilaton target and use ``-emu`` to launch the VM. + (``intermediate`` and ``codeGenIntermediate`` modules, and ``codeGenVirtual`` and ``virtualmachine`` module for the VM related stuff) +#. Currently the 6502 ASM code generator still works directly on the *Compiler AST*. A future version + should replace this by working on the IR code, and should be much smaller and simpler. + (``codeGenCpu6502`` module) +#. Other code generators may either work on the intermediate AST or on the IR. Selection of what code generator + to use is mostly based on the compilation target, and is done in the ``asmGeneratorFor()`` function. diff --git a/docs/source/todo.rst b/docs/source/todo.rst index 86b3159bf..499a55bd8 100644 --- a/docs/source/todo.rst +++ b/docs/source/todo.rst @@ -3,7 +3,6 @@ TODO For next release ^^^^^^^^^^^^^^^^ -- write some documentation about the compiler architecture and where to plug a code generator onto. - vm: implement remaining sin/cos functions in virtual/math.p8 and merge tables ...