Arcom MERLIN (ROM-DOS/Sockets) Manual de usuario

CONTROL SYSTEMS

J640 2192-10850-000-000

Page 1

MERLIN

Embedded Industrial

Internet Appliance

Library Technical Manual

Product Information

Full information about other Arcom products is available by contacting our Website at:

www.arcomcontrols.com

Useful Contact Information

Customer Support Europe Customer Support US

Tel: +44 (0)1223 412 428

Fax: +44 (0)1223 403 409

E-mail:suppor[email protected]

Tel: 816 941 7025

Fax: 816 941 7807

E-mail: support@arcomcontrols.com

Sales offices Sales hotlines

United Kingdom:

Arcom Control Systems Ltd

Clifton Road

Cambridge CB1 7EA, UK

Tel: 01223 411 200

Fax: 01223 410 457

E-mail:

[email protected]

United States:

Arcom Control Systems Inc

13510 South Oak Street

Kansas City MO 64145 USA

Tel: 816 941 7025

Fax: 816 941 7807

E-mail:

[email protected]

Belgium:

Groen Nummer:

Tel: 0800 7 3192

Fax: 0800 7 3191

France:

Numero Vert

Tel: 0800 90 84 06

Fax: 0800 90 84 12

Germany:

Kostenlose Infoline:

Tel: 08001 824 511

Fax:08001 824 512

Netherlands:

Gratis Nummer:

Tel: 0800 0221136

Fax: 0800 0221148

Italy:

Numero Verde:

Tel: 0800 790841

Fax: 0800 780841

Whilst Arcom’s sales team is always available to assist you in making your decision, the final

choice of boards or systems is solely and wholly the responsibility of the buyer. Arcom’s entire

liability in respect of the boards or systems is as set out in Arcom’s standard terms and

conditions of sale.

If you intend to write your own low level software, you can start with the source code on the

disk, which is supplied. This is example code only to illustrate use on Arcom’s products. It has

not been commercially tested. No warranty is made in respect of this code and Arcom shall

incur no liability whatsoever or howsoever arising from any use made of the code.

All trademarks recognised.

Arcom Control Systems Ltd

operate a company-wide quality

management system which has

been certified by the British

Standards Institution (BSI) as

compliant with ISO9001:1994

CONTROL SYSTEMS

J640 2192-10850-000-000

Page 2

Contents

Contents........................................................................................................................................2

Revision History............................................................................................................................3

Preface...........................................................................................................................................3

Software Library............................................................................................................................4

TSR (“Terminate and Stay Resident”) Support.............................................................................4

SSI (“Server Side Include”) Support.............................................................................................4

CGI (“Common Gateway Interface”) Support...............................................................................4

Data Types.....................................................................................................................................5

Logic............................................................................................................................................5

Include Files.................................................................................................................................5

TSR (“Terminate and Stay Resident”) Support...........................................................................6

Issues Pertaining to Stack Size....................................................................................................7

Coreleft() Function.......................................................................................................................8

SMALL Model Executable Example.............................................................................................9

Choice of wSPTop Parameter (when loading a TSR)...................................................................9

Choice of wSPTop Parameter (when registering CGI handler or SSI file) ..................................10

TSR Example.............................................................................................................................11

SSI (“Server Side Includes”) Support........................................................................................12

An Example SSI Implementation................................................................................................15

Dynamic SSI Variable Update....................................................................................................17

CGI (“Common Gateway Interface”) Support ...........................................................................18

Common Gateway Interface Demonstration Applications...........................................................28

Stack Overflow Example............................................................................................................29

Embedded LAN Connections.....................................................................................................30

TCP/IP Servers ............................................................................................................................30

FTP............................................................................................................................................30

HTTP.........................................................................................................................................30

NETBIOS/SMB Support...............................................................................................................30

Configuring the MERLIN to access a remote Windows 9x drive over Ethernet...........................30

NETBIOS / SMB Troubleshooter................................................................................................31

Connecting the MERLIN to a Modem.........................................................................................31

Configuring the MERLIN for Modem Operation..........................................................................31

Host Configuration.....................................................................................................................32

Connecting to an NT RAS server............................................................................................32

Connecting to a Windows 9x system......................................................................................33

Modem Connectivity Troubleshooter ......................................................................................35

Direct RS232 Cable Connection.................................................................................................35

MERLIN Configuration...............................................................................................................35

Host Configuration.....................................................................................................................36

Connection to a Windows NT system.....................................................................................36

Connecting from a Windows 9x system..................................................................................37

Direct Cable Connectivity Troubleshooter...............................................................................37

Glossary ......................................................................................................................................38

CONTROL SYSTEMS

J640 2192-10850-000-000

Page 3

Revision History

Manual Date Comments

Issue A

Issue B

Issue C

080201

150301

260601

First release of manual

[ECO 2957] Embedded LAN Connections section added

[ECO 2985] Changes to sections discussing stack sizes

Preface

The Arcom MERLIN (ROM-DOS/Sockets) Development Kit enables you to build full Ethernet and

PSTN dial-up network support (modem required) into your target systems.

This includes:

• TCP/IP API with TCP, UDP and ICMP

• Support for BOOTP, DHCP, or static I.P. addressing

• FTP and HTTP servers and clients with extension API’s.

• CGI and SSI extensions to the HTTP server and API’s.

• NETBIOS, SMB support (drive redirection to Windows shares)

• SMTP and POP3 support for sending and receiving e-mails

This manual is in two parts. The first part details the MERLIN EIIA software library functions and

support. The second part explains how to make various network connections between the

MERLIN and other networks via the Ethernet or the COM3 serial port (directly to another PC or via

a modem).

CONTROL SYSTEMS

J640 2192-10850-000-000

Page 4

Software Library

The MERLIN EIIA software library enhances and extends the Datalight Sockets TCP/IP stack.

The library is supplied as a set of binaries pre-built for use with the Borland C++ 4.52 compiler. A

number of examples are provided which demonstrate use of the library functionalities. If Borland

C++ 4.52 is required, a copy may be obtained from Arcom Control Systems.

At this time the library comprises the following components:

TSR (“Terminate and Stay Resident”) Support

Allows loading of a program in the background. The program code and data will remain in memory,

until unloaded. This facilitates use of ‘callbacks’ (see later)

SSI (“Server Side Include”) Support

Allows creation of HTML template files. These files may contain variables, defined using a certain

HTML tag. When a client requests the template file it is parsed and the variable is replaced with an

application definable string. This replacement string may be defined or redefined by the application

at any time.

This allows dynamic content to be generated simply and without the requirement to modify HTML

source files.

CGI (“Common Gateway Interface”) Support

Allows the execution of user application code when specified URL requests are received from

clients. Additionally supports the parsing of data received from these clients. Returned data may be

in the form of dynamic HTML or other depending on application requirements.

CONTROL SYSTEMS

J640 2192-10850-000-000

Page 5

Data Types

The .\include directory contains the ARTYPES.H include file. This include file defines a

number of Arcom standard data types

#define UCHAR unsigned char 8-bit

#define SCHAR signed char 8-bit

#define BYTE unsigned char 8-bit

#define UINT16 unsigned int 16-bit

#define SINT16 signed int 16-bit

#define WORD unsigned int 16-bit

#define UINT32 unsigned long 32-bit

#define SINT32 signed long 32-bit

#define ULONG unsigned long 32-bit

#define FLAG unsigned char 8-bit (1/0)

Logic

A number of logical definitions are also made here:

#define TRUE 1

#define FALSE 0

#define SUCCESS 0

#define ERR_HW -1

#define ERR_HTTPD -2

#define ERR_FILE -10

#define ERR_PARAM -20

#define ERR_UNKNOWN -2

#define ERR_NORXDAT -3

#define ERR_NOKEY ERR_NORXDAT

Include Files

The .\include directory contains the ARAPI.H include file. This include file declares the

publicised API to the Arcom E.I.I.A. library.

The demonstration board API may be found in the ARDEMO.H include file.

CONTROL SYSTEMS

J640 2192-10850-000-000

Page 6

TSR (“Terminate and Stay Resident”) Support

Allows loading of a program in the background. The program code and data will remain in

memory, until unloaded. This facilitates use of ‘callbacks’ (see later)

Function FLAG fArFindTSR( UCHAR *sID )

Description Check if a program corresponding to string sID is installed as a TSR

Parameters UCHAR *sID

If NULL then use this program’s ID

(i.e. the executable filename without the .EXE)

Returns TRUE - TSR found

FALSE- TSR not found

Notes None

Function FLAG fArLoadTSR( SINT16 wSPTop )

Description Install the currently loaded executable program as a TSR.

Parameters SINT16 wSPTop

Top of stack for any call-backs. If (wSPTop == 0) then the default

behaviour is to use the current stack pointer plus 50 bytes, which is

likely to result in approximately 64KBytes of memory being reserved

for the data, heap and stack of the TSR if the TSR was compiled

using the small memory model (with default heap and stack sizes).

For efficient memory allocation when loading TSR functions, set

wSPTop to equal the maximum estimated stack (+ heap + allocated

data) size required by the TSR (+ a small safety margin).

Returns This function DOES NOT RETURN if it works as the program has, by

definition, finished execution but remains in memory.

FALSE- TSR Error Installing TSR

Notes The program name (i.e. the filename without the .EXE extension) is

used as the TSR name. Any files open at the time the call is made

remain open.

For details on the correct use of wSPTOP see “Issues Pertaining to

Stack Size” at the end of this sub-section.

TSR code should be < 64Kb in size and should be compiled in

SMALL model ideally. The entire executable program remains within

memory. There is no concept of a transient loader component being

discarded

CONTROL SYSTEMS

J640 2192-10850-000-000

Page 7

Function FLAG *fArUnloadTSR( UCHAR *sID )

Description Uninstall an installed TSR program

Parameters UCHAR *sID

If non-NULL then unload the TSR corresponding to the sID string

which is in memory. Alternatively unload the TSR in memory with a

name corresponding to the program name of this executable (i.e.

without the .EXE extension)

Returns TRUE - TSR Uninstalled

FALSE - Error Uninstalling TSR

Notes Anything registered within the TSR will not be unregistered

This is an extremely important point – if a TSR registers against a

URL then callbacks will be generated into that body of code. If the

TSR is unloaded from memory without unregistering from the URL

then callbacks will continue to be made into the original code area

which will, in all probability, cause a system failure. As such it is

recommended that the TSR unloading facility should be used only in

a development environment.

Issues Pertaining to Stack Size

DOS applications may be compiled and linked in a number of different “memory models”. A

memory model defines a set of pointer constraints for compiled code.

e.g.

An application compiled in TINY model must have a total size of less than 64Kb

(CODE size + DATA size + STACK size < 64Kb)

An application compiled in SMALL model must have a total code size of less than 64Kb. The size

of the data combined with the stack must be less than 64Kb also.

(CODE size < 64Kb, [DATA + STACK] < 64Kb)

There are similar constraints for the MEDIUM, COMPACT, LARGE and HUGE models. For further

details please refer to your compiler reference manual.

If we consider the memory map of an executable in isolation it appears something like the

following:

CONTROL SYSTEMS

J640 2192-10850-000-000

Page 8

TOP OF AVAILABLE APPLICATION MEMORY (TOP OF STACK)

Top of stack

Bottom of stack

The stack expands downwards as the

running program makes calls to functions

and/or creates ‘local’ variables.

Function calls cause parameters and a

return address to be placed on the stack.

Local variables are also placed on the

stack.

The stack contracts as called functions

make returns, and as this causes local

variables to be discarded.

Free space

The stack expands into this free space

from above. The heap (also known as

the allocated data) expands into this free

space from below.

If we run out of free space then our stack

can become corrupt and/or our data can

become corrupt. This will usually cause

a system failure

Top of allocated data

Bottom of allocated data

The allocated data contains all global

application data. Additionally, if the

application dynamically allocates near

data blocks then the top of the allocated

data area can grow upward into the free

space.

As dynamically allocated data blocks are

freed the top of the allocated data area

may contract (although this is dependent

on issues of contiguity)

Top of program code

Bottom of program code

The program code occupies a given

amount of memory and this will not

change during the lifetime of any normal

DOS executable.

BOTTOM OF APPLICATION MEMORY

As can be seen from the above, if the stack extends down too far or the allocated data increases

too much then the stack and heap areas may overlap – causing corruption and a probable system

failure.

Coreleft() Function

There is a Borland C++ function available which returns the amount of space between the heap

and the stack during program execution. See the Borland documentation for details of coreleft()

and farcoreleft() functions.

CONTROL SYSTEMS

J640 2192-10850-000-000

Page 9

SMALL Model Executable Example

For a SMALL model executable we have one area for code (the code ‘segment’) and another area

for both the data and stack (data/stack segment). The maximum size of both of these segments is

64Kb.

When the executable is loaded into memory the top of the stack (TOS - which also corresponds to

the top of this application) is set to the top of the data/stack segement.

This gives us the maximum possible space of 64Kb for data and stack. Now ordinarily this would

be the best arrangement. However, when loading TSRs we must conserve as much memory as

possible. The standard TOS results in a minimum requirement of 64Kb TSR memory allocation

which could increase to a maximum of 128Kb with the code segment.

Our stack size (as a rule of thumb) will be 4Kb or 8Kb unless we require:

• Large local (stack) data structures

• Recursive functions

• Floating Point Arithmetic

In the above cases the required stack size can be expected to increase.

Choice of wSPTop Parameter (when loading a TSR)

The above discussion illustrates that it is useful to be able to restrict the size of the stack, which

has the effect of reducing the memory requirement for a TSR.

Once a TSR has been installed using fArLoadTSR() code in that TSR will only be executed as a

result of a “callback” from either the TCP/IP stack or the HTTP server.

The HTTP server uses it’s own internal stack. When it generates a callback to a user supplied

function (see later) it switches the stack to that of the user supplied function. This new stack will be

the stack in use when the function was registered (e.g. that of the executable which was shortly to

become a TSR, or the user program that was running when the CGI handler was registered). At

the end of the callback the stack is reset to that of the HTTP server.

Given that for most TSR’s we do not require the full 64Kb segment for data and stack (in small

model) we can reduce the value of the top of the stack, which is the top of the available application

memory, when the callback is made.

If for example, a program (which has a compiled size of say 8KBytes) is loaded using

fArLoadTSR() and wSPTop is set to 0, the TSR will take up 8KBytes of memory for the program

code and allocated data PLUS approximately 64KBytes (less the program’s allocated data size) for

the heap and stack. For fArLoadTSR(), the wSPTop parameter directly specifies where the top of

the stack should begin (in bytes above the end of the program code). Thus if we know that the

stack, heap and allocated data will always take up less than 10KBytes, we could set wSPTop to

10*1024.

Our stack is now ‘lower down’ and so we have less free space. It is critical to ensure that the

stack will not grow down into the allocated data space at any time.

CONTROL SYSTEMS

J640 2192-10850-000-000

Page 10

A suggested methodology is to first use either the TDUMP program or your application .MAP file to

see how much application data your program uses.

For details on TDUMP or mapfiles see the relevant compiler reference manual.

If you use dynamic memory allocation in your application – this is not recommended for TSRs –

then you should calculate how this will increase your data area usage (heap usage). Remember to

take into account data fragmentation.

Finally, select a value of wSPTop:

wSPTop = (Total Data Usage)

+ (Worst case estimated stack usage)

+ (Safety margin)

If you find that your TSR application is exhibiting strange behaviours try increasing the size of

wSPTop.

Choice of wSPTop Parameter (when registering CGI handler or SSI file)

The wSPTop parameter in the wArSSIAddFile() and wArCGIRegister() functions is handled slightly

differently from the fArLoadTSR() function discussed above. When a TSR is loaded, it has its own

stack, used only by the TSR. However, a CGI handler for example, will use the same memory

segment for its stack as the user program that executed the wArCGIRegister() function uses for its

stack. This size of the user program stack will be dynamic and its maximum size cannot always be

exactly determined, only estimated.

The point in memory that the CGI handler will use as the top of its stack is determined at the

moment that it is registered, not at the time of a callback. Thus at the moment a handler is

registered, an estimate must be made regarding the maximum size that the user program stack

might reach before a callback is made. If wSPTop is set to 0, the default top of the handler stack is

set to 1000 bytes below the current user program stack pointer.

This 1000 byte safety margin will work in most circumstances unless the user program has large

local variable arrays or recursive functions. If a much smaller safety margin was used, there is a

danger that the callback stack will be placed over existing user program stack variables, causing

corruption of the user program’s local variables and/or other stack data. If a much larger safety

margin was used, there might be a danger of the callback stack reaching down into the user

program’s allocated memory area and corrupting that data (e.g. global variables).

To increase the safety margin to 2000 bytes, for example, wSPTop should be set to “_SP - 2000”

(where _SP is the current stack pointer). Alternatively, if it is easier to estimate the maximum size

required of the CGI handler stack (+ the user program allocated data and heap size), then wSPTop

could be set directly to that total value (+ a safety margin). Obviously the safety margin used here

must be small enough to ensure that the callback stack still begins below the stack of the user

program.

Tabla de contenidos

Otros manuales de Microcontrolador de Arcom

Arcom

Arcom ELAN-104NC Manual de instrucciones

Arcom

Arcom SBC-MediaGX Manual de instrucciones

Manuales populares de Microcontrolador de otras marcas

AMS

AMS AS7261 Demo Kit Manual de usuario

Novatek

Novatek NT6861 Manual de usuario

Espressif Systems

Espressif Systems ESP8266 SDK Guía de configuración

Nuvoton

Nuvoton ISD61S00 ChipCorder Guía

STMicrolectronics

STMicrolectronics ST7 Assembler Linker Manual de usuario

Texas Instruments

Texas Instruments Chipcon CC2420DK Manual de usuario

Lantronix

Lantronix Intrinsyc Open-Q 865XR SOM Manual de usuario

NEC

NEC 78GK0S/K 1+ Series Instrucciones de instalación y funcionamiento

Mikroe

Mikroe SEMITECH N-PLC Click Instrucciones de instalación y funcionamiento

Intel

Intel Agilex Manual de usuario

Cypress

Cypress CY4607 HX2VL Manual de usuario

DIGITAL-LOGIC

DIGITAL-LOGIC MICROSPACE Manual de usuario

Texas Instruments

Texas Instruments TMS320F2837 D Series Manual de usuario

CYPRES

CYPRES CY14NVSRAMKIT-001 Manual de usuario

Texas Instruments

Texas Instruments INA-DUAL-2AMP-EVM Manual de usuario

Espressif Systems

Espressif Systems ESP8266EX Instrucciones de funcionamiento

Abov

Abov AC33M8128L Manual de usuario

Laird

Laird BL654PA Manual de usuario