user manual st (structured text) coding guidelines

ENGINEERING TOMORROW

User Manual

ST (Structured Text) Coding Guidelines

www.powersolutions.danfoss.com

User Manual ST (Structured Text) Coding Guidelines

About this Manual

Organization and Headings To help you quickly find information in this manual, the material is divided into sections, topics, subtopics, and details, with descriptive headings set in bold type. Chapter or section titles appear at the top of every page in large bold type.

In the PDF version of this document, clicking an item underlined in blue italic type jumps you to the referenced page in the document.

Special Text Formatting Controls and indicators are set in bold black type.

Table of Contents A Table of Contents (TOC) appears on the next page. In the PDF version of this document, the TOC entries are hyperlinked.

Revision History

Revison Date Comment Author

001 October 2013 First version VG

002 October 2013 First revision WL

003 January 2014 Updated to use Danfoss template, input from SDT added. TO

004 (AA) January 2014 SDT review input added: Place all PLUS+1 specific guidelines in a separate chapter

TO

©2014 Danfoss Power Solutions (US) Company. All rights reserved.

All trademarks in this material are properties of their respective owners.

PLUS+1, GUIDE, and Sauer-Danfoss are trademarks of Danfoss Power Solutions (US) Company. The Danfoss, PLUS+1 GUIDE, PLUS+1 Compliant, and Sauer-Danfoss logotypes are trademarks of Danfoss Power Solutions (US) Company.

2 L1415499 · AA · December 2014

User Manual Structured Text (ST) Coding Guidelines

Contents

Introduction ........................................................................................................................................................... 5 About this Document ................................................................................................................................ 5

Source Files ............................................................................................................................................................ 6 File Naming .................................................................................................................................................... 6

Naming Conventions ......................................................................................................................................... 7 Reserved Words ........................................................................................................................................... 7 Variable Naming .......................................................................................................................................... 7

White Spaces ......................................................................................................................................................... 8 New Lines ....................................................................................................................................................... 9 Indentation .................................................................................................................................................. 12 Line Length .................................................................................................................................................. 12

Comments ............................................................................................................................................................ 13

Data Type Declarations ................................................................................................................................... 14 Derived Type Declaration ....................................................................................................................... 14 Structure Declaration ............................................................................................................................... 14 Enumerated Type Declaration.............................................................................................................. 14

Function Declarations ...................................................................................................................................... 15 Variable Declaration ................................................................................................................................. 15 Statements ................................................................................................................................................... 15 Expressions .................................................................................................................................................. 16

Function Block Declarations .......................................................................................................................... 17

Code Reuse ........................................................................................................................................................... 18 Standard Defined Functions and Function Blocks ....................................................................... 18 User-Defined Functions and Function Blocks ................................................................................ 18 International Code Reuse Considerations ....................................................................................... 18

Safety and Real-Time Concerns in an Embedded Environment...................................................... 19 Error Codes ................................................................................................................................................... 19 Recursion and Stack ................................................................................................................................. 19 Loops .............................................................................................................................................................. 19 Floating Point Data Types ...................................................................................................................... 19

L1415499 · Rev AA · December 2014 3


Contents

PLUS+1 GUIDE Specific Guidelines .............................................................................................................20 Tool Specific Notes ....................................................................................................................................20 Standard Defined Functions and Function Blocks .......................................................................20 User-Defined Functions and Function Blocks ................................................................................20 Error Codes ...................................................................................................................................................20 Loops ..............................................................................................................................................................20 Floating Point Data Types ......................................................................................................................20 Pointers and Other Extensions to the Standard ............................................................................20

4 L1415499 · Rev AA · December 2014


Introduction

About this Document This document contains recommended coding guidelines for Structured Text (ST) code in general, and also in the context of the PLUS+1 GUIDE tool (last chapter only).



Source Files

File Naming File names should start with a capital letter.

If a file name consists of several words then each word should start with a capital letter (camel case).

Spaces should not be used. Camel case style or underscore style (separating words by the symbol ‘_’) should be used instead.

Naming should be consistent using either camel case or underscore style.

not

Main.xml

EngineControl.xml

Sensor_Driver.xml

Generic_Sensor_Driver.xml Generic_SensorDriver.xml



Naming Conventions

Names should be speaking, i.e., they should designate the semantics of the named construct.

Abbreviations are not recommended.

Names should be in upper case for the following constructs:

1. Global variable declarations.

2. Data type declarations.

3. Functions.

4. Function blocks.

Reserved Words Reserved words should be upper case.

Variable Naming Variable names should have consistent capitalization pattern (either all starting with a capital letter or none).

not

Boolean variable names should not be negated.

not

TYPE MODE : BOOL; END_TYPE

Balance : INT; Id : INT;

balance : INT; Id : INT;

IsError : BOOL; IsNotError : BOOL;



White Spaces

Space should be used before and after binary operator and NOT.

Space should be used after ‘,’.

Spaces should be used before and after ‘:’.

Spaces should be used before and after ‘:=’.

White spaces should not be used between unary operator and operand (except NOT).

White spaces should not be used before ‘;’.

White spaces should not be used between function/function block name and its open parenthesis.

Ok := NOT IsError; S := -1 + W * H;

S := SUB(1, 2);

VAR_INPUT A1 : INT; END_VAR

S := FUNC(IN1 := 1, IN2 := 2);

(* Not correct *) S := - a;

(* Correct *) S := -a;

(* Not correct *) S := -a ;

(* Correct *) S := -a;

(* Not correct *) S := ADD (1, 2);

(* Correct *) S := ADD(1, 2);



White Spaces

White spaces should not be used before ‘,’.

White spaces should not be used before ‘[‘.

White spaces should not be used before ‘)’.

White spaces should not be used after ‘(‘.

New Lines New line should be used before each statement.

New line should be used after ‘;’.

(* Not correct *) S := ADD(1 , 2);

(* Correct *) S := ADD(1, 2);

(* Not correct *) S := ARR [1];

(* Correct *) S := ARR[1];

(* Not correct *) S := ADD(1, 2 );

(* Correct *) S := ADD(1, 2);

(* Not correct *) S := ADD( 1, 2);

(* Correct *) S := ADD(1, 2);

(* Not correct *) S := ADD(1, 2); S:= 3;

(* Correct *) S := ADD(1, 2); S := 3;



White Spaces

New line should be used before and after block comment.

New line should be used before block delimiter keywords (except STRUCT):

1. TYPE END_TYPE2. VAR END_VAR3. VAR_INPUT END_VAR4. VAR_IN_OUT END_VAR5. VAR_OUTPUT END_VAR6. VAR_GLOBAL END_VAR7. VAR_TEMP END_VAR8. IF END_IF9. CASE_END_CASE10. FOR END_FOR11. WHILE END_WHILE12. REPEAT END_REPEAT

TYPE POINT : STRUCT X : INT := 0; Y : INT := 0; END_STRUCT; END_TYPE

(* Not correct *) (* Room area Written by JH. *)S := H * W;

(* Correct *) (* Room area

Written by JH. *) S := H * W;

VAR A1 : INT := 100; END_VAR

10 L1415499 · Rev AA · December 2014


White Spaces

For STRUCT type declarations the following applies:

1. There should be a new line after TYPE

2. STRUCT should be written on the same line as the name of the type

3. There should be a new line after STRUCT

4. There should be a new line before END_STRUCT

New line should not be used:

1. Before assignment operator ‘:=’

2. Before function name (in declaration)

3. Before function block name

4. Between VAR/VAR_INPUT/VAR_OUTPUT/VAR_IN_OUT andCONSTANT/RETAIN/NON_RETAIN

5. Between IF/CASE/WHILE/UNTIL and its expression

6. Between FOR and variable name

TYPE POINT : STRUCT X : INT := 0;

Y : INT := 0; END_STRUCT; END_TYPE

(* Not correct *) VAR CONSTANT SENSOR_ID : INT := 100; CORRECTION : INT := 100; END_VAR

(* Correct *) VAR CONSTANT SENSOR_ID : INT := 100; CORRECTION : INT := 100; END_VAR

L1415499 · Rev AA · December 2014 11


White Spaces

IndentationIndention should contain two (2) spaces.

Each new enter block delimiter keyword adds indentation level for the code inside block.

Each new exit block delimiter keyword should have same indentation as its enter block delimiter keyword.

Line Length Line length should not exceed 130 characters.

VAR BALANCE : INT; END_VAR

12 L1415499 · Rev AA · December 2014


Comments

Use comments to document code.

Block comments should be placed before commented code.

Single line comment should be indented to the same level as the following code.

Trailing comment should comment the code on the same line.

L1415499 · Rev AA · December 2014 13


Data Type Declarations

Use data type declarations to define sets of values.

Use data type declarations if the declared type is used at least twice.

Name of a type declaration should be placed on a new line and indentation.

It is recommended to initialize type on the same line as its name.

Derived Type Declaration Use derived type declarations to define sets of values that are conceptually separated from other sets of values with the same encoding (base type).

It is not recommended to declare more than 1 type per line.

Structure Declaration Use structure type declarations to define sets of structured values that have conceptually cohesive elements variables.

Element variables should be initialized if value is known.

It is recommended to declare no more than 1 variable per line.

It is recommended to initialize variable on the same line as its name.

Enumerated Type Declaration Use enumerated type declarations to define sets of simple values, i.e., no operations on the set elements other than test of (non-)equivalence.

It is recommended to define enumeration values on the same line as a type name.

TYPE BALANCE : INT := 7; END_TYPE

TYPE POINT : STRUCT X : INT := 0; Y : INT := 0; END_STRUCT; END_TYPE

TYPE ENGINE_MODE : (LOW, HIGH) := LOW; END_TYPE

14 L1415499 · Rev AA · December 2014


Function Declarations

Use functions to abstract computations that are used at least twice.

Function return type should be on the same line as function name.

Variable Declaration See Structure Declaration on page 14

Variables which are not used shouldn’t be declared.

Within each category, it is recommended that variables are ordered, either by their types, alphabetically, in the order of their usage in the code, or in some other consistent way.

Statements Functions should have assigned return value.

Output variables should be assigned.

Empty statement lists are not recommended.

A line should contain no more than one statement.

A single blank line should be used to separate code into logically cohesive parts.

A function size of less than 300 lines of code is recommended (otherwise revise the functional abstraction).

It is recommended to use less than 6 indentation levels (otherwise revise the functional abstraction).

Explicit type conversion is recommended.

THEN should be on the same line as the IF/ELSIF keywords; the statements in the THEN and ELSE blocks should be indented one level.

L1415499 · Rev AA · December 2014 15


Function Declarations

Expressions The following expressions should be simple, no complex expressions or function calls are recommended (otherwise use temporary variables):

1. Call parameter

2. IF expression

3. CASE expression

4. FOR variable assignment expression

5. FOR final value expression

6. WHILE expression

7. REPEAT expression

Constant loop and conditional expressions (i.e. always returning TRUE or always returning FALSE) are not recommended.

(* Not correct *) IF (A OR B) and (NOT C) XOR (D >= 15) THEN Result := 0; ELSE Result := 1; END_IF;

(* Correct *) Z := (A OR B) and (NOT C) XOR (D >= 15); IF Z THEN Result := 0; ELSE Result := 1; END_IF;

16 L1415499 · Rev AA · December 2014


Function Block Declarations

See Function Declarations on page 15.

L1415499 · Rev AA · December 2014 17


Code Reuse

It is recommended to reuse code when possible.

Standard Defined Functions and Function Blocks The functions and function blocks defined by the standard should be used when applicable.

User-Defined Functions and Function Blocks For reusability, it is recommended that common utility functions are collected into separate files by type of functionality.

Such common utility files can then be reused in multiple projects.

International Code Reuse Considerations To enable code reuse within international coding teams, or if the code is or will be used internationally, the following recommendations apply:

• Names of functions and variables should be in English.

• Code comments should be in English.

18 L1415499 · Rev AA · December 2014


Safety and Real-Time Concerns in an Embedded Environment

This section describes coding guidelines that applies to real time control systems.

Error Codes When calling a function that returns error and/or status parameters, those parameter should be examined after the call has returned.

Recursion and Stack Avoid nesting calls too deeply, and make sure that your tests cover the worst-case nesting depth.

Avoid recursion.

Loops Avoid using potential endless loop constructs like while and repeat until. Instead prefer use of the for-loop with a fixed number of iterations.

Floating Point Data Types Floating point calculations are slower than integer calculations and should be avoided.

L1415499 · Rev AA · December 2014 19


PLUS+1® GUIDE Specific Guidelines

Tool Specific Notes Files will have an XML extension and be stored in PLCopenXML format by the tool. File types such as *.st and *.exp are supported, but only as import sources to *.xml format. As a consequence, this document will not describe specific guidelines for these file formats.

PLUS+1 GUIDE supports functions and function blocks to be called from graphical code only, either directly or indirectly from other program organization units. Therefore this document will not describe specific guidelines for constructs such as programs, configurations, tasks and resources.

For compatibility with other tools, PLUS+1 GUIDE supports a number of language extensions that are technically outside the language definition. Using these extensions will let the code compile, but with warnings.

Standard Defined Functions and Function Blocks In PLUS+1 GUIDE, the standard functions and function blocks are available from the “Code Blocks” trees on the right-hand side of the editor.

User-Defined Functions and Function Blocks User defined functions and function blocks are available from the “Code Blocks” trees in PLUS+1 GUIDE.

Error Codes PLUS+1 GUIDE defines a number of runtime error codes that can be obtained by calling the built-in function GET_CURRENT_RUNTIME_ERROR_FLAGS().

This should be done after calling functionality that might lead to any of the error flags to be set.

These runtime error codes are described in the GUIDE manual.

Loops PLUS+1 GUIDE generated code will terminate while- and repeat until-loops that take too long to execute during runtime.

(Use GET_CURRENT_RUNTIME_ERROR_FLAGS() after such loops to find out if this has happened.)

Floating Point Data Types Note that some PLUS+1 hardware units, such as MCxx-xx, do not fully support the LREAL type.

Pointers and Other Extensions to the Standard Pointers and other extensions to the standard are included in PLUS+1 GUIDE only for compatibility with other tools, and should be avoided in new code.

In old imported code it is recommended that such code is rewritten.

20 L1415499 · Rev AA · December 2014

User Manual ST (Structured Text) Coding Guidelines

(This page is intentionally blank.)

Products we offer:

• Bent Axis Motors

• Closed Circuit Axial Piston

Pumps and Motors

• Displays

• Electrohydraulic Power

Steering

• Electrohydraulics

• Hydraulic Power Steering

• Integrated Systems

• Joysticks and Control

Handles

• Microcontrollers and Software

• Open Circuit Axial Piston Pumps

• Orbital Motors

• PLUS+1™ GUIDE

• Proportional Valves

• Sensors

Local address:

Danfoss Power Solutions US Company 2800 East 13th Street Ames, IA 50010, USA Phone: +1 515 239-6000

Danfoss Power Solutions GmbH & Co. OHG Krokamp 35 D-24539 Neumünster, Germany Phone: +49 4321 871 0

Danfoss Power Solutions ApS Nordborgvej 81 DK-6430 Nordborg, Denmark Phone: +45 7488 4444

Danfoss Ltd. Power Solutions (Shanghai) Co. Ltd. Building #22, No.1000 Jin Hai Rd Jin Qiao, Pudong New District Shanghai, China 201206 Phone: +86 21 3418 5200

Comatrol www.comatrol.com

Schwarzmüller-Inverter www.schwarzmueller-inverter.com

Turolla www.turollaocg.com

Hydro-Gear www.hydro-gear.com

Sauer-Danfoss-Daikin www.daikin-sauer-danfoss.com

Danfoss Power Solutions is a global manufacturer and supplier of high-quality hydraulic and electronic components. We specialize in providing state-of-the-art technology and solutions that excel in the harsh operating conditions of the mobile off-highway market. Building on our extensive applications expertise, we work closely with our customers to ensure exceptional performance for a broad range of off-highway vehicles.

We help OEMs around the world speed up system development, reduce costs and bring vehicles to market faster. Danfoss—Your Strongest Partner in Mobile Hydraulics.

Go to www.powersolutions.danfoss.com for further product information.

Wherever off-highway vehicles are at work, so is Danfoss.

We offer expert worldwide support for our customers, ensuring the best possible solutions for outstanding performance. And with an extensive network of Global Service Partners, we also provide comprehensive global service for all of our components.

Please contact the Danfoss Power Solution representative nearest you.

Danfoss can accept no responsibility for possible errors in catalogues, brochures and other printed material. Danfoss reserves the right to alter its products without notice. This also applies to products already on order provided that such alterations can be made without subsequential changes being necessary in specifcations already agreed. All trademarks in this material are property of the respective companies. Danfoss and the Danfoss logotype are trademarks of Danfoss Power Solutions (US) Company. All rights reserved.

L1415499 · Rev AA · December 2014 www.danfoss.com ©2014 Danfoss Power Solutions (US) Company

user manual st (structured text) coding guidelines

Documents