Section B) rtfm-core compiler

This section we cover
B.1) the -core compiler options
B.2) an overview of the -core compiler design
B.3) compiler implementation.

B.1) Compiler options:

The -core compiler has the following options:

The RTFM-core compiler v1.0, Per Lindgren (c) 2014

Usage core [--async_err] [-gcc|-ccomp|-clang] [-rt|-km3] [-v] [-D]   [-gv_task file.gv] [-gv_res file.gv] [-d_ast] [-o outfile.c] [-i] infile.core

Options summary:
  -i            : infile
  -o            : outfile (default infile.c)
  -async_err    : async_err (default disable)
  -gv_task      : graphviz file (default none)
  -gv_res       : graphviz file (default none)
  -gcc          : for gcc (default)
  -ccomp        : for ccomp
  -clang        : for clang
  -rt           : for Pthread Linux (default)
  -km3          : for ARM Cortex M3
  -v            : verbose mode (default disable)
  -D            : debug mode (default disable)
  -d_ast        : dump AST
  -help         : Display this list of options
  --help        : Display this list of options
  
Recognised source file:
infile.core      RTFM-core source infile (root)

Output C file:
-o outfile.c     Compiler output (defaults to input.c)

Compilation options:
-async_err       Enable : Treat inconsistent timing requirements as errors 
                 (default warning)

Backend options:
-gcc             Generate code for GCC backend (default)
-ccomp           Generate code for CCOMP backend
-clang           Generate code for CLANG backend

Target options:
-rt              Target RTFM Run-Time (OSX/Linux/Windows) (default)
-km3             Target RTFM Kernel ARM Cortex M3

General options:
-v               Enable : Verbose compilation (default disabled)
-D               Enable : Generate output for debugging (default disabled)

Additional options:
-gv_task file.gv Enable : Task and resource structure in gv format 
                 (default disabled)
-gv_res  file.gv Enable : Resource dependency graph (lock structure) in gv 
                 format (default disabled)
-d_ast           Enable : Dump internal AST (default disabled)

All file paths are relative to the current directory.


See section X for compiling C-code output for run-time execution.

B.2) Compiler design

As a coarse-grained view the following diagram shows the steps taken by the compiler to transform the input program given in RTFM-core language into C code.
rtfm-core-steps.png

The next diagram represents the flow of information through the rtfm-core-ompiler in more detail. It corresponds to the main function within the Main.ml file.
rtfm-core_1.png

As first step the whole input program is processed by the function parse_prog. This also means recursive processing of included input files. The function resturns a list of toplevel definitions which is the AST of the input program.
rtfm-core_2.png


The rtfm-core compiler performs the following steps:
1. Lexing and parsing of the input program to an internal AST representation. Single line and nested comments are taken care of in the lexer.

2. Task/Func instance generation to and internal SpecAST representation. Tasks/Funcs in the program input are treated as definitions. Each async Isrs, reachable from Isrs, Reset and Idle are recursively generates unique task and function instances.

This allows single buffering of task arguments given a schedulable system where deadlines are less/equal to inter-arrival time.

3. Specialisation of the SpecAST. Each task instance has a unique identifier given form the path of origin (e.g., reset_task1_0), corresponds to the first async to task1 from the reset task. ( reset_task1_1 to the 2nd, etc.) During specialisation path names are propagated to the statements. Special case for asyncs closing a cycle is considered.

4. Compile time SRP analysis for deriving resource ceilings.

5. (Optional for bare metal executables)
  1. Mapping of task instances to free places of the interrupt vector.
  2. C-code generation for the RTFM-Kernel API

6. (Optional for thread based executables)
  1. Lock analysis, detecting potential deadlock chains.

7. (Optional for Graphviz output)
  1. gv_task detailed view over the system instance
  2. gv_res overview of resource dependencies visualising potential deadlock as a cycle in the resource dependency graph

B.3) Compiler implementation:

File by file:
  1. AST.ml
    1. defines the AST for parsing -core programs
    2. provides pretty printing for the AST constructs
  2. Common.ml
    1. defines some common (to -core and -coore) data structures and functions
  3. Env.ml
    1. defines lookup functions (more refactoring could be done)
  4. Error.ml
    1. defines error handling for the lexer (and parser)
  5. Gv.ml
    1. provides .gv output for tasks
  6. ICGenRT.ml
    1. C-code generation for the thread based run-time (currently required to build CompCert-C only systems due to lack of weak-pointer support in CompCert-C)
  7. IsrCGen.ml
    1. C-code generation for interrupt vector output
  8. IsrVector.ml
    1. IsrVector specification (for LPC1769 Cortex M3) for now, replace this file to change ARM target (ongoing work to be replaced by configuration file option)
  9. Lexer.mll
    1. ocamllex lexer used in combination with Menhir
  10. Locks.ml
    1. lock related analysis for thread based run-times
  11. Main.ml
    1. the main file
  12. Options.ml
    1. defines the compiler options and default values
  13. Parser.mly
    1. grammar for parser generation using Menhir
  14. SpecAST.ml
    1. defines the AST for task generation and specialisation
  15. SRP.ml
    1. analys for resource ceiling computation (used for code generation targeting both bare-metal and threads)
  16. TaskGenSpec.ml
    1. analysis for task generation and specialisation

Word form the author:

The -core compiler together with supporting tools have been designed and implemented from scratch during a 3 month period (June,-August 2014).

It is an endeavour of some complexity, and I was completely new to both OCaml and Menhir at this point (June). Despite that many design choices and implementation techniques can be improved on, I'm confident that the choice of OCaml and Menhir was a good one. I will consistently seek to improve both functionality and readability of the compiler implementation. Even the -core language (and its semantics) can and will be further refined.

Especially the timing semantics, and static analysis thereof is a work-in-progress, and you will see some additions during the fall.

/Per Lindgren, founder of RTFM-lang August 2014.



Last edited Sep 17, 2014 at 8:40 PM by andreaslindner, version 10