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
• Linux-Gpib
• Green Springs IP488
• National Instruments GPIB-1014D

asynDriver is a general purpose facility for interfacing device specific code to low level drivers. asynDriver allows 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.

asynDriver has the following key concepts:

• Device support communicates with drivers via interfaces

  Drivers take care of the details of how to communicate with a device and implement interfaces for use by device support. Interfaces are defined for both message and register based devices. In the past when support was written for a new type of device, device support for standard EPICS records had to be written in addition to the driver support. Now a driver just implements one or more of the standard interfaces.

• A port provides access to device instances

  A port, which has a portName, identifies a communication path to one or more device instances. For example a GPIB port can have up to 15 devices connected to it. An RS232 port communicates with a single device. Drivers register a port. Device support connects to a port.

• asynManager controls access to a port

  asynManager, a component of asynDriver, provides exclusive access to a driver via calls to queueRequest or lockPort/unlockPort. Once device support has access, it can make an arbitrary number of calls to the driver knowing that no other support can call the driver. Device and driver support do not need to implement queues or semaphores since asynManager does this for them.

• asynTrace provides a general purpose diagnostic facility

  Rules are defined for providing diagnostic messages. Provided device and driver support follow the rules, a user can obtain several levels of diagnostic information that can be displayed on the console, written to a file, or sent to the EPICS errlog facility.

• asynRecord - Generic access to an device/port

  asynRecord is an EPICS record and set of associated MEDM displays that provide access to:

  • A port or a device connected to a port

    The port or port,addr can be changed dynamically. Thus with one asynRecord in an IOC, it is possible to talk to any device that has an asyn compatible driver.

  • asynTrace - All asynTrace options can be specified asynRecord.
  • Connection Management

    Display and change connection, enable, and autoConnect state

  • Standard interfaces

    These can be used to communicate with devices. For example if a new instrument arrives that has a serial, gpib, or ethernet port, then it is often possible to communicate with it just by attaching an asynRecord to it.

• Extensive Serial Support

  asynDriver provides many facilities for communicating with RS232, RS485, GPIB, and ethernet.

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, asynGpib, and other interfaces.
• standard interfaces: Standard message and register based interfaces are defined. Low Level Drivers implement standard interfaces. 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 accessed via Ethernet/Serial converter boxes. TCP/IP and UDP/IP socket communication are supported..
• VXI-11: A replacement for the VXI-11 support of the Franksen gpibCore support.
• Linux-gpib: Support for the Linux GPIB Package library.
• gsIP488: A low level driver for the Greensprings IP488 Industry Pack module.
• ni1014: A low level driver for the National Instruments VME 1014D.
• Serial Bus Support: The asynManager lockPort/unlockPort methods and the asynLockPortNotify interface were added to make it easier to support serial bus drivers that use the standard serial support.

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.
• synApps (The APS BCDA synchrotron applications). The mca, dxp, serial, GPIB, Ip330, IpUnidig, DAC128V and quadEM applications in this package have all been converted to asyn.

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 are included with asynDriver.

Dirk Zimoch has created a version of STREAMS that uses asynDriver.

Hopefully Allen Honey will get time to convert devAscii.

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

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.

Mark Rivers

Mark became an active developer of asynDriver soon after he started converting SYNAPPS to use asynDriver. He soon pushed to have asynDriver support synchronous drivers, support register based drivers, and support interrupts. With these additions asynDriver is a framework for interfacing to a large class of devices instead of just message based asynchronous devices.

Yevgeny A. Gusev

Yevgeny has found bugs and suggested improvements in the way asynManager handles queue timeouts and cancels. He provides an expert and welcome set of eyes to look at difficult code!!!

Definitions

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 uses 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 "method" rather than "function pointer".

• port

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

• portDriver

  Code that communicates with a port.

• portThread

  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. EIA232 serial ports, only support a single device. Whenever this document uses the word device without a qualifier, it means something that is connected to a port.

• device support

  Code that interacts with a device.

• synchronous

  Support that does not voluntarily give up control of the CPU.

• asynchronous

  Support that is not synchronous. Some examples of asynchronous operations are epicsThreadSleep, epicsEventWait, and stdio operations. Calls to epicsMutexTake are considered to be synchronous operations, i.e. they are permitted in synchronous support.

• asynDriver

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

• asynManager

  An interface and the code which implements the methods for interfaces asynManager and asynTrace.

• asynchronous Driver

  A driver that blocks 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. Typical examples are VME register based devices.

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

• interrupt

  As implemented by asynManager, interrupt just means "I have a new value for port, address".

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

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

These are interfaces provided by asynManager or interfaces implemented by all or most port drivers.

The interfaces are:

asynManager provides services for communicating with a device connected to a port.

asynCommon is an interface 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 an interface for generating diagnostic messages.

asynLockPortNotify is an interface that is implemented by a driver which is an asynUser of another driver. An example is a serial bus driver that uses standard serial support. asynManager calls asynLockPortNotify whenever it locks or unlocks the port.

asynDrvUser is an interface for communicating information from device support to a driver without the device support knowing any details about what is passed.

Generic Interfaces

In addition to asynCommon and optionally asynDrvUser, port drivers can implement one or more of the following message and/or register based interfaces.

asynOctet methods for message based devices

asynFloat64 methods for devices that read/write IEEE float values

asynFloat64Array methods for devices that read/write arrays of IEEE float values

asynInt32 methods for devices that read/write integer values. Many analog I/O drivers can use this interface.

asynInt32Array methods for devices that read/write arrays of integer values

asynUInt32Digital methods for devices that read/write arrays of digital values. This interface provides a mask to address individual bits within registers.

asynManager

asynManager is an interface and associated code. It is the "heart" of asynDriver since it manages the interactions between device support code and drivers. It provides the following services:

• reporting

  Method: report

• asynUser creation

  Methods: createAsynUser, duplicateAsynUser, freeAsynUser

  An asynUser is a "handle" for accessing asynManager services and for calling interfaces implemented by drivers. An asynUser must only be created via a call to createAsynUser or duplicateAsynUser since asynManager keeps private information for each asynUser. freeAsynUser puts the asynUser on a free list rather than calling free. Clients can continually create and free asynUsers quickly and without fragmenting memory.

  The call to createAsynUser specifies a processCallback and a timeoutCallback. These are the callbacks that will be called as a result of a queueRequest.

  An asynUser should not be shared between parts of code that can simultaneously access a driver. For example device support for standard EPICS records should create an asynUser for each record instance.

• Basic asynUser services

  Methods: connectDevice, disconnect, findInterface

  These methods should only be called by the code that created the asynUser.

  After an asynUser is created the user calls connectDevice. The user is connected to a port driver that can communicate with a device. findInterface is called for each interface the user requires. disconnect is called when the user is done with the device.

• Queuing services

  Methods: queueRequest, cancelRequest, lockPort, unlockPort, blockProcessCallback, unblockProcessCallback

  queueRequest is a request to call the processCallback specified in the call to createAsynUser. Most interface methods must only be called from processCallback via a call to queueRequest or between calls to lockPort/unlockPort.. Exceptions to this rule must be clearly documented ( a common exception are methods registerInterruptUser/cancelInterruptUser).

  queueRequest semantics differ for ports that can block and ports that do not block

  When registerPort is called by a driver that can block, a thread is created for the port. A set of queues, based on priority, is created for the thread. queueRequest puts the request on one of the queues. The port thread takes the requests from the queues and calls the associated callback. Only one callback is active at a time.

  When registerPort is called by a driver that does not block, a mutex is created for the port. queueRequest takes the mutex, calls the callback, and releases the mutex. The mutex guarantees that two callbacks to a port are not active at the same time.

  lockPort is a request to lock all access to low level drivers until unlockPort is called. If the port blocks then lockPort and all calls to the port driver may block. lockPort/unlockPort are provided for use by code that is willing to block or for communication with synchronous ports.

  blockProcessCallback is a request to prevent acccess to a device or port by other asynUsers between queueRequests. blockProcessCallback can be called from a processCallback or when the asynUser has no request queued. When called from processCallback blocking starts immediately, otherwise blocking starts the next time processCallback is called. Blocking means that no other asynUser's processCallback will be called until unblockProcessCallback is called. blockProcessCallback only works with drivers that can block and an error is returned if it is called for non-blocking drivers.

• Basic Driver services

  Methods: registerPort,registerInterface

  registerPort is called by a portDriver. registerInterface is called by a portDriver or an interposeInterface.

  Each port driver provides a configuration command that is executed for each port instance. The configuration command performs port specific initializations, calls registerPort, and registerInterface for each interface it implements.

• Attribute Retrieval

  Methods: isMultiDevice, canBlock, getAddr, getPortName, isConnected, isEnabled, isAutoConnect

  These methods can be called by any code that has access to the asynUser

• Connection services

  Methods: enable,autoConnect

  These methods can be called by any code that has access to the asynUser.

  These methods can be called to set the enable and autoConnect settings for a port and/or device. queueManager implements autoConnect by calling asynCommon:connect just before it calls processCallback. It does this if autoConnect is true and a port/device is enabled but not connected.

• Exception services

  Methods: exceptionCallbackAdd, exceptionCallbackRemove, exceptionConnect, exceptionDisconnect

  Device support code calls exceptionCallbackAdd and exceptionCallbackRemove. The complete list of exceptions is defined in asynDriver.h as "enum asynException".

  Whenever a port driver connects or disconnects, normally as a result of a call to asynCommon:connect or asynCommon:disconnect, it must also call exceptionConnect or exceptionDisconnect.

• Interrupt services

  Methods: registerInterruptSource, getInterruptPvt, createInterruptNode, freeInterruptNode, addInterruptUser, removeInterruptUser, interruptStart, interruptEnd

  Interrupt just means: "I have a new value." Many asyn interfaces, e.g. asynInt32, provide interrupt support. These interfaces provide methods addInterruptUser and removeInterruptUser. Device support calls addInterruptUser if it wants to be called whenever an interrupt occurs. Drivers or other code that implements the interface calls the registered users when it has new data. asynManager provides services that help drivers implement thread-safe support for interrupts.

  A driver that supports interrupts calls registerInterruptSource for each interface that has associated interrupts. It calls interruptStart to obtain a list of all registered users and interruptEnd after it calls the registered users. The driver is also responsible for calling addInterruptUser and removeInterruptUser.

  If any calls are made to addInterruptUser or removeInterruptUser between the calls to interruptStart and interruptEnd, asynManager puts the request on a list and processes the request after interruptEnd is called.

  Many standard interfaces, e.g. asynInt32, provide methods registerInterruptUser, cancelInterruptUser. These interfaces also provide an auxilliary interface, e.g. asynInt32Base, and code which implements registerInterruptUser and cancelInterruptUser.

  On operating systems like vxWorks or RTEMS interruptStart,interruptEnd MUST NOT be called from interupt level.

• General purpose freelist service

  Methods: memMalloc, memFree

  These methods do not require an asynUser. They are provided for code that must continually allocate and free memory. Since memFree puts the memory on a free list instead of calling free, they are more efficient that calloc/free and also help prevent memory fragmentation.

• Interpose service

  Method: interposeInterface

  Code that calls interposeInterface implements an interface which is either not supported by a port driver or that is "interposed" between the caller and the port driver. For example asynInterposeEos interposes asynOctet. It performs end of string processing for port drivers that do not support it.

  interposeInterface is recursive, i.e. an arbitrary number of interpose layers can exist above a single port,addr.

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. An asynUser connected to the port can issue requests that affect all address on the port. For example disabling access to the port prevents access to all addresses on the port.

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 exceptionDisconnect whenever they disconnect.

Protecting a Thread from Blocking

The methods asynManager:report and asynCommon:report can be called by any thread, but the caller is blocked until the report finishes. lockPort, unlockPort and most port methods may block. The other asynManager methods can be called by any thread including portThread. None of these methods block.

Unless stated otherwise the methods for other interfaces must only be called by processCallback or by calls between lockPort/unlockPort.

Interface methods registerInterruptUser and cancelInterruptUser must never block. The registerInterruptUser callback must not block because it could be called by a non blocking driver.

portThread

If a driver calls asynManager:registerPort with the ASYN_CANBLOCK attributes bit set, then asynManager creates a thread for the port. Each portThread has its own set of queues for the calls to queueRequest. Four queues are maintained. One queue is used only for asynCommon:connect and asynCommon:disconnect requests. The other queues provide different priorities: low, medium, and high. 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, go back to 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, go back to 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 blocked by another thread, skip this element.
   • If not blocked and user has requested blocking, then blocked.
   • Remove from queue and:
     • lockPort
     • call user callback
     • unlockPort

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.

Initialization

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

User code creates an asynUser, which is a "handle" for accessing asynDriver facilities, by calling

    pasynManager->createAsynUser(processCallback,timeoutCallback);

• An asynUser is the means by which asynManager manages multiple requests for accessing a port.
• processCallback,which is used by queueRequest described below, is the addresss of a user supplied callback routine.
• timeoutCallback is the address of caller supplied callback that will be called if a queueRequest remains on the queue too long.
• Device support code should create an asynUser for each "atomic" access to low level drivers, i.e. a set of calls that must not be interlaced with other calls to the low level drivers. For example device support for EPICS record support should create an asynUser for each record instance.
• Device support code should NOT try to share an asynUser between multiple sources of requests for access to a port. If this is done then device support must itself handle contention issues that are already handled by asynManager.

User code connects to a low level driver via a call to

    status = pasynManager->connectDevice(pasynUser,portName,addr);

     pasynInterface = pasynManager->findInterface(pasynUser,asynOctetType,1);

Requesting access to a port

User code can request access to a port by two methods:

• queueRequest -

  The processCallback passed to createAsynUser makes calls to the port interfaces.

• lockPort/unlockPort -

  The caller can make calls to the port interfaces while the lock is held. These calls and calls to the port may block and thus should NOT be used by code that should not block, e.g. synchronous device support for EPICS records.

queueRequest - Flow of Control

User code requests access to a port by calling:

    status = pasynManager->queueRequest(pasynUser,priority,timeout);

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

The first example shows access to a port that can block.

Figure 1: Asynchronous Control Flow

1. Record processing calls device support with PACT 0 (Processing is not active).
2. 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. Subsequent operations for this I/O request are handled in the port driver thread.
4. The portThread removes the I/O request from the work queue.
5. The portThread calls the processCallback located in Record device support.
6. processCallback calls the low-level driver. 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 processCallback.
7. processCallback requests that the record be processed. NOTE: The process request will be made by one of the standard callback requests rather than the port thread.
8. Record support calls device support again, this time with PACT 1(processing is active). Device support updates fields in the record and returns to record support which completes record processing.

The second example shows access to a port that cannot block.

Figure 2: Synchronous Control Flow

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

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 (or asynManager:dupliateAsynUser) and asynManager:freeAsynUser.

typedef struct asynUser {
    char *errorMessage;
    int errorMessageSize;
    /* timeout must be set by the user */
    double       timeout;  /*Timeout for I/O operations*/
    void         *userPvt;
    void         *userData;
    /*The following is for user to/from driver communication*/
    void         *drvUser;
    /*The following is normally set by driver*/
    int          reason;
    /* The following are for additional information from method calls */
    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

/*standard values for asynUser.reason*/
#define ASYN_REASON_SIGNAL -1

typedef struct interruptNode{
    ELLNODE node;
    void    *drvPvt;
}interruptNode;

typedef struct asynManager {
    void      (*report)(FILE *fp,int details,const char*portName);
    asynUser  *(*createAsynUser)(userCallback process,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 (*blockProcessCallback)(asynUser *pasynUser, int allDevices);
    asynStatus (*unblockProcessCallback)(asynUser *pasynUser, int allDevices);
    asynStatus (*lockPort)(asynUser *pasynUser);
    asynStatus (*unlockPort)(asynUser *pasynUser);
    asynStatus (*getAddr)(asynUser *pasynUser,int *addr);
    asynStatus (*getPortName)(asynUser *pasynUser,const char **pportName);
    /* 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);
    /*The following are methods for interrupts*/
    asynStatus (*registerInterruptSource)(const char *portName,
                               asynInterface *pasynInterface, void **pasynPvt);
    asynStatus (*getInterruptPvt)(asynUser *pasynUser,
                               const char *interfaceType, void **pasynPvt);
    interruptNode *(*createInterruptNode)(void *pasynPvt);
    asynStatus (*freeInterruptNode)(asynUser *pasynUser,interruptNode *pnode);
    asynStatus (*addInterruptUser)(asynUser *pasynUser,
                                  interruptNode*pinterruptNode);
    asynStatus (*removeInterruptUser)(asynUser *pasynUser,
                                  interruptNode*pinterruptNode);
    asynStatus (*interruptStart)(void *pasynPvt,ELLLIST **plist);
    asynStatus (*interruptEnd)(void *pasynPvt);
}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

asynCommon describes the methods that must be implemented by drivers.

/* 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;

asynDrvUser

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

#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;

asynLockPortNotify

This is provided for port drivers that are an asynUser of another port driver. For example a serial bus driver can be implemented by connecting to a standard serial port to perform the actual I/O. When the serial bus port is locked, either by the requester calling lockPort or because a queueRequest was dequeued, then the serial bus driver needs to lock the associated serial port.

The serial bus driver registers interface asynLockPortNotify. Whenever the serial bus port is locked, asynManager calls pasynLockPortNotify.lock. The serial bus driver calls asynManager.lockPort for the serial port to which it is connected. Similarly for unlockPort. Thus while the serial bus port is locked, the serial bus is also locked.

asynLockPortNotify is used only by asynManager itself. It is not put in the list of interfaces for the port.

asynLockPortNotify is:

#define asynLockPortNotifyType "asynLockPortNotify"
typedef struct  asynLockPortNotify {
    asynStatus (*lock)(void *drvPvt,asynUser *pasynUser);
    asynStatus (*unlock)(void *drvPvt,asynUser *pasynUser);
}asynLockPortNotify;

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.

#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;

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, size_t 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 *fp);
    FILE       *(*getTraceFile)(asynUser *pasynUser);
    asynStatus (*setTraceIOTruncateSize)(asynUser *pasynUser,size_t size);
    size_t     (*getTraceIOTruncateSize)(asynUser *pasynUser);
    int        (*print)(asynUser *pasynUser,int reason, const char *pformat, ...);
    int        (*printIO)(asynUser *pasynUser,int reason,
               const char *buffer, size_t 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 or to errlog.
• 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 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:

    asynPrint(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 portThread. 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 to 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 useful when asynPrint is called before connectDevice.

These are interfaces for communicating with message based devices, where message based means that the device communicates via octet strings, i.e. arrays of 8 bit bytes. Three interfaces are provided: asynOctet, asynOctetBase, and asynOctetSyncIO. asynOctet is generic message based interface. asynOctetBase is an interface used by port drivers that implement asynOctet. It's primary putpose is to help with interrupt support. asynOctetSyncIO provides a synchronous inteface to asynOctet and can be used by code that is willing to block.

asynOctet

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

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

#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*/

typedef void (*interruptCallbackOctet)(void *userPvt, asynUser *pasynUser,
                      char *data,size_t numchars, int eomReason);

typedef struct asynOctetInterrupt {
    asynUser *pasynUser;
    int      addr;
    interruptCallbackOctet callback;
    void *userPvt;
}asynOctetInterrupt;


#define asynOctetType "asynOctet"
typedef struct asynOctet{
    asynStatus (*write)(void *drvPvt,asynUser *pasynUser,
                    const char *data,size_t numchars,size_t *nbytesTransfered);
    asynStatus (*writeRaw)(void *drvPvt,asynUser *pasynUser,
                    const char *data,size_t numchars,size_t *nbytesTransfered);
    asynStatus (*read)(void *drvPvt,asynUser *pasynUser,
                    char *data,size_t maxchars,size_t *nbytesTransfered,
                    int *eomReason);
    asynStatus (*readRaw)(void *drvPvt,asynUser *pasynUser,
                    char *data,size_t maxchars,size_t *nbytesTransfered,
                    int *eomReason);
    asynStatus (*flush)(void *drvPvt,asynUser *pasynUser);
    asynStatus (*registerInterruptUser)(void *drvPvt,asynUser *pasynUser,
                    interruptCallbackOctet callback, void *userPvt,
                    void **registrarPvt);
    asynStatus (*cancelInterruptUser)(void *drvPvt, asynUser *pasynUser,
                    void *registrarPvt);
    asynStatus (*setInputEos)(void *drvPvt,asynUser *pasynUser,
                    const char *eos,int eoslen);
    asynStatus (*getInputEos)(void *drvPvt,asynUser *pasynUser,
                    char *eos, int eossize, int *eoslen);
    asynStatus (*setOutputEos)(void *drvPvt,asynUser *pasynUser,
                    const char *eos,int eoslen);
    asynStatus (*getOutputEos)(void *drvPvt,asynUser *pasynUser,
                    char *eos, int eossize, int *eoslen);
}asynOctet;
/* asynOctetBase does the following:
   calls  registerInterface for asynOctet.
   Implements registerInterruptUser and cancelInterruptUser
   Provides default implementations of all methods.
   registerInterruptUser and cancelInterruptUser can be called
   directly rather than via queueRequest.
*/

#define asynOctetBaseType "asynOctetBase"
typedef struct asynOctetBase {
    asynStatus (*initialize)(const char *portName,
        asynDriverasynInterface *pasynOctetInterface,
        int processEosIn,int processEosOut,int interruptProcess);
    void       (*callInterruptUsers)(asynUser *pasynUser,void *pasynPvt,
        char *data,size_t *nbytesTransfered,int *eomReason);
} asynOctetBase;
epicsShareExtern asynOctetBase *pasynOctetBase;

asynOctetBase is an interface and implementation for drivers that implement interface asynOctet. asynOctetBase implements registerInterruptUser and cancelInterruptUser.

For single device support, it can optionally implement interrupt support. A driver that implements interrupts must call registerInterruptSource. If it asks asunOctetBase to handle interrupts it calls asynOctetBase:callInterruptUsers when it has new data.

For single device support asynOctetBase can optionally call asynInterposeEosConfig to handle end of string processing for input and/or output.

Any null method in the interface passed to initialize are replaced by a method supplied by asynOctetBase.

For an example of how to use asynOctetBase look at asyn/testApp/src/echoDriver.c

pasynOctetBase->initialize(...

asynOctetSyncIO

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.

typedef struct asynOctetSyncIO {
   asynStatus (*connect)(const char *port, int addr,
                         asynUser **ppasynUser, const char *drvInfo);
   asynStatus (*disconnect)(asynUser *pasynUser);
   asynStatus (*openSocket)(const char *server, int port, char **portName);
   asynStatus (*write)(asynUser *pasynUser,
                  char const *buffer, size_t buffer_len,
                  double timeout,size_t *nbytesTransfered);
   asynStatus (*writeRaw)(asynUser *pasynUser,
                  char const *buffer,size_t buffer_len,
                  double timeout,size_t *nbytesTransfered);
   asynStatus (*read)(asynUser *pasynUser, char *buffer, size_t buffer_len,
                  double timeout, size_t *nbytesTransfered,int *eomReason);
   asynStatus (*readRaw)(asynUser *pasynUser, char *buffer, size_t buffer_len,
                  double timeout, size_t *nbytesTransfered,int *eomReason);
   asynStatus (*writeRead)(asynUser *pasynUser,
                  const char *write_buffer, size_t write_buffer_len,
                  char *read_buffer, size_t read_buffer_len,
                  double timeout,
                  size_t *nbytesOut, size_t *nbytesIn, int *eomReason);
   asynStatus (*flush)(asynUser *pasynUser);
   asynStatus (*setInputEos)(asynUser *pasynUser,
                  const char *eos,int eoslen);
   asynStatus (*getInputEos)(asynUser *pasynUser,
                  char *eos, int eossize, int *eoslen);
   asynStatus (*setOutputEos)(asynUser *pasynUser,
                  const char *eos,int eoslen);
   asynStatus (*getOutputEos)(asynUser *pasynUser,
                  char *eos, int eossize, int *eoslen);
   asynStatus (*writeOnce)(const char *port, int addr,
                  char const *buffer, size_t buffer_len, double timeout,
                  size_t *nbytesTransfered, const char *drvInfo);
   asynStatus (*writeRawOnce)(const char *port, int addr,
                  char const *buffer, size_t buffer_len, double timeout,
                  size_t *nbytesTransfered, const char *drvInfo);
   asynStatus (*readOnce)(const char *port, int addr,
                  char *buffer, size_t buffer_len, double timeout,
                  size_t *nbytesTransfered,int *eomReason, const char *drvInfo);
   asynStatus (*readRawOnce)(const char *port, int addr,
                  char *buffer, size_t buffer_len, double timeout,
                  size_t *nbytesTransfered,int *eomReason, const char *drvInfo);
   asynStatus (*writeReadOnce)(const char *port, int addr,
                  const char *write_buffer, size_t write_buffer_len,
                  char *read_buffer, size_t read_buffer_len,
                  double timeout,
                  size_t *nbytesOut, size_t *nbytesIn, int *eomReason,
                  const char *drvInfo);
   asynStatus (*flushOnce)(const char *port, int addr,const char *drvInfo);
   asynStatus (*setInputEosOnce)(const char *port, int addr,
                  const char *eos,int eoslen,const char *drvInfo);
   asynStatus (*getInputEosOnce)(const char *port, int addr,
                  char *eos, int eossize, int *eoslen,const char *drvInfo);
   asynStatus (*setOutputEosOnce)(const char *port, int addr,
                  const char *eos,int eoslen,const char *drvInfo);
   asynStatus (*getOutputEosOnce)(const char *port, int addr,
                  char *eos, int eossize, int *eoslen,const char *drvInfo);
} asynOctetSyncIO;
epicsShareExtern asynOctetSyncIO *pasynOctetSyncIO;

End of String Support

asynOctet provides methods for handling end of string (message) processing. It does not specify policy. Device support code, interpose layers, or low level drivers can all handle EOS processing. An application developer must decide what policy will be followed for individual devices. The policy will be determined by the device, the device support, and the driver.

Introduction

This section descibes interfaces for register based devices. Support is provided for:

• Int32 - registers appear as 32 integers
• UInt32Digital - registers appear a 32 bit unsigned integers and masks can be used to address specific bits.
• Float64 - registers appear as double precision floats.
• Int32Array - Arrays of 32 bit integers.
• Float64Array - Arrays of double precision floats.

Note that hardware may have registers with smaller sizes, e.g. 16 bit registers. The standard interfaces can still be used by setting the unused bits to 0.

For Int32, UInt32Digital, and Float64 three interfaces are provided. In addition a default implementation and a synchronous inplementation are provided. Lets use Int32 as an example.

• asynInt32 - An interface with methods: read, write, getBounds, registerInterruptUser, and cancelInterruptUser.
• asynInt32Base - An interface used by drivers that implement asynInt32. It also has an implementation that:
  • registers the asynInt32 interface
  • has default methods for read, write, and getBounds. A null method in the interface passed to initialize is replaced by a method implemented by asynInt32Base.
  • implements registerInterruptUser and cancelInterruptUser. The caller should leave these methods null because asynInt32Base always replaces them by it's implementation.
  Drivers that implement asynInt32 normally call asynInt32Base:initialize. It implements registerInterruptUser and cancelInterruptUser. If the driver provides interrupt support it must:
  • Call pasynInt32Base->initialize
  • Call pasynManager->registerInterruptSource
  • Interact with asynManager to call the users that have registered with asynInt32Base:registerInterruptUser
  asyn/testEpicsApp/src/int32Driver.c provides an example of how to provide support for interrupts.
• asynInt32SyncIO - A synchronous interface to asynInt32

addr - What does it mean for register based interfaces?

Low level register based drivers are normally 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 - The driver supports an array of UInt32 values. addr selects an array element. For example a 128 bit digital I/O module appears as an array of four UInt32 registers.

Example Drivers

Two examples of drivers that might implement and use the interfaces are:

• Analog to Digital Convertor.

  An example is a 16 channel ADC. The driver implements interfaces asynCommon and asynInt32. It uses interface asynInt32Base. It can call asynManager:interruptStart and asynManager:interruptEnd to support interrupts. It can use pasynUser->reason and addr to decide which callbacks to call. asyn/testEpicsApp/int32Driver.c is a soft example of how to implement a driver that implements asynInt32 and also asynFloat64.

• Digital I/O module

  An example is a 64 bit combination digital input and digital output module. The driver implements interfaces asynCommon and asynUInt32Digital. It uses interface asynUInt32DigitalBase. It can call asynManager:interruptStart and asynManager:interruptEnd to support interrupts. It can use reason, mask, and addr to decide which callbacks to call. asyn/testEpicsApp/uint32DigitalDriver.c is a soft example of a driver that implements asynUInt32Digital.

asynInt32

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

typedef void (*interruptCallbackInt32)(void *userPvt, asynUser *pasynUser,
                                       epicsInt32 data);
typedef struct asynInt32Interrupt {
    int addr;
    asynUser *pasynUser;
    interruptCallbackInt32 callback;
    void *userPvt;
} asynInt32Interrupt;
#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);
    asynStatus (*registerInterruptUser)(void *drvPvt,asynUser *pasynUser,
                           interruptCallbackInt32 callback, void *userPvt,
                           void **registrarPvt);
    asynStatus (*cancelInterruptUser)(void *drvPvt, asynUser *pasynUser,
                    void *registrarPvt);
} asynInt32;

/* asynInt32Base does the following:
   calls  registerInterface for asynInt32.
   Implements registerInterruptUser and cancelInterruptUser
   Provides default implementations of all methods.
   registerInterruptUser and cancelInterruptUser can be called
   directly rather than via queueRequest.
*/

#define asynInt32BaseType "asynInt32Base"
typedef struct asynInt32Base {
    asynStatus (*initialize)(const char *portName,
                            asynInterface *pint32Interface);
} asynInt32Base;
epicsShareExtern asynInt32Base *pasynInt32Base;

asynInt32Base is an interface and associated code that is used by drivers that implement interface asynInt32. asynInt32Base provides code to handle registerInterruptUser/cancelInterruptUser. The driver must itself call the callbacks via calls to asynManager:interruptStart and asynManager:interruptEnd.

pasynInt32Base->initialize(...

The default implementation of each method does the following:

asynInt32SyncIO

asynInt32SyncIO describes a synchronous interface to asynInt32. The code that calls it must be willing to block.

#define asynInt32SyncIOType "asynInt32SyncIO"
typedef struct asynInt32SyncIO {
    asynStatus (*connect)(const char *port, int addr,
                          asynUser **ppasynUser, const char *drvInfo);
    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, const char *drvInfo);
    asynStatus (*readOnce)(const char *port, int addr,
                    epicsInt32 *pvalue,double timeout, const char *drvInfo);
    asynStatus (*getBoundsOnce)(const char *port, int addr,
                    epicsInt32 *plow, epicsInt32 *phigh,const char *drvInfo);
} asynInt32SyncIO;
epicsShareExtern asynInt32SyncIO *pasynInt32SyncIO;

asynInt32Array

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

typedef void (*interruptCallbackInt32Array)(
              void *userPvt, asynUser *pasynUser,
              epicsInt32 *value, size_t nelements);
typedef struct asynInt32ArrayInterrupt {
    asynUser *pasynUser;
    int addr;
    interruptCallbackInt32Array callback;
    void *userPvt;
} asynInt32ArrayInterrupt;
#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);
    asynStatus (*registerInterruptUser)(void *drvPvt, asynUser *pasynUser,
             interruptCallbackInt32Array callback, void *userPvt,
             void **registrarPvt);
    asynStatus (*cancelInterruptUser)(void *drvPvt, asynUser *pasynUser,
                    void *registrarPvt);
} asynInt32Array;

#define asynInt32ArrayBaseType "asynInt32ArrayBase"
typedef struct asynInt32ArrayBase {
    asynStatus (*initialize)(const char *portName,
                            asynInterface *pint32ArrayInterface);
} asynInt32ArrayBase;
epicsShareExtern asynInt32ArrayBase *pasynInt32ArrayBase;

pasynInt32ArrayBase->initialize(...

asynUInt32Digital

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

typedef enum {
    interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
} interruptReason;

typedef void (*interruptCallbackUInt32Digital)(void *userPvt,
                 asynUser *pasynUser, epicsUInt32 data);
typedef struct asynUInt32DigitalInterrupt {
    epicsUInt32 mask;
    int addr;
    asynUser *pasynUser;
    interruptCallbackUInt32Digital callback;
    void *userPvt;
} asynUInt32DigitalInterrupt;
#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);
    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);
    asynStatus (*registerInterruptUser)(void *drvPvt, asynUser *pasynUser,
        interruptCallbackUInt32Digital callback,void *userPvt,epicsUInt32 mask,
        void **registrarPvt);
    asynStatus (*cancelInterruptUser)(void *drvPvt, asynUser *pasynUser,
                    void *registrarPvt);
} asynUInt32Digital;

/* asynUInt32DigitalBase does the following:
   calls  registerInterface for asynUInt32Digital.
   Implements registerInterruptUser and cancelInterruptUser
   Provides default implementations of all methods.
   registerInterruptUser and cancelInterruptUser can be called
   directly rather than via queueRequest.
*/

#define asynUInt32DigitalBaseType "asynUInt32DigitalBase"
typedef struct asynUInt32DigitalBase {
    asynStatus (*initialize)(const char *portName,
                            asynInterface *pasynUInt32DigitalInterface);
} asynUInt32DigitalBase;
epicsShareExtern asynUInt32DigitalBase *pasynUInt32DigitalBase;

asynUInt32DigitalBase is an interface and associated code that is used by drivers that implement interface asynUInt32Digital. asynUInt32DigitalBase provides code to implement registerInterruptUser and cancelInterruptUser.

pasynUInt32DigitalBase->initialize(...

The default implementation of each method does the following:

asynUInt32DigitalSyncIO

asynUInt32DigitalSyncIO describes a synchronous interrace to asynUInt32Digital. The code that calls it must be willing to block.

#define asynUInt32DigitalSyncIOType "asynUInt32DigitalSyncIO"
typedef struct asynUInt32DigitalSyncIO {
    asynStatus (*connect)(const char *port, int addr,
                       asynUser **ppasynUser, const char *drvInfo);
    asynStatus (*disconnect)(asynUser *pasynUser);
    asynStatus (*write)(asynUser *pasynUser,
                       epicsUInt32 value,epicsUInt32 mask,double timeout);
    asynStatus (*read)(asynUser *pasynUser,
                       epicsUInt32 *pvalue,epicsUInt32 mask,double timeout);
    asynStatus (*setInterrupt)(asynUser *pasynUser,
                       epicsUInt32 mask, interruptReason reason,double timeout);
    asynStatus (*clearInterrupt)(asynUser *pasynUser,
                       epicsUInt32 mask,double timeout);
    asynStatus (*getInterrupt)(asynUser *pasynUser,
                       epicsUInt32 *mask, interruptReason reason,double timeout);
    asynStatus (*writeOnce)(const char *port, int addr,
                       epicsUInt32 value,epicsUInt32 mask,double timeout,
                       const char *drvInfo);
    asynStatus (*readOnce)(const char *port, int addr,
                       epicsUInt32 *pvalue,epicsUInt32 mask,double timeout,
                       const char *drvInfo);
    asynStatus (*setInterruptOnce)(const char *port, int addr,
                       epicsUInt32 mask, interruptReason reason,double timeout,
                       const char *drvInfo);
    asynStatus (*clearInterruptOnce)(const char *port, int addr,
                       epicsUInt32 mask,double timeout,const char *drvInfo);
    asynStatus (*getInterruptOnce)(const char *port, int addr,
                       epicsUInt32 *mask, interruptReason reason,double timeout,
                       const char *drvInfo);
} asynUInt32DigitalSyncIO;
epicsShareExtern asynUInt32DigitalSyncIO *pasynUInt32DigitalSyncIO;

asynFloat64

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

typedef void (*interruptCallbackFloat64)(void *userPvt, asynUser *pasynUser,
            epicsFloat64 data);
typedef struct asynFloat64Interrupt {
    asynUser *pasynUser;
    int addr;
    interruptCallbackFloat64 callback;
    void *userPvt;
} asynFloat64Interrupt;
#define asynFloat64Type "asynFloat64"
typedef struct asynFloat64 {
    asynStatus (*write)(void *drvPvt, asynUser *pasynUser, epicsFloat64 value);
    asynStatus (*read)(void *drvPvt, asynUser *pasynUser, epicsFloat64 *value);
    asynStatus (*registerInterruptUser)(void *drvPvt, asynUser *pasynUser,
        interruptCallbackFloat64 callback, void *userPvt,void **registrarPvt);
    asynStatus (*cancelInterruptUser)(void *drvPvt, asynUser *pasynUser,
                    void *registrarPvt);
} asynFloat64;

/* asynFloat64Base does the following:
   calls  registerInterface for asynFloat64.
   Implements registerInterruptUser and cancelInterruptUser
   Provides default implementations of all methods.
   registerInterruptUser and cancelInterruptUser can be called
   directly rather than via queueRequest.
*/

#define asynFloat64BaseType "asynFloat64Base"
typedef struct asynFloat64Base {
    asynStatus (*initialize)(const char *portName,
                            asynInterface *pasynFloat64Interface);
} asynFloat64Base;
epicsShareExtern asynFloat64Base *pasynFloat64Base;

pasynFloat64Base->initialize(...

The default implementation of each method does the following:

asynFloat64SyncIO

asynFloat64SyncIO describes a synchronous interrace to asynFloat64. The code that calls it must be willing to block.

#define asynFloat64SyncIOType "asynFloat64SyncIO"
typedef struct asynFloat64SyncIO {
    asynStatus (*connect)(const char *port, int addr,
                       asynUser **ppasynUser, const char *drvInfo);
    asynStatus (*disconnect)(asynUser *pasynUser);
    asynStatus (*write)(asynUser *pasynUser,epicsFloat64 value,double timeout);
    asynStatus (*read)(asynUser *pasynUser,epicsFloat64 *pvalue,double timeout);
    asynStatus (*writeOnce)(const char *port, int addr,
                       epicsFloat64 value,double timeout,const char *drvInfo);
    asynStatus (*readOnce)(const char *port, int addr,
                       epicsFloat64 *pvalue,double timeout,const char *drvInfo);
} asynFloat64SyncIO;
epicsShareExtern asynFloat64SyncIO *pasynFloat64SyncIO;

asynFloat64Array

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

typedef void (*interruptCallbackFloat64Array)(
              void *userPvt, asynUser *pasynUser, epicsFloat64 *data,
              size_t nelements);
typedef struct asynFloat64ArrayInterrupt {
    asynUser *pasynUser;
    int addr;
    interruptCallbackFloat64Array callback;
    void *userPvt;
} asynFloat64ArrayInterrupt;
#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);
    asynStatus (*registerInterruptUser)(void *drvPvt, asynUser *pasynUser,
         interruptCallbackFloat64Array callback,
         void *userPvt,void **registrarPvt);
    asynStatus (*cancelInterruptUser)(void *drvPvt, asynUser *pasynUser,
                    void *registrarPvt);
} asynFloat64Array;

/* asynFloat64ArrayBase does the following:
   calls  registerInterface for asynFloat64Array.
   Implements registerInterruptUser and cancelInterruptUser
   Provides default implementations of all methods.
   registerInterruptUser and cancelInterruptUser can be called
   directly rather than via queueRequest.
*/

#define asynFloat64ArrayBaseType "asynFloat64ArrayBase"
typedef struct asynFloat64ArrayBase {
    asynStatus (*initialize)(const char *portName,
                            asynInterface *pfloat64ArrayInterface);
} asynFloat64ArrayBase;
epicsShareExtern asynFloat64ArrayBase *pasynFloat64ArrayBase;

pasynFloat64ArrayBase->initialize(...

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 processEosIn processEosOut

where

• port is the name of the port.
• addr is the address
• processEosIn (0,1) means (do not, do) implement eosIn commands.
• processEosOut (0,1) means (do not, do) implement eosOut commands.

This command should appear immediately after the command that initializes a port Some drivers provide configuration options to call this automatically.

asynInterposeFlush

This can be used to simulate flush processing for asynOctet if the port driver doesn't 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

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 complicated devices other support is required. This release provides the following:

• devAsynInt32 - support for drivers that implement interface asynInt32
• devAsynInt32Array - support for drivers that implement interface asynInt32Array
• devAsynUInt32Digital - support for drivers that implement interface asynUInt32Digital
• devAsynFloat64 - support for drivers that implement interface asynFloat64
• devAsynFloat64Array - support for drivers that implement interface asynFloat64Array
• devAsynOctet - support for drivers that implement interface asynOctet
• devEpics - This is just a single file devEpics.dbd that includes the dbd files for the above support.

The support uses the following conventions for DTYP and INP. OUT fields are the same as INP.

    field(DTYP,"asynXXX")
    field(INP,"@asyn(portName,addr,timeout) drvParams")
     or
    field(INP,"@asynMask(portName,addr,mask,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.
• mask - This is for devAsynUInt32Digital.
• 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.

For example:

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

asynManager interrupts and EPICS device support

devAsynInt32, devAsynFloat64, devAsynUInt32Digital, and devAsynPctet call registerInterruptUser for input record. The callback is used in one of two ways:

• Input Records except Average

  It is used to support SCAN = "I/O Intr".

• Input records that are averaged, i.e. asynInt32Average or asynFloat64Average.

  These records are normally scanned periodically. The registerInterruptUser callback is used to calculate an average value between record processes.

asynInt32 device support

The following support is available:

device(ai,INST_IO,asynAiInt32,"asynInt32")
device(ai,INST_IO,asynAiInt32Average,"asynInt32Average")
device(ao,INST_IO,asynAoInt32,"asynInt32")
device(mbbi,INST_IO,asynMbbiInt32,"asynInt32")
device(mbbo,INST_IO,asynMbboInt32,"asynInt32")
device(longin,INST_IO,asynLiInt32,"asynInt32")
device(longout,INST_IO,asynLoInt32,"asynInt32")

devAsynInt32.c provides EPICS device support for drivers that implement interface asynInt32.

• aiRecord

  A value is given to rval. Linear conversions are supported if the driver implements getBounds.

  • asynInt32 - SCAN "I/O Intr" is supported. If the record is "I/O Intr" scanned then when the registerInterruptUser callback is called, it saves the value and calls scanIoRequest. When the record is processed the saved value is put into rval. If the record is not "I/O Intr" scanned then each time the record is processed, a new value is read via a call to pasynInt32->read.
  • asynInt32Average - The registerInterruptUser callback adds the new value to a sum and also increments the number of samples. When the record is processed the average is computed and the sum and number of set to zero.
• aoRecord

  rval is written. Linear conversions are supported if the driver properly implements getBounds.

• longinRecord

  A value is given to val. Each time the record is processed a new value is read. SCAN "I/O Intr" is supported similar to aiRecord.

• longoutRecord

  val is written.

• mbbiRecord

  A value is given to rval. mask is computed from nobt and shft. Each time the record is processed a new value is read. SCAN "I/O Intr" is supported similar to aiRecord.

• mbboRecord

  rval is written. mask is computed from nobt and shft.

Analog Input Example Records

   record(ai,"aiInt32") {
        field(SCAN,"I/O Intr")
        field(DTYP,"asynInt32")
        field(INP,"@asyn($(port),$(addr))")
        field(EGUF,"10.0")
        field(EGUL,"-10.0")
        field(PREC,"3")
   }
   record(ai,"aiInt32Average") {
        field(SCAN,"10 second")
        field(DTYP,"asynInt32Average")
        field(INP,"@asyn($(port),$(addr))")
        field(EGUF,"10.0")
        field(EGUL,"-10.0")
        field(PREC,"3")
   }

Analog Output Example Record

    record(ao,"aoInt32") {
        field(DTYP,"asynInt32")
        field(OUT,"@asyn($(port),$(addr))")
        field(EGUF,"10.0")
        field(EGUL,"-10.0")
        field(PREC,"3")
   }

Long Input Example Records

   record(longin,"liInt32") {
        field(SCAN,"I/O Intr")
        field(DTYP,"asynInt32")
        field(INP,"@asyn($(port),$(addr))")
   }

Long Output Example Record

    record(longout,"loInt32") {
        field(DTYP,"asynInt32")
        field(OUT,"@asyn($(port),$(addr))")
   }

Multibit Binary Input Example Records

   record(mbbi,"mbbiInt32") {
        field(SCAN,"I/O Intr")
        field(DTYP,"asynInt32")
        field(INP,"@asyn($(port),$(addr))")
        field(NOBT,"2")
        field(SHFT,"2")
        field(ZRST,"zeroVal")
        field(ONST,"oneVal")
        field(TWST,"twoVal")
        field(THST,"threeVal")
   }

Multibit Binary Output Example Record

    record(mbbo,"mbboInt32") {
        field(DTYP,"asynInt32")
        field(OUT,"@asyn($(port),$(addr))")
        field(NOBT,"2")
        field(SHFT,"16")
        field(ZRST,"zeroVal")
        field(ONST,"oneVal")
        field(TWST,"twoVal")
        field(THST,"threeVal")
   }

asynInt32Array device support

The following support is available:

device(waveform,INST_IO,asynInt32ArrayWfIn,"asynInt32ArrayIn")
device(waveform,INST_IO,asynInt32ArrayWfOut,"asynInt32ArrayOut")

devAsynInt32Array.c provides EPICS device support for drivers that implement interface asynInt32Array. It has support for both reading and writing a waveform. It does not support interrupt processing.

devAsynUInt32Digital

The following support is available:

device(bi,INST_IO,asynBiUInt32Digital,"asynUInt32Digital")
device(bo,INST_IO,asynBoUInt32Digital,"asynUInt32Digital")
device(longin,INST_IO,asynLiUInt32Digital,"asynUInt32Digital")
device(longout,INST_IO,asynLoUInt32Digital,"asynUInt32Digital")
device(mbbi,INST_IO,asynMbbiUInt32Digital,"asynUInt32Digital")
device(mbbo,INST_IO,asynMbboUInt32Digital,"asynUInt32Digital")
device(mbbiDirect,INST_IO,asynMbbiDirectUInt32Digital,"asynUInt32Digital")
device(mbboDirect,INST_IO,asynMbboDirectUInt32Digital,"asynUInt32Digital")

devAsynUInt32Digital.c provides EPICS device support for drivers that implement interface asynUInt32Digital. The INP or OUT field must define asynMask. The mask specified in the argument to asynMask is used in the calls to asymUInt32Digital methods. In addition it is used to set the mask fields in bi and bo records and the mask and shft fields in mbbi, mbbo, mbbiDirect, and mbboDirect records.

• biRecord

  A value is given to rval. asynInt32 - SCAN "I/O Intr" is supported. If the record is "I/O Intr" scanned then when the registerInterruptUser callback is called, it saves the value and calls scanIoRequest. When the record is processed the saved value is put into rval. If the record is not "I/O Intr" scanned then each time the record is processed, a new value is read via a call to pasynUInt32Digital->read.

• boRecord

  rval is written.

• longinRecord

  A value is given to val. Each time the record is processed a new value is read. SCAN "I/O Intr" is supported similar to aiRecord.

• longoutRecord

  val is written.

• mbbiRecord

  A value is given to rval. Each time the record is processed a new value is read. SCAN "I/O Intr" is supported similar to aiRecord.

• mbboRecord

  rval is written.

• mbbiDirectRecord

  A value is given to rval. Each time the record is processed a new value is read. SCAN "I/O Intr" is supported similar to aiRecord.

• mbboDirectRecord

  rval is written.

Binary Input Example Record

record(bi,"biUInt32Bit0") {
    field(SCAN,"I/O Intr")
    field(DTYP,"asynUInt32Digital")
    field(INP,"@asynMask( $(port) , 0, 0x1 , 1.0) ")
    field(ZNAM,"zero")
    field(ONAM,"one")
}

Binary Output Example Record

record(bi,"boUInt32Bit2") {
    field(DTYP,"asynUInt32Digital")
    field(INP,"@asynMask( $(port) , 0, 0x4 , 1.0) ")
    field(ZNAM,"zero")
    field(ONAM,"one")
}

Long Input Example Record

record(longin,"liUInt32") {
    field(SCAN,"I/O Intr")
    field(DTYP,"asynUInt32Digital")
    field(INP,"@asynMask( $(port) , 0, 0xffffffff , 1.0) ")
}

Long Output Example Record

record(longout,"loUInt32") {
    field(DTYP,"asynUInt32Digital")
    field(INP,"@asynMask( $(port) , 0, 0xffffffff , 1.0) ")
}

Multibit Input Example Record

record(mbbi,"mbbiUInt32") {
    field(SCAN,"I/O Intr")
    field(DTYP,"asynUInt32Digital")
    field(INP,"@asynMask( digital , 0, 0x3 , 1.0) ")
    field(ZRST,"zero")
    field(ONST,"one")
    field(TWST,"two")
    field(THST,"three")
    field(ZRVL,"0x0")
    field(ONVL,"0x1")
    field(TWVL,"0x2")
    field(THVL,"0x3")
}

Multibit Output Example Record

record(mbbo,"mbboUInt32") {
    field(DTYP,"asynUInt32Digital")
    field(OUT,"@asynMask( digital , 0, 0x7 , 1.0) ")
    field(ZRST,"zero")
    field(ONST,"one")
    field(TWST,"two")
    field(THST,"three")
    field(FRST,"four")
    field(FVST,"five")
    field(SXST,"six")
    field(SVST,"seven")
    field(ZRVL,"0x0")
    field(ONVL,"0x1")
    field(TWVL,"0x2")
    field(THVL,"0x3")
    field(FRVL,"0x4")
    field(FVVL,"0x5")
    field(SXVL,"0x6")
    field(SVVL,"0x7")
}

devAsynFloat64 device support

The following support is available:

device(ai,INST_IO,asynAiFloat64,"asynFloat64")
device(ai,INST_IO,asynAiFloat64Average,"asynFloat64Average")
device(ao,INST_IO,asynAoFloat64,"asynFloat64")

devAsynFloat64.c provides EPICS device support for drivers that implement interface asynFloat64.

• aiRecord

  A value is given to val.

  • asynFloat64 - SCAN "I/O Intr" is supported. If the record is "I/O Intr" scanned then when the registerInterruptUser callback is called, it saves the value and calls scanIoRequest. When the record is processed the saved value is put into val. If the record is not "I/O Intr" scanned then each time the record is processed, a new value is read via a call to pasynFloat64->read.
  • asynFloat64Average - The registerInterruptUser callback adds the new value to a sum and also increments the number of samples. When the record is processed the average is computed and the sum and number of set to zero.
• aoRecord

  val is written.

asynFloat64Array device support

The following support is available:

device(waveform,INST_IO,asynFloat64ArrayWfIn,"asynFloat64ArrayIn")
device(waveform,INST_IO,asynFloat64ArrayWfOut,"asynFloat64ArrayOut")

devAsynFloat64Array.c provides EPICS device support for drivers that implement interface asynFloat64Array. It has support for both reading and writing a waveform. It does not support interrupt processing.

octet device support

The following support is available:

device(stringin,INST_IO,asynSiOctetCmdResponse,"asynOctetCmdResponse")
device(stringin,INST_IO,asynSiOctetWriteRead,"asynOctetWriteRead")
device(stringin,INST_IO,asynSiOctetRead,"asynOctetRead")
device(stringout,INST_IO,asynSoOctetWrite,"asynOctetWrite")
device(waveform,INST_IO,asynWfOctetCmdResponse,"asynOctetCmdResponse")
device(waveform,INST_IO,asynWfOctetWriteRead,"asynOctetWriteRead")
device(waveform,INST_IO,asynWfOctetRead,"asynOctetRead")
device(waveform,INST_IO,asynWfOctetWrite,"asynOctetWrite")

Support for drivers that implement interface asynOctet. The support is for stringin/stringout and waveform records. The waveform support is similar to the string support. The waveform records must define FTVL to be CHAR or UCHAR, i.e. it must be an array of octets. The waveform provides the following features not provided by the string support:

• unlimited size - string records hold a maximum of 40 characters.
• non ascii - Thus arbitrary octet arrays are supported.

Four types of support are provided:

• CmdResponse The INP field is of the form:

      field(INP,"@asyn(portName,addr,timeout) cmd")

  During record initialization, cmd is converted by dbTranslateEscape. The resultant string is the command to send to the device. When the record is processed the command is sent to the device and the response read into the record.
• WriteRead The INP field is of the form:

      field(INP,"@asyn(portName,addr,timeout) pvname")

  pvname must refer to a field in a record in the same IOC. During record initialization the pvname is locatedd. When the record is processed dbGet is called to read the current value of pvname. This value is sent to the device. A read is then issued and the result stored in the record. For asynSiOctetWriteRead, the value obtained from pvname is passed through dbTranslateEscape before sending it. For asynWfOctetWriteRead it is not passed through dbTranslateEscape.
• Write The INP(OUT) field is of the form:

      field(INP,"@asyn(portName,addr,timeout) drvUser")

  drvUser is information that is passed to the portDriver if it implements interface asynDrvUser. When the record is processed the value stored in the record is sent to the device.
• Read The INP field is of the form:

      field(INP,"@asyn(portName,addr,timeout) drvUser")

  drvUser is information that is passed to the portDriver if it implements interface asynDrvUser. When the record is processed a read request is made. The result is read into the record.

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);
    }
    epicsEventSignal(pmydata->done);
}

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

    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;
    pmyData->done = epicsEventCreate(epicsEventEmpty);
    status = pasynManager->queueRequest(pasynUser,asynQueuePriorityLow, 0.0);
    if(status) {
        asynPrint(pasynUser,ASYN_TRACE_ERROR,
            "queueRequest failed %s\n",pasynUser->errorMessage);
    }
    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
   testBlock.db
adl/
   test.adl
src/
   devTestBlock.dbd
   echoDriver.c
   addrChangeDriver.c
   devTestBlock.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 iocsh 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.

addrChangeDriver is a multidevice driver that is an asynUser of another port driver. In the example application it connects to echoDriver. An example where this technique might be used is a port driver for mult-drop serial that connects to a standard serial port.

An instance of addrChangeDriver is started via the iocsh commandL:

addrChangeDriverInit(portName,lowerPort,addr)

where

• portName - the port name for this instance.
• lowerPort - the port to which addrChangeDriver connects
• addr - The address to which addrChangeDriver connects

devTestBlock is device support that tests blockProcessCallback. It has device support for stringin records. The INP field has the syntax:

    field(INP,"@asyn(port,addr,timeout) pvname)

• asyn(port,addr,timeout) is same as for devEpics support.
• pvname - The name of a record in the same ioc.

When the stringin record is processed the following occurs.

• When process is called and PACT is :
  • TRUE - then it just returns to record support.
  • FALSE - It does what follows.
• When processing starts the state is stateIdle.
• blockProcessCallback is called.
• callbackRequestDelayed is called (.1 second delay). The callback calls queueRequest.
• When processCallback is called it does the following:
  • calls unblockProcessCallback
  • If state is stateIdle
    • Calls dbGet to get a string value from pvname
    • calls pasynOctet->write to send the string
    • sets state to stateWrite
    • Calls blockProcessCallback
    • callbackRequestDelayed is called The callback calls queueRequest.
    • completes. processCallback will be called again
  • If state is stateWrite
    • calls pasynOctet->read and puts the value in VAL.
    • Sets state = stateIdle
    • requests the the record be processed. This time PACT will be TRUE

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 stringOut record attaches to the device support supplied by asynOctetWriteRead.c. When the calcRecord is processed the following happens:

• The calcRecord acts as a counter that overflows when the count reaches 10. After counting to forward links ti the stringIn record.
• The string in record gets the current value of the counter converted to s character string and forward links to the stringOut record.
• The stringOut record gets the value from the stringIn record an calls queueRequest. The record is left with PACT true.
• The processCallback calls pasynOctet->write passing the value obtained from the stringIn record. The then does does a pasynOctet->read. When this completes it asks for the record to complete processing.
• The stringOut record completes processing.

testBlock.db is a template similar to test.db except that it attached to device support testBlock instead of asynOctetWriteRead.

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 asynRecord.db. It starts one version of addrChangeDriver which connects to port A.

It loads six versions of test.db and four versions of testBlock.db The test.adl file attaches to these database records.

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:

/* GPIB Addressed Commands*/
#define IBGTL "\x01"    /* Go to local */
#define IBSDC "\x04"    /* Selective Device Clear */
#define IBGET "\x08"    /* Group Execute Trigger */
#define IBTCT "\x09"    /* Take Control */

/* GPIB Universal Commands*/
#define IBDCL 0x14      /* Device Clear */
#define IBLLO 0x11      /* Local Lockout */
#define IBSPE 0x18      /* Serial Poll Enable */
#define IBSPD 0x19      /* Serial Poll Disable */
#define IBUNT 0x5f      /* Untalk */
#define IBUNL 0x3f      /* Unlisten */

/* Talk, Listen, Secondary base addresses */
#define TADBASE    0x40   /* offset to GPIB listen address 0 */
#define LADBASE    0x20   /* offset to GPIB talk address 0 */
#define SADBASE    0x60   /* offset to GPIB secondary address 0 */

#define NUM_GPIB_ADDRESSES    32
#include "asynDriver.h"
#include "asynInt32.h"
#define asynGpibType "asynGpib"
/* GPIB drivers */
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 (*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. asynGpib.c implements asynCommon and asynOctet. It supports asynInt32 by using the methods from asynInt32Base. asynInt32 is the way asynGpib reports SRQs to asynUsers. An asynUser that wishes to receive SRQs calls pasynInt32->registerInterruptUser and must set asynUser.reason = ASYN_REASON_SIGNAL.

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,
        noProcessEosIn)
   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.
• addr - This argument is ignored since serial devices are configured with multiDevice=0.
• noAutoConnect - Zero or missing indicates that portThread should automatically connect. Non-zero if explicit connect command must be issued.
• noProcessEos If 0 then asynInterposeEosConfig is called specifying both processEosIn and processEosOut.

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. When a serial port connects the current values are fetched.

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 vxWorks sioLib serial support does not provide support for modem control lines. It also uses clocal for what is actually crtscts. For vxWorks the standard serial support accepts both clocal and crtscts for getOption and setOption. 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,
        noProcessEos)

• 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.
• noProcessEos If 0 then asynInterposeEosConfig is called specifying both processEosIn and processEosOut.

Only asynOctet methods writeRaw, readRaw, and flush are implemented. Calling the other methods will result in an error unless asynInterposeEos is used for the other asunOctet methods. readRaw blocks until at least one character has been received or until a timeout occurs. readRaw 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". Note that the Agilent E2050A does not follow the standard. For it the vxiName must be "hpib"
• 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. NOTE: For the Agilent E2050 vxiName must be "hpib". For the Agilent E5810 use the name "gpib0". For an instrument that supports VXI11 try "inst0".
• 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

Linux-Gpib

The linux-gpib port driver was written to support The Linux GPIB Package library.

In order to build this support the Linux GPIB Package must be installed. Also in configure/RELEASE the statement:

    LINUX_GPIB=NO

    LINUX_GPIB=YES

Configuration command is:

    GpibBoardDriverConfig(portName,autoConnect,BoardIndex,timeout,priority)

• portName - An ascii string specifying the port name that will be registered with asynDriver.
• noAutoConnect - Non-zero indicates that portThread should automatically connect. Zero means explicit connect command must be issued.
• boardIndex -Integer containing index of board (0 means /dev/gpib0). Normally it is 0. This must be the same as in gpib.conf file (minor number - board index) of driver configuration.
• timeout - Time in seconds in which an i/o operation must complete. Zero means disabled. This is "general" timeout for every call to low level drivers. For actual read/write operations timeout must be defined in device support. Both timeouts are converted into integers 0-17 which represents disabled to 1000 seconds.
• priority - An integer specifying the priority of the port thread. A value of 0 will result in a default value being assigned.

An example is:

GpibBoardDriverConfig("L0",1,0,3,0)

NOTES:

• AsynOption Interface is supported. Key (hexadecimal) and val (integer) arguments to setPortOptions function must be appropriate values represented as character arrays. See GPIB library documentation for details.
• pgpibCmd type GPIBREADW and GPIBEFASTIW were not tested.
• The linux-port driver was tested with PC104-GPIB board from Measurement Computing.

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 portThread. 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 portThread. 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(level,portName)
    asynInterposeFlushConfig(portName,addr,timeout)
    asynInterposeEosConfig(portName,addr,processIn,processOut)
    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,timeout,buffer_len,drvInfo)
    asynOctetRead(entry,nread)
    asynOctetWrite(entry,output)
    asynOctetWriteRead(entry,output,nread)
    asynOctetFlush(entry)
    asynOctetSetInputEos(portName,addr,eos,drvInfo)
    asynOctetGetInputEos(portName,addr,drvInfo)
    asynOctetSetOutputEos(portName,addr,eos,drvInfo)
    asynOctetGetOutputEos(portName,addr,drvInfo)

asynReport calls asynCommon:report for a specific port if portName is specified, or for all registered drivers and interposeInterface if portName is not specified.

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.
• timeout - timeout as an integer in milliseconds. The default is 1.
• buffer_len - length of buffer for I/O. Default=160. NOTE: output strings passed to asynOctetWrite can have escape characters. The buffer_len must be large enough to handle escape characters. For example if \x02 appears in an output string it counts as four characters.
• drvInfo - A string to pass to the driver via interface asynDrvUser.
• 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, asynOctetDisconnect, 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
asynOctetDisconnect("myid")

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.