IBM
Contents Index Previous Next



Connection of Host and Target


General

The following sections will detail the technical requirements and the technical implementation of the connection between host and target. The following items will be outlined:

Structure of Communications Link Software

This is the structure for the communications link software, which is - in principle - applicable for host, as well as for target site:

Figure 612 : Structure of the communications link software

The following subsections describe the current implementation and how to implement a new communications link software.

Default Implementation of Communications Link Software

Message Transfer and Presentation of Messages

State Machine and Handshake

For all the commands and messages, there is a small state machine to handle the correct transfer of information. All messages, which have the suffix _REQ (request) in their name (message tag) are to be confirmed from the target with one of the _CNF (confirmation) messages. (See the file tmcod.h, where all message tags are defined).

For messages which take parameters, there is always (no exception) a special _CNF message which carries the response parameters back to the requestor. The requestor is usually the host.

For the messages, which do not carry parameters, a positive confirmation is done via the message CMD_OKAY_CNF.

If a message cannot be recognized or processed within the target, a negative confirmation CMD_ERROR_CNF is used in all cases.

Each _REQ message must be confirmed before the next one can be sent.

Messages with an _IND (indication) suffix are mostly sent from target to host in order to indicate a specific situation. For these messages, the sender is always the originator.

Message Formats

The following subsections give a complete list of messages which can be sent to and received from the target.

Each typedef shown below is packed into a data link frame in its target representation.

That means a memcpy (destbuffer,struct,sizeof(struct)) is performed to copy a structure to/from the data link frame.

On host site, it is therefore necessary to perform message encoding and message decoding.

Formats Concerning the Cmicro Tracer

All messages belonging to the Cmicro Tracer are part of the message class XMK_MICRO_TRACER (F1h).

Formats Concerning the Cmicro Recorder

All messages belonging to the Cmicro Recorder are part of the message class XMK_MICRO_RECORDER (F2h).

Formats Concerning the Command and Debug Interface

All messages belonging to the Cmicro Commands are part of the message class XMK_MICRO_COMMAND (F0h).

Used Default Protocol

The data link part of the communications link is represented by the data link module and the coder module. The coder module ensures that each data link frame is encoded / decoded according to definitions of the default protocol.

Each frame of the Cmicro Protocol is seen from the physical layer as binary data.

Each frame consists of the following items:

The following is an example of a coded Cmicro Protocol frame for a MS DOS PC, where the message tag is coded as CMD_TSTATIC_CREATE. Note this is only an example and the real coding may be different.

Example 624 : Coding for MS-DOS PC

Message-class

Message-tag

SYNC

Message- length

-any kind of data-

Checksum

0xF1

0x06

0xAA

0x02


0x??

The functions described in The API on Target can be used to encode / decode these frames.

The Communications Link's Target Site

The Data Link Layer

General

The data link of the communications link usually handles the separately message transfer of information from host and to host.

The data link uses the services and functions of the physical layer in order to transmit and receive information.

The data link offers functionality that makes it possible to send and to receive messages via the physical layer assigned to the data link. This functionality can be used by all programs (if implemented so). Mainly it is the SDL Target Tester which uses the data link layer services in order to send and to receive messages. But the users may want to send and receive messages, too. This is possible by using the data link layer functions and by regarding the defined protocol used for each message.

The data link layer offers the following functionality:

The data link layer is represented by the following functions, which are exported by the data link (mg_dl) module.

Data Link Functions Used by SDL Target Tester

The SDL Target Tester's target library uses the following C functions of the link and buffering file mg_dl.c. The body of each C function may be rewritten according to the users needs.

xmk_DLInit

Initialization of data link

xmk_DLQuery

Polling the receiver of data link

xmk_DLRead

Reading a message from data link

xmk_DLWrite

Writing a message to data link

xmk_DLDeinit

Deinitialization of data link

These functions are fixed into the SDL Target Tester's data link layer and they handle the mapping and the access to the physical layer.

The Physical Layer

General

Any type of physical communications link can be used to connect host and target, e.g. it could be a V.24, a TCP/IP or a IEEE 488 interface or it could be any other serial or parallel interface.

The physical layer of the communications link normally handles the byte-wise transfer of messages from host to target and the other way around.

It uses the services of the underlaying hardware like interrupts, CPU registers or memory mapped I/O.

The physical layer offers functionality to the data link layer in order to make it possible to transfer any kind of information, including SDL Target Tester data and / or user data.

The physical layer offers the following functionality:

Physical Layer Functions Used by the Data Link Layer (Default)

As described above the data link layer of the SDL Target Tester's target library is shown in the files mt_cod.c and mg_dl.c. Please note that mg_dl.c is only a template with a default implementation for the connection between data link and physical layer.

Distributed with the SDL Target Tester's target library, there are several template files for the physical layer (TCP/IP and V.24 interfaces) contained in the cmicro/template/commlink directory in the installation directory. These template files are tested only for the specific hardware in the Cmicro Package test environments. An error free compilation or execution cannot be guaranteed for the user's target hardware.

There are physical layer templates for the following target hardware:

For use in the target executable, one of the modules listed above is automatically included in mg_dl.c. Which physical layer module is included depends on the compiler selected and the flags set in ml_mcf.h (e.g. XMK_USE_V24 or XMK_USE_SOCKETS).

The template module mg_dl.c works as follows:

The function xmk_DLInit initializes the buffers used for the data link and calls the initialization of the physical layer (by default this is xmk_V24Init).

xmk_DLDeinit is the counterpart of xmk_DLInit and frees the interface device. This function is normally empty in microcontroller applications but has to be used on PCs, under Microsoft Windows or UNIX.

xmk_DLWrite is called when a complete frame should be sent to the host. There are two ways the connection to the physical layer can be handled.

  1. Blocked
    If a frame is to be sent it is necessary that the previous frame has already been completely sent. If not, the data link has to wait until the previous frame is sent. See the module mg_dl.c (for the compilers KEIL_C51 and IARC51) to get an idea of this connection.
  2. Unblocked
    If the frame should be sent, it is handed over to a ring buffer. Although the previous frame has not been sent completely, SDL can execute because the data link does not have to wait.
    One exception must be mentioned: If the transmitter's ring buffer (used for V.24 communication) is full (macro XMK_MAX_SEND_ENTRIES) the data link will still have to wait here. Also the size allowed for the ring buffer's entries must be great enough (to verify this see the macro XMK_MAX_SEND_ONE_ENTRY.

xmk_DLRead will be polled with each cycle of the SDL loop xmk_RunSDL (see module mk_main.c). If the transmitter and the receiver of the physical layer are not implemented as interrupt service routines (which is strongly recommended) the transmit and receive functions have to be called here (xmk_V24Receive and xmk_V24Send for the distributed V.24 templates). In addition for the V.24 interface the XON handshake has to be called here doing xmk_V24Handshake.

As in xmk_DLWrite there are two ways the receiver buffers can be handled in xmk_DLRead. It is also possible to use a ring buffer for the receiver's side. Similar as in xmk_DLWrite it is necessary to fill the macros XMK_MAX_RECEIVE_ONE_ENTRY and XMK_MAX_RECEIVE_ENTRIES with useful values.

Steps to Implement a Communications Link

Extension to the Template Makefile

In the distribution of the Cmicro Package there are several template makefiles.

On UNIX the existing makefile templates are called makeoptions.no_tester and makeoptions.with_tester.

In Windows the existing makefile templates are called makeno_t.opt and makew_t.opt.

The intention is to give one template makefile where the SDL Target Tester is not included (which means that there is no compilation of any SDL Target Tester C code), and to give one template makefile including the SDL Target Tester.

In the template makefiles that include the SDL Target Tester, it is necessary to define the communications link software by adding the name of the C module(s) that contain(s) this. This can be achieved by changing the list of the object files given in sctLINKTARGET_WITH_TESTER (e.g. 8051_v24.suffix). In addition, the compilation rules for this/these additional module(s) must be specified as well in the makefile.

Finally, the makefile name must be changed into makeoptions on UNIX, and into make.opt in Windows.

Note:

The makeoptions and make.opt files below the predefined kernel directories in <sdtdir>/SCMA* are not intended to be used for target or target debug applications.

Adapting the Data Link Layer

The data link layer for the SDL Target Tester on target site is represented by the module dl.c with the functions

Several ways to fill these functions are already given in mg_dl.c.

The data link layer can be build using a ring buffer for all the trace message or writing each message directly to the physical layer.

Furthermore the data link layer must be build to work together with the physical layers (E.g. ISR driven or not).

It is recommended to have a look into the distributed template mg_ dl.c which shows different ways.

Adapting the Physical Layer

There are given tested physical layers for the micro controllers 8051 and 80166.

The structure of these physical layers should be taken and filled with the functions for the needed communications link. E.g. the function to write to a serial interface must be replaced by a function to write to an Ethernet interface.

The Communications Link's Host Site

The sdtgate is one executable of the SDL Target Tester's tool chain on host site. It is built to simplify the communication between the host and the target.

In this release of the SDL Target Tester, the sdtgate is built using a V.24 interface and the sockgate is build using a TCP/IP interface. But as you can see in this subsection, it will be very simple to implement any other communication interface as a new executable.

Communication between the SDL Target Tester Executables

The SDL Target Tester executables sdtmtui, sdtmt and sdtgate communicate with the help of the Cmicro Postmaster. The Cmicro Postmaster handles all the communication between the SDL Target Tester tool chain and is started automatically when the SDL Target Tester is invoked.

The Default V.24 Connection: Sdtgate

Fork Parameters for the Sdtgate

There are two groups of fork parameters handed over to the sdtgate.

The Sdtgate Device Specifications

Inside the SDL Target Tester configuration file sdtmt.opt there are 7 entries for the gateway executable.

Example 625 : On UNIX

USE_GATE             <pathname>/sdtgate
GATE_CHAR_PARAM_1    /dev/ttya
GATE_CHAR_PARAM_2    0
GATE_CHAR_PARAM_3    0
GATE_INT_PARAM_1     9600
GATE_INT_PARAM_2     0
GATE_INT_PARAM_3     0

On UNIX, it muse be ensured that the device (/dev/ttya above) is accessible. Ask the system administrator if there are problems to open this device.

Example 626 : In Windows

USE_GATE             <pathname>/sdtgate.exe
GATE_CHAR_PARAM_1    COM2
GATE_CHAR_PARAM_2    0
GATE_CHAR_PARAM_3    0
GATE_INT_PARAM_1     9600
GATE_INT_PARAM_2     0
GATE_INT_PARAM_3     0

USE_GATE gives the name of the used gate only.

Inside the delivered sdtgate for V.24 interface only the GATE_CHAR_PARAM_1 (a string) and the GATE_INT_PARAM_1 (an integer) are used. For future developments there are 2 further string parameters and two further integer parameters which are handed over when forking the gate.

The delivered version of the sdtgate uses fixed values for parity, start bits, stop bits...

These are: databits = 8, startbits = 1, stopbits = 1, parity = none

Coding Rules

There are two coding rule pieces of information the gate needs to work.

These are the length of a character on the target in octets (normally 1) and the position of the character. This value is necessary for special micro controller memory layouts e.g. the MSP58C80 gets the character length of 2 octets but the used character is the lower octet only. In this case the character position is 1. Normally if the character size is 1 the character position is 0.

The TCP/IP Connection: Sockgate

The Sockgate Device Specifications

Like the sdtgate, the sockgate is using only 3 of the 7 entries for the gateway executable inside the SDL Target Tester configuration file sdtmt.opt.

Example 627 :

USE_GATE             <pathname>/sockgate
GATE_CHAR_PARAM_1    207.46.138.0
GATE_CHAR_PARAM_2    0
GATE_CHAR_PARAM_3    0
GATE_INT_PARAM_1     9000
GATE_INT_PARAM_2     0
GATE_INT_PARAM_3     0

USE_GATE gives the name of the used gate only.

It must be ensured that the IP-address (207.46.138.0 above) is accessible.

Inside the delivered sockgate only the GATE_CHAR_PARAM_1 (a string) and the GATE_INT_PARAM_1 (an integer) are used. The delivered version of the sockgate uses an address string (a valid IP-address) and a port number (valid between 1 and 65535).

Building an Custom Made Communications Link

All the C files and libraries necessary to re-build the default gateway sdtgate are delivered with the SDL Target Tester. The files for a custom built gateway are named usergate to distinguish between the custom and the delivered sdt- and sockgate.

The Modules Building a Usergate

The following files are part of the usergate:

 cmicro
    + sdtmpm
    |   + sunos5
    |   |   + sdtmlib.a (SunOS 5 version)
    |   + wini386
    |       + sdtmpmcl.lib (Microsoft C++ 6.0 version)
    |       + sdtmpmcl5.lib (Microsoft C++ 5.0 version)
    + mcod
    |   + mcodfnc.[ch]pp
    |   + mcodlib.[ch]pp
    |   + mcod.h
    + sdtgate
    |   + mg_ctrl.[ch]
    |   + usergate.rc (Windows only)
    |   + sunos5
    |   |   + usergate.[ch] (SunOS 5 version)
    |   + wini386
    |       + usergate.[ch] (Windows version)
    + template
         + mg_dl.[ch]
         + commlink
             + <interface>.[ch]

Files with suffix .h and .hpp are not listed but are still being used.

<interface> stands for the selected interface type.

On UNIX the module ux_v24.c is used (ux_sock.c for sockets).

In Windows the module win32v24.c is used (win_sock.c for sockets).

The purpose of each module is as follows:

Compiler Settings

Current Restrictions for Communications Link Software

SDL Restrictions

It is impossible to transfer pointer values via the communications link. An example may be the SDL predefined sort charstring which is by default implemented as a pointer in C.

To avoid problems, users must not use SDL sorts that are implemented as pointers (like charstring), whenever it is required to send / receive them via the communications link (e.g. Cmicro Tracer or Cmicro Recorder functionality). This means, that this kind of sorts should only be used in signals inside the SDL system but not at it's environment.

Message Length

The maximum length of the message length is restricted.

An explanation follows:

Each message is transferred as:

Header + Data + CRC

The length field contained in the header may represent the values from 0 to 255. If the MSB in the message tag is set to "1", then the length field is expected to be a 2 octet values, which makes it possible to represent the value from 256 to 65535.

However, the length field consisting of 2 octets is currently not implemented.

In fact, no message may be greater than 4 + 255 + 1 = 260 characters in total (1 character normally is equal to 1 Byte, which consists of 8 Bits).

Connection of a Newly Implemented Communications Link

The SDL Target Tester uses only a few C function calls in order to send and receive information via the communications link. From the C syntax point of view, users only have to implement the body of these functions and to link them together with the SDL Target Tester's target library into one executable program.

However, when considering timing constraints, critical paths, interrupts and similar things, users have to note the following.

Critical Paths

Critical paths occur in any type of software which uses interrupts. Especially the transfer of information between ordinary C code and interrupt service routines must be considered, e.g. for the communication from the physical layer (which may be implemented as an ISR) to the data link layer (which may be implemented as ordinary C functions).

Critical paths may occur at any place in the software which accesses global C variables.

The beginning of each critical path must be blocked with something like "disable interrupts" (see XMK_BEGIN_CRITICAL_PATH in the compiler section of ml_typ.h). The end of a critical path must be released with something like "enable interrupts" (see XMK_END_CRITICAL_PATH).

Timing Constraints

Often there are timing constraints to be considered within the target system. Timing problems must be prevented. Each ISR must be implemented with a few statements only, in order to make the execution time as short as possible.

Interrupts

C functions which should be compiled as ISRs by the C compiler in use are mostly

marked by a preprocessor directive or by a special C compiler keyword. The C compilers reference manual must be consulted in order to implement ISRs.

Open Interface

The open interface can be used to implement user host executables which are able to communicate with the SDL Target Tester at the target site. The SDL Target Tester at the target site is represented by the target library.

Using the Open Interface

In order to use the open interface in this way, the following are of interest:

It is not of great interest what the format of the data link frames is because it is possible either to use the existing protocol or to re-implement the protocol (e.g. it may be necessary in order to integrate the SDL Target Tester into an existing communication link's software).

The host site must send each message in target representation.

For instance, if the target system uses integers as 2 octet values with the ordering higher octet first, then the host must send an integer value with higher octet and then lower octet, irrespective of its own layout.

For the other direction (reception of messages at host site), the host must also map the information according to the relation between the target memory layout and its own internal representation.

Accessing the Data Link by User

The user can send information via the communication link by calling the C function xmk_DLWrite with appropriate parameters. The following example shows one possibility.

Example 628

#define HelloWorldTag <AnyValueAllowed>

char buffer     [20];
char helloworld [15];
int  length     = 0;
int  write_result ;
strcpy (helloworld, 'Hello World'); 


buffer [0] = 0x11; 
length ++;
/* any value for Messageclass, except      */
/* reserved values for SDL Target Teste    */
/* reserved values begin from 250 to 255   */

buffer [1] = HelloWorldTag; 
length ++;
/* any value for Messagetag                */
/* Messagetag is made unique together      */
/* with Messageclass, so that no           */
/* conflict occurs.                        */

buffer [2] = strlen (helloworld); 
length ++;
/* length of data for this message         */
/* length is given without calculating     */
/* the CRC field                           */

memcpy (buffer [3], helloworld, strlen (helloworld);
length += strlen (helloworld);
/* It is assumed, that no stringterminator */
/* is included in the message (the length  */
/* can be calculated from Messagelength)   */

buffer [length] = xmk_EvalChkSum (buffer, length); 
/* Evaluate the checksum of current buffer */

write_result = xmk_DLWrite (buffer, 5 + strlen (helloworld));
/* transmit buffer via communications link */

The user can receive information from the communication link by calling the C function xmk_DLRead with appropriate parameters.

Example 629 : xmk_RunSDL ()

The following section is partially implemented within the module mk_main.c

p_data = xmk_DLRead () ;
if (p_data != (char *) NULL)
{
  /* if anything received, decode it    */
  /* according to Cmicro Protocol       */
  result = xmk_Cod_Decode (p_data, 
                           &MessageClass,
                           &Messagetag,
                           &MessageLength,
                           buffer,
                           sizeof (buffer));
if (MessageClass == XMK_MICRO_COMMAND)
{
  result = xmk_HandleCmd ( Messagetag, (xmk_U_CMDS*) buffer );
  return;
}

/*
** Received user message
*/
if (MessageClass != 0xF8)
{
  ErrorHandler (-7777);
  return ;
}

if (HelloWorldTag == Messagetag)
{
  /* HelloWorldTag is used in this example to */
  /* identify the hello world message         */
  /* The user can choose any value for the    */
  /* Message tag                               */
  char helloworld [15];

  memset (helloworld, 0, sizeof (helloworld)); 
  memcpy (helloworld, buffer, MessageLength);
  printf ('%s', helloworld);
}

The above examples assume that the Cmicro protocol (which is described in Used Default Protocol) is used.


http://www.ibm.com/rational
Contents Index Previous Next