asynDriver: Asynchronous Driver Support

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

• Generic Serial
• vxi11
• Green Springs IP488

asynDriver is a general purpose facility for interfacing device specific code to low level communication drivers

A primary target for asynDriver is EPICS IOC device support but, other than using libCom, it is independent of EPICS.

The following are some of the existing EPICS general purpose device support systems that have been converted to use asynDriver.

• gpibCore is the operating-system-independent version of the Winans/Franksen GPIB support.
• mpfSerial is the serial support provided with MPF (Message Passing Facility)

The following are some of the existing EPICS general purpose device support systems that could be converted to use asynDriver.

• streams is the protocol file based support for serial/GPIB/CAN from Dirk Zimoch.
• devAscii/drvAscii is serial support from KECK Observatory.
• devOrnl is serial support from John Sinclair at Oak Ridge National Lab.

Each of these systems is used at EPICS facilities for accessing GPIB and/or serial devices. Because device support has been written for many instruments and thousands of database records use the device support, users will not be easily persuaded to switch from their existing solution. Thus asynDriver implements a framework below device support that can be used by all of the above systems so that all can share the same drivers.

Each system needs to be modified so that the device support component is compatible with existing use but replace the driver part with asynDriver. The benefit is that all could share the same set of low level drivers.

gpibCore has already been converted and is included with asynDriver.

Marty Kraimer will convert mpfSerial. Hopefully Dirk Zimoch will get time soon to convert streams and Allen Honey time to convert devAscii.

In the future other protocols will be supported especially for Ethernet based devices.

This version provides

• asynManager, i.e. the software layer between device support and drivers.
• devGpib: EPICS device support that replaces the device support layer of the Winans/Franksen gpibCore support.
• asynGpib: a replacement for the drvGpibCommon layer of the Franksen gpibCore support.
• genericSerial: Support for devices connected to serial ports and devices connected through Ethernet/Serial converter boxes.
• vxi11: A replacement for the vxi11 support of the Franksen gpibCore support.
• gsIP488: A low level driver for the Greensprings IP488 Industry Pack module. This support is only implemented for vxWorks.

Coming Soon

• gsIP488:

  The current version does not implement gpib specific methods. This will be done for a future release.

• NI1014:

  The National Instruments 1014 VME to GPIB driver has not been converted to asynDriver. This also will be done for a future release.

Remaining Issues

• Locking data structures:

  asynManager locks it's internal data structures so that modifications are thread safe. One exception is that report does not lock. If new ports or process modules are registered while report is active, report could have problems. Does this matter?

• Interrupts:

  Interface asynGpib defines methods to handle SRQs. Should a more general interrupt mechanism be provided? Perhaps is is best to wait until a need arises.

The idea of creating asynDriver resulted from many years of experience with writing device support for serial and GPIB devices. The following individuals have been most influential.

John Winans

John provided the original EPICS GPIB support. Databases using John's support can be used without modification with devGpib. With small modifications, device support modules written for John's support can be used.

Benjamin Franksen

John's support only worked on vxWorks. In addition the driver support was implement as a single source file. Benjamin defined an interface between drvCommon and low level controllers and split the code into drvGpib and the low level drivers. He also created the support for drvVxi11.

Eric Norum

Eric started with Benjamin's code and converted it to use the Operating System Independent features of EPICS 3.14.

Marty Kraimer

Marty started with Eric's version and made changes to support secondary addressing and to replace ioctl with code to support general bus management, universal commands, and addressed commands.

Pete Owens

Pete, for the Diamond Light Source, did a survey of several types of device/driver support packages for serial devices. Diamond decided to use the streams support developed by Dirk Zimoch.

Dirk Zimoch

Dirk developed streams, which has a single device support model, but supports arbitrary low level message based drivers, i.e. GPIB, serial, etc.

Jun-ichi Odagare

Jun-ichi developed NetDev, a systems that provides EPICS device support for network based devices. It has a single device support model but provides a general framework for communicating with network based devices.

asynDriver is a software layer between device specific code and communication drivers that send/receive messages to/from devices. asynDriver defines the following terminology:

• interface

  All communication between software layers is done via interfaces. An interface definition is a C language structure consisting entirely of methods (functions). An asynDriver interface is analogous to a C++ or Java pure virtual interface.

• port

  A communication entity over which message are sent. Whenever this document uses the word port without a qualifier, it means a communication port. A port provides access to one or more devices.

The interfaces are defined so that most device specific code can communicate via a large variety of different types of port. If device support does all it's communication via reads and writes of messages consisting of 8 bit bytes (octets) then it should work with almost all types of port. If device support requires more complicated support then the types of ports will be more limited.

Examples of ports are GPIB controllers, serial ports, Ethernet ports, etc. One or more devices can be attached to a port. For example only one device can be attached to an RS-232 port but up to 15 devices can be attached to a GPIB port.

Multiple layers can exist between device specific code and a port driver. A process module can be registered with the queue manager. Just like a port driver a process module implements interfaces. The asynManager:findInterface method looks first for process module interfaces and then for driver interfaces. A process module normally calls drivers as part of it's processing.

For more complicated protocols additional layers can be created. For example GPIB support is implemented as an asynGpib interface which is called by user code and a asynGpibPort interface which is called by asynGpib.

A driver can implement multiple interfaces. For example asynGpib implements asynCommon, asynOctet, and asynGpib.

Asynchronous driver support uses the Operating System Independent features of EPICS base. It is, however, independent of record/device support. Thus it can be used by other code, e.g. a sequence program.

Asynchronous Driver Components

• asynManager

  Provides the following services.

  • A thread for each communication port.
  • A method to connect to a device.
  • A method for locating port driver interfaces.
  • queueRequest. This is a non-blocking method, i.e. it can be called from scan threads. A callback specified by the user is called by the interface thread. The user callback can then make an arbitrary number of calls to the driver. These calls may be blocking calls.
  • A transaction service, i.e. user code can lock out other users while it makes multiple queueRequest.
• asynCommon

  asynCommon is a set of methods that must be implemented by all drivers. The methods are:

  • report - Report status of device.
  • connect - Open the port.
  • disconnect - Close the port.
  • setPortOption - Set port option.
  • showPortOption - Show port option.
• asynOctet

  asynOctet is a set of methods implemented by any driver that accepts octet messages (messages consisting of 8-bit bytes) and returns octet responses. This interface will be sufficient for most device specific code. For example the code for streams protocol files needs only this interface. The term octet is used instead of ASCII because the only requirement is that messages consist of 8-bit bytes. The methods are:

  • read - input a message. The routine returns the number of 8-bit bytes read from the device or -1 to indicate error.
  • write - output a message. The routine returns the number of 8-bit bytes written to the device or -1 to indicate error.
  • flush - if input is buffered flush the buffer.
  • setEos - Specify an end of message string for detecting the end of input messages.
  • getEos - Get the currect end of message string.>/li>
• asynTrace

  asynTrace is a set of methods for generating diagnostic messages.

Overview of implementation

During initialization a driver registers each communication port with asynManager.

User code creates an asynUser by calling pasynManager->createAsynUser. The address of the asynUser is passed to most other asynDriver methods.

User code connects to a device, which is located located at some address on a port, and communicates with the device via combination of asynManager and one or more interfaces.

User code communicates with drivers via the following method:

1. It calls:

    pasynManager->queueRequest(...)

2. The callback specified in createAsynUser calls the driver via one of the driver interfaces.

Comments:

1. Streams, devAscii, and mpfSerial need only asynManager and asynOctet. devGpib needs only asynManager, asynCommon, asynOctet, and asynGpib.
2. It is expected that most users will connect to these interfaces via device support. However other code can call it. Examples are sequence programs, test programs, utility commands, etc.
3. Device support can consist of more than one type of support. For example most functions could be accessed via steams but asynGpib could be used to handle SRQs.

asynDriver.h

asynDriver.h contains the following definitions:

typedef enum {
    asynSuccess,asynTimeout,asynOverflow,asynError
}asynStatus;

typedef enum {
    asynQueuePriorityLow,asynQueuePriorityMedium,asynQueuePriorityHigh
}asynQueuePriority;

typedef struct asynUser {
    char *errorMessage;
    int errorMessageSize;
    /* The following can be set by the user */
    double timeout;  /*Timeout for I/O operations*/
    void *userPvt;
}asynUser;

typedef void (*userCallback)(asynUser *pasynUser);

typedef struct asynInterface{
    const char *interfaceType; /*For example asynCommonType*/
    void *pinterface;          /*For example pasynCommon */
    void *drvPvt;
}asynInterface;

typedef struct asynManager {
    void       (*report)(FILE *fd,int details);
    asynUser  *(*createAsynUser)(userCallback queue,userCallback timeout);
    asynStatus (*freeAsynUser)(asynUser *pasynUser);
    asynStatus (*connectDevice)(asynUser *pasynUser,
                                const char *portName,int addr);
    asynStatus (*disconnectDevice)(asynUser *pasynUser);
    asynInterface *(*findInterface)(asynUser *pasynUser,
                                const char *interfaceType,int processModuleOK);
    asynStatus (*queueRequest)(asynUser *pasynUser,
                              asynQueuePriority priority,double timeout);
    /*cancelRequest returns (0,-1) if request (was, was not) queued*/
    int        (*cancelRequest)(asynUser *pasynUser);
    asynStatus (*lock)(asynUser *pasynUser);   /*lock portName,addr */
    asynStatus (*unlock)(asynUser *pasynUser);
    int        (*getAddr)(asynUser *pasynUser);
    /* drivers call the following*/
    asynStatus (*registerPort)(const char *portName,
                              asynInterface *paasynInterface,int nasynInterface,
                              unsigned int priority,unsigned int stackSize);
    /* paasynInterface is pointer to array of asynInterface */
    /*process modules call the following */
    asynStatus (*registerProcessModule)(
                    const char *processModuleName,const char *portName,int addr,
                    asynInterface *paasynInterface,int nasynInterface);
}asynManager;
epicsShareExtern asynManager *pasynManager;

/*Methods supported by ALL asyn drivers*/
#define asynCommonType "asynCommon"
typedef struct  asynCommon {
    void       (*report)(void *drvPvt,FILE *fd,int details);
    /*following are to connect/disconnect to/from hardware*/
    asynStatus (*connect)(void *drvPvt,asynUser *pasynUser);
    asynStatus (*disconnect)(void *drvPvt,asynUser *pasynUser);
    /*The following are generic methods to set/get port options*/
    asynStatus (*setPortOption)(void *drvPvt, asynUser *pasynUser,
                                const char *key, const char *val);
    asynStatus (*getPortOption)(void *drvPvt, asynUser *pasynUser,
                                const char *key, char *val, int sizeval);
}asynCommon;

/* Methods supported by low level octet drivers. */
#define asynOctetType "asynOctet"
typedef struct asynOctet{
    int        (*read)(void *drvPvt,asynUser *pasynUser,
                       char *data,int maxchars);
    int        (*write)(void *drvPvt,asynUser *pasynUser,
                        const char *data,int numchars);
    asynStatus (*flush)(void *drvPvt,asynUser *pasynUser);
    asynStatus (*setEos)(void *drvPvt,asynUser *pasynUser,
                         const char *eos,int eoslen);
    asynStatus (*getEos)(void *drvPvt,asynUser *pasynUser,
                         char *eos, int eossize, int *eoslen);
}asynOctet;

/*asynTrace is implemented by asynManager*/
/*All asynTrace methods can be called from any thread*/
/* traceMask definitions*/
#define ASYN_TRACE_ERROR     0x0001
#define ASYN_TRACEIO_DEVICE  0x0002
#define ASYN_TRACEIO_FILTER  0x0004
#define ASYN_TRACEIO_DRIVER  0x0008
#define ASYN_TRACE_FLOW      0x0010

/* traceIO mask definitions*/
#define ASYN_TRACEIO_NODATA 0x0000
#define ASYN_TRACEIO_ASCII  0x0001
#define ASYN_TRACEIO_ESCAPE 0x0002
#define ASYN_TRACEIO_HEX    0x0004

/* asynPrint and asynPrintIO are macros that act like
   int asynPrint(asynUser *pasynUser,int reason, const char *format, ... );
   int asynPrintIO(asynUser *pasynUser,int reason,
        const char *buffer, int len, const char *format, ... );
*/
typedef struct asynTrace {
    /* lock/unlock are only necessary if caller performs I/O other then*/
    /* by calling asynTrace methods                                    */
    asynStatus (*lock)(asynUser *pasynUser);
    asynStatus (*unlock)(asynUser *pasynUser);
    asynStatus (*setTraceMask)(asynUser *pasynUser,int mask);
    int        (*getTraceMask)(asynUser *pasynUser);
    asynStatus (*setTraceIOMask)(asynUser *pasynUser,int mask);
    int        (*getTraceIOMask)(asynUser *pasynUser);
    asynStatus (*setTraceFILE)(asynUser *pasynUser,FILE *fd);
    FILE       *(*getTraceFILE)(asynUser *pasynUser);
    asynStatus (*setTraceIOTruncateSize)(asynUser *pasynUser,int size);
    int        (*getTraceIOTruncateSize)(asynUser *pasynUser);
    int        (*print)(asynUser *pasynUser,int reason, const char *pformat, ...);
    int        (*printIO)(asynUser *pasynUser,int reason,
               const char *buffer, int len,const char *pformat, ...);
}asynTrace;
epicsShareExtern asynTrace *pasynTrace;

asynUser

asynUser describes a structure that user code must provide for most asynManager and driver methods. Code must allocate and free an asynUser by calling asynUserCalloc and asynUserFree.

epicsSnprintf(pasynUser->errorMessage,pasynUser->errorMessageSize,"<format>",...)

asynManager

asynManager contains the following methods.

asynInterface *pasynInterface;
asynOctet *pasynOctet;
void *pasynOctetPvt;
...
pasynInterface = pasynManager->findInterface(
        pasynUser,asynOctetType,1);
if(!pasynInterface) { /*error do something*/}
pasynOctet = (asynOctet *)pasynInterface->pinterface;
pasynOctetPvt = pasynInterface->pdrvPvt;
...
pasynOctet->read(pasynOctetPvt,pasynUser,...
        

asynCommon

asynCommon describes the methods that must be implemented by all drivers.

asynOctet

NOTE: The name octet is used instead of ASCII because it implies that communication is done via 8-bit bytes.

asynOctet describes the methods implemented by drivers that use octet strings for sending commands and receiving responses from a device.

asynTrace

asynDriver provides a trace facility with the following attributes:

• Tracing is turned on/off for individual instruments, i.e. a portName,addr
• The output is sent to a file or to stdout.
• A mask determines the type of information that can be displayed.
  • ASYN_TRACE_ERROR Run time errors are reported, e.g. timeouts.
  • ASYN_TRACEIO_DEVICE High level device support reports I/O activity.
  • ASYN_TRACEIO_FILTER Any layer between device support and the low level driver reports any filtering it does on I/O.
  • ASYN_TRACEIO_DRIVER Low level driver reports I/O activity.
  • ASYN_TRACE_FLOW Report logic flow. Device support should report all queue requests, callbacks entered, and all calls to drivers. Layers between device support and low level drivers should report all calls they make to lower level drivers. Low level drivers should only report calls they make to other support.
• Another mask determines how message buffers are printed.
  • ASYN_TRACEIO_NODATA Dont print any data from the message buffers
  • ASYN_TRACEIO_ASCII Print with a "%s" style format.
  • ASYN_TRACEIO_ESCAPE Call epicsStrPrintEscaped.
  • ASYN_TRACEIO_HEX Print each byte with " %2.2x".

In order for the trace facility to perform properly, device support, and all drivers must use the trace facility according to the above guidelines. Device and driver support can directly call the asynManager methods. The asynPrint and asynPrintIO macros are provided so that it is easier for device/driver support. Support can have calls like.

    asynPrintIO(pasynUser,ASYN_TRACE_FLOW,"%s Calling queueRequest\n",
        someName);

The asynPrintIO call is designed for device support or drivers that do not know it they are sending ascii strings or binary data. The can make calls like:

    asynPrintIO(pasynUser,ASYN_TRACEIO_DRIVER,data,nchars,"%s nchars %d ",
       someName,nchars);

The asynTrace methods are implemented by asynManager. These methods can be used by any code that has created an asynUser and connected to a device. All methods can be called by any thread. If a thread performs all I/O via calls to print or printIO, then it does not have to call lock or unlock. If it does want to do it's own I/O, it must lock before any I/O and unlock after. For example:

    pasynTrace->lock(pasunUser);
    fd = pasynTrace->getTraceFILE(pasunUser);
    /*perform I/O of fd */
    pasynTrace->unlock(pasunUser);

The following reads from an instrument via octet messages.

#include <asynCommon.h>
...
#define BUFSIZE 80
typedef struct myData {
    asynOctet *pasynOctet;
    void *pdrvPvt;
    char buffer[BUFSIZE];
}myData;

void queueCallback(asynUser *pasynUser)
    myData *pmydata = (myData *)puserPvt;
    asynOctet *pasynOctet = pmydata->pasynOctet;
    void *pdrvPvt = pmydata->pdrvPvt;
    asynStatus status;
    int retlen;

    asynPrint(pasynUser,ASYN_TRACE_FLOW,"queueCallback entered\n");
    status = pasynOctet->setEos(pdrvPvt,pasynUser,"\n",1);
    if(status!=asynSuccess) {
        asynPrint(pasynUser,ASYN_TRACE_ERROR,
            "queueCallback setEos failed %s\n",pasynUser->errorMessage);
    }
    retlen = pasynOctet->read(pdrvPvt,pasynUser,pmydata->buffer,BUFSIZE);
    if(retlen<=0) {
        asynPrint(pasynUser,ASYN_TRACE_ERROR,
            "queueCallback read failed %s\n",pasynUser->errorMessage);
    } else {
        asynPrintIO(pasynUser,ASYN_TRACEIO_DEVICE,
            pmydata->buffer,BUFSIZE,
            "queueCallback read returned: retlen %d data %s\n",
            retlen,pmydata->buffer);
    }
}

void mainThread(void)
{
    myData *pmyData;
    asynUser *pasynUser;
    asynStatus status;
    asynInterface *pasynInterface;

    pmyData = calloc(1,sizeof(myData));
    pasynUser = pasynManager->createAsynUser(queueCallback,0);
    pasynUser->userPvt = pmyData;
    status = pasynManager->connectDevice(pasynUser,"serialPort1",0)
    if(status!=asynSuccess) {
        printf("can't connect to serialPort1 %s\n",pasynUser->errorMessage);
        exit(1);
    }
    pasynInterface = (asynOctet *)pasynManager->findInterface(
        pasynUser,asynOctetType,1);
    if(!pasynInterface) {
        printf("%s driver not supported\n",asynOctetType);
        exit(-1);
    }
    pmyData->pasynOctet = (asynOctet *)pasynInterface->pinterface;
    pmyData->pdrvPvt = pasynInterface->pdrvPvt;
    status = pasynManager->queueRequest(pasynUser,asynQueuePriorityLow, 0.0);
    if(status) {
        asynPrint(pasynUser,ASYN_TRACE_ERROR,
            "queueRequest failed %s\n",pasynUser->errorMessage);
        exit(1);
    }
    /*Note that callback will be called by another thread*/
    ...
}

The flow of control is as follows:

1. A port driver calls registerPort. This step is not shown in the above example.
2. mainThread allocates myData and an asynUser.
3. mainThread connects to a device and to the asynOctet interface for the port driver..
4. When it is ready to communicate with the driver it calls queueRequest.
5. The thread associated with the port calls the callback which then calls the port driver's setEos and read methods.

GPIB has additional features that are not supported by asynCommon and asynOctet. asynGpib defines two interfaces.

• asynGpib - This is the interface that device support calls.. It provides the following:
  • A set of GPIB specific methods that device support can call.
  • Code that handles generic GPIB functions like SRQ polling.
  • A registerPort method which is called by GPIB port drivers.
• asynGpibPort - A set of methods implemented by GPIB drivers

asynGpib.h

asynGpibDriver.h contains the following definitions:

#include "asynDriver.h"

#define asynGpibUserType "asynGpibUser"
/* GPIB drivers */
/*asynGpib defines methods called by GPIB aware users*/
struct asynGpib{
    /*addressedCmd,...,ren are just passed to device handler*/
    asynStatus (*addressedCmd) (void *drvPvt,asynUser *pasynUser,
        const char *data, int length);
    asynStatus (*universalCmd) (void *drvPvt,asynUser *pasynUser, int cmd);
    asynStatus (*ifc) (void *drvPvt,asynUser *pasynUser);
    asynStatus (*ren) (void *drvPvt,asynUser *pasynUser, int onOff);
    /* The following are implemented by asynGpib */
    asynStatus (*registerSrqHandler)(void *drvPvt,asynUser *pasynUser,
        srqHandler handler, void *srqHandlerPvt);
    void (*pollAddr)(void *drvPvt,asynUser *pasynUser, int onOff);
    /* The following are called by low level gpib drivers */
    /*srqHappened is passed the pointer returned by registerPort*/
    void *(*registerPort)(
        const char *portName,
        asynGpibPort *pasynGpibPort, void *asynGpibPortPvt,
        unsigned int priority, unsigned int stackSize);
    void (*srqHappened)(void *asynGpibPvt);
};
epicsShareExtern asynGpib *pasynGpib;


struct asynGpibPort {
    /*asynCommon methods */
    void (*report)(void *drvPvt,FILE *fd,int details);
    asynStatus (*connect)(void *drvPvt,asynUser *pasynUser);
    asynStatus (*disconnect)(void *drvPvt,asynUser *pasynUser);
    asynStatus (*setPortOption)(void *drvPvt,asynUser *pasynUser,
                                const char *key,const char *val);
    asynStatus (*getPortOption)(void *drvPvt,asynUser *pasynUser,
                                const char *key,char *val,int sizeval);
    /*asynOctet methods passed through from asynGpib*/
    int (*read)(void *drvPvt,asynUser *pasynUser,char *data,int maxchars);
    int (*write)(void *drvPvt,asynUser *pasynUser,const char *data,int numchars);
    asynStatus (*flush)(void *drvPvt,asynUser *pasynUser);
    asynStatus (*setEos)(void *drvPvt,asynUser *pasynUser,
                const char *eos,int eoslen);
    asynStatus (*getEos)(void *drvPvt,asynUser *pasynUser,
                char *eos, int eossize, int *eoslen);
    /*asynGpib methods passed thrtough from asynGpib*/
    asynStatus (*addressedCmd) (void *drvPvt,asynUser *pasynUser,
                const char *data, int length);
    asynStatus (*universalCmd) (void *drvPvt, asynUser *pasynUser, int cmd);
    asynStatus (*ifc) (void *drvPvt,asynUser *pasynUser);
    asynStatus (*ren) (void *drvPvt,asynUser *pasynUser, int onOff);
    /*asynGpibPort specific methods */
    int (*srqStatus) (void *drvPvt);
    asynStatus (*srqEnable) (void *drvPvt, int onOff);
    asynStatus (*serialPollBegin) (void *drvPvt);
    int (*serialPoll) (void *drvPvt, int addr, double timeout);
    asynStatus (*serialPollEnd) (void *drvPvt);
};

asynGpib

asynGpib describes the interface for device support code. It provides gpib specific functions like SRQ handling. It makes calls to asynGpibPort. Note that asynGpib.c also implements asynCommon and asynOctet.

asynGpibPort

asynGpibPort is the interface that is implemented by gpib drivers, e.g. the vxi11. It provides:

Generic Serial

The generic serial driver supports devices connected to serial ports on the IOC and devices connected through Ethernet/Serial converter boxes.

Serial ports are configured with the drvGenericSerialConfigure and asynSetPortOption commands:

   drvGenericSerialConfigure("portName","ttyName",priority,openOnlyOnDisconnect)
   asynSetPortOption("portName","key","value")

• portName - The portName that is registered with asynGpib.
• ttyName - The name of the serial port. This can specify a local hardware serial port (e.g. "/dev/ttyS0") or the Internet host name and TCP port number of an Ethernet terminal concentrator (e.g. "164.54.9.90:4002", or "serials8n3:4002").
• priority - Priority at which the asyn I/O thread will run. If this is zero or missing then epicsThreadPriorityMedium is used.
• openOnlyOnDisconnect - If zero the driver will attempt to reconnect to the serial port on the first I/O operation following an error. If non-zero the driver will not attempt to reconnect until explicit disconnect/reconnect commands have been issued. A missing argument is taken to be zero.

The following table summarizes the generic serial driver asynSetPortOption keys and values. Default values are enclosed in square brackets.

Serial ports directly attached to a vxWorks IOC may need to be set up using hardware-specific commands. Once this is done the standard drvGenericSerialConfigure and asynSetPortOption commands can be issued. For example, the following example shows the configuration procedure for a port on a GreenSprings octal UART Industry-Pack module on a GreenSprings VIP616-01 carrier.

ipacAddVIPC616_01("0x6000,B0000000")
tyGSOctalDrv(1)
tyGSOctalModuleInit("RS232", 0x80, 0, 0)
tyGSOctalDevCreate("/tyGS/0/0",0,0,1000,1000)
drvGenericSerialConfigure("L0","/tyGS/0/0",0,0)
asynSetPortOption("L0","baud","9600")

vxi11

• VXI-11.1 - A standard for communicating with VXIbus instruments. These devices have a vxiName that starts with "vxi".
• VXI-11.2 - A standard for communicating with a IEEE 488.1 device. This means that the TCP/IP connection is talking to a GPIB controller that is talking to a GPIB bus. These devices have an vxiName that starts with "gpib".
• VXI-11.3 - A standard for communicating with IEEE 488.2 instruments. This means that the TCP/IP connection is talking directly with an instrument. These devices have an vxiName that starts with "inst".

Consult the following documents (available on-line for free) for details.

VMEbus Extensions for Instrumentation
    VXI-11   TCP/IP Instrument Protocol Specification
    VXI-11.1 TCP/IP-VXIbus Interface Specification
    VXI-11.2 TCP/IP-IEEE 488.1 Interface Specification
    VXI-11.3 TCP/IP-IEEE 488.2 Instrument Interface Specification

The following commands may be specified in the st.cmd file

    E2050Reboot("inet_addr")
    E5810Reboot("inet_addr","password")
    vxi11Configure("portName","inet_addr",recoverWithIFC,timeout,"vxiName",priority)

• inet_addr - Internet Address
• password - password. If given as 0 the default E5810 is used.
• portName - The portName that is registered with asynGib.
• inet_addr - Internet address.
• recoverWithIFC - (0,1) => (don't, do) issue IFC when error occurs.
• timeout - I/O operation timeout in seconds as a double. If 0.0 then a default is assigned.
• vxiName - Must be chosen as specified above.
• priority - Priority at which the asyn I/O thread will run. If this is zero or missing then epicsThreadPriorityMedium is used.

Green Springs IP488

This is support for the Green Springs Industry Pack GPIB carrier. The configuration command is:

    gsIP488Configure(portName,carrier,module,intVec,priority)

portName

An ascii string specifying the port name the will be registered with asynDriver.

carrier

An integer identifying the Industry Pack Carrier

module

An integer identifying the module on the carrier

intVec

An integer specifying the interrupt vector

priority

In integer specifying the priority of the port thread. A value of 0 will result in a defalt value being assigned

An example is:

#The following is for the Greensprings IP488 on an MV162 
ipacAddMVME162("A:l=3,3 m=0xe0000000,64")
gsIP488Configure("L0",0,0,0x61,0)

iocsh commands

    asynReport(filename,level)
    asynSetTraceMask(portName,addr,mask)
    asynSetTraceIOMask(portName,addr,mask)
    asynSetPortOption(portName,key,val)
    asynShowPortOption(portName,key)

asynReport calls asynCommon:report for all registered drivers and processModules. asynSetTraceMask calls asynTrace:setTraceMask for the specified port and address. asynSetTraceIOMask calls asynTrace:setTraceIOMask for the specified port and address. asynSetPortOption calls asynCommon:setPortOption. asynShowPortOption calls asynCommon:getPortOption.

where

filename

An ascii string naming a file to which the report is sent. If this is null or a null string then the output is sent to stdoutlevel

The report level.

portName

An ascii string specifying the portName of the driver.

addr

In integer specifying the address of the instrument.

mask

The mask value to set. See the mask bit definitions in asynDriver.h

key

The key for the option desired.

val

The value for the option.

devAsynTrace

This provides a generic facility for setting trace options via MEDM. It consists of the following components:

devAsynTrace.c

An EPICS IOC device support module for setting trace options. It has an associated devAsynTrace.dbd file that must be included by any application that wants to use this facility. This also provides a driver(drvAsyn) that has a report method called by dbior.

asynTrace.db

A generic database that uses devAsynTrace. It uses the following macros as a prefix for all its process-variable names: $(ioc):$(port)$(addr).

asynTrace.adl

A generic medm display for setting trace variables It uses the same macros as the generic database.

The following is the medm display.

Install and build asynDriver

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

.../support/asyn/

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 support <top>.

.../support/asyn/X-Y

where X-Y is the release. For example.

.../support/asyn/1-1

4. Edit the config/RELEASE file and set the paths to your installation of EPICS_BASE, ASYN, and IPAC. IPAC is only needed if you are building for vxWorks.
5. Run make in the top level directory and check for any compilation errors.

Using asynDriver components with an EPICS iocCore application

Since asynDriver does NOT provide support for specific instruments an application must obtain instrument specific support elsewhere. This section only explains how to include asynDriver components.

In the configure/RELEASE file add definitions for IPAC and EPICS_BASE.

In the src directory where the application is built

• Add the following to Makefile

          <app>_LIBS += asyn
      

• Add the following to <app>Include.dbd

        include "asyn.dbd"
        include "devAsynTrace.dbd"
      

In the st.cmd file add.

dbLoadRecords("db/asynTrace.db","ioc=<ioc>,port=<port>,addr=<addr>")

This is done for each instrument. You must provide correct values for <ioc>,<port>, and <addr>

Once the application is running the medm display for each imstrument can be started by:

medm -x -macro "ioc=<ioc>,port=<port>,addr=<addr>" <asyntop>/testApp/adl/asynTrace.adl &

Again this done for each instrument. You must provide correct values for <ioc>,<port>, and <addr>

Copyright (c) 2002 University of Chicago All rights reserved.
asynDriver is distributed subject to the following license conditions:

SOFTWARE LICENSE AGREEMENT
Software: asynDriver

 1. The "Software", below, refers to asynDriver (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.