readme
changeset 625 c0bda77b37a0
parent 457 67d8b07bac22
equal deleted inserted replaced
412:aad38592bdde 625:c0bda77b37a0
     6 
     6 
     7   The following compiler has been based on the
     7   The following compiler has been based on the
     8   FINAL DRAFT - IEC 61131-3, 2nd Ed. (2001-12-10)
     8   FINAL DRAFT - IEC 61131-3, 2nd Ed. (2001-12-10)
     9 
     9 
    10 
    10 
    11   Copyright (C) 2003-2011  Mario de Sousa (msousa@fe.up.pt)
    11   Copyright (C) 2003-2012  Mario de Sousa (msousa@fe.up.pt)
       
    12 
       
    13 
       
    14 ****************************************************************
       
    15 ****************************************************************
       
    16 ****************************************************************
       
    17 *********                                              *********
       
    18 *********                                              *********
       
    19 *********         O V E R A L L    G O A L S           *********
       
    20 *********                                              *********
       
    21 *********                                              *********
       
    22 ****************************************************************
       
    23 ****************************************************************
       
    24 ****************************************************************
       
    25 
       
    26 
       
    27 
       
    28  This project has the goal of producing an open source compiler for the programming languages defined
       
    29 in the IEC 61131-3 standard. These programming languages are mostly used in the industrial automation 
       
    30 domain, to program PLCs (Programmable Logic Controllers).
       
    31 
       
    32  This standard defines 5 programming languages:
       
    33      - IL : Instructtion List
       
    34             A textual programming language, somewhat similar to assembly.
       
    35      - ST : Structured Text
       
    36             A textual programming language, somewhat similar to Pascal.
       
    37      - FBD: Function Block Diagram
       
    38             A graphical programming language, somewhat similar to an electrical circuit diagram based on small 
       
    39              scale integration ICs (Integrated Circuits) (counters, AND/OR/XOR/... logic gates, timers, ...).
       
    40      - LD : Ladder Diagram
       
    41             A graphical programming language, somewhat similar to an electrical circuit diagram based on 
       
    42              relays (used for basic cabled logic controllers).
       
    43      - SFC: Sequential Function Chart
       
    44             A graphical programming language, that defines a state machine, based largely on Grafcet.
       
    45             (may also be expressed in textual format).
       
    46 
       
    47  Of the above 5 languages, the standard defines textual representations for IL, ST and SFC. 
       
    48 It is these 3 languages that we target, and we currently support all three, as long as they are
       
    49 expressed in the textual format as defined in the standard.
       
    50 
       
    51  Currently the matiec project generates two compilers (more correctly, code translaters, but we like
       
    52 to call them compilers :-O ): iec2c, and iec2iec
       
    53 
       
    54  Both compilers accept the same input: a text file with ST, IL and/or SFC code.
       
    55 
       
    56  The iec2c compiler generates ANSI C code which is equivalent to the IEC 61131-3 code expressed in the input file.
       
    57 
       
    58  The iec2iec compiler generates IEC61131-3 code which is equivalent to the IEC 61131-3 code expressed in the input file.
       
    59 This last compiler should generate and output file which should be almost identical to the input file (some formating 
       
    60 may change, as well as the case of letters, etc.). This 'compiler' is mostly used by the matiec project contributors
       
    61 to help debug the lexical and syntax portions of the compilers.
       
    62 
       
    63 
       
    64 
       
    65  To compile/build these compilers, just
       
    66 $./configure; make
       
    67 
       
    68 
    12 
    69 
    13 
    70 
    14 
    71 
    15 ****************************************************************
    72 ****************************************************************
    16 ****************************************************************
    73 ****************************************************************
    23 ****************************************************************
    80 ****************************************************************
    24 ****************************************************************
    81 ****************************************************************
    25 ****************************************************************
    82 ****************************************************************
    26 
    83 
    27  The compiler works in 4(+1) stages:
    84  The compiler works in 4(+1) stages:
    28  Stage 1   - Lexical analyser      - implemented with flex (iec.flex)
    85  ==================================
    29  Stage 2   - Syntax parser         - implemented with bison (iec.y)
    86  Stage 1    - Lexical analyser       - implemented with flex (stage1_2/iec_flex.ll)
    30  Stage 3   - Semantics analyser    - currently in its early stages
    87  Stage 2    - Syntax parser          - implemented with bison (stage1_2/iec_bison.yy)
    31  Stage 4   - Code generator        - implemented in C++
    88  Stage pre3 - Populate symbol tables - Symbol tables that will ease searching for symbols in the abstract symbol tree.
    32  Stage 4+1 - Binary code generator - gcc, javac, etc...
    89  Stage 3    - Semantics analyser     - currently does type checking only
       
    90  Stage 4    - Code generator         - generates ANSI C code
       
    91 
       
    92  Stage 5    - Binary code generator - gcc, javac, etc... (Not integrated into matiec compiler. Must be called explicitly by the user.)
       
    93 
    33 
    94 
    34 
    95 
    35  Data structures passed between stages, in global variables:
    96  Data structures passed between stages, in global variables:
    36  1->2   : tokens (int), and token values (char *)
    97  ==========================================================
    37  2->1   : symbol tables (defined in symtable.hh)
    98    1->2   : tokens (int), and token values (char *) (defined in stage1_2/stage1_2_priv.hh)
    38  2->3   : abstract syntax tree (tree of C++ classes, in absyntax.hh file)
    99    2->1   : symbol tables (implemented in util/symtable.[hh|cc], and defined in stage1_2/stage1_2_priv.hh)
    39  3->4   : Same as 2->3
   100    2->3   : abstract syntax tree (tree of C++ objects, whose classes are defined in absyntax/absyntax.hh)
    40  4->4+1 : file with program in c, java, etc...
   101 pre3->3,4 : global symbol tables (defined in util/[d]symtable.[hh|cc] and declared in absyntax_utils/absyntax_utils.hh)
       
   102    3->4   : abstract syntax tree (same as 2->3), but now annotated (i.e. some extra data inserted into the absyntax tree)
       
   103 
       
   104    4->5   : file with program in c, java, etc...
       
   105 
       
   106 
    41 
   107 
    42 
   108 
    43  The compiler works in several passes:
   109  The compiler works in several passes:
    44  Pass 1: executes stages 1 and 2 simultaneously
   110  ====================================
    45  Pass 2: executes stage 3
   111 
    46  Pass 3: executes stage 4
   112 Stage 1 and Stage 2
    47  Pass 4: executes stage 4+1
   113 -------------------
       
   114   Executed in one single pass. This pass will:
       
   115   - Do lexical analysis
       
   116   - Do syntax analysis
       
   117   - Execute the absyntax_utils/add_en_eno_param_decl_c visitor class
       
   118     This class will add the EN and ENO parameter declarations to all
       
   119     functions that do not have them already explicitly declared by the user.
       
   120     This will let us handle these parameters in the remaining compiler just as if
       
   121     they were standard input/output parameters.
       
   122 
       
   123 
       
   124 Stage Pre3
       
   125 ----------
       
   126   Executed in one single pass. This pass will populate the following symbol tables:
       
   127    - function_symtable;            /* A symbol table with all globally declared functions POUs. */
       
   128    - function_block_type_symtable; /* A symbol table with all globally declared functions block POUs. */
       
   129    - program_type_symtable;        /* A symbol table with all globally declared program POUs. */
       
   130    - type_symtable;                /* A symbol table with all user declared (non elementary) datat type definitions. */
       
   131    - enumerated_value_symtable;    /* A symbol table with all identifiers (values) declared for enumerated types. */
       
   132 
       
   133 
       
   134 Stage 3
       
   135 -------
       
   136   Executes two algorithms (flow control analysis, and data type analysis) in several passes.
       
   137 
       
   138   Flow control:
       
   139      Pass 1: Does flow control analysis (for now only of IL code) 
       
   140              Implemented in -> stage3/flow_control_analysis_c
       
   141              This will anotate the abstract syntax tree 
       
   142              (Every object of the class il_instruction_c that is in the abstract syntax tree will have the variable 'prev_il_instruction' correctly filled in.)
       
   143 
       
   144   Data Type Analysis
       
   145      Pass 1: Analyses the possible data types each expression/literal/IL instruction/etc. may take 
       
   146              Implemented in -> stage3/fill_candidate_datatypes_c
       
   147              This will anotate the abstract syntax tree 
       
   148              (Every object of in the abstract syntax tree that may have a data type, will have the variable 'candidate_datatypes' correctly filled in.
       
   149              Additionally, objects in the abstract syntax tree that represen function invocations will have the variable 
       
   150               'candidate_functions' correctly filled in.)
       
   151 Pass 2: Narrows all the possible data types each expression/literal/IL instruction/etc. may take down to a single data type 
       
   152              Implemented in -> stage3/narrow_candidate_datatypes_c
       
   153              This will anotate the abstract syntax tree 
       
   154              (Every object of in the abstract syntax tree that may have a data type, will have the variable 'datatype' correctly filled in.
       
   155               Additionally, objects in the abstract syntax tree that represen function invocations will have the variables 
       
   156               'called_function_declaration' and 'extensible_param_count' correctly filled in.
       
   157               Additionally, objects in the abstract syntax tree that represen function block (FB) invocations will have the variable
       
   158               'called_fb_declaration' correctly filled in.)
       
   159      Pass 2: Prints error messages in the event of the IEC 61131-3 source code being analysed contains semantic data type incompatibility errors.
       
   160              Implemented in -> stage3/print_datatype_errors_c
       
   161 
       
   162   
       
   163 Stage 4
       
   164 -------
       
   165   Has 2 possible implementations.
       
   166   
       
   167   iec2c  :  Generates C source code in a single pass (stage4/generate_c).
       
   168   iec2iec:  Generates IEC61131 source code in a single pass (stage4/generate_iec).
       
   169 
       
   170 
       
   171 
       
   172 
       
   173 
       
   174 
       
   175 ****************************************************************
       
   176 ****************************************************************
       
   177 ****************************************************************
       
   178 *********                                              *********
       
   179 *********                                              *********
       
   180 *********               N O T E S                      *********
       
   181 *********                                              *********
       
   182 *********                                              *********
       
   183 ****************************************************************
       
   184 ****************************************************************
       
   185 ****************************************************************
       
   186 
       
   187 
       
   188 
       
   189 
    48 
   190 
    49 
   191 
    50  NOTE 1
   192  NOTE 1
    51  ======
   193  ======
    52  Note that stage 2 passes data back to stage 1. This is only
   194  Note that stage 2 passes data back to stage 1. This is only
   386 
   528 
   387 
   529 
   388 
   530 
   389 **************************************************************************
   531 **************************************************************************
   390 
   532 
   391   Copyright (C) 2003-2011  Mario de Sousa (msousa@fe.up.pt)
   533   Copyright (C) 2003-2012  Mario de Sousa (msousa@fe.up.pt)