asynDriver: Asynchronous Driver Support

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

• Local Serial Port
• TCP/IP or UDP/IP Port
• VXI-11
• Green Springs IP488
• National Instruments GPIB-1014D

asynDriver is a general purpose facility for interfacing device specific code to low level drivers. It supports both asynchronous (can block) and synchronous (do not block) drivers.. The name asynDriver is used because, high level device support makes all calls to drivers from a callback. asynDriver is designed so that it is easy to write non blocking device support that works with both blocking and non blocking drivers.

A primary target for asynDriver is EPICS IOC device support but, other than using libCom, much of 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.
• MPFOSI (Message Passing Facility). It is no longer needed or supported since asynDriver can completely replace MPF.

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.

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 and mpfSerial have already been converted and is included with asynDriver.

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: the software layer between device support and drivers.
• asynRecord: EPICS record support that provides a generic interface to asynManager, asynCommon, asynOctet, and asynGpib.
• standard interfaces: Standard message and register based interfaces are defined. Low Level Drivers are expected to implement standard interfaces whenever possible. Device support communicates with low level drivers via standard interfaces.
• devEpics: Generic device support for EPICS records.
• 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.
• drvAsynSerialPort: Support for devices connected to serial ports.
• drvAsynIPPort: Support for devices connected to devices connected through Ethernet/Serial converter boxes, TCP/IP sockets or UDP/IP sockets.
• VXI-11: A replacement for the VXI-11 support of the Franksen gpibCore support.
• gsIP488: A low level driver for the Greensprings IP488 Industry Pack module.
• ni1014: A low level driver for the National Instruments VME 1014D.

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 implemented 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 system 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 drivers that communicate with devices. It supports both blocking and non-blocking communication and can be used with both register and message based 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 function pointers. An asynDriver interface is analogous to a C++ or Java pure virtual interface. Although the implementation is in C, the spirit is object oriented. Thus this document uses the term "member" rather than "function pointer".

• port

  An entity which provides access to a device. A port provides access to one or more devices.

• portDriver

  Code that communicates with a port.

• port thread

  If a portDriver can block, a thread is created for each port, and all I/O to the portDriver is done via this thread.

• device

  A device (instrument) connected to a port. For example a GPIB interface can have up to 15 devices connected to it. Other ports, e.g. serial ports, can only support a single device. Whenever this document uses the word device without a quailifier, it means something that is connected to a port.

• asynDriver

  This is the name for the support described in this manual. It is also the name of the header file that describes the core interfaces

• asynManager

  The code which implements the asynManager and asynTrace methods.

• asynSynchronous Driver

  A driver that may block while communicating with a device. Typical examples are serial, gpib, and network based drivers.

• synchronous Driver

  A driver that does not block while communicating with a device.

• Message Based Interfaces

  Interfaces that use octet arrays for read/write operations.

• Register Based Interfaces

  Interfaces that use integers or floats for read/write operations.

Synchronous/asynchronous and message/register are orthogonal concepts. For example a register based driver can be either synchronous or asynchronous. The terminology register vs message is adapted from VXI.

Standard interfaces are defined so that most device specific code can communicate with multiple port drivers. For example if device support does all its communication via reads and writes consisting of 8 bit bytes (octets), then it should work with all port drivers that support octet messages. If device support requires more complicated support, then the types of ports will be more limited. Standard interfaces are also defined for drivers that accept 32 bit integers or 64 bit floats. Additional interfaces can be defined, and it is expected that additional standard interfaces will be defined.

Examples of portDrivers that block are GPIB controllers, serial ports, Ethernet ports, etc. Examples of portDrivers that do not block are VME register based devices.

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 software layer calls interposeInterface in order to be placed between device specific code and drivers. 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 an asynGpibPort interface which is called by asynGpib.

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

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

Standard Interfaces

This section briefly describes the interfaces provided by asynManager and standard interfaces implemented by port drivers. asynManager members are called by application threads. Except for asynCommon:report, port driver methods can only be called from the user supplied callback passed in the call to createAsynUser.

The interfaces are:

asynManager provides services for communicating with a device connected to a port. The following services are provided:

• report - A method that reports the status of all ports.
• A thread for each port that can block.
• Methods to connect/disconnect to a device or port.
• A method for locating port driver interfaces.
• queueRequest. This is a non-blocking method, i.e. it can be called from scan threads. If the portDriver does not block, queueRequest itself calls the process callback specified in the call to createAsynUser. It provides a lock so that multiple threads do not try to access the low level driver simultaneously. If the portDriver can block than the request is queued for the port thread. The user callback can make an arbitrary number of calls to the driver.
• Methods that provide a transaction service, i.e. members lock/unlock can lock out other users while multiple queueRequests are issued.
• Methods for registering ports and interfaces.
• Methods called by a driver when it connects or disconnects from a port or device.
• A Method for interposing an interface between clients and drivers.
• Methods for enable and autoConnect.

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

• report - Report status of port.
• connect - Connect to the port or device.
• disconnect - Disconnect from the port or device.

asynTrace is a set of methods for generating diagnostic messages.

asynDrvUser is a set of methods for communication user specific information from a user to a driver

In addition to the standard interfaces port drivers must implement one or more of the message and/or register based interfaces described in later sections.

Brief Theory of Operation

During initialization, port drivers register each communication port as well as all supported interfaces.

User code creates an asynUser by calling pasynManager->createAsynUser(processCallback,...). The address of the asynUser is passed to most other asynDriver methods. processCallback is the addresss of a caller supplied callback routine, which will be described shortly. An asynUser is a "handle" for accessing asynDriver facilities. It is the means by which asynManager manages multiple requests for access to a port. Device support code should NOT try to share an asynUser between multiple sources of requsts for access to a port. For example device support for EPICS records should normally allocate a separate asynUser for each record instance.

User code connects to a low level driver via a call to pasynManager->connectDevice(pasynUser,portName,addr). This call must specify the name of the port and the address of the device. It then calls findInterface to locate the interfaces with which it calls the driver.

User code makes calls to the low level driver via an interface. All calls must be made from the queue callback passed to createAsynUser. A request to call queue callback is made by calling queueRequest. A thread that calls queueRequest is guaranteed not to block. If queueRequest is called for a port that can block the request is queued to a thread dedicated to the port. If queueRequest is called for a port does not block it just calls queue callback. In either case asynManager guarantees that multiple threads do not simultaneously call a low level driver. This guarantee is valid only if low level drivers are only accessed by calling queueRequest.

The following examples are based on EPICS IOC record/device support.

Figure 1: Asynchronous Control Flow

1. Record processing calls Record device support.
2. Record device support calls queueRequest.
3. queueRequest places the request on the driver work queue. The application thread is now able to go on and perform other operations. All subsequent operations for this I/O request are handled in the port driver thread.
4. The port thread removes the I/O request from the work queue.
5. The port thread calls the callback located in Record device support.
6. The record device support calls the low-level driver.
7. The low-level driver read or write routine blocks until the I/O completes or until a timeout occurs. The low-level driver routine returns the results of the I/O operation to the record device support code which completes record processing.

Figure 2: Synchronous Control Flow

1. Record processing calls Record device support.
2. Record device support calls queueRequest.
3. Since the port is synchronous, i.e. can not block, queueRequest calls the callback provided by record device support.
4. Record device support calls the low-level driver read or write routine.
5. The low-level driver routine returns the results of the I/O operation to the record device support code which completes record processing.

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 STREAMS, but asynGpib could be used to handle SRQs (service requests).

asynDriver.h describes the following:

• asynStatus - An enum that describes the status returned by many methods.
• asynException - An enum that describes exceptions.
• asynQueuePriority - An enum that describes the queue priorities.
• asynUser - A struture that contains generic information and is the "handle" for calling most methods.
• asynInterface - a structure that describes an interface.
• asynManager - An interface for communicating with asynDriver.
• asynCommon - An interface providing methods that must be implemented by all low level drivers.
• asynTrace - An interface plus associated functions and definitions that implement the trace facility.

asynStatus

Defines the status returned by most methods. If a method returns a status other than asynSuccess, and one of the arguments to the method is pasynUser, then the method is expected to write a message into pasynUser->errorMessage.

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

asynException

Defines the exceptions for method exceptionOccurred

typedef enum {
    asynExceptionConnect,asynExceptionEnable,asynExceptionAutoConnect,
    asynExceptionTraceMask,asynExceptionTraceIOMask,
    asynExceptionTraceFile,asynExceptionTraceIOTruncateSize
} asynException;

asynQueuePriority

This defines the priority passed to queueRequest.

typedef enum {
    asynQueuePriorityLow,asynQueuePriorityMedium,asynQueuePriorityHigh,
    asynQueuePriorityConnect
}asynQueuePriority;

asynUser

Describes a structure that user code passes to most asynManager and driver methods. Code must allocate and free an asynUser by calling asynManager:createAsynUser and asynManager:freeAsynUser.

typedef struct asynUser {
    char *errorMessage;
    int errorMessageSize;
    /* The following must be set by the user */
    double       timeout;  /*Timeout for I/O operations */
    void         *userPvt;   /* pointer to user private */
    void         *userData;
    /*The following is for user to/from driver communication*/
    void         *drvUser;
    int          auxStatus; /*For auxillary status*/
}asynUser;

epicsSnprintf(pasynUser->errorMessage,pasynUser->errorMessageSize,

              "<format>",...)

asynInterface

This defines an interface registered with asynPortManager:registerPort or asynManager:interposeInterface.

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

asynManager

This is the main interface for communicating with asynDriver.

/*registerPort attributes*/
#define ASYN_MULTIDEVICE  0x0001
#define ASYN_CANBLOCK     0x0002

typedef void (*userCallback)(asynUser *pasynUser);
typedef void (*exceptionCallback)(asynUser *pasynUser,asynException exception);

typedef struct asynManager {
    void      (*report)(FILE *fp,int details);
    asynUser  *(*createAsynUser)(userCallback queue,userCallback timeout);
    asynUser  *(*duplicateAsynUser)(asynUser *pasynUser,
                                 userCallback queue,userCallback timeout);
    asynStatus (*freeAsynUser)(asynUser *pasynUser);
    void       *(*memMalloc)(size_t size);
    void       (*memFree)(void *pmem,size_t size);
    asynStatus (*isMultiDevice)(asynUser *pasynUser,
                                const char *portName,int *yesNo);
    /* addr = (-1,>=0) => connect to (port,device) */
    asynStatus (*connectDevice)(asynUser *pasynUser,
                                const char *portName,int addr);
    asynStatus (*disconnect)(asynUser *pasynUser);
    asynStatus (*exceptionCallbackAdd)(asynUser *pasynUser,
                                       exceptionCallback callback);
    asynStatus (*exceptionCallbackRemove)(asynUser *pasynUser);
    asynInterface *(*findInterface)(asynUser *pasynUser,
                            const char *interfaceType,int interposeInterfaceOK);
    asynStatus (*queueRequest)(asynUser *pasynUser,
                              asynQueuePriority priority,double timeout);
    asynStatus (*cancelRequest)(asynUser *pasynUser,int *wasQueued);
    asynStatus (*canBlock)(asynUser *pasynUser,int *yesNo);
    asynStatus (*lock)(asynUser *pasynUser);   /*lock portName,addr */
    asynStatus (*unlock)(asynUser *pasynUser);
    asynStatus (*getAddr)(asynUser *pasynUser,int *addr);
    /* drivers call the following*/
    asynStatus (*registerPort)(const char *portName,
                              int attributes,int autoConnect,
                              unsigned int priority,unsigned int stackSize);
    asynStatus (*registerInterface)(const char *portName,
                              asynInterface *pasynInterface);
    asynStatus (*exceptionConnect)(asynUser *pasynUser);
    asynStatus (*exceptionDisconnect)(asynUser *pasynUser);
    /*any code can call the following*/
    asynStatus (*interposeInterface)(const char *portName, int addr,
                              asynInterface *pasynInterface,
                              asynInterface **ppPrev);
    asynStatus (*enable)(asynUser *pasynUser,int yesNo);
    asynStatus (*autoConnect)(asynUser *pasynUser,int yesNo);
    asynStatus (*isConnected)(asynUser *pasynUser,int *yesNo);
    asynStatus (*isEnabled)(asynUser *pasynUser,int *yesNo);
    asynStatus (*isAutoConnect)(asynUser *pasynUser,int *yesNo);
}asynManager;
epicsShareExtern asynManager *pasynManager;

asynInterface *pasynInterface;
asynOctet *pasynOctet;
void *pasynOctetPvt;
...
pasynInterface = pasynManager->findInterface(
        pasynUser,asynOctetType,1);
if(!pasynInterface) { /*error do something*/}
pasynOctet = (asynOctet *)pasynInterface->pinterface;
pasynOctetPvt = pasynInterface->pdrvPvt;
/* The following call must be made from a callback */
pasynOctet->read(pasynOctetPvt,pasynUser,...
        

asynCommon

/* Device Interface supported by ALL asyn drivers*/
#define asynCommonType "asynCommon"
typedef struct  asynCommon {
    void       (*report)(void *drvPvt,FILE *fp,int details);
    /*following are to connect/disconnect to/from hardware*/
    asynStatus (*connect)(void *drvPvt,asynUser *pasynUser);
    asynStatus (*disconnect)(void *drvPvt,asynUser *pasynUser);
}asynCommon;

asynCommon describes the methods that must be implemented by drivers.

Trace Interface

/*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 than*/
    /* 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 *fp);
    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;

asynTrace

asynDriver provides a trace facility with the following attributes:

• Tracing is turned on/off for individual devices, i.e. a portName, addr.
• Trace has a global trace mask for asynUsers not connected to a port or port, addr.
• The output is sent to a file or to stdout.
• A mask determines the type of information that can be displayed. The various choices can be ORed together.
  • 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 report calls they make to other support.
• Another mask determines how message buffers are printed. The various choices can be ORed together.
  • ASYN_TRACEIO_NODATA Don't 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. Device and driver support can directly call the asynTrace 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 issue read or write requests. They 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 is connected to a device. All methods can be called by any thread. That is, an application thread and/or a port 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 its own I/O, it must lock before any I/O and unlock after. For example:

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

If the asynUser is not connected to a port, i.e. pasynManager->connectDevice has not been called, then a "global" device is assumed. This is usefull when asynPrint is called before connectDevice.

These are interfaces for communicating with message based devices, where message based means that the device accepts octet strings, i.e. an array of 8 bit bytes, and responds with octet strings. Three interfaces are provided: asynOctet, asynOctetSyncIO, and asynOctetTrapReadWrite. asynOctetSyncIO provides a synchronous inteface to asynOctet and can be used by code that is willing to block. asynOctetTrapReadWrite is an interposeInterface that can be used to intercept calls to asynOctet.

asynOctet

#define ASYN_EOM_CNT 0x0001 /*Request count reached*/
#define ASYN_EOM_EOS 0x0002 /*End of String detected*/
#define ASYN_EOM_END 0x0004 /*End indicator detected*/

#define asynOctetType "asynOctet"
typedef struct asynOctet{
    asynStatus (*read)(void *drvPvt,asynUser *pasynUser,
                       char *data,int maxchars,int *nbytesTransfered,
                       int *eomReason);
    asynStatus (*write)(void *drvPvt,asynUser *pasynUser,
                        const char *data,int numchars,int *nbytesTransfered);
    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;

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.

asynOctetSyncIO

typedef struct asynOctetSyncIO {
   asynStatus (*connect)(const char *port, int addr, asynUser **ppasynUser);
   asynStatus (*disconnect)(asynUser *pasynUser);
   asynStatus (*openSocket)(const char *server, int port, char **portName);
   int        (*write)(asynUser *pasynUser, char const *buffer, int buffer_len,
                  double timeout); 
   int        (*read)(asynUser *pasynUser, char *buffer, int buffer_len,
                  const char *ieos, int ieos_len, int flush, double timeout,
                  int *eomReason);
   int        (*writeRead)(asynUser *pasynUser,
                  const char *write_buffer, int write_buffer_len,
                  char *read_buffer, int read_buffer_len,
                  const char *ieos, int ieos_len, double timeout,
                  int *eomReason);
   asynStatus (*flush)(asynUser *pasynUser);
   int        (*writeOnce)(const char *port, int addr,
                  char const *buffer, int buffer_len, double timeout);
   int        (*readOnce)(const char *port, int addr,
                  char *buffer, int buffer_len,
                  const char *ieos, int ieos_len, int flush, double timeout,
                  int *eomReason);
   int        (*writeReadOnce)(const char *port, int addr,
                  const char *write_buffer, int write_buffer_len,
                  char *read_buffer, int read_buffer_len,
                  const char *ieos, int ieos_len, double timeout,
                  int *eomReason);
} asynOctetSyncIO;
epicsShareExtern asynOctetSyncIO *pasynOctetSyncIO;

asynOctetSyncIO provides a convenient interface for software that needs to perform "synchronous" I/O to an asyn device, i.e. that starts an I/O operation and then blocks while waiting for the response.  The code does not need to handle callbacks or understand the details of the asynManager and asynOctet interfaces. Examples include motor drivers running in their own threads, SNL programs, and the shell commands described later in this document.

asynOctetTrapReadWrite

#define asynOctetTrapReadWriteType "asynOctetTrapReadWrite"
typedef void (*asynOctetTrapReadWriteCallback) (asynUser *pasynUser,
    const char *data, int numchars, asynStatus status);

/* asynOctetTrapReadWrite methods are thread-safe but might block.
*  Thus, they can be called directly by a task that is allowed to
*  block, or indirectly with asynManager->queueRequest()
*  Note that, when using asynManager->queueRequest, a callback
*  cannot be installed or removed as long as some other asynUser has
*  locked the port/address.
*
*  Before pasynUser is freed, it must remove all callbacks that it has
*  previously installed or the system might crash!
*/

typedef struct asynOctetTrapReadWrite {
    asynStatus (*installReadCallback) (void *drvPvt, asynUser *pasynUser,
        asynOctetTrapReadWriteCallback callback);
    asynStatus (*installWriteCallback) (void *drvPvt, asynUser *pasynUser,
        asynOctetTrapReadWriteCallback callback);
    asynStatus (*removeReadCallback) (void *drvPvt, asynUser *pasynUser,
        asynOctetTrapReadWriteCallback callback);
    asynStatus (*removeWriteCallback) (void *drvPvt, asynUser *pasynUser,
        asynOctetTrapReadWriteCallback callback);
} asynOctetTrapReadWrite;

int epicsShareAPI asynOctetTrapReadWriteConfig(const char *portName, int addr);

asynOctetTrapReadWriteConfig intercepts all asynOctet messages and calls all registered callbacks for read and write messages.

Introduction

This section descibes interfaces for the following classes of drivers:

• Int32 - data is passed as 32 bit integers.

  This class has the following interfaces:

  • asynInt32 - read, write, getBounds.
  • asynInt32Callback - registerCallback/cancelCallback to receive Int32 value.
  • asynInt32Array - read/write arrays of Int32 values.
  • asynInt32ArrayCallback - registerCallback/cancelCallback to receive arrays of Int32.
  • asynInt32SyncIO - A synchronous interface to asynInt32
• UInt32Digital - Data is passed as 32 bit unsigned integers and a mask that selects bits from the integer.
  • asynUInt32Digital - read/write.
  • asynUInt32DigitalCallback - registerCallback/cancelCallback to receive UInt32 value. It also has methods to setInterrupt/getInterrupt.
• Float64 - data is passed as double precision floats.

  This class has the following interfaces:

  • asynFloat64 - read/write.
  • asynFloat64Callback - registerCallback/cancelCallback to receive Float64 value.
  • asynFloat64Array - read/write arrays of Float64 values.
  • asynFloat64ArrayCallback - registerCallback/cancelCallback to receive arrays of Float64.

NOTE: UInt32Digital and Float64 should also have synchronous interfaces. This will be provided in the next release.

addr - What does it mean?

If a low level driver is declared multi-device the meaning of addr is:

• Int32 - The driver supports an array of Int32 values. addr selects an array element. For example a 16 channel ADC would support addr 0 through 15.
• Int32Array - Each addr is an array of Int32 values.
• Float64 - The driver supports an array of Float64 values. addr selects an array element.
• Float64Array - Each addr is an array of Float64 values.
• UInt32Digital - This remains to be determined. One possibility is that addr has the value

      ind*32*32 + shift*32 + nbits

  where:
  • ind - The index that selects an element of an Int32 array.
  • shift - Selects the low order bit on the Int32 value.
  • nbits - The number of bits.
  For example a driver for a 128 bit digital I/O module would support it as an array of four UInt32 registers. If:

   addr = 1156 = 1*32*32 + 4*32 + 4

  then bits 0x00F0 of the second register are selected. This rule should provide the proper behavior for trace, etc.

asynInt32

#define asynInt32Type "asynInt32"
typedef struct asynInt32{
    asynStatus (*write)(void *drvPvt, asynUser *pasynUser, epicsInt32 value);
    asynStatus (*read)(void *drvPvt, asynUser *pasynUser, epicsInt32 *value);
    asynStatus (*getBounds)(void *drvPvt, asynUser *pasynUser,
                            epicsInt32 *low, epicsInt32 *high);
}asynInt32;

asynInt32 describes the methods implemented by drivers that use integers for communicating with a device.

asynInt32Callback

#define asynInt32CallbackType "asynInt32Callback"
/*cancelCallback cancels based on callback and userPvt */
typedef struct asynInt32Callback {
    asynStatus (*registerCallback)(void *drvPvt, asynUser *pasynUser,
                             void (*callback)(void *userPvt, epicsInt32 data),
                             void *userPvt);
    asynStatus (*cancelCallback)(void *drvPvt, asynUser *pasynUser,
                             void (*callback)(void *userPvt, epicsInt32 data),
                             void *userPvt);
} asynInt32Callback;
 

asynInt32Callback provides methods for drivers that collect data and make it available to registered clients. An example is an interrupt based driver.

asynInt32Array

#define asynInt32ArrayType "asynInt32Array"
typedef struct asynInt32Array{
    asynStatus (*write)(void *drvPvt, asynUser *pasynUser,
                       epicsInt32 value, size_t nelements);
    asynStatus (*read)(void *drvPvt, asynUser *pasynUser,
                      epicsInt32 *value, size_t nelements, size_t *nIn);
}asynInt32Array;

asynInt32Array describes the methods implemented by drivers that use arrays of integers for communicating with a device.

asynInt32ArrayCallback

#define asynInt32ArrayCallbackType "asynInt32ArrayCallback"
/*cancelCallback cancels based on callback and userPvt */
typedef struct asynInt32ArrayCallback {
    asynStatus (*registerCallback)(void *drvPvt, asynUser *pasynUser,
             void (*callback)(void *userPvt,epicsInt32 *val,epicsUInt32 nelem),
             void *userPvt);
    asynStatus (*cancelCallback)(void *drvPvt, asynUser *pasynUser,
             void (*callback)(void *userPvt,epicsInt32 *val,epicsUInt32 nelem),
             void *userPvt);
} asynInt32ArrayCallback;

asynInt32ArrayCallback provides methods for drivers that collect data and make it available to registered clients. An example is an interrupt based driver.

asynInt32SyncIO

#define asynInt32SyncIOType "asynInt32SyncIO"
typedef struct asynInt32SyncIO {
    asynStatus (*connect)(const char *port, int addr, asynUser **ppasynUser);
    asynStatus (*disconnect)(asynUser *pasynUser);
    asynStatus (*write)(asynUser *pasynUser, epicsInt32 value,double timeout);
    asynStatus (*read)(asynUser *pasynUser, epicsInt32 *pvalue,double timeout);
    asynStatus (*getBounds)(asynUser *pasynUser,
                            epicsInt32 *plow, epicsInt32 *phigh);
    asynStatus (*writeOnce)(const char *port, int addr,
                            epicsInt32 value,double timeout);
    asynStatus (*readOnce)(const char *port, int addr,
                            epicsInt32 *pvalue,double timeout);
    asynStatus (*getBoundsOnce)(const char *port, int addr,
                            epicsInt32 *plow, epicsInt32 *phigh);
} asynInt32SyncIO;
epicsShareExtern asynInt32SyncIO *pasynInt32SyncIO;

asynInt32SyncIO describes a asyncronous interrace to asynInt32. The code that calls it must be willing to block.

asynUInt32Digital

#define asynUInt32DigitalType "asynUInt32Digital"
typedef struct asynUInt32Digital {
    asynStatus (*write)(void *drvPvt, asynUser *pasynUser,
         epicsUInt32 value, epicsUInt32 mask);
    asynStatus (*read)(void *drvPvt, asynUser *pasynUser,
        epicsUInt32 *value, epicsUInt32 mask);
} asynUInt32Digital;

asynUInt32Digital describes the methods for communicating via bits of an Int32 register.

asynUInt32DigitalCallback

typedef enum {
    interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
} interruptReason;

#define asynUInt32DigitalCallbackType "asynUInt32DigitalCallback"
/*cancelCallback cancels based on callback and userPvt */
typedef struct asynUInt32DigitalCallback {
    asynStatus (*registerCallback)(void *drvPvt, asynUser *pasynUser,
        void (*callback)(void *userPvt, epicsUInt32 data),
        epicsUInt32 mask, void *userPvt);
    asynStatus (*cancelCallback)(void *drvPvt, asynUser *pasynUser,
        void (*callback)(void *userPvt, epicsUInt32 data),
        epicsUInt32 mask, void *userPvt);
    asynStatus (*setInterrupt)(void *drvPvt, asynUser *pasynUser,
        epicsUInt32 mask, interruptReason reason);
    asynStatus (*clearInterrupt)(void *drvPvt, asynUser *pasynUser,
        epicsUInt32 mask);
    asynStatus (*getInterrupt)(void *drvPvt, asynUser *pasynUser,
        epicsUInt32 *mask, interruptReason reason);
} asynUInt32DigitalCallback;

asynUInt32Digital describes methods for communicating with interupt driven drivers.

asynFloat64

#define asynFloat64Type "asynFloat64"
typedef struct asynFloat64 {
    asynStatus (*write)(void *drvPvt, asynUser *pasynUser, epicsFloat64 value);
    asynStatus (*read)(void *drvPvt, asynUser *pasynUser, epicsFloat64 *value);
} asynFloat64;

asynFloat64 describes the methods for communicating via IEEE double precision float values.

asynFloat64Callback

#define asynFloat64CallbackType "asynFloat64Callback"
/*cancelCallback cancels based on callback and userPvt */
typedef struct asynFloat64Callback {
    asynStatus (*registerCallback)(void *drvPvt, asynUser *pasynUser,
                        void (*callback)(void *userPvt, epicsFloat64 data),
                        void *userPvt);
    asynStatus (*cancelCallback)(void *drvPvt, asynUser *pasynUser,
                        void (*callback)(void *userPvt, epicsFloat64 data),
                        void *userPvt);
} asynFloat64Callback;

asynFloat64Callback is like asynInt32Callback except that it uses Float64 values

asynFloat64Array

#define asynFloat64ArrayType "asynFloat64Array"
typedef struct asynFloat64Array {
    asynStatus (*write)(void *drvPvt, asynUser *pasynUser,
                       epicsFloat64 *value, size_t nelements);
    asynStatus (*read)(void *drvPvt, asynUser *pasynUser,
                       epicsFloat64 *value, size_t nelements, size_t *nIn);
} asynFloat64Array;

asynFloat64Array describes the methods for communicating via IEEE double precision float values.

asynFloat64ArrayCallback

#define asynFloat64ArrayCallbackType "asynFloat64ArrayCallback"
/*cancelCallback cancels based on callback and userPvt */
typedef struct asynFloat64ArrayCallback {
    asynStatus (*registerCallback)(void *drvPvt, asynUser *pasynUser,
         void (callback)(void *userPvt, epicsFloat64 *data,epicsUInt32 nelems),
         void *userPvt);
    asynStatus (*cancelCallback)(void *drvPvt, asynUser *pasynUser,
         void (callback)(void *userPvt, epicsFloat64 *data,epicsUInt32 nelems),
         void *userPvt);
} asynFloat64ArrayCallback;

asynFloat64ArrayCallback is like asynInt32Callback except that it uses an array of Float64 values

asynDrvUser

#define asynDrvUserType "asynDrvUser"
typedef struct  asynDrvUser {
    /*The following do not have to be called via queueRequest callback*/
    asynStatus (*create)(void *drvPvt,asynUser *pasynUser,
        const char *drvInfo, const char **pptypeName,size_t *psize);
    asynStatus (*getType)(void *drvPvt,asynUser *pasynUser,
        const char **pptypeName,size_t *psize);
    asynStatus (*destroy)(void *drvPvt,asynUser *pasynUser);
}asynDrvUser;

asynDrvUser provides methods that allow an asynUser to communicate user specific information to/from a port driver

asynOption

#define asynOptionType "asynOption"
/*The following are generic methods to set/get device options*/
typedef struct asynOption {
    asynStatus (*setOption)(void *drvPvt, asynUser *pasynUser,
                                const char *key, const char *val);
    asynStatus (*getOption)(void *drvPvt, asynUser *pasynUser,
                                const char *key, char *val, int sizeval);
}asynOption;

asynOption provides a generic way of setting driver specific options. For example the serial port driver uses this to specify baud rate, stop bits, etc.

asynInterposeEos

This can be used to simulate EOS processing for asynOctet if the port driver doesn't provide EOS support. If an EOS is specified it looks for the eos on each read. It is started by the shell command:

    asynInterposeEosConfig port addr

where

• port is the name of the port.
• addr is the address

this command should appear immediately after the command that initializes a port

asynInterposeFlush

This can be used to simulate flush processing for asynOctet if the port driver doesnt provide support for flush. It just reads and discards characters until no more characters arive before timeout seconds have occured. It is started by the shell command:

    asynInterposeFlushConfig port addr timeout

where

• port is the name of the port.
• addr is the address
• timeout is the time to wait for more characters

this command should appear immediately after the command that initializes a port

NOTE: The generic device support for epics records is in an early stage of development. Although it is usable it needs improvement. It will likely evolve rapidly over the next several releases of asynDriver.

Generic device support is provided for standard EPICS records. This support should be usable for a large class of low level register based drivers. For truly complicated devices other support is required.

The support uses the following conventions for DTYP and INP or OUT.

    field(DTYP,"asyn xxx")
    field(INP,"@asyn(portName,addr,timeout) drvParams")
     or
    field(OUT,"@asyn(portName,addr,timeout) drvParams")

where

• xxx - The name of the type of interface supported.
• portName - The name of the port.
• addr - The address. If addr is not specified the default is 0
• timeout - The timeout value for asynUser.timeout. If not specified the default is 1.0
• drvParams - This is passed to the low level driver via the asynDrvUser interface. This this is a way to pass information to the low level driver at initialization time.

For example:

    field(DTYP,"asyn Int32")
    field(INP,"@asyn(portA,0,.1) thisIsForDriver")

aiRecord generic device support

The following support is available:

device(ai,INST_IO,devAiAsynInt32,"asyn Int32")
device(ai,INST_IO,devAiAsynFloat64,"asyn Float64")
device(ai,INST_IO,devAiAsynInt32Average,"asyn Int32Average")
device(ai,INST_IO,devAiAsynFloat64Average,"asyn Float64Average")
device(ai,INST_IO,devAiAsynInt32Interrupt,"asyn Int32Interrupt")
device(ai,INST_IO,devAiAsynFloat64Interrupt,"asyn Float64Interrupt")

Support for drivers the implement interface Int32 and/or Float64. The Interrupt and Average support requires that the driver supports the asynInt32Callback and/or asynFloat64Callback interfaces.< If Interrupt is chosen the record normallly has SCAN set to "I/O Intr". A record with one of the Average supports is normally periodically scanned. Each time the record processes it receives the average of all the values obtained since the last time the record processed.

aoRecord generic device support

The following support is available:

device(ao,INST_IO,devAoAsynInt32,"asyn Int32")
device(ao,INST_IO,devAoAsynFloat64,"asyn Float64")

Support for port drivers that implement interface asynInt32 or asynFloat64.

Other generic device support

The following support is available:

device(bi,INST_IO,devBiAsynUInt32Digital,"asyn UInt32Digital")
device(bo,INST_IO,devBoAsynUInt32Digital,"asyn UInt32Digital")
device(longin,INST_IO,devLiAsynUInt32Digital,"asyn UInt32Digital")
device(longout,INST_IO,devLoAsynUInt32Digital,"asyn UInt32Digital")

This needs documentation

Multiple Device vs Single Device Port Drivers

When a low level driver calls registerPort, it declares if it handles multiple devices. This determines how the addr argument to connectDevice is handled and what getAddr returns.

• multiDevice false

  The addr argument to connectDevice is ignored and getAddr always returns -1

• multiDevice true

  If connectDevice is called with addr<0, the connection is to the port and getAddr always returns -1. If addr>=0, then the caller is connected to the device at the specified address. getAddr will return this address.

Connection Management

asynManager keeps track of the following states:

• connection

  Is the port or device connected? This state is initialized to disconnected.

• enabled

  Is the port or device enabled? This state is initialized to enabled.

• autoConnect

  Does asynManager call connect if it finds the port or device disconnected? This is initialized to the state specified in the call to registerPort.

If the port does not support multiple devices, then port and device status are the same. If the port does support multiple devices, then asynManager keeps track of the states for the port and for every device connected to the port.

Whenever any of the states change for a port or device, then all users that previously called exceptionCallbackAdd for that port or device are called.

Low level drivers must call pasynManager:exceptionConnect whenever they connect to a port or port,addr and must call exceptionDisconnect whenever they disconnect.

Flow of Control

The methods asynManager:report and asynCommon:report can be called by any thread, but the caller is blocked until the report finishes. The following discussion applys to all methods except report.

The asynManager methods can be called by any thread including portThread. None of these methods (except report) block.

Unless stated otherwise the methods for other interfaces must only be called by the queue callback specified in the call to createAsynUser, i.e. queueRequest must be called.

portThread

If a driver calls asynManager:registerPort with the ASYN_CANBLOCK bit of attributes set then asynManager creates a thread for the port. Each portThread has its own set of queues for the calls to queueRequest. portThread runs forever implementing the following algorithm:

1. Wait for work by calling epicsEventMustWait. Other code such as queueRequest call epicsEventSignal.
2. If the port is disabled, return 1.
3. For every element in queue, asynQueuePriorityConnect:
   • Removes the element from the queue.
   • Calls the user's callback
4. If the port is not connected and autoConnect is true for the port, then attempt to connect to the port.
5. If the port is still not connected, return 1.
6. For each element of the queues asynQueuePriorityHigh, ...,asynQueuePriorityLow.
   • If disabled, skip this element.
   • If not connected and autoConnect is true for the device, then attempt to connect to the device.
   • If not connected, skip this element.
   • If locked by another thread, skip this element.
   • If not locked and user has requested lock, then lock.
   • Remove from queue and call user callback.

The actual code is more complicated because it unlocks before it calls code outside asynManager. This means that the queues can be modified and exceptions may occur.

A special record type asynRecord is provided. Details are described in asynRecord. This section provides a brief description of how to use it.

Each IOC can load one or more instances of asynRecord. An example is:

cd ${ASYN}
dbLoadRecords("db/asynRecord.db","P=asyn,R=Test,PORT=L0,ADDR=15,IMAX=0,OMAX=0")

The example creates a record with name "asynTest" (formed from the concatenation of the P and R macros) that will connect to port "L0" and addr 15. After the ioc is started, it is possible to change PORT and/or ADDR. Thus, a single record can be used to access all asyn devices connected to the IOC. Multiple records are only needed if one or more devices need a dedicated record.

An medm display is available for accessing an asynRecord. It is started as follows:

cd <asyn>/medm
medm -x -macro "P=asyn,R=Test" asynRecord.adl

The following medm display appears.

The following reads from a device via octet messages:

#include <asynDriver.h>
...
#define BUFFER_SIZE 80
typedef struct myData {
    epicsEventId done;
    asynOctet    *pasynOctet;
    void         *drvPvt;
    char         buffer[BUFFER_SIZE];
}myData;

static void queueCallback(asynUser *pasynUser) {
    myData     *pmydata = (myData *)pasynUser->userPvt;
    asynOctet  *pasynOctet = pmydata->pasynOctet;
    void       *drvPvt = pmydata->drvPvt;
    asynStatus status;
    int        writeBytes,readBytes;
    int        eomReason;

    asynPrint(pasynUser,ASYN_TRACE_FLOW,"queueCallback entered\n");
    status = pasynOctet->write(drvPvt,pasynUser,pmydata->buffer,
              strlen(pmydata->buffer),&writeBytes);
    if(status!=asynSuccess) {
        asynPrint(pasynUser,ASYN_TRACE_ERROR,
            "queueCallback write failed %s\n",pasynUser->errorMessage);
    } else {
        asynPrintIO(pasynUser,ASYN_TRACEIO_DEVICE,
            pmydata->buffer,strlen(pmydata->buffer),
            "queueCallback write sent %d bytes\n",writeBytes);
    }
    status = pasynOctet->read(drvPvt,pasynUser,pmydata->buffer,
         BUFFER_SIZE,&readBytes,&eomReason);
    if(status!=asynSuccess) {
        asynPrint(pasynUser,ASYN_TRACE_ERROR,
            "queueCallback read failed %s\n",pasynUser->errorMessage);
    } else {
        asynPrintIO(pasynUser,ASYN_TRACEIO_DEVICE,
            pmydata->buffer,BUFFER_SIZE,
            "queueCallback read returned: retlen %d eomReason 0x%x data %s\n",
            readBytes,eomReason,pmydata->buffer);
    }
    if(pmydata->done) epicsEventSignal(pmydata->done);
}

static void asynExample(const char *port,int addr,const char *message)
{
    myData        *pmyData;
    asynUser      *pasynUser;
    asynStatus    status;
    asynInterface *pasynInterface;
    int           canBlock;

    pmyData = (myData *)pasynManager->memMalloc(sizeof(myData));
    memset(pmyData,0,sizeof(myData));
    strcpy(pmyData->buffer,message);
    pasynUser = pasynManager->createAsynUser(queueCallback,0);
    pasynUser->userPvt = pmyData;
    status = pasynManager->connectDevice(pasynUser,port,addr);
    if(status!=asynSuccess) {
        printf("can't connect to serialPort1 %s\n",pasynUser->errorMessage);
        exit(1);
    }
    pasynInterface = pasynManager->findInterface(
        pasynUser,asynOctetType,1);
    if(!pasynInterface) {
        printf("%s driver not supported\n",asynOctetType);
        exit(-1);
    }
    pmyData->pasynOctet = (asynOctet *)pasynInterface->pinterface;
    pmyData->drvPvt = pasynInterface->drvPvt;
    canBlock = 0;
    pasynManager->canBlock(pasynUser,&canBlock);
    if(canBlock) pmyData->done = epicsEventCreate(epicsEventEmpty);
    status = pasynManager->queueRequest(pasynUser,asynQueuePriorityLow, 0.0);
    if(status) {
        asynPrint(pasynUser,ASYN_TRACE_ERROR,
            "queueRequest failed %s\n",pasynUser->errorMessage);
    }
    if(canBlock) epicsEventWait(pmyData->done);
    status = pasynManager->freeAsynUser(pasynUser);
    if(status) {
        asynPrint(pasynUser,ASYN_TRACE_ERROR,
            "freeAsynUser failed %s\n",pasynUser->errorMessage);
    }
    epicsEventDestroy(pmyData->done);
    pasynManager->memFree(pasynUser->userPvt,sizeof(myData));
}

The flow of control is as follows:

1. A port driver calls registerPort. This step is not shown in the above example.
2. asynExample allocates myData and an asynUser.
3. asynExample 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. queueCallback is called. It calls the port driver's write and read methods.

The asynDriver distribution includes code to test asynDriver. It is also an example of how to interface to asynManager. The example resides in <top>/testApp and contains the following components:

Db/
   test.db
adl/
   test.adl
src/
   devAsynTest.c
   devAsynTest.dbd
   echoDriver.c
   interposeInterface.c

echoDriver is a port driver that echos messages it receives. It implements asynCommon and asynOctet. When asynOctet:write is called it saves the message. When asynOctet:read is called, the saved message is returned and the message is flushed. echoDriverInit has an argument that determines if it acts like a multiDevice or a single device port driver.

An instance of echoDriver is started via the iocsk command:

echoDriverInit(portName,delay,noAutoConnect,multiDevice)

where

• portName - the port name for this instance.
• delay - The time to delay after a read or write. If delay is 0 then echoDriver registers as a synchronous port driver, i.e. bit ASYN_CANBLOCK of attributes is not set. If delay>0 then ASYN_CANBLOCK is set.
• noAutoConnect - Determines initial setting for port.
• multiDevice - If true then it supports two devices with addresses 0 and 1. If false it does not set ASYN_MULTIDEVICE, i.e. it only supports a single device.

test.db is a template containing three records: a calc record, which forward links to a stringout record which forward links to a stringin record. The string records attach to the device support supplied by devAsynTest.c. The stringout and stringin records share the same asynUser. When the stringout record processes it:

• Fetches the current value from the calc record (converted to ascii).
• Calls pasynManager->lock.
• Calls pasynManager->queueRequest.
• The callback calls pasynOctet->write and then asks for the record to complete processing.
• The stringout record forward links to the stringin record.

• Calls pasynManager->queueRequest.
• The callback routine:
  • calls pasynOctet->read
  • Checks what it received vs what the stringout record wrote. If the values match, it sets its VAL field to "OK", otherwise it writes an error message into VAL.
  • Asks for the record to complete processing.
• The stringin record calls pasynManager->unlock.

devAsynTest also does additional checking for connect state and enable/disable.

Executing "medm -x test.adl" produces the display:

It assumes that an ioc has been started via:

cd <top>/iocBoot/ioctest
../../bin/solaris-sparc/test st.cmd

This starts two versions of echoDriver as port "A" and "B". port A acts as single device port. port B acts as a multiDevice port that has two devices. For each of the three possible devices, the st.cmd file starts up two sets of records from test.db The st.cmd file also loads a set of records from asynTest.db for port A and for port B and for each of the two devices attached to port B. It also loads a set of records from asynGeneric.db.

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

asynGpibDriver.h

asynGpibDriver.h contains the following definitions:

#include "asynDriver.h"
#define asynGpibType "asynGpib"
#define asynGpibType "asynGpib"
/* GPIB drivers */
typedef void (*srqHandler)(void *userPrivate,int gpibAddr,int statusByte);
typedef struct asynGpib asynGpib;
typedef struct asynGpibPort asynGpibPort;
/*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,
        int attributes,int autoConnect,
        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);
    /*asynOctet methods passed through from asynGpib*/
    asynStatus (*read)(void *drvPvt,asynUser *pasynUser,
                      char *data,int maxchars,int *nbytesTransfered,
                      int *eomReason);
    asynStatus (*write)(void *drvPvt,asynUser *pasynUser,
                      const char *data,int numchars,int *nbytesTransfered);
    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 */
    asynStatus (*srqStatus) (void *drvPvt,int *isSet);
    asynStatus (*srqEnable) (void *drvPvt, int onOff);
    asynStatus (*serialPollBegin) (void *drvPvt);
    asynStatus (*serialPoll) (void *drvPvt, int addr, double timeout,int *status);
    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 VXI-11. It provides:

Local Serial Port

The drvAsynSerialPort driver supports devices connected to serial ports on the IOC.

Serial ports are configured with the drvAsynSerialPortConfigure and asynSetOption commands:

   drvAsynSerialPortConfigure("portName","ttyName",priority,noAutoConnect,noEos)
   asynSetOption("portName",addr,"key","value")

• portName - The portName that is registered with asynGpib.
• ttyName - The name of the local serial port (e.g. "/dev/ttyS0").
• priority - Priority at which the asyn I/O thread will run. If this is zero or missing,then epicsThreadPriorityMedium is used.
• noAutoConnect - Zero or missing indicates that portThread should automatically connect. Non-zero if explicit connect command must be issued.
• noEos - Zero or missing indicates that the generic EOS handler will be interposed. Non-zero will not interpose the EOS handler.
• addr - This argument is ignored since serial devices are configured with multiDevice=0.

The setEos and getEos methods have no effect and return asynError. The read method blocks until at least one character has been received or until a timeout occurs. The read method transfers as many characters as possible, limited by the specified count. asynInterposeEos can be used to support EOS.

The following table summarizes the drvAsynSerialPort driver asynSetOption keys and values. Default values are enclosed in square brackets.

The clocal and crtscts parameter names are taken from the POSIX termios serial interface definition. The clocal parameter controls whether the modem control lines (Data Terminal Ready, Carrier Detect/Received Line Signal Detect) are used (clocal=N) or ignored (clocal=Y). The crtscts parameter controls whether the hardware handshaking lines (Request To Send, Clear To Send) are used (crtscts=Y) or ignored (crtscts=N). The default parameter values (clocal=Y, crtscts=N) are those of a 'data-leads-only' serial interface.

The vxWorks serial driver does not provide independent control of the hardware handshaking and modem control lines, thus clocal=Y implies crtscts=N and clocal=N implies crtscts=Y.

vxWorks IOC serial ports may need to be set up using hardware-specific commands. Once this is done, the standard drvAsynSerialPortConfigure and asynSetOption 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)
drvAsynSerialPortConfigure("L0","/tyGS/0/0",0,0,0)
asynSetOption("L0",0,"baud","9600")

TCP/IP or UDP/IP Port

The drvAsynIPPort driver supports devices which communicate over a TCP/IP or UDP/IP connection. A typical example is a device connected through an Ethernet/Serial converter box.

TCP/IP or UDP/IP connections are configured with the drvAsynIPPortConfigure command:

   drvAsynIPPortConfigure("portName","hostInfo",priority,noAutoConnect,noEos)

• portName - The portName that is registered with asynGpib.
• hostInfo - The Internet host name, port number and optional IP protocol of the device (e.g. "164.54.9.90:4002", "serials8n3:4002", "serials8n3:4002 TCP" or "164.54.17.43:5186 udp"). If no protocol is specified, TCP will be used.
• priority - Priority at which the asyn I/O thread will run. If this is zero or missing, then epicsThreadPriorityMedium is used.
• noAutoConnect - Zero or missing indicates that portThread should automatically connect. Non-zero if explicit connect command must be issued.
• noEos - Zero or missing indicates that the generic EOS handler will be interposed. Non-zero will not interpose the EOS handler.

The setEos and getEos methods have no effect and return asynError. The read method blocks until at least one character has been received or until a timeout occurs. The read method transfers as many characters as possible, limited by the specified count.

There are no asynSetOption key/value pairs associated with drvAsynIPPort connections.

asynInterposeEos and asynInterposeFlush can be used to provide additional functionality.

VXI-11

• VXI-11.1 - A standard for communicating with VXIbus devices. 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 devices. This means that the TCP/IP connection is talking directly with an device. These devices have an vxiName that starts with "inst".

Consult the following documents (available on-line) 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,noAutoConnect)

• 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 datatype 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.
• noAutoConnect - Zero or missing indicates that portThread should automatically connect. Non-zero if explicit connect command must be issued.

The vxi11 driver implements two timeouts: ioTimeout and rpcTimeout (Remote Procedure Call timeout). The ioTimeout is taken from asynUser:timeout. The rpcTimeout is handled internally for each port. It has a default of 4 seconds but can be changed by calling setOptions. For example:

asynSetOption L0 -1 rpctimeout .1

Green Springs IP488

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

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

• portName - An ascii string specifying the port name that 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 - An integer specifying the priority of the port thread. A value of 0 will result in a defalt value being assigned
• noAutoConnect - Zero or missing indicates that portThread should automatically connect. Non-zero if explicit connect command must be issued.

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

National Instruments GPIB-1014D

This is support for a National Instruments VME GPIB interface. The configuration command is:

    ni1014Config(portNameA,portNameB,base,vector,level,priority,noAutoConnect)

• portNameA - An ascii string specifying the port name that will be registered with asynDriver for portA.
• portNameB - An ascii string specifying the port name that will be registered with asynDriver for portB. If only one port should be registered, then leave this as a null string. The support should also work for a single port NI1014 but has not been tested.
• base - VME A16 base address.
• vector - VME interrupt vector.
• level - An integer specifying the interrupt level.
• priority - In integer specifying the priority of the port thread. A value of 0 will result in a defalt value being assigned
• noAutoConnect - Zero or missing indicates that portThread should automatically connect. Non-zero if explicit connect command must be issued.

An example is:

ni1014Config("L0","L1",0x5000,0x64,5,0,0)

NOTES:

• Ports A and B are almost but not quite the same. Thus the code for connecting to port A is slightly different than the code for portB.
• In order to disconnect and reconnect either port, BOTH ports must be disconnected and reconnected.
• When the ports are connected, portA MUST be connected before port B.
• Programmed I/O, via interrupts, rather than DMA is implemented. Thus no A24 address space is required.

iocsh Commands

    asynReport(filename,level)
    asynInterposeFlushConfig(portName,addr,timeout)
    asynInterposeEosConfig(portName,addr)
    asynSetTraceMask(portName,addr,mask)
    asynSetTraceIOMask(portName,addr,mask)
    asynSetTraceFile(portName,addr,filename)
    asynSetTraceIOTruncateSize(portName,addr,size)
    asynSetOption(portName,addr,key,val)
    asynShowOption(portName,addr,key)
    asynAutoConnect(portName,addr,yesNo)
    asynEnable(portName,addr,yesNo)
    asynOctetConnect(entry,portName,addr,oeos,ieos,timeout,buffer_len)
    asynOctetRead(entry,nread,flush)
    asynOctetWrite(entry,output)
    asynOctetWriteRead(entry,output,nread)
    asynOctetFlush(entry)

asynReport calls asynCommon:report for all registered drivers and interposeInterface.

asynInterposeFlushConfig is a generic interposeInterface that implements flush for low level drivers that don't implement flush. It just issues read requests until no bytes are left to read. The timeout is used for the read requests.

asynInterposeEosConfig is a generic interposeInterface that implements End of String processing for low level drivers that don't.

asynSetTraceMask calls asynTrace:setTraceMask for the specified port and address.

asynSetTraceIOMask calls asynTrace:setTraceIOMask for the specified port and address.

asynSetTraceFile calls asynTrace:setTraceFile. The filename is handled as follows:

• Not specified - A NULL pointer is passed to setTraceFile. Subsequent messages are sent to errlog.
• An empty string ("") or "stdout" - stdout is passed to setTraceFile.
• Any other string - The specified file is opened with an option of "w" and the file pointer is passed to setTraceFile.

asynSetTraceIOTruncateSize calls asynTrace:setTraceIOTruncateSize

asynSetOption calls asynCommon:setOption. asynShowOption calls asynCommon:getOption.

asynOctetConnect, ...asynOctetFlush provide shell access to asynOctetSyncIO methods. The entry is a character string constant that identifys the port,addr.

where

• filename - An ascii string naming a file. If null or a null string, then the output is sent to stdout.
• level - The report level.
• portName - An ascii string specifying the portName of the driver.
• addr - In integer specifying the address of the device. For multiDevice ports a value of -1 means the port itself. For ports that support a single device, addr is ignored.
• 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.
• yesNo - The value (0,1) means (no,yes).
• entry - A character string that identifies the asynOctetConnect request.
• oeos,ieos - The output and input End of String terminator.  Default="\r"
• timeout - timeout as an integer in milliseconds. The default is 1.
• buffer_len - length of buffer for I/O. Default=80.
• nread - max number of bytes to read. Default=buffer_len.
• flush - (0,1) means (don't, do) flush before reading. Default=0.
• output - output string.

The commands asynOctetConnect, asynOctetRead, asynOctetWrite, asynOctetWriteRead, asynOctetFlush allow I/O to a device from the ioc shell. Examples are:

asynOctetConnect("myid","A",0,"\n","\n",1,20)
asynOctetWrite("myid","testnew")
asynOctetRead("myid")
testnew\n
asynOctetWriteRead("myid","this is test")
this is test\n

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 number. For example:

.../support/asyn/3-1

4. Edit the config/RELEASE file and set the paths to your installation of EPICS_BASE 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 devices an application must obtain device specific support elsewhere. This section only explains how to include asynDriver components.

In the configure/RELEASE file add definitions for IPAC, ASYN, 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 and uncomment the line or lines appropriate for your application:

        include "asyn.dbd"
        #include "drvAsynSerialPort.dbd"
        #include "drvAsynIPPort.dbd"
        #include "drvVxi11.dbd"
        #include "drvGsIP488.dbd"
        #include "drvIpac.dbd"
        #registrar(mv162ipRegistrar)
      

In the st.cmd file add:

dbLoadRecords("db/asynRecord.db", "P=<ioc>, R=<record>, PORT=<port>, ADDR=<addr>, OMAX=<omax>, IMAX=<imax>")

You must provide values for <ioc>, <record>, <port>, <addr>, <omax>, and <imax>.

Once the application is running, medm displays for an ioc can be started by: medm -x -macro "P=<ioc>,R=<record>" <asyntop>/medm/asynRecord.adl &

You must provide correct values for <ioc> and <record>. Once asynRecord is started, it can be connected to different devices.

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.