SoftPlc7 HLL-Interface

SUMMARY

This document describes how to create a HLL-Function

CONTENTS

  1. Introduction
  2. Procedure
  3. Parameter Passing (FC and SFC)
  4. Parameter Passing (FB and SFB)
  5. Data Format

Introduction

The program modules of a common Step7 program usually consist of a list of elementary assembler-code. After converting a Step7 project for use on SoftPLC7 it can be loaded and executed as known from a HardPLC7.
Beside the individual program modules there are lots of functionalities the system offers.
These functionalities are collected in so called SFCs (System Functions) and SFBs (System Function Blocks).
Any individual Step7 program may revert to those functionalities just by calling the corresponding SFCs and SFBs.
For SoftPLC7 the most common system functionalities – SFCs and SFBs – are rebuild in HLL-Functions.
For SFBs that are not available yet, the HLL-Interface offers a comfortable solution. The interface offers access to internal operand areas, DBs, flags etc. also presents classes for trans-sectoral pointers and ANY-Pointers.

Procedure

The SoftPLC7 programs as well as the HLL-Interface are written in C++. To rebuild an SFB you first have to create a DLL in C++. To use the HLL-Interface the Header-File ‘HllHandler.h’ and the library ‘SoftPlcKernel.lib’ must be integrated. The project ‘SoftPlc7SampleHll’ may be used as a body for such a DLL, it shows by means of simple examples how to rebuild an FC und an FB.


An HLL-Function must always have the following signature:

extern”C” void__declspec(dllexport) FktName(HllHandler* pHandler);

The HllHandler class represents the real interface since it handles any data exchange to the SoftPLC; not only it provides many functions itself, but also is used as a parameter by functions of other classes.

Parameter Passing (FC and SFC)

Prior of calling the (S)FC in the local memory area space is allocated for all parameters. IN-Parameters are written to that area, then the module is called and afterwards the OUT-Parameters are read from the area. The cross reference to the memory area is realised by a pointer list P#VLx.0 within the code of the called function.

A pointer to that list is available via the function: 

void*  HllHandler::GetFCParams()
The provided pointer must now casted onto an HllTR32*: 
HllPTR32* pParams = (HllPTR32*) pHandler->GetFCParams();
Afterwards any single parameter is accessible for read and write:
WORD   wParameter1 = pParams[0].GetSourceWORD(); //presuming the first parameter is type WORD
BOOL   bParameter2 = pParams[1].GetSourceBit(); //presuming the second parameter is type BOOL
pParams[0].SetSourceWORD(0x1234); // it is written to memory in that order: 0x12,0x34
pParams[1].SetSourceBit(true)

Parameter Passing (FB and SFB)

Function blocks, different to functions, do not have a pointer list to the local memory area, but they will be called via a so-called Instance-Data-Block to exchange data.


Example: 
In the kernel the macro command 
      CALL   FB 1, DB 10
is disassembled to
      AUF    DI 10;  (selects DB10 as Instance-DB)
      UC     FB 1 ;  (calling FB1, DB10 is used as parameter list there)

The pointer to the start address of the instance-DB is available within the HLL-Function by the command:

void*  HllHandler::GetFBParams();

The Parameters located at that window address are in ascending order.
If there are 3 parameters of the type WORD, DWORD and ANY (in that order), byte 0 and 1 will hold parameter 1, byte 2 to 5 will hold parameter 2 and byte 6 to 15 will hold parameter 3. If the type within the parameter list is changed (1=BYTE, 2=WORD) it is rounded up to the next even address.
Several consecutive BOOL-Parameter are organized in the same byte.
It is advisable to cast the provided pointer for a class, which manipulates the values within the instance DB via access function.
In the project SoftPLC7SampleHll it is demonstrated by the function SampleFunctionFB.

Data Format

The SoftPLC7 stores datatyps broader than 8 bits in the ‘little-endian-format’ that is, higher-ranking bytes are stored at lower addresses.
So the DWORD-Parameter 0x1234ABCD is stored ascending as 0x12, 0x34, 0xAB, 0xDC.
Casting the Windows start address of a (DWORD*) would, after dereferencing, return the value 0xCDAB3412. To simplify programming global functions for read and write WORD-, DWORD- and FLOAD-Values are provided.