License Agreement

MPF is available via the open source license described at the end of this document.

Contents

MPF

MPF Serial Support

Introduction

MPFOSI (Message Passing Facility Operating System Independent) is the successor to MPF (See next section). The main goal is to provide an EPICS 3.14 migration path for existing MPF users. MPFOSI uses the Operating System Independent features of EPICS base 3.14 and should work on all 3.14 IOC platforms.

NOTE: This version has only been tested with the MPF client and server on the same IOC. The remote server mode is not built. If remote server mode is dropped then support for user defined message types can be added.

This document describes the following components:

Message Passing Facility

MPF provides client server message passing. The messages are handled by message routers. A local message router is provided.

A base class DevMpf is provided for writing epics device support that communicates with MPF.

Serial support that interfaces to asynDriver. All low level asyn drivers that implement the asynCommon and asynOctet interfaces are this accessable by MPF.

All code is written in C++. It is written to minimize dependencies between various components. The standard C library but not the standard C++ library is used.

Acknowledgments

MPF is the successor to HIDEOS which was written with the following goals:

• Support Industry Pack modules on an MV162 VME processor with limited memory. This required the development of a small standalone operating system.
• Communicate with an EPICS processor residing in the same VME crate via the VME backplane.
• Support a variety of IP modules.

When other IP carriers became available, it was decided that that it was too time consuming to support processors besides the MV162. Thus MPF was developed. It supports the same type of client server relationship as Hideos but support two types of communication: 1) If the client and server reside on the same processor, messages are passed in memory, and 2) If the client and server reside on different processors, message are passed via TCP. The original MPF was only supported on vxWorks. When EPICS base evolved to be Operating System Independent (OSI), the OSI version of MPF was devloped. When this document refers to MPF it means the OSI version. When it refers to EPICS base it means the OSI version of base.

The following people have contributed to MPF:

Jim Kowalkowski

Jim developed HIDEOS, the precursor of MPF. Many of the basic ideas for MPF come from Hideos. In addition the IP support for the ip330, GpibGsTi9914, OctalUart, and dac128 started with the Hideos support for these modules

Joe Sullivan

Joe developed the vxWorks board support packages that allow VME back plane communication.

Tom Coleman

Tom developed the original 162 Industry Pack Support and GpibGsTi9914 for MPF.

Mohan Ramanathan

Mohan was an early user of MPF and suffered patiently through the initial problems.

Andrew Johnson

Andrew made the changes so that IPAC support could be used with MPF.

Mark Rivers

Mark contributed many ideas that make the serial support general purpose, ,which is described eleswhere. He also developed support for digital and analog support which is also described elsewhere.

Requires

• Epics base release 3.14.5 or later
• IPAC 2.7 or later
• asynDriver 1.1 or later

Install and Build MPF

Installation and Building

1. Create an installation directory for the module, usually this will end with

.../support/mpfosi/

2. Place the distribution file in this directory. Then issue the commands (Unix style)

gunzip <file>.tar.gz
tar xvf <file>.tar

3. This creates a <top> application with EPICS base 3.14 style rules.

.../support/mpfosi/mpfosiX-Y

where X-Y is the release. For example.

.../support/mpfosi/mpf2-1

4. Edit the configure/RELEASE file and set the paths to ASYN, IPAC, and EPICS_BASE. Each of these must be built before mpfosi.
5. Run make in the top level directory and check for any compilation errors.

Now proceed to the next two sections.

Getting Started

The iocBoot directory has a number of sub directories for running mpf tests and/or examples. The best example is a test which connects an epics database to a mpf server. To start the test:

• Start the IOC

  cd iocBoot/iocepicslocal
  ../../bin/<arch>/test st.cmd
          

• Run medm from <top>/testApp/adl and ask for file epicsTest.adl

• serverInt32 is started. It just echoes any Int32 message sent to it.
• The client has 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.
• The medm display allows you to set the scan rate for all client records.

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

Using MPF in Applications

It is a good idea to keep mpf separate from applications which use it. An application can access mpf components by making the following changes:

• In <top>/configure/RELEASE add the line:

  MPF=<full path name>

• In the Makefile where the application is built add the following:

  <prod>_LIBS += mpf asyn
      # For vxWorks applications only
      #<prod>_LIBS += Ipac TyGSOctal
  <prod>_LIBS += $(EPICS_BASE_IOC_LIBS)

The xxxInclude.dbd file must include some combination of the following:

include "mpf.dbd"
include "devStringMpf.dbd"
include "mpfSerial.dbd"
include "mpfSerialVx.dbd"

NOTE:

• mpf.dbd is always needed
• devStringMpf.dbd is needed only if you use devStringMpf
• mpfSerial.dbd is required for serial support on non-vxWorks systems
• mpfSerialVx.dbd is required for serial support on vxWorks systems.

  mpfSerialVx.dbd contains a registrar command for the IPAC carrier support that works on an MV162. It also includes registrar commands for other IPAC carrier support. Most applications will have to copy mpfSerialVx.dbd to where the application is build and modify it so that the correct carrier support is chosen.

The st.cmd file must contain commands to start MPF routers and MPF servers. Look at the iocBoot/iocxxx/st.cmd files provided with MPF for examples.

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

Epics Record to MPF server - Flow of Control

INP("C1 S0 @Int32")

• C1 identifies the location of the server. Location is described below in the section on Router Configuration.
• S0 is not used
• Int32 is the name of the MPF supplied server

• The ai record support module calls DevMpf::read_write.
• DevMpf calls DevMpfInt32Test::startIO.
• startIO calls DevMpf::sendReply.
• LocalRouter puts the message on the  serverInt32 queue.
• DevMpfInt32Test , DevMpf and record support finish the beginning phase of asynchronous record processing.
• The serverInt32 task wakes up from MessageServer::waitForMessage.
•  serverInt32 calls MessageServer::receive.
• For more complicated servers some other code, i.e. ip support would then be called. The simple example just echos the received message.
• serverInt32 calls MessageServer::reply.
• DevMpf::messageClientCallback is called.
• DevMpf make an epics callbackRequest.
•  serverInt32 again calls MessageServer::waitForMessage.
• The epics callback task calls DevMpf::callDeviceSupport which calls the RSET::process.
• The ai record support module calls DevMpf::read_write which calls DevMpfInt32Test::completeIO.
• DevMpfInt32Test, DevMpf, and record support finish the asynchronous completion phase of record processing.

Diagnostic Aids

WARNING: A queue overflow usually means that the queue size was made too small.

mrr

It provides a report like the following:

mrr
clientRouterList
 1 LMRClient
   sendPerSec 0
serverRouterList
 1 LMRServer
   replyPerSec 0

msr ("serverName")
msr

msr "Int32"
Int32
         queueSize 10
           inQueue 0
     queueRequests 132171
queueFullResponses 0
     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.

Message Routers

This version only supports a local message router. All mention of router should be removed from MPFOSI.

NOTE: In the future I hope that support for client and server on separate IOCs can be abandoned. If it is then the concept of message routers will go away. For now the localMessageRouter must be started.

The local message router passes message between a client and server residing in the same processor. When the client passes a message to a server the message is just appended to the server's queue. When the server sends a reply to the client, the client processes the message immediately. Thus when a client sends to the server the client never waits for the server. The server, however, will wait for the client to process a reply message.

The local message router must be started.

localMessageRouterStart(location)

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.

The definition of class Message is:

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);
    ....
}

Client and server code normally only call new, delete, the methods described in the following table, and message specific methods. The other methods are called by MPF itself. A message is allocated via a call to new and released via a call to delete. When delete is called the message is placed on a free list. Only one of the message types derived from Message can be created, i.e. it is not possible to create an object of type Message.

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.

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.cpp 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.
 

Int32Message

Int32ArrayMessage

Float64Message

Float64ArrayMessage

SerialConfigMessage

OutOfBandMessage

MPF Device support

DevMpf is an abstract base class for implementing EPICS 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
    // The following must be called after object is constructed
    void bind();
    // The following are usefull during record initilization 
    bool connectWait() {return(connectWait(5.0));}
    bool connectWait(double timeout);
    // 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);
    int sendWait(Message *pmessage,replyType type)
        {return(sendWait(pmessage,type,5.0));}
    int sendWait(Message*,replyType,double timeout);
    // This routine gets a pointer to the user portion of the parm field
  
    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;
    bool isConnected() { return((connectState==connectYes) ? true : false);}
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:

• connectWait can be called to wait for connection to the server. This should NOT be called as part of record processing. It is OK in the constructor or in a private thread.
• sendWait can be called to wait until the server processes the message and sends a response. This should NOT be called as part of record processing. It is OK in the constructor or in a private thread.
• 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.
 

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>)

MPF Directory Structure

<top>/
    configure/
           RELEASE
    mpfApp/
           coreSrc/
           messageSrc/
           registerSrc/
           testSrc/
           utilSrc/
           devMpfSrc/
           serialSrc
    testApp/
           adl/
           Db/
           src/
    testSerialApp/
           adl/
           Db/
           src/
    iocBoot/
           iocepicslocal/
           iocmpflocal/
           iocserialhost/
           iocserialvxWorks/

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.

Introduction to Serial Support

NOTE: serialServer is now implemented by using asynDriver. serialServer and asynDriver BOTH create a thread for each serial port. This causes unnecessary context switching. If remote MPF servers are abandoned then a better method can be developed that uses only one thread.

mpfSerial provides support for EPICS records to communicate with serial devices, i.e. RS232, RS485, etc. The basic concept is:

• When a record starts processing, device support sends a message via the Message Passing Facility (MPF) to a serial server.
• The serial server provides a thread which processes the messages it receives from device support. It uses asynDriver to communicate with a low level driver.
• When the serial server completes the operation requested it sends a message via MPF to device support.

The support is structured so that special requirements can be satisfied by writing device support and/or a serial server. As long as this support satisfies the conventions defined in serialserver.h then the low level drivers should still work.

mpfSerial consists of the folowing:

• devStringMpf - device support that communicates with a serial server.
• serialServer - general purpose serial server.

The major difference between the OSI (Operating System Independent) version of mpfSerial and the previous version is that the low lever driver support is asynDriver. This approach allows mpfSerial to be used with anything that asynDriver supports.

NOTE: The only serial device support discussed in this manual is devStringMpf. Most mpfSerial users use the genericBus/serialMpfApp support that comes with SYNAPPS.

Serial Test

To use the the version that uses writeRead requests on Unix/Linux do the following:

cd iocBoot/iocserialhost
../../bin/<arch>/testSerial st.cmd

NOTE: The st.cmd file is for a linux system and MOXA box in my office. It will have to be modified for your environment.

record(calc,"serial$(port):calc$(ind)")
{
    field(SCAN, "Event")
    field(EVNT, "1")
    field(CALC,"a=1000?0:a+1")
    field(FLNK,"serial$(port):StringOut$(ind)")
    field(INPA,"serial$(port):calc$(ind)")
}
record(stringout,"serial$(port):StringOut$(ind)")
{
    field(DOL,"serial$(port):calc$(ind)")
    field(OMSL,"closed_loop")
    field(FLNK,"serial$(port):StringIn$(ind)")
}
record(stringin,"serial$(port):StringIn$(ind)")
{
    field(DTYP,"MPFwriteRead")
    field(INP, "#C$(card) S0 @serial$(port),serial$(port):StringOut$(ind)")
}

• A single event record is loaded. The event record performs a post_event of event number 1.
• Sets of records are created from the template. The stringin record sends messages to a serialServers. There are two sets for each ports.
• An medm display (testSerialApp/adl/epicsSerial.adl) consists of the following:
  • NOTE: The display works for both iocserialhost and iocserialVxworks. For iocserialhost there will be unconnected pvs since there are not enough ports.
  • The first row contains of a controller to change the scan mechanism of the event record. Thus setting this to be periodically scanned causes all the calc records to process.
  • 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.
  • A bash script (testSerialApp/adl/starttrace) starts an medm screen for each port attachs to the asynTrace database. This script works for my test environment. It will have to be modified for yours.

Initialization Commands

This section describes initialization commands that appear in a st.cmd file. A simple example may make this section easier to understand. The following commands initialize everything needed for accessing a single serial port on an x86 Linux based ioc.

localMessageRouterStart(1)
drvGenericSerialConfigure("port0","/dev/ttyS0",0,0)
initSerialServer("serial0","port0",0,1000,2,"")

The following is an example record that connects to this port.

record(stringin,"name")
{
    field(DTYP,"MPFread")
    field(INP, "#C1 S0 @serial0")
}

NOTE: #C1 means DevMpf location 1, which is the argument given to localMessageRouterStart.

mpfSerial initialization Commands

Consult the asynDriver documentation for how to configure port drivers. For example look at the documentation for drvGenericSerialConfigure. The only configuration command provided by mpfSerial is:

int initSerialServer(const char *serverName,const char *portName, int addr,
    int bufsize, int queueSize, const char *eomstr);

The arguments are:

Other Initialization Commands

IPAC and asynDriver initialization commands are also required. Look at the st.cmd files in iocserialhost and iocserialvxWorks for examples. The initialization commands are described in the IPAC and asynDriver documentation.

Example st.cmd file for a Linux x86 IOC

The following example starts two serial ports on the ioc and four serial ports on a MOXA ethernet serial server that resides at address :164.54.9.90 and responds to TCP connect requests at TCP ports 4001,...,4004.

localMessageRouterStart(1)
drvGenericSerialConfigure("port0","/dev/ttyS0",0,0)
drvGenericSerialConfigure("port1","/dev/ttyS1",0,0)
drvGenericSerialConfigure("port2","164.54.9.90:4001",0,0)
drvGenericSerialConfigure("port3","164.54.9.90:4002",0,0)
drvGenericSerialConfigure("port4","164.54.9.90:4003",0,0)
drvGenericSerialConfigure("port5","164.54.9.90:4004",0,0)
initSerialServer("serial0","port0",1000,2,"")
initSerialServer("serial1","port1",1000,2,"")
initSerialServer("serial2","port2",1000,2,"")
initSerialServer("serial3","port3",1000,2,"")
initSerialServer("serial4","port4",1000,2,"")
initSerialServer("serial5","port5",1000,2,"")

Example st.cmd for a vxWorks IOC

The vxWorks support uses the standard vxWorks serial ports and/or drvIpac. The mpf installation includes a test for vxWorks that works on an MV162 with a Green Springs OctalUART installed in slot 2. In the mpf installation look at iocBoot/iocserialvxWorks/st.cmd. See the drvIpac documentation for how to configure other carriers. The example starts eight serial ports for a Green Springs OctalUART Industry Pack module.

Serial Support Theory

mpfSerial support consists of three levels:

• Device support
• Serial server
• asynDriver

mpfSerial provides code for all the first two levels and uses asynDriver for the lowest level. It is designed so that additional code can be written at either bthe Device Support or Serial server levels in order to support special requirements.

The mpfSerial support interface is described in serialServer.h

serialServer.h

The interface between device support and the serial server. The definitions use fields of messages that are defined by MPF.

#define cmdWrite        0x1
#define cmdRead         0x2
#define cmdWriteRead    (cmdWrite|cmdRead)
//Following are additional options
#define cmdFlush        0x4
#define cmdSetEom       0x8
//Following are for serialGetConfig
#define cmdGetConfig    0x1
/*
 * cmdFlush - flush before starting write and/or read
 * cmdSetEom - change current eom
 *
 * for example the following could be specified
 * message->cmd = cmdWriteRead|cmdFlush;
*/
/* Generic serial server messages

SerialConfigMessage.
   This just calls SerialPort::config.
   It returns an Int32Message. status is 0 for success.

Int32Message.
       cmdGetConfig
              Returns a SerialConfigMessage with current settings
Char8ArrayMessage
       cmdWrite        : write request
       cmdRead         : read request
       cmdWriteRead    : writeRead request

       other fields from input message

       timeoutUnits     timeout units.
       timeout          The timeout value in timeoutUnits
       extra            If >0 the maximum number of chars to read

       If cmdSetEom is set

       eomSize          If 0 dont look for eom; otherwise must be 1 or 2
       eomString        1 or 2 character eomString

       Return values
                        A Char8ArrayMessage message, which
                        contains any input characters read

                        status is one of the serialStatus values
*/

serialServer.h is the interface between device suport and a serial server.

Some serial devices have a protocal that is not compatible with serialServer and/or devStringMpf. In such cases new device support and/or a new server must be supplied. SerialServer and devStringMpf provide a model of how to write special support. If a special application requires BOTH new device support and a new server than serialServer.h may not be applicable. If, however, either serialserver or devStringMpf is used then the conventions described in serialServer.h must be followed.

devStringMpf

NOTE: Perhaps NO current mpfSerial users use this for device support, because it provides no nice way of handling termination characters.

• 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.

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>")
}

serialServer

serialServer is a generic server which implements the serialSever.h interface and communicates with low level drivers via the SerialPort interface. It accepts SerialConfig, Int32, and Char8Array messages. Client code must include file "serialServer.h", which contains definitions for commands, options, and for return status.

When serialServer receives a SerialConfigMessage it calls SerialPort::config and returns an Int32Message. The status field in Int32Message is one of the serialStatus values. Low level drivers may only support a subset of the config options.

If an Int32Message is sent to serialServer, the only valid command is cmdGetConfig. It returns a SerialConfigMessage with the current configuration. Low level drivers may only support a subset of the config options.

When serialServer receives a Char8Array message it returns  a Char8Array message. The return message contains any characters read and a serialStatus value.
 

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

The cmd field can also contain the following options:
 

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

License Agreement

Copyright (c) 2002 University of Chicago. All rights reserved.

MPF - Message Passing Facility
MPF is distributed subject to the following license conditions:

 SOFTWARE LICENSE AGREEMENT
 Software: MPF

 1. The "Software", below, refers to MPF (in either source code, or
    binary form and accompanying documentation). Each licensee is
    addressed as "you" or "Licensee."

 2. The copyright holders shown above and their third-party licensors
    hereby grant Licensee a royalty-free nonexclusive license, subject to
    the limitations stated herein and U.S. Government license rights.

 3. You may modify and make a copy or copies of the Software for use
    within your organization, if you meet the following conditions:
      a. Copies in source code must include the copyright notice and this
         Software License Agreement.
      b. Copies in binary form must include the copyright notice and this
         Software License Agreement in the documentation and/or other
         materials provided with the copy.

 4. You may modify a copy or copies of the Software or any portion of it,
    thus forming a work based on the Software, and distribute copies of
    such work outside your organization, if you meet all of the following
    conditions:
      a. Copies in source code must include the copyright notice and this
         Software License Agreement;
      b. Copies in binary form must include the copyright notice and this
         Software License Agreement in the documentation and/or other
         materials provided with the copy;
      c. Modified copies and works based on the Software must carry
         prominent notices stating that you changed specified portions of
         the Software.

 5. Portions of the Software resulted from work developed under a U.S.
    Government contract and are subject to the following license: the
    Government is granted for itself and others acting on its behalf a
    paid-up, nonexclusive, irrevocable worldwide license in this computer
    software to reproduce, prepare derivative works, and perform publicly
    and display publicly.

 6. WARRANTY DISCLAIMER. THE SOFTWARE IS SUPPLIED "AS IS" WITHOUT WARRANTY
    OF ANY KIND. THE COPYRIGHT HOLDERS, THEIR THIRD PARTY LICENSORS, THE
    UNITED STATES, THE UNITED STATES DEPARTMENT OF ENERGY, AND THEIR
    EMPLOYEES: (1) DISCLAIM ANY WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
    BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS
    FOR A PARTICULAR PURPOSE, TITLE OR NON-INFRINGEMENT, (2) DO NOT ASSUME
    ANY LEGAL LIABILITY OR RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS,
    OR USEFULNESS OF THE SOFTWARE, (3) DO NOT REPRESENT THAT USE OF THE
    SOFTWARE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS, (4) DO NOT WARRANT
    THAT THE SOFTWARE WILL FUNCTION UNINTERRUPTED, THAT IT IS ERROR-FREE
    OR THAT ANY ERRORS WILL BE CORRECTED.

 7. LIMITATION OF LIABILITY. IN NO EVENT WILL THE COPYRIGHT HOLDERS, THEIR
    THIRD PARTY LICENSORS, THE UNITED STATES, THE UNITED STATES DEPARTMENT
    OF ENERGY, OR THEIR EMPLOYEES: BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
    CONSEQUENTIAL, SPECIAL OR PUNITIVE DAMAGES OF ANY KIND OR NATURE,
    INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS OR LOSS OF DATA, FOR ANY
    REASON WHATSOEVER, WHETHER SUCH LIABILITY IS ASSERTED ON THE BASIS OF
    CONTRACT, TORT (INCLUDING NEGLIGENCE OR STRICT LIABILITY), OR
    OTHERWISE, EVEN IF ANY OF SAID PARTIES HAS BEEN WARNED OF THE
    POSSIBILITY OF SUCH LOSS OR DAMAGES.