1

     2

     3

     4

  MATIEC - IEC 61131-3 compiler

     5

     6

     7

  The following compiler has been based on the

     8

  FINAL DRAFT - IEC 61131-3, 2nd Ed. (2001-12-10)

     9

    10

    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

    69

    70

    71

    72

****************************************************************

    73

****************************************************************

    74

****************************************************************

    75

*********                                              *********

    76

*********                                              *********

    77

*********   O V E R A L L    A R C H I T E C T U R E   *********

    78

*********                                              *********

    79

*********                                              *********

    80

****************************************************************

    81

****************************************************************

    82

****************************************************************

    83

    84

 The compiler works in 4(+1) stages:

    85

 ==================================

    86

 Stage 1    - Lexical analyser       - implemented with flex (stage1_2/iec_flex.ll)

    87

 Stage 2    - Syntax parser          - implemented with bison (stage1_2/iec_bison.yy)

    88

 Stage pre3 - Populate symbol tables - Symbol tables that will ease searching for symbols in the abstract symbol tree.

    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

    94

    95

    96

 Data structures passed between stages, in global variables:

    97

 ==========================================================

    98

   1->2   : tokens (int), and token values (char *) (defined in stage1_2/stage1_2_priv.hh)

    99

   2->1   : symbol tables (implemented in util/symtable.[hh|cc], and defined in stage1_2/stage1_2_priv.hh)

   100

   2->3   : abstract syntax tree (tree of C++ objects, whose classes are defined in absyntax/absyntax.hh)

   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

   107

   108

   109

 The compiler works in several passes:

   110

 ====================================

   111

   112

Stage 1 and Stage 2

   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

   190

   191

   192

 NOTE 1

   193

 ======

   194

 Note that stage 2 passes data back to stage 1. This is only

   195

possible because both stages are executed in the same pass.

   196

   197

   198

   199

 NOTE 2

   200

 ======

   201

 It would be nice to get this parser integrated into the gcc

   202

group of compilers. We would then be able to compile our st/il

   203

programs directly into executable binaries, for all the processor

   204

architectures gcc currently supports.

   205

 The gcc compilers are divided into a frontend and backend. The

   206

data structure between these two stages is called the syntax

   207

tree. In essence, we would need to create a new frontend that

   208

would parse the st/il program and build the syntax tree.

   209

Unfortunately the gcc syntax tree is not very well documented,

   210

and doing semantic checking on this tree would probably be a

   211

nightmare.

   212

 We therefore chose to follow the same route as the gnat (ada 95)

   213

and cobol compilers, i.e. generate our own abstract syntax tree,

   214

do semantic checking on our tree, do whatever optimisation

   215

we can at this level on our own tree, and only then build

   216

the gcc syntax tree from our abstract syntax tree.

   217

 All this may still be integrated with the gcc backend to generate

   218

a new gnu compiler for the st and il programming languages.

   219

Since generating the gcc syntax tree will probably envolve some

   220

trial and error effort due to the sparseness of documentation,

   221

we chose to start off by coding a C++ code generator for

   222

our stage 4. We may later implement a gcc syntax tree generator

   223

as an alternative stage 4 process, and then integrate it with

   224

the gcc toplevel.c file (command line parsing, etc...).

   225

   226

   227

   228

****************************************************************

   229

****************************************************************

   230

****************************************************************

   231

*********                                              *********

   232

*********                                              *********

   233

*********               S T A G E      1               *********

   234

*********                                              *********

   235

*********                                              *********

   236

****************************************************************

   237

****************************************************************

   238

****************************************************************

   239

   240

   241

   242

Issue 1

   243

=======

   244

   245

 The syntax defines the common_character_representation as:

   246

<any printable character except '$', '"' or "'"> | <escape sequences>

   247

   248

 Flex includes the function print_char() that defines

   249

all printable characters portably (i.e. whatever character

   250

encoding is currently being used , ASCII, EBCDIC, etc...)

   251

Unfortunately, we cannot generate the definition of

   252

common_character_representation portably, since flex

   253

does not allow definition of sets by subtracting

   254

elements in one set from another set (Note how

   255

common_character_representation could be defined by

   256

subtracting '$' '"' and "'" from print_char() ).

   257

This means we must build up the defintion of

   258

common_character_representation using only set addition,

   259

which leaves us with the only choice of defining the

   260

characters non-portably...

   261

   262

 In short, the definition we use for common_character_representation

   263

only works for ASCII character encoding!

   264

   265

   266

   267

   268

Issue 2

   269

=======

   270

   271

We extend the IEC 61131-3 standard syntax to allow inclusion of 

   272

other files. The accepted syntax is:

   273

   274

   {#include "<filename>" }

   275

   276

We use a pragma directive for this (allowed by the standard itself),

   277

 since it is an extension of the standard. In principle, this would 

   278

be ignored by other standard complient compilers!

   279

   280

   281

   282

****************************************************************

   283

****************************************************************

   284

****************************************************************

   285

*********                                              *********

   286

*********                                              *********

   287

*********               S T A G E      2               *********

   288

*********                                              *********

   289

*********                                              *********

   290

****************************************************************

   291

****************************************************************

   292

****************************************************************

   293

   294

 Overall Comments

   295

 ================

   296

   297

   298

 Comment 1

   299

 ---------

   300

 We have augmented the syntax the specification defines to include

   301

restrictions defined in the semantics of the languages.

   302

   303

 This is required because the syntax cannot be parsed by a LALR(1)

   304

parser as it is presented in the specification. Many reduce/reduce

   305

and shift/reduce conflicts arise. This is mainly because the parser

   306

cannot discern how to reduce an identifier. Identifiers show up in

   307

many places in the syntax, and it is not entirely possible to

   308

figure out if the identifier is a variable_name, enumeration

   309

value, function block name, etc... only from the context in

   310

which it appears.

   311

   312

 A more detailed example of why we need symbol tables are

   313

the type definitions...  In definition of new types

   314

(section B 1.3.3) the parser needs to figure out the class of

   315

the new type being defined (enumerated, structure, array, etc...).

   316

This works well when the base classes are elementary types

   317

(or structures, enumeration, arrays, etc. thereof). It becomes

   318

confusing to the parser when the new_type is based on a previously

   319

user defined type.

   320

   321

TYPE

   322

  new_type_1 : INT := 99;

   323

  new_type_2 : new_type_1 := 100;

   324

END_TYPE

   325

   326

 When parsing new_type_1, the parser can figure out that the

   327

identifier new_type_1 is a simple_type_name, because it is

   328

based on a elementary type without structure, arrays, etc...

   329

 While parsing new_type_2, it becomes confused how to reduce

   330

the new_type_2 identifier, as it is based on the identifier

   331

new_type_1, of which it does not know the class (remember, at this

   332

stage new_type_1 is a simple identifier!).

   333

 We therefore need to keep track of the class of the user

   334

defined types as they are declared, so that the lexical analyser

   335

can tell the syntax parser what class the type belongs to. We

   336

cannot use the abstract syntax tree itself to search for the

   337

declaration of new_type_1 as we only get a handle to the root

   338

of the tree at the end of the parsing.

   339

   340

 We therefore maintain an independent and parallel table of symbols,

   341

that is filled as we come across the type delcarations in the code.

   342

Actually, we ended up also needing to store variable names in

   343

the symbol table. Since variable names come and go out of scope

   344

depending on what portion of code we are parsing, we sometimes

   345

need to remove the variable names from the symbol table.

   346

Since the ST and IL languages only have a single level of scope,

   347

I (Mario) found it easier to simply use a second symbol table for

   348

the variable names that is completely cleared when the parser

   349

reaches the end of a function (function block or program).

   350

   351

What I mean when I say that these languages have a single level

   352

of scope is that all variables used in a function (function block

   353

or program) must be declared inside that function (function block

   354

or program). Even global variables must be re-declared as EXTERN

   355

before a function may access them! This means that it is easy

   356

to simply load up the variable name symbol table when we start

   357

parsing a function (function block or program), and to clear it

   358

when we reach the end. Checking whether variables declared

   359

as EXTERN really exist inside a RESOURCE or a CONFIGURATION

   360

is left to stage 3 (semantic checking) where we can use the

   361

abstract tree itself to search for the variables (NOTE: semantic

   362

cheching at stage 3 has not yet been implemented, so we may yet

   363

end up using a symbol table too at that stage!).

   364

   365

 Due to the use of the symbol tables, and special identifier

   366

tokens depending on the type of identifier it had previously

   367

been declared in the code being parsed, the syntax was slightly

   368

changed regarding the definition of variable names, derived

   369

function names, etc... FROM for e.g.:

   370

variable_name: identifier;

   371

TO

   372

variable_name: variable_name_token;

   373

   374

 Flex first looks at the symbol tables when it finds an identifier,

   375

and returns the correct token corresponding to the identifier

   376

type in question. Only if the identifier is not currently stored

   377

in any symbol table, does flex return a simple identifier_token.

   378

   379

 This means that the declarations of variables, functions etc...

   380

were changed FROM:

   381

function_declaration: FUNCTION derived_function_name ...

   382

TO

   383

function_declaration: FUNCTION identifier ...

   384

since the initial definition of derived_function_name had been

   385

changed FROM

   386

derived_function_name: identifier;

   387

TO

   388

derived_function_name: derived_function_name_token;

   389

   390

   391

   392

   393

 Comment 2

   394

 ---------

   395

 Since the ST and IL languages share a lot of common syntax,

   396

I have decided to write a single parser to handle both languages

   397

simultaneously. This approach has the advantage that the user

   398

may mix the language used in the same file, as long as each function

   399

is written in a single lanuage.

   400

   401

 This approach also assumes that all the IL language operators are

   402

keywords, which means that it is not possible to define variables

   403

using names such as "LD", "ST", etc...

   404

Note that the spec does not consider these operators to be keywords,

   405

so it means that they should be available for variable names! On the

   406

other hand, all implementations of the ST and IL languages seems to

   407

treat them as keywords, so there is not much harm in doing the same.

   408

   409

 If it ever becomes necessary to allow variables with names of IL 

   410

operators, either the syntax will have to be augmented, or we can 

   411

brake up the parser in two: one for ST and another for IL.

   412

   413

   414

   415

/********************************/

   416

/* B 1.3.3 - Derived data types */

   417

/********************************/

   418

   419

Issue 1

   420

=======

   421

   422

According to the spec, the valid construct

   423

TYPE new_str_type : STRING := "hello!"; END_TYPE

   424

has two possible routes to type_declaration...

   425

   426

Route 1:

   427

type_declaration: single_element_type_declaration

   428

single_element_type_declaration: simple_type_declaration

   429

simple_type_declaration: identifier ':' simple_spec_init

   430

simple_spec_init: simple_specification ASSIGN constant

   431

(shift:  identifier <- 'new_str_type')

   432

simple_specification: elementary_type_name

   433

elementary_type_name: STRING

   434

(shift: elementary_type_name <- STRING)

   435

(reduce: simple_specification <- elementary_type_name)

   436

(shift: constant <- "hello!")

   437

(reduce: simple_spec_init: simple_specification ASSIGN constant)

   438

(reduce: ...)

   439

   440

   441

Route 2:

   442

type_declaration: string_type_declaration

   443

string_type_declaration: identifier ':' elementary_string_type_name string_type_declaration_size string_type_declaration_init

   444

(shift:  identifier <- 'new_str_type')

   445

elementary_string_type_name: STRING

   446

(shift: elementary_string_type_name <- STRING)

   447

(shift: string_type_declaration_size <- /* empty */)

   448

string_type_declaration_init: ASSIGN character_string

   449

(shift: character_string <- "hello!")

   450

(reduce: string_type_declaration_init <- ASSIGN character_string)

   451

(reduce: string_type_declaration <- identifier ':' elementary_string_type_name string_type_declaration_size string_type_declaration_init )

   452

(reduce: type_declaration <- string_type_declaration)

   453

   454

   455

 At first glance it seems that removing route 1 would make

   456

the most sense. Unfortunately the construct 'simple_spec_init'

   457

shows up multiple times in other rules, so changing this construct

   458

would mean changing all the rules in which it appears.

   459

I (Mario) therefore chose to remove route 2 instead. This means

   460

that the above declaration gets stored in a

   461

simple_type_declaration_c, and not in a string_type_declaration_c

   462

as would be expected!

   463

   464

   465

/***********************/

   466

/* B 1.5.1 - Functions */

   467

/***********************/

   468

   469

   470

Issue 1

   471

=======

   472

   473

 Due to reduce/reduce conflicts between identifiers

   474

being reduced to either a variable or an enumerator value,

   475

we were forced to keep a symbol table of the names

   476

of all declared variables. Variables are no longer

   477

created from simple identifier_token, but from

   478

variable_name_token.

   479

   480

 BUT, in functions the function name may be used as

   481

a variable! In order to be able to parse this correctly,

   482

the token parser (flex) must return a variable_name_token

   483

when it comes across the function name, while parsing

   484

the function itself.

   485

We do this by inserting the function name into the variable

   486

symbol table, and having flex return a variable_name_token

   487

whenever it comes across it.

   488

When we finish parsing the function the variable name

   489

symbol table is cleared of all entries, and the function

   490

name is inserted into the library element symbol table. This

   491

means that from then onwards flex will return a

   492

derived_function_name_token whenever it comes across the

   493

function name.

   494

   495

In order to insert the function name into the variable_name

   496

symbol table BEFORE the function body gets parsed, we

   497

need the parser to reduce a construct that contains the

   498

the function name. That is why we created the extra

   499

construct 'function_name_declaration', i.e. to force

   500

the parser to reduce it, before parsing the function body,

   501

and therefore get an oportunity to insert the function name

   502

into the variable name symbol table!

   503

   504

   505

/********************************/

   506

/* B 3.2.4 Iteration Statements */

   507

/********************************/

   508

   509

Issue 1

   510

=======

   511

   512

For the 'FOR' iteration loop

   513

   514

  FOR control_variable ASSIGN expression TO expression BY expression DO statement_list END_FOR

   515

   516

The spec declares the control variable in the syntax as

   517

   518

  control_variable: identifier;