Contents

Acknowledgments

Requires

• vxWorks 5.3 or later
• Epics base release 3.13.beta12 or later
• drvIpac 2-1 or later. For details see drvIpac.

Introduction

Message Passing Facility

MPF provides client server message passing.  The messages are handled by message routers. Both local and remote message routers are provided.

Industry Pack modules are supported via drvIpac, which supports dumb VME carriers as well as the mv162 and mv172. For details see drvIpac.

Device support is provided that communicates with MPF.

MPF replaces HIDEOS

Background:

Strategy:

The most important goal is to provide a migration path for existing HIDEOS applications. An EPICS Hideos application uses the following Hideos components:

EPICS Records

The DTYP and INP fields of records can specify a connection to HIDEOS device support.  For some devices, MPF supports the HIDEOS conventions, which means existing EPICS record instances do not have to be modified when converting from HIDEOS to EPICS. In other cases, e.g. the ip330, changes are necessary.

Modified to interface to the new MPF.

These are more generic. IP support is independent of MPF. MPF servers are provided to talk to the IP support.

Message types are more general than the Hideos messages. Network messages are passed in an architecture independent representation. Hideos only allowed in-line methods. MPF removes this restriction.

Everything currently residing under the HIDEOS_SYS sub directory is abandoned.

1. Network Transparent message passing. This allows messages to be passed between different machine architectures.
2. Connection Management - The initial release allows either server or client to be started first. It allows either client or server to be rebooted without booting the partner. Rebooting the server usually works without rebooting the client. The converse has not been successfully tested.
3. Messages can have regular methods. (HIDEOS required that all message methods be inline)

Hardware Configurations

• Epics and IP support on a single processor.
• Epics on one processor. vxWorks and IP support on another processor.
• Epics and IP support for a "dumb" VME IP module.

When MPF is used between processors, communication is via a tcp connection. Thus the two processors can reside anywhere as long as it is possible for them to communicate via tcp.

Install and Build MPF

Obtain a tar file of MPF.

cd
tar -xvf <file>

cd
cd mpf/config
vi RELEASE
cd ..

• set EPICS_BASE to reference your epics base. This MUST be release baseR3.13.0.beta12 or later.
• Set IPAC to reference the ipac driver software, which must be release 2-1 or later.

In order to run the tests included with MPF, the following files must be edited in mpf/iocBoot

iocgpibclient/st.cmd
iocgpibserver/st.cmd
iocmpfclient/st.cmd
iocmpfserver/startServers
iocrstclient/st.cmd
iocrstserver/st.cmd
ioctcpclient/testClientWaitBuffer100
ioctcpclient/testClientWaitNoBuffer
ioctcplocal/tcpTestWaitLocalBuffer100
ioctcplocal/tcpTestWaitLocalNoBuffer
ioctcpserver/testServerWaitBuffer100
ioctcpserver/testServerWaitNoBuffer
iocip330scanclient/st.cmd
iocip330scanserver/st.cmd

Now issue the commands:

cd
cd mpf
gnumake

Multiple Processor VME system

• An mv167 resides in the first slot. It has an ethernet connection. It also provides a back plane gateway for other processors in the same crate. It is processor number 0.
• An mv162 resides in the second slot. It has no ethernet interface. It has network access via the back plane and appears on the same local area network as the mv167. It is processor number 1.
• Additional mv162s could appear in other slots. They are similar to the first mv162.

• IPmv167 - The address of the mv167
• IPgateway - The address of the MVE gateway, which is managed by the mv167 vxWorks support
• IPmv162 - Each mv162 needs its own address
• IPhost - The address of the vxWorks boot host.

MV167

boot device          : ei
processor number     : 0
host name            : <host>
file name            : <full path>/vxWorks
inet on ethernet (e) : <IPmv167>:<subnet mask>
inet on back plane (b): <IPgateway>
host inet (h)        : <IPhost>
gateway inet (g)     :
user (u)             : <user>
ftp password (pw) (blank = use rsh): <password>
flags (f)            : 0x0
target name (tn)     : ioc167
startup script (s)   : <full path name>/st.cmd
other (o)            :

boot device          : sm=0x80000600
processor number     : 1
host name            : <host>
file name            : <full path>/vxWorks
inet on ethernet (e) :
inet on back plane (b): <IPmv162>
host inet (h)        : <IPhost>
gateway inet (g)     : <IPgateway>
user (u)             : <user>
ftp password (pw) (blank = use rsh): <password>
flags (f)            : 0x0
target name (tn)     : ioc162
startup script (s)   : <full path name>/st.cmd

Getting Started

• check the inet addresses given to tcpMessageRouterClientStart in <top>/iocBoot/iocrstclient/st.cmd and tcpMessageRouterServerStart in <top>/iocBoot/iocrstserver/st.cmd.
• boot the mv167 with startup file <top>/iocBoot/iocrstclient/st.cmd
• boot the mv162 with startup file <top>/iocBoot/iocrstserver/st.cmd
• On the mv167 console give the command

< startEpicsSerial

• run medm from <top>/epicsDevApp/adl and ask for file epicsSerial.adl

The test consists of the following:

• On the mv162 the following servers are started:
• serverInt32 is started. It just echoes any Int32 message sent to it.
• serverChar8array is started. It just echoes any Char8Array message sent to it.
• a serialServer is started for each serial port.
• The mv167 has the following records:
• Four ai records which use DevMpfInt32Test. this device support keeps a private counter which counts from egul to eguf. After incrementing the counter an Int32 message is sent to serverInt32. The reply is put in the val field.
• Four sets of records which communicate with serverChar8array are present.  Each set consists of the following records:

record(calc,"Char8Array:calc$(ind)")
{
    field(CALC,"a=1000?0:a+1")
    field(FLNK,"Char8Array:solnk$(ind)")
    field(INPA,"Char8Array:calc$(ind)")
}
record(stringout,"Char8Array:solnk$(ind)")
{
    field(DOL,"Char8Array:calc$(ind)")
    field(OMSL,"closed_loop")
    field(FLNK,"Char8Array:StringIn$(ind)")
}
record(stringin,"Char8Array:StringIn$(ind)")
{
    field(DTYP,"MPFwriteRead")
    field(INP, "#C1 S0 @Char8Array,Char8Array:StringOut$(ind)")
}

The calc record  counts from 0 to 1000 and links to a stringout record which reads the value of the calc record and forward links to a  stringin record.  The stringin record reads the value from the stringout record and sends it to serverChar8array. The reply from serverChar8array is put into the val field.
• 16 sets of records like the previous set except that they send messages to the serialServers. There are two sets for each of the 8 octal/serial ports.
• The medm display consists of the following:
• The first four rows are the ai records.
• The next four row are the string records for the serverChar8array
• The next 8 rows are the string records for serialServer. One for each port.
• The last 8 rows are also string records for serialServer. One for each port.
• The first column of each row is a controller to set the scan rate for that row.

Studying the above will show how to write servers, device support, build servers and client, and boot servers and clients.

Using MPF in Applications

Edit the files CONFIG_APP and RELEASE.

In CONFIG_APP add the lines:

ifdef MPF
USR_INCLUDES += -I$(MPF)/include
MPF_BIN = $(MPF)/bin/$(T_A)
USER_DBDFLAGS += -I $(MPF)/dbd
endif

MPF=<full path name>

LIBOBJS += $(MPF_BIN)/mpfLib

include "devMpf.dbd"

mpf/bin

Epics applications

• mpfLib - Everthing needed by the message passing facility.
• mpfDevLib - DevMpf and devStringMpf
• devAiIp330Scan.o
• devAoDAC128V.o

Server applications

• mpfLib - Everthing needed by the message passing facility
• ipLib - IP support plus generic serial and gpib support.
• mpfServerLib - Serial and Gpib servers
• GpibGsTi9914.o
• OctalUART.o
• ip330ScanLib - ip330Scan.o and ip330ScanServer.o
• dac128VLib - dac128V.o and dac128VServer.o

Complete list

• GpibGsTi9914.o - Greensprings IP Gpib support
• GpibHideosLocal.o - Local interface for drvGbib
• GpibHideosRemote.o - Remote interface for drvGpib
• OctalUART.o - GreenSprings Octal Uart support
• clientChar8Array.o v- Client test
• clientInt32.o - Client test
• dac128VLib - dac128V.o dac128VServer.o
• devAiIp330Scan.o - Acromag IP 330 scanning support
• devAoDAC128V.o -  Systran DAC128V device support
• iocCore - epics base iocCore for use by tests.
• ip330ScanClientLib - client library for ip330 test
• ip330ScanLib - ip330Scan.o and ip330ScanServer.o
• ip330ScanLocalLib - test ip330 on single processor
• ipLib - SerialPort.o serialPortSniff.o Gpib.o,gpibSniff.o IndustryPackModule.o

IndustryPackCarrier.o IndustryPackIpac.o ipacLib
NOTE: ipacLib,  from the unbundled ipac support, contains drvIpac.o and drivers for the GreenSpring VIPC310, VIPC610 and VIPC616 carrier boards and the MVME162 (which is also used for the MVME172).
• mpfDevLib - DevMpf.o devStringMpf.o
• mpfDevTest - Library for tests.
• mpfKernelLib - Message.o localRouter.o RMRClient.o RMRServer.o Tcp.o TcpBadProto.o
• mpfLib - mpfUtilLib mpfKernelLib mpfMessageLib
• mpfMessageLib - Code for all message types
• mpfServerLib - serialServer.o gpibServer.o
• mpfServerTest - Library for tests.
• mpfTest - Library for tests.
• mpfUtilLib - FreeList.o DLList.o WatchDog.o DataFreeList.o

mpf/dbd

• devAiIp330Scan.dbd - Acromag IP330 scan support
• devMpf.dbd - Generic stringin and stringout support
• devAoDAC128V.dbd - Systran DAC128V  support

MPF Directory Structure

<top>/
    config/
           RELEASE
    utilApp/
           utilSrc/
    mpfApp/
           kernelSrc/
           messageSrc/
           libSrc/
           testSrc/
    ipApp/
           src/
    mpfServerApp/
           serverSrc/
           testSrc/
                 clientInt32.cc
                 serverInt32.cc
    epicsDevApp/
           Db/
           adl/
           epicsDevSrc/
                 devStringMpf.cc
    dac128VApp/
           src/
                 dac128V.cc
                 dac128VServer.cc
                 devAoDAC128V.cc
                 devAoDAC128V.dbd
    iocBoot/
           iocrstclient/
           iocrstserver/
           iocmpfclient/
           iocmpfserver/
           iocmpflocal/
           ioctcpclient/
           ioctcpserver/

Epics Record to IP - Flow of Control

INP("C1 S0 @serialServer,<command>")

• C1 identifies the location of the server. Location is described below in the section on Router Configuration.
• S0 is not used
• serialServer is the name of an MPF supplied server
• command is the command string to send to the device.

• The stringin record support module calls DevMpf::read_write.
• DevMpf calls DevStringin::startIO.
• DevStringin::startIO calls DevMpf::sendReply.
• If a local router connects to serialServer
• LocalRouter puts the message on the serialServer queue.
• Else if a remote router connects to serialServer
• The message is put on the RMRclient queue.
• DevStringin , DevMpf and record support finish the beginning phase of asynchronous record processing.
• If a remote router connects to serialServer
• RMRclientTask sends a TCP message to RMRserver.
• tcpTask receives the message and calls RMRserver::receiveCallback.
• RMRserver puts the message on the serialServer queue.
• The serialServer task wakes up from SerialServer::waitForMessage.
• serialServer calls SerialServer::receive and then SerialPort::writeRead, which is a method of OctalSerial.
• OctalSerial sends to the serial port and waits for the response before returning to serialServer.
• serialServer calls SerialServer::reply.
• If a local router connects to serialServer
• DevMpf::messageClientCallback is called.
• DevMpf make an epics callbackRequest.
• SerialServer again calls SerialServer::waitForMessage.
• Else if a remote router connects to serialServer
• The reply message is put on the RMRserver queue.
• SerialServer again calls SerialServer::waitForMessage.
• RMRserverTask sends a TCP message to the RMRclient.
• The client tcpTask receives the message and calls RMRclient::receiveCallback.
• RMRclient calls DevMpf::messageClientCallback.
• DevMpf make an epics callbackRequest.
• The epics callback task calls DevMpf::callDeviceSupport which calls the RSET::process.
• The stringin record support module calls DevMpf::read_write which calls DevStringin::completeIO.
• DevStringin, DevMpf, and record support finish the asynchronous completion phase of record processing.

Message Passing Overview

Messages are sent through a router. Two routers are provided: localRouter and RMR (Remote Message Router). The localRouter passes messages between a client and server residing on the same processor. RMR sends messages between a client and server on different processors via a tcp connection.

Message Client

typedef void (*clientCallback)(Message *message,void *clientPvt);
class MessageClient
{
public:
    MessageClient(clientCallback,void *clientPvt);
 
    int bind(char *server, int location);
    int send(Message *message);
    void *getClientPvt();
private:
    ...
}

1. Create an instance of MessageClient for each server with which it wants to communicate.
2. Issue a bind call to establish communication.
3. Call send to send messages.
4. Provide a callback which is called whenever a connection is made or broken and is also called whenever the server sends a message to the client.

Message Server

class MessageServer
{
public:
    MessageServer(const char* name);
    void waitForMessage();
    Message *receive();
    Message *allocReplyMessage(Message *clientMessage,messageType type);
    int reply(Message *);
    void setQueueSize(int size);
    const char *getName() const;
    void report() const;
private:
     ...
}

1. Create an instance of MessageServer.
2. Call waitForMessage if it wants to block until it receives messages.
3. Call receive to accept messages.
4. Call reply to send messages to a client.
5. Call allocReplyMessage if it wants to send additional additional messages to a client

Messages

• Message - The base class. It provides the following methods for message users:  getType, getClientType, setClientType, getClientExtra, setClientExtra.
• Connect - A message that is passed when a client connects or disconnects from a server.
• StandardFields - This is not an actual message type but a class that provides fields, which can be used with other message types.  The fields are timeout, cmd, status, address, and extra. The meaning of these fields are determined by particular client/servers.
• Char8Array - A message for passing character strings. It supports the standard fields.
• Int32 - A message for passing integer values. It supports the standard fields.
• Int32Array - A message for passing arrays of integer values. It supports the standard fields.
• Float64 - A message for passing float values. It supports the standard fields.
• Float64Array - A message for passing arrays of float values. It supports the standard fields.
• SerialConfig - A message for configuring serial ports, e.g. baudrate.
• OutOfBand - A message not requested by the other side.

Message instances are kept on a free list. Thus malloc is called only if the free list is empty. Free is never called. Each message type has it's own free list.

Example

Diagnostic Aids

mrr

For servers it provides a report like the following:

iocrstserver> mrr
clientRouterList
serverRouterList
 1 RMRServer stateConnected queueSize 100 inQueue 0 replyQueueFull 0
   sendPerSec 240 receivePerSec 240  tcpSendPerSec 10 tcpReceivePerSec 10

• queueSize - The maximum number reply messages which can be queued.
• inQueue - The number of unsent reply messages.
• replyQueueFull - The number of times a reply request was rejected because the reply queue was full.

For clients it produces the following type of report

iocrstclient> mrr
clientRouterList
 1 RMRClient stateConnected queueSize 100 inQueue 0 sendQueueFull 0
   Server Int32 has 4 clients. bindState connected
   Server Char8Array has 4 clients. bindState connected
   Server serial[0] has 2 clients. bindState connected
   Server serial[1] has 2 clients. bindState connected
   Server serial[2] has 2 clients. bindState connected
   Server serial[3] has 2 clients. bindState connected
   Server serial[4] has 2 clients. bindState connected
   Server serial[5] has 2 clients. bindState connected
   Server serial[6] has 2 clients. bindState connected
   Server serial[7] has 2 clients. bindState connected
   sendPerSec 240 receivePerSec 240  tcpSendPerSec 10 tcpReceivePerSec 10
serverRouterList

msr ("serverName")
msr

iocrstserver> msr "serial[7]"
serial[7]
          queueSize 2
            inQueue 0
      queueRequests 132171
 queueFullResponses 1
      replyRequests 132171

• queueSize - The maximum number of unprocessed requests that can be placed in the servers queue.
• inQueue - The number of unprocessed requests currently in the servers queue.
• queueRequests - The number of queue requests that have been made since the server was started.
• queueFullResponses - The number of times a queue request was made and the receive queue was already full. When this happens a ConnectMessage is sent to the client.
• replyRequests - The number of reply requests that have been made since the server was started.

serialPortSniff("portName",seconds)

serialPortSniff "UART[5]",1
value = 0 = 0x0
iocrstserver>
T31 T34 R31 T35 R34 T00 R35 R00 T31 T34 14154.5.14
R31 T36 R34 T00 R36 R00 T34 T31 R34 T32 164.6.4142
R31 T00 R32 R00 T31 T34 R31 T37 R34 T00 1.2.14174.
R37 R00 T31 T34 R31 T38 R34 T00 R38 R00 7.14184.8.
T31 T34 R31 T39 R34 T00 R39 R00 T31 T35 14194.9.15
R31 T30 R35 T00 R30 R00 T31 T35 R31 T31 105.0.1511
R35 T00 R31 R00 T34 T31 R34 T33 R31 T00 5.1.41431.
R33 R00 T31 T35 R31 T32 R35 T00 R32 R00 3.15125.2.
T31 T35 R31 T33 R35 T00 R33 R00 T31 T35 15135.3.15
R31 T34 R35 T00 R34 R00 145.4.
serialPortSniff done

gpibSniff("moduleName",seconds)

gpibSniff("a-ip488",3) 
value = 0 = 0x0
iochp3458> 
R
T_?V
R-8.874270409E-01 0x0d 0x0a
T_?_?V
R-9.341735006E-01 0x0d 0x0a
T_?_?V
R-9.575970835E-01 0x0d 0x0a
T_?_?V
R-1.004537279E+00 0x0d 0x0a
T_?_?V
R-1.027972941E+00 0x0d 0x0a
T_?_?V
R-1.051432207E+00 0x0d 0x0a
T_?
gpibSniff done

Message Routers

Local Message Router

Remote Message Router

Router Configuration

Each vxWorks system using the message passing system needs the following command in the startup file:

routerInit

localMessageRouterStart(location)

If tcp communication is desired then for each remote system the client must have the following command:

tcpMessageRouterClientStart(location,port,"address",bufSize,queueSize)

• location is the location of the server.
• port is the port the server will use to listen for a connection.
• address is the inet address of the server.
• bufSize determines that maximum size message accepted by the client.
• queueSize is the maximum number of send messages that will be queued.

tcpMessageRouterServerStart(location,port,"address",bufSize,queueSize)

• location is the location of the server.
• port is the port the server will use to listen for a connection.
• address is the inet address of the server. This argument can be null, in which case the server will accept connections via all internet interfaces attached to it's cpu.
• bufSize determines that maximum size message accepted by the server.
• queueSize is the maximum number of reply messages that will be queued.

Message

Overview

• Clients must allocate a message via a call

<message class> *pmessage = new <message class>;

for example an Int32 message can be allocated as follows:

Int32Message *pmessage = new Int32Message;

• Servers allocate a message via a call to the allocReplyMessage of class MessageServer. For example an Int32 reply message can be allocated via a call:

Int32Message *pmessage =(Int32Message*)pMessageServer->
    allocReplyMessage(preceive,messageTypeInt32);

where preceive must be a message received from the client. The reason is that the receive message contains information describing where the client is located.
 
• The final destination of a message must call delete to free the message via the statement:

delete pmessage;

Thus the server must delete any message received from a client and a client must delete reply messages from the server.

class Message
{
public:
    messageType  getType();
    int32 getClientType();
    void setClientType(int32 type);
    int32 getClientExtra();
    void setClientExtra(int32 extra);
    virtual ~Message();
    virtual int  toBuffer(char **buffer);
    virtual int  fromBuffer(const char **buffer);
    virtual int  fromBufferSwitch(const char **buffer);
    virtual void print() const;
    static Message *allocate(messageType type);
protected:
    Message(messageType type);
    ....
}

The virtual methods must be implement by any class that derives from Message. The toBuffer and fromBuffer methods are called to put and take messages from a buffer that passes over a communication link.

method	Recommended Meaning
getType	Returns the message type
getClientType setClientType	These methods are for use by a client to access field clientType. When the server allocates a reply message via a call to allocateReplyMessage, the clientType from the clients message is copied to the reply message. In general a server should not use these methods. They are intended for clients that send multiple messages to a server and need to match reply messages with messages sent. Classes derived from DevMpf MUST NOT use these because DevMpf itself uses them. Use clientExtra instead.
getClientExtra setClientExtra	These access a field clientExtra which is similar to clientType. They can be used by classes derived from DevMpf.

Architecture Independent Message Passing

• signed and unsigned 16 and 32 bit integers
• IEEE float and double.
• strings, i.e. C char 8 arrays. MPF itself uses some strings as ascii strings. Other strings are uninterpreted 8-bit values whose contents are guaranteed not to undergo any conversions during transmission.

MPF provides a header file "mpfType.h" which defines typedefs for int16, uint16, int32, uint32, float32, and float64. MPF provides static methods to transfer the following to/from network buffers:

• signed and unsigned 16 and 32 bit integers
• IEEE float and double
• char8 arrays which are uninterpeted bytes.

Adding New Message Types

• messageType.h and messageType.cc must be modified.

These files contain instructions about what to add. This is a simple change.
• A header and source file for the new message must be created.

ConnectMessage

• connectNo - Sent when client router detects a disconnect from server.
• connectYes - Sent when a successful connection is made to server.
• connectNoRouter - No router exists.
• connectNoServer - Sent when a bind request is made but server router can not find server.
• connectQueueFull - Sent when a message is sent to server but the servers queue is full.

StandardFieldsMessage

Free Lists for Array Messages

Char8ArrayMessage

Char8ArrayMessage provides the following methods for allocating and freeing the string value.
 

method	usage
allocValue	This is a static method which looks for the smallest freelist that can provide the needed space. If the requested size is larger than the size for the largest freelist, it calls new to allocate space.
setSize	Sets the current size for the array. This size MUST be less than that allocated by allocValue.
getSize	Gets the current array size.
getMaxSize	This gets the size allocated by the call to allocValue
freeValue	This puts storage obtained by allocValue back on the appropriate free list or calls delete if the storage was obtained via a call to new. This method is called automatically when a Char8Array message is deleted.

Int32Message

Int32ArrayMessage

Float64Message

Float64ArrayMessage

SerialConfigMessage

OutOfBandMessage

MPF Device support

// return codes for startIO and completeIO.

#define MPF_OK                  0
#define MPF_NoConvert           2

enum replyType {replyTypeNone, replyTypeCompleteIO, replyTypeReceiveReply};

class DevMpf
{
public:
    DevMpf(dbCommon*,link*,bool iointValid);

    // Following must be implemented by device support modules
    virtual long startIO(dbCommon*)=0;  // start async IO
    virtual long completeIO(dbCommon*,Message *)=0; // end async IO
    // the following can be implemented by device support modules
    virtual void receiveReply(dbCommon*,Message *);
    virtual void connectIO(dbCommon*,Message *);     // connection message
    virtual void outOfBandIO(dbCommon*,OutOfBandMessage *);// outOfBand
    virtual long convert(dbCommon*,int pass);   // do linear conversion
    // send a message to MPF server with no reply expected
    int send(Message*);
    // send a message to MPF server and wait for reply via completeIO
    int sendReply(Message*);
    // send a message stating the type of reply
    int send(Message*,replyType);
    // This routine gets a pointer to the user portion of the parm field
    const char* getUserParm() const { return((const char*)userParm); }
    long getStatus() const { return(status);}
    // Following are DSET routines
    static long read_write(void*);      // generic DSET read/write routine
    static long ioint(int cmd,dbCommon*,IOSCANPVT* iopvt); // DSET i/o intr
    static long linconv(void*,int); // calls convert
    IOSCANPVT ioscanpvt;
    bool iointValid;
private:
    ...

}

If the support is for a simple device, i.e. a device that can be supported via the following:

• When the associated record starts the first phase of record processing, the device support issues a sendReply message to the server.
• When the reply is received the record completes processing.
• Device support doesn't have to do anything special when it first connects to it's server

For devices that are not simple, e.g. devices that must take special action when connecting to the server, additional methods are available: In particular:

• receiveReply and send(message,replyTypeReceiveReply) are available. receiveReply does not interact with record processing. Thus the device support can interact with the server without processing the record. This can be used to send a series of messages to the server. DevMpf uses the message field clientType to distinguish the reply type.
• connectIO can be implemented so that the device client is called everytime the support is connected or disconnected with the server.
• The  Message methods getClientExtra and  putClientExtra can be used by the device support to match response with request messages. NOTE: DevMpf uses getClientType and  putClientType so device support MUST NOT use these methods.
• After connection processing is complete device support can revert to the simple processing described above.

ioscanpvt is for provided for convenience.  If a derived class wishes to support io interrupt processing it can request that the base class perform the necessary initialization. The derived class must, however, call scanIoRequest.
 

method	Usage	meaning
DevMpf	Constructor	The constructor must be given the address of the record and link (INP or OUT). iointValid specifies if the base class should initialize  ioscanpvt
startIO	Called by DevMpf	When a request is made to process a record this is called only when the following conditions are all true: The server is connected, PACT is false, and no reply message from the server is available. This MUST be implemented by any class derived from DevMpf. This method is always called as a result of a record being processed and the record is not active. If startIO issues a send(message,replyTypeCompleteIO) then PACT is set TRUE, i.e. the record will not complete processing until the reply message is received and completeIO is called.
completeIO	Called by DevMpf	DevMpf calls this when the reply to a send(message,replyTypeCompleteIO) is received. This MUST be implemented by any class that derives from DevMpf. This method  is always called as a result of a record being processed
receiveReply	Called by DevMpf	DevMpf calls this when the reply to a send(message,replyTypeReceiveReply) is received. This call does not involve record processing. The default method just prints a message and deletes the message it received.
connectIO	Called by DevMpf Default supplied by DevMpf.	DevMpf calls this when it receives a ConnectMessage. DevMpf provides a default implementation.  If device support implements this method it should call DevMpf::connectIO (just before returning) to ensure correct behavior.
outOfBandIO	Called by DevMpf Default supplied by DevMpf.	DevMpf calls this when it receives an OutOfBand message. For example if server receives a send (no reply) message that can not be processed, the server can send an OutOfBand message to the client.  The default method just prints a message and deletes the message it received.
convert	Called by DevMpf, Default supplied by DevMpf	This is the DSET convert routine for ai, ao type records. The default version does nothing. Device support derived from base can provide it's own version.
send(Message*)		Equivalent to send(message,replyTypeNone)
sendReply		Equivalent to send(message,replyTypeCompleteIO)
send(Message*,replyType)	Called by derived class	Send a message to the server.  SetClientType is called to specify the replyType. If the message is successfully sent and replyType is replyTypeCompleteIO pact is set true. NOTE: Only one send(message,replyTypeCompleteIO) should be outstanding, i.e. after calling send(message,replyTypeCompleteIO) wait for completeIO to be called before issuing another send.
getUserParm	Called by derived class	Get the portion of the parm of the INP or OUT link that follows the server name.
getStatus	Called by derived class	Get the status. A 0 value is success. Any other value is device dependent.
read_write	Called by record support	This is the read or write DSET routine. Handled automatically by DevMpf
ioint	Called by record support	This is DSET get_io_intr routine. Handled automatically by DevMpf
linconv	Called by record support	This is DSET linr_conv routine. It calls convert.

The INP or OUT field MUST have the format:

field(INP or OUT, "#C<location> S<signal> @<server>,<deviceSpecific>")

Device Support Entry Tables

MAKE_LINCONV_DSET(<dset name>,<dev init>)
MAKE_DSET(<dset name>,<dev init>)

Utility Classes

• FreeList - A class that keeps objects of a particular class on a free list.
• DLList - A double linked list class.
• WatchDog - A class that is a C++ interface to the vxWorks wdLib.
• DataFreeList - A free list class for date.
• Reboot - A class providing support for the vxWorks rebootHookAdd facility.

FreeList provides the same functionality as the freeList facility provided with epics base, in fact it is just freeList redone in C++.

DLList is a double linked list class that does not require nodes to be embedded in objects placed in a list. This is different than the ellList facility provided by epics base.

WatchDog is a class that provides functionality similar to the vxWorks wdLib. The major exception is that the user supplied callback is called by a WatchDog supplied task rather than being called at interrupt level.

DataFreeList is a class for data free lists. It provides free lists of sizes ranging from 16 bytes to 4096 bytes. It is used by the array message types.

Reboot can be used to turn off interrupts when a soft reboot is being performed.

These classes are not described in this document. If you want to use them in new code look at examples in existing code.
 

IndustryPack Support

IndustryPack Support consists of the following components:

IndustryPackCarrier

The base class for an IndustryPack carrier. It allows access to IndustryPack carrier configuration and control independent of the specific carrier hardware board.

The base class for a specific site on a specific carrier, i.e. the place where an IP module resides.

Implements the IndustryPackCarrier and IndustryPackSite classes which actually pass requests on to the ipac software to implement.

Provides IndustryPack Module configuration independent of the specific IP carrier. This class is used by specific module support such as OctalUART and GpibGsTi9914.

IndustryPackCarrier

class IndustryPackCarrier
{
 public:
  IndustyPackCarrier();
  int registerName(const char *carrierName);
  static IndustryPackCarrier *find(const char *carrierName);
  IndustryPackSite *findSite(const char *siteName);
  IndustryPackSite *addSite(IndustryPackSite *pSite);
  const char *getCarrierName();
  virtual volatile void *allocMemMapIP(int size) = 0;
 private:
    ...
};

class IndustryPackSite
{
 public:
  IndustryPackSite();
  const char *getSiteName();
  virtual volatile void* allocMemMapIP(int size) = 0;
  virtual volatile IP_ID_PROM* getMemBaseID() = 0;
  virtual volatile void* getMemBaseIO() = 0;
  virtual volatile void* getMemBaseIP() = 0;
  virtual int intConfig(int num) = 0;
  virtual void intEnable(int num) = 0;
  virtual void intDisable(int num) = 0;
 protected:
  const char *siteName;
  IndustryPackCarrier *pIpCarrier;
 private:
};

IndustryPackIpac

ipacAddCarrier(&ipmv162,"A:l=3,3 m=0xe0000000,64;B:l=3,3 m=0xe0010000,64;
C:l=3,3 m=0xe0020000,64;D:l=3,3 m=0xe0030000,64")
initIpacCarrier("carrierName", 0)

IndustryPackModule

class IndustryPackModule
{
public:
  static IndustryPackModule * createIndustryPackModule(
      const char *moduleName,
      const char *carrierName,
      const char *siteName);
  static IndustryPackModule *find(const char *moduleName);
  static IndustryPackModule *find(
      const char *carrierName,
      const char *siteName);
  volatile void *allocMemMapIP(int size);
  int intConfig(int num);
  int intEnable(int num);
  int intDisable(int num);
  volatile IP_ID_PROM *getMemBaseID();
  volatile void *getMemBaseIO();
  volatile void *getMemBaseIP();
  int getMemSizeIP();
  unsigned char getManufacturer();
  unsigned char getModel();
  unsigned char getRevision();

private:
  
  ...
};

Serial Support

SerialPort

An abstract base class for a serial port. It allows access to a serial port independent of the specific serial interface.

Implements SerialPort for the Green Springs Quad/Octal IP carrier.

A generic MPF server for SerialPort. It accepts Char8Array messages.

Provides EPICS device support to send  string to a MPF server and receive a reply string.

Because devices attached to serial ports have private protocols, serialServer and devStringMpf may not be usable. In such cases new device support and/or a new server  must be supplied. Usually only new device support is necessary, because serialServer is sufficiently generic.  For special devices a new server may also be needed. SerialServer and devStringMpf provide a model of how to write special support. This section provides details about SerialPort so the the code for serialServer is easier to follow.

SerialPort is independent of MPF and Industry Pack. It can be used as the base class for any type of serial port, i.e. VME, IP, etc. The code for OctalSerial provides a model of what needs to be done to derive from SerialPort.

SerialPort

enum byteHandlerRC {byteHandlerOK,byteHandlerEndRead,byteHandlerError};
enum serialPortStatus
    {serialPortSuccess, serialPortTimeout, serialPortFailure};

typedef byteHandlerRC (*BYTE_HANDLER)(void* parm,unsigned char byte);

typedef void (*PEEK_HANDLER)
    (void* parm,bool isReceive, unsigned char byte);
// If registered PEEK_HANDLER is called for every byte transmitted or received

class SerialPort
{
public:
    SerialPort();

public:
    SerialPort();
    int registerName(const char *portName);
    static SerialPort *find(const char *portName);
    static SerialPort *bind(const char *portName,void* bhparm,BYTE_HANDLER bh);
    void release();
    static bool setSniffHandler(
        const char *portName,void* phParm,PEEK_HANDLER ph);
    static void freeSniffHandler(const char *portName);
    serialPortStatus getStatus() { return(ioStatus);}
    virtual serialPortStatus write(
        unsigned char *data, int nbytes, int timeoutSeconds) = 0;
    virtual serialPortStatus read(int timeoutSeconds) =0;
    virtual serialPortStatus writeRead(
        unsigned char *data, int nbytes, int timeoutSeconds) =0;
    virtual bool config( int baud, int stopBits, int bitsPerChar,
        char parity, char flowControl) = 0;
    void clientStartIoTimeout(int seconds);
protected:
    void startIoTimeout(int seconds);
    void waitIo();
    requestType request;
    serialPortStatus ioStatus;
    BYTE_HANDLER bh;
    void* bhParm;
    PEEK_HANDLER ph;
    void* phParm;
    SEM_ID ioComplete;

private:

    ...

};

The bind call must supply a byte handler which is called for every input character received by the serial port. The byte handler returns one of the following values.
 

Byte Handler Return Codes

byteHandlerOK	If any read request is outstanding, just continue.
byteHandlerEndRead	If any read request is outstanding terminate it with success.
byteHandlerError	If any read request is outstanding terminate it with failure.

OctalUART Support

initOctalUART("moduleName","carrierName","carrierSite",nports,intVec)

After the OctalUart is initialized each port can be initialized via the command.
 

initOctalUARTPort("portName","moduleName",port,baud,"parity",
    stop_bits,bits_char,"flowType")

serialServer

When serialServer receives a SerialConfigMessage it calls SerialPort::config and returns an Int32Message. A status of 0 means success.

When serialServer receives a Char8Array message it returns  a Char8Array message. The return message contains any characters read and a status value which has one of the following values:
 

serialServerStatusOK	Request operation OK
serialServerStatusTimeout	Operation timeout.
serialServerStatusOverflow	Input buffer overflow
serialServerStatusError	Other error

The cmd field of the Char8Array message can contain a command and also options. The commands are:
 

cmdWrite	Write value to the port. A Char8Array message is returned. Only the status field is of interest.
cmdRead	Read from from the serial port. A Char8Array message is returned. The value contains the input. Status should always be checked. Input is read until the first of the following occurs: 1) the end of message string is read, 2) extra is non zero and extra bytes are read, 3) A read buffer overflow occurs, or 4) a timeout occurs.
cmdWriteRead	The output string is sent to the serial port and a input string read. The port is enabled for input BEFORE any bytes are sent to the port.

The cmd field can also contain the following options:
 

cmdFlush	Flush the input buffer before starting I/O. This is useful when circularBuffer mode is enabled.
cmdStartCircularBuffer	Start circular buffer mode. When circular buffer mode is enabled, input is accepted even when no read request is present.
cmdStopCircularBuffrer	Stop circularBuffer mode, i.e. ignore any input characters unless an input request is active.
cmdSetEom	Set end of message string. If the option is set then the fields eomLen and eomString determine the new end of message string.

The following additional fields of the Char8ArrayMessage are also honored by the serialServer:
 

timeout	The timeout value in seconds. This field must be set.
numberRetrys	Number of times to retry the request if the initial request fails.
extra	If extra <= 0 then it is ignored. If extra is > 0 then it is the maximum number of bytes to read before ending the read. Disabling the end of message string and specifying extra allows serialServer to read binary data.
eomLen	If cmdSetEom is set, this field determines the length of the end of message string. It can have the value 0, 1, or 2. A zero value disables the end of message string. If the value is 1 or 2 the string is determined by eomString
eomString	If cmdSetEom is set and eomLen is 1 or 2, this is the end of message string.

The following command initializes a serial server:

initSerialServer("serverName","portName",bufSize,queuesize,"eomstr",circularBufferMode)

Discussion of Circular Buffer Mode

Circular Buffer mode is provided for devices that respond with multiple lines of output in response to a single command request. Although it is possible to run with circular buffer mode always enabled this is not recommended because, if any errors occur, it is possible for writes and reads to get "out of sync". A better way to handle multiline requests is the following:

• The command is requested as

cmd = cmdWrite | cmdFlush | cmdStartCircularBuffer
• Each input line is read with

cmd = cmdRead

devStringMpf

• devSiMpfWriteRead - device choice is "MPFwriteRead"
• devSiMpfRead - device choice is "MPFread"
• devSoMpfWrite - device choice is "MPFwrite"

A record which uses MPFwriteRead has DTYP and INP defined as follows:

record(stringin,"<pvname>")
{
    field(DTYP,"MPFwriteRead")
    field(INP, "#C<location> S0 @<server>,<inputRecord>")
}

When the record is processed the following happens:

• A dbGet, with a DBR_STRING request type, gets a string from inputString. The inputRecord MUST reside in the same cpu. Since a dbGet is used, the record is not locked while reading the value.
• The string obtained by dbGet is put into a Char8Array message and sent to the server with a cmdWriteRead request.
• When the server sends a reply message the record is updated.

• The message sent to the serial port always ends with a '0' character.
• It is not possible to specify a terminator for input. initSerialServer, however, accepts the argument eomstr, which is the terminator. Thus if all input messages have the same terminator, this is a way to specify the terminator. Note however that the terminator must be a single character.

A record which uses MPFread has DTYP and INP defined as follows:

record(stringin,"<pvname>")
{
    field(DTYP,"MPFread")
    field(INP, "#C<location> S0 @<server>")
}

record(stringout,"<pvname>")
{
    field(DTYP,"MPFwrite")
    field(OUT, "#C<location> S0 @<server>")
}

DISCUSSION

Also what do we do about null terminators for strings? serialServer does not add or remove null terminator nor should it. What about device or record support?  If we have serialPortRecord we could have additional options to handle this. What about flow control? How do we handle this in a generic way? What else am I missing?

Gpib Support

• Gpib - An abstract base class.
• gpibSniff - The module that implements sniff for gpib.
• GpibGsTi9914 - Support for the Green Springs GPIB IP using the ti9914.
• GpibHideosLocal - This is an interface between the EPICS base drvGpib support and Gpib residing on the same processor. It does NOT use the MPF.
• GpibHideosRemote - This is an interface between the EPICS base drvGpib support and Gpib residing on another processor. It uses MPF to pass requests and replies between the processors.

Restriction: Only one of GpibHideosLocal or GpibHideosRemote can be used on a particular processor. Removing this restriction requires changes to the version of drvGpib supplied with base.

Systran DAC128V Support

mpf/dac128VApp/src/dac128VREADME

ip330Scan

Device support sends Int32Messages with the following info:

address - channel
value - gain

value - 32 bit unsigned integer from 0 to 0xffff
status - 0 means success. -1 means failure

initIp330Scan("modulename","carrier","site",
    "type","range",intVec,queueSize)

The device definition is:

device(ai,VME_IO,devAiIp330Scan,"ip330Scan")

field(SCAN,"1 second")
field(DTYP,"ip330Scan")
field(INP,"#C{card} S{signal} @{servername},{gain}

The following summerizes the configuration options. The DIP Switch Settings column correspond to the value switches 1 - 10. A value of 101100001 corresponds to switches 1,3,4,9 on and 2,5,6,7,8 off.
 

Range	DIP Switch	Gain	Full Value	Low Value
-5to5	1011000010	0	5	-5
-5to5	1011000010	1	2.5	-2.5
-5to5	1011000010	2	1.25	-1.25
-5to5	1011000010	3	0.625	-.0625
-10to10	0100110010	0	10	-10
-10to10	0100110010	1	5	-5
-10to10	0100110010	2	2.5	-2.5
-10to10	0100110010	3	1.25	-1.25
0to5	1010100100	0	5	0
0to5	1010100100	1	2.5	0
0to5	1010100100	2	1.25	0
0to5	1010100100	3	0.625	0
0to10	1011001000	0	10	0
0to10	1011001000	1	5	0
0to10	1011001000	2	2.5	0
0to10	1011001000	3	1.25	0

Note for Hideos Users

This support is similar to the hideos ip330adc support. The main differences for database records are:

• The DTYP has changed
• The INP field has a different format.
• Callibration records are no longer required. Callibration is now done automatically
• The device definition has changed

EXAMPLE Implementation: ip330Scan

devAiIp330Scan.cc

class DevAiIp330Scan : public DevMpf
{
public:
        DevAiIp330Scan(dbCommon*,DBLINK*);
        long startIO(dbCommon* pr);
        long completeIO(dbCommon* pr,Message* m);
        long convert(dbCommon* pr,int pass);
        static long dev_init(void*);
private:
        int channel;
        int gain;
};

MAKE_LINCONV_DSET(devAiIp330Scan,DevAiIp330Scan::dev_init)

DevAiIp330Scan::DevAiIp330Scan(dbCommon* pr,DBLINK* l)
: DevMpf(pr,l,false)
{
    vmeio* io = (vmeio*)&(l->value);
    gain = 0;
    channel=io->signal;
    aiRecord* prec=(aiRecord*)pr;
    const char* up = getUserParm();
    if(up && strlen(up)>0) {
        // decode the parm field, format: "gain"
        if((sscanf(up,"%d",&gain)<1) || gain<0 || gain>3) {
            epicsPrintf("%s Illegal INP parm field\n", prec->name);
            prec->pact=TRUE;
        }
    }
    convert((dbCommon *)prec,1);
    return;
}

long DevAiIp330Scan::startIO(dbCommon* )
{
    Int32Message *message = new Int32Message;
    message->value =gain;
    message->address =channel;
    return(sendReply(message));
}

long DevAiIp330Scan::completeIO(dbCommon* pr,Message* m)
{
    aiRecord* pai = (aiRecord*)pr;
    if((m->getType()) != messageTypeInt32) {
        epicsPrintf("%s ::completeIO illegal message type %d\n",
                    pai->name,m->getType());
        recGblSetSevr(pai,READ_ALARM,INVALID_ALARM);
        delete m;
        return(MPF_NoConvert);
    }
    Int32Message *pint32Message = (Int32Message *)m;
    if(pint32Message->status) {
        recGblSetSevr(pai,READ_ALARM,INVALID_ALARM);
        delete m;
        return(MPF_NoConvert);
    }
    pai->rval=pint32Message->value;
    pai->udf=0;
    delete m;
    return(MPF_OK);
}

long DevAiIp330Scan::convert(dbCommon* pr,int /*pass*/)
{
    aiRecord* pai = (aiRecord*)pr;
    pai->eslo=(pai->eguf-pai->egul)/(double)0xffff;
    return 0;
}

long DevAiIp330Scan::dev_init(void* v)
{
        aiRecord* pr = (aiRecord*)v;
        DevAiIp330Scan* pDevAiIp330Scan
            = new DevAiIp330Scan((dbCommon*)pr,&(pr->inp));
        return pDevAiIp330Scan->getStatus();
}

ip330ScanServer.cc

class Ip330ScanServer {
public:
    Ip330Scan *pIp330Scan;
    MessageServer *pMessageServer;
    static void ip330Server(Ip330ScanServer *);
};

static char taskname[] = "ip330";
extern "C" int initIp330Scan(
    const char *moduleName, const char *carrierName, const char *siteName,
    const char *typeString,const char *rangeString, int intVec,
    int queueSize)
{
    Ip330Scan *pIp330Scan = Ip330Scan::init(moduleName,carrierName,siteName,
        typeString,rangeString,intVec);
    if(!pIp330Scan) return(0);
    Ip330ScanServer *pIp330ScanServer = new Ip330ScanServer;
    pIp330ScanServer->pIp330Scan = pIp330Scan;
    pIp330ScanServer->pMessageServer = new MessageServer(moduleName,queueSize);
    int taskId = taskSpawn(taskname,100,VX_FP_TASK,2000,
        (FUNCPTR)Ip330ScanServer::ip330Server,(int)pIp330ScanServer,
        0,0,0,0,0,0,0,0,0);
    if(taskId==ERROR)
        printf("%s ip330Server taskSpawn Failure\n",
            pIp330ScanServer->pMessageServer->getName());
    return(0);
}

• Calls Ip330Scan::init which creates a new instance of Ip330Scan. All IP support modules require the arguments moduleName, carrierName, and siteName. The arguments typeString, and rangeString are specific to the ip330. The argument intVec  is common to any IP modules that uses interrupts.
• Creates a new instance of Ip330ScanServer and initializes the address of the Ip330Scan which was just created.
• Creates a new MessageServer and stores it's address in Ip330ScanServer. Since this implementation only allows a single MessagerServer for each Ip330Scan it makes the serverName the same as the moduleName. queueSize is set to the maximum number of messages that the server can queue.
• Spawns a task that executes ip330Server.

void Ip330ScanServer::ip330Server(Ip330ScanServer *pIp330ScanServer)
{
    while(true) {
        MessageServer *pMessageServer = pIp330ScanServer->pMessageServer;
        Ip330Scan *pIp330Scan = pIp330ScanServer->pIp330Scan;
        pMessageServer->waitForMessage();
        Message *inmsg;
        while((inmsg = pMessageServer->receive())) {
            if(inmsg->getType()!=messageTypeInt32) {
                printf("%s ip330Server got illegal message type %d\n",
                    pMessageServer->getName(), inmsg->getType());
                delete inmsg;
            } else {
                Int32Message *pmessage = (Int32Message *)inmsg;
                pmessage->status = 0;
                int gain = pmessage->value;
                int channel = pmessage->address;
                if(pIp330Scan->setGain( gain,channel)) pmessage->status= -1;
                if(pmessage->status==0) {
                    pmessage->value = (int32)pIp330Scan->getValue(channel);
                }
                pMessageServer->reply(pmessage);
            }
        }
    }
}

Ip330Scan.h

class WatchDog;
class MessageServer;
class IndustryPackModule;
class ip330ADCregs;
class ip330ADCchans;

enum signalType {differential, singleEnded};
class Ip330Scan
{
public:
    static Ip330Scan * init(
        const char *moduleName, const char *carrierName,
        const char *siteName,
        const char *type,const char *range,int intVec);
    int getValue(int channel);
    int setGain(int gain,int channel);
private:
    Ip330Scan(IndustryPackModule *pIndustryPackModule,
         signalType type, int range, int intVec);
    ...

};

Ip330Scan.cc

Ip330Scan * Ip330Scan::init(
    const char *moduleName, const char *carrierName, const char *siteName,
    const char *typeString,const char *rangeString, int intVec)
{
    IndustryPackModule *pIPM = IndustryPackModule::createIndustryPackModule(
        moduleName,carrierName,siteName);
    if(!pIPM) return(0);
    unsigned char manufacturer = pIPM->getManufacturer();
    unsigned char model = pIPM->getModel();
    if(manufacturer!=ACROMAG_ID) {
        printf("initIp330Scan manufacturer 0x%x not ACROMAG_ID\n",
            manufacturer);
        return(0);
    }
    if(model!=ACRO_IP330) {
       printf("initIp330Scan model 0x%x not a ACRO_IP330\n",model);
       return(0);
    }
    .... // device specific details
    Ip330Scan *pIp330Scan = new Ip330Scan(pIPM,type,range,intVec);
    return(pIp330Scan);
}

Ip330Scan:: Ip330Scan(
    IndustryPackModule *pIndustryPackModule,
    signalType type, int range, int intVec)
: pIPM(pIndustryPackModule), type(type), range(range), accumulated(0)
{
    ... // device specific details
    pIPM->intConfig(0); pIPM->intConfig(1);
    if(intConnect(INUM_TO_IVEC(intVec),(VOIDFUNCPTR)intFunc,(int)this)==ERROR){
        printf("Ip330Scan intConnect Failure\n");
    }
    pIPM->intDisable(0);
    pIPM->intClear(0);
    ... // device specific details
}

Performance

The local tests were run on an mv162. The remote tests were run on an mv167 client  and mv162 server. I think they were both 25 MHz processors. msgPerSec and tcpPerSec are round trip, i.e. a send and receive. The message in all cases was just an Int32 value. The no buffer case means that a value was sent and the client waited for that response before sending the next message. The buffer case means that the specified number of values were sent before waiting for the responses.

Raw TCP  performance

MPF Performance

EPICS to remote server performance

octalSerialPort performance