asynDriver: Asynchronous Driver Support - Release Notes
February 28, 2007
Release 4-7
drvAsynSerialPort
Clean up operation on POSIX/termios systems (everything but vxWorks). The
old mechanism was prone to polling during read operations rather than using
the termios read timeout mechanism.
devGpib
asynRecord sets line-buffering on trace file.
Peter Mueller provided code to remove/restore a device from/to the SRQ
polling list.
drvGsIP488.c
Clean up dangling 'default' statement.
devGpib
Fixed error in GPIBACMD operations.
linuxGpib
Patches from Gasper Jansa to improve option handling.
devEpics
Fixed null pointer dereference for all device support when SCAN=I/O Intr
and asyn port could not be found.
asynRecord
Fixed buffer overflow error when NRRD>40 and IFMT=ASCII.
asynGpib
Read method now sets return status and *eomReason properly.
drvAsynIPPort/drvAsynSerialPort
*eomReason now set to ASYN_EOM_CNT when read count has been satisfied.
Fix timeout settings on RTEMS.
Add support for UDP broadcasts. Specify "UDP*" and the network broadcast
address in the port configuration command:
drvAsynIPPortConfigure("L0", "192.168.1.255:1234 UDP*", 0, 0,
0)
drvAsynSerialPort
Full support for new timeout semantics (timeout<0 means "wait forever
for characters to arrive", timeout=0 means "return characters immediately
available", timeout>0 means "return a timeout status if no characters are
received within the specified number of seconds").
Release 4-6
drvAsynIPPort/drvAsynSerialPort
Fixed NULL pointer dereference.
drvAsynIPPort
Previous versions of drvAsynIPPort.c (1.29 and earlier, asyn R4-5 and
earlier) attempted to allow 2 things:
- Use an EPICS timer to time-out an I/O operation, such as send(), recv()
and connect().
- Periodically check (every 5 seconds) during a long I/O operation to see
if the operation should be cancelled.
Item 1) above was not really implemented because there is no portable
robust way to abort a pending I/O operation. So the timer set a flag which
was checked after the poll() was complete to see if the timeout had occured.
This was not robust, because there were competing timers (timeout timer and
poll) which could fire in the wrong order.
Item 2) was not implemented, because asyn has no mechanism to issue a
cancel request to a driver which is blocked on an I/O operation.
Since neither of these mechanisms was working as designed, the driver has
been re-written to simplify it. If one or both of these are to be
implemented in the future the code as of version 1.29 should be used as the
starting point.
If pasynUser->timeout < 0 an infinite timeout is now used.
Fixed bug so that ports connected with a file descriptor in
pasynUser->reason execute code to set timeouts.
Fixed bug to return error if pasynCommon->connect is called when port
already connected.
asynTrace
Added two new functions which are related to pasynTrace->print and
pasynTrace->printIO the way vprintf is related to printf.
- pasynTrace->vprint Same as pasynTrace->print except that instead
of a variable of arguments it takes a va_list argument as its last
parameter.
- pasynTrace->vprintIO Same as pasynTrace->printIO except that
instead of a variable of arguments it takes a va_list argument as its
last parameter.
asynManager
Changed pasynManager->connectDevice for ports which have the properties
autoConnect=1 and isConnected=0. In this case a request is queued to call
asynCommon->connect for that port. This ensures that ports that have a
pasynUser connected to them will report being connected even if no I/O has
yet been done. Previously such ports reported a disconnected state until the
first I/O or operation such as setTraceMask. This was confusing.
Clarify documentation on meaning of pasynUser->timeout. Previously
there was no documented method of specifying an "infinite" timeout to a
driver, and the meaning of timeout=0.0 was not defined. The new definitions
are:
> 0.0 Wait for up to timeout seconds for the I/O to complete
= 0.0 Peform any I/O that can be done without blocking. Return timeout
error if no I/O can be done without blocking.
< 0.0 Infinite timeout. Wait forever for I/O to complete.
devEpics
Fixed bugs with asynFloat64Average device support. The wrong interrupt
function was being called, and UDF was not being cleared.
Release 4-5
memMalloc/memFree
memMalloc was allocating the amount of memory the caller requested rather
than the amount required for the freeList. If memFree was called and the
memory reallocated to a user requesting a larger size, memory corruption
occured. This is fixed.
SyncIO routines
If the connect call fails the asynUser is no longer freed. Instead a
message is put into asynUser.errorMessage. The caller must call disconnect in
order to free the storage for the asynUser.
The SyncIO routines no longer call asynPrint if there is an error and
there is a valid asynUser available. Rather they return an error message in
pasynUser->errorMessage. The SyncIO*Once functions still call asynPrint
for errors, because they do not have a way of returning an error message.
Serial, TCP/UDP/IP
Handle 0-length write requests.
TCP/UDP/IP
Added drvAsynIPServerPort to support TCP and UDP socket servers.
Added iocBoot/testIPServer to test TCP server support.
drvAsynIPPort now closes TCP sockets when remote system closes
connection.
drvAsynIPPort connect function now uses pasynUser->reason as a file
descriptor if it is > 0. This allows drvAsynIPServerPort to re-use asyn
ports it creates.
Made drvAsynIPPort add null byte at end of input if there is room.
Made drvAsynIPPort:readRaw set eomReason to 0. It was not setting
eomReason at all previously.
Serial
Made drvAsynSerialPort add null byte at end of input if there is room.
Made drvAsynSerialPort:readRaw set eomReason to 0. It was not setting
eomReason at all previously.
Interfaces
Added asynCommonSyncIO for synchronous support of the asynCommon
interface.
VME GPIB
Add delay loops to get these boards to work with faster VME CPU
modules.
Release 4-4
VXI11
Better support was provided for VXI-11.3 controllers, i.e. talking
directly to an ethernet port on an instrument. In particular a TDS3054B was
tested.
WARNING: The VXI-11.1 ansd VXI-11.3 standards do NOT allow access to GPIB
lines, i.e. conmmands like Untalk/Unlisten are not possible. The previous
support issued these commands after each read or write. Some really old GPIB
devices may fail. If so the device specific code must be modified to sent
these commands separately.
win32
Changes were made to allow asyn to build on native Windows (win32-x86)
architecture.
There are two asyn components that do not yet work on win32-x86.
- Local serial ports. The asyn uses the "termios" API for serial ports,
and termios is not available for native Windows.
- VXI-11. The asyn VXI-11 support uses the Sun XDR API, which is not
available for native Windows.
Users who want to use local serial ports or VXI-11 on Windows can use the
Cygwin EPICS build (cygwin-x86).
devGpib: devGpibConvertExample
An example of how to implement convert routines for devGpib support
modules is available in asyn/devGpib/devGpibConvertExample.c
devAsynOctet.c
The UDF field is now set FALSE when the VAL field is updated.
Release 4-3
asynManager
- lock/unlock renamed to blockProcessCallback/unblockProcessCallback
The names have been changed and now these methods only work for
asynchronous ports. An error is returned if blockProcessCallback is
called for a synchronous port.
- lockPort/unlockPort
These are new asynManager methods. They can be used in place of
queueRequest if the caller can block. They have been added to make it
easier to implement a driver with one addressing scheme that is a
asynUser of a driver with a different addressing scheme. For example a
multi-drop serial driver can be implemented that calls a standard serial
driver.
- asynLockPortNotify
This is a new interface for driver's that call other drivers.
cancelInterruptUser
The cancelInterruptUser methods of all interfaces has been changed from
asynStatus (*cancelInterruptUser)(void *registrarPvt, asynUser *pasynUser);
to
asynStatus (*cancelInterruptUser)(void *drvPvt, asynUser *pasynUser,
void *registrarPvt);
asynTrace
The length and size arguments now have type size_t.
devGpib
Several improvements were made to devSupportGpib.c. All changes should be
transparent to code that uses devGpib.
asynOctetBase
The maxchars argument to callInterruptUsers has been removed.
asynReport
The filename argument has been removed.
devAsynFloat64
For asynAoFloat64 it now uses
oval instead of val.
asynFloat64Array, asynInt32Array, asynOctet, asynOctetSyncIO
All length and size arguments now have type size_t.
asynFloat64SyncIO, asynInt32SyncIO, asynOctetSyncIO, and
asynUInt32DigitalSyncIO
These all use lockPort/unlockPort instead of queueRequest.
Release 4-2-1
devAsynFloat64
Device support was not returning 2 (do not convert) for ai records when it
should. This meant that the VAL field was being set back to 0 by the record
after device support wrote to it. This bug is fixed.
asynRecord
The record sometimes did not read the current input and output EOS values
from the driver when it connected. This bug is fixed.
Release 4-2
Acknowledgement
Yevgeny A. Gusev has again reported some hard to recognize bugs. He must
have spent many hours looking at the code. His extra set of very good eyes
are much appreciated!!. He also thought of the way to handle support that
uses one addressing scheme but wants to use support that has a different
addressing scheme. For example support for mult-drop serial that wants to use
the standard serial support
Release 4-2
asynInterposeEos
If read reads maxchars, it forced the last character to be 0 and returned
asynOverflow if it wasn't. This is fixed.
drvAsynSerialPort,drvAsynIPPort - Error reporting
These did not properly set an error message in asynUser.errorMessage when
they returned asynError. This is fixed.
drvAsynSerialPort - serial port options
Changes were made to the way serial port options are handled.
- initial values
Previosly defaults were assigned for all options. Now the initial
values are fetched from either the termios (POSIX) or sioLib
(vxWorks).
- vxWorks clocal and crtscts
The vxWorks sioLib uses clocal for what POSIX calls crtscts. The new
serial support for vxWorks accepts both clocal and crtscts to specify
RTSCTS (Request to send, Clear to send).
asynRecord - Serial Port Options
This has a new option to set Modem Control.
Release 4-1
The only code change was to fix the drvAsynIPPort and drvAsynSerialPort
segmentation faults on cygwin-x86.
Release 4-0
Incompatible Changes.
APOLOGY: Many interfaces have changed since release 3-3. This is the
reason this release is called 4-0.
- asynManager - Only report has changed. Many new methods have been
added. asynManager:report takes an additional parameter, portName.
- asynOctet - The read/write methods are similar to before. The new
version has sepearate end of string methods for input and output.
- register based interfaces - Extensive changes have occured.
- devGpib - Unless special conversion routines call low level drivers,
debGpib support should work without any changes.
- devEpics -
- Extensive changes have occured. The support naming now follows the
names of asyn interfaces. For example devAsynInt32 contains device
support for interface asynInt32.
- device definitions have changed.
Blanks no longer appear in the menu choices. For example.
device(ai,INST_IO,devAiAsynInt32,"asyn Int32")
is now
device(ai,INST_IO,asynAiInt32,"asynInt32")
- asynOctetSyncIO
- All read and write methods now return asynStatus and have
additional args to return the number of bytes sent/received.
- asynRecord
- The IEOS and OEOS fields are set to the current values for the port
when the record connects to the port. If they are modified after the
record connects to the port, then the EOS strings will be changed
using asynOctet->setOutputEos or asynOctet->setIbputEos.
IMPORTANT: The values of IEOS and OEOS in the database file are never
used, because they are modified when the record connects to the
port.
New Features
- interrupt support -A major new feature is support for interrupts. See
asynDriver.html for details.
- linuxGpib - This is support for the linuxGpib open source project. It
contains support for many linux gpib kernel drivers. The asyn support was
provided by Rok Sabjan (cosyLab).
- cancelRequest - If cancelRequest is called while either the process or
timeout callback is active, it now waits until the callback
completes.
- asynRecord
- Added PCNCT field to connect/disconnect from port, and to indicate
if port is currently connected.
- Added DRVINFO and REASON fields to provide control for the drvUser
interface.
- Added support for register interfaces (asynInt32,
asynUInt32Digital, and asynFloat64). New I/O fields for this support
are I32INP, I32OUT, UI32INP, UI32OUT, UI32MASK, F64INP, and F64OUT.
The new IFACE field is used to select the currently active
interface.
- Added new fields to indicate if a particular interface is supported
by the driver. These fields are OCTETIV, I32IV, UI32IV, F64IV,
OPTIONIV, and GPIBIV.
- Added support for I/O Intr scanning for any driver/interface that
supports callbacks. asynOctet does not yet support callbacks.
Release 3-3
Incompatible Changes.
- MAY BE MORE - This release has major new features. Implementing the new
features may have caused some imcompatibilities, This list is likely to
grow as existing users report problems.
- queueRequest - If the portDriver does not block then the queue callback
is called by queueRequest rather than by a separate thread. User code can
call canBlock to find out how the callback is called.
- registerPort - The argument multiDevice has been replaced by
attributes. Attributes currently has two bits ASYN_MULTIDEVICE and
ASYN_CANBLOCK. The port driver is responsible for setting both bits
correctly.
- setOption/getOption have been moved from asynCommon to a new interface
asynOption.
Major New Features
- Support for synchronous drivers.
- Support for register based drivers.
- Generic register based device support for EPICS records.
- Additional fields have been added to asynUser.
- Added pasynManager->memMalloc() and pasynManager->memFree()
for allocating and freeing memory with a freelist. This is primarily
meant to be used with pasynManager->duplicateAsynUser() and the
new pasynUser->userData field.
asynDriver.h
The following changes have been made
- userData - this is a new field in asynUser.
- registerPort - Field multiDevice is replaced by attributes. Currently
two attributes are defined: ASYN_MULTIDEVICE and ASYN_CANBLOCK.
- duplicateAsynUser - This is a new method that creates a new asynUser
and initializes it with values from an existing asynUser. freeAsynUser
now puts the asynUser of a free list rather than calling free.
- memMalloc/memFree - New methods that manage storage. It uses a set of
free lists of different sizes.
- asynCommon no longer has methods setOption/getOption.
- asynOctet is now defined in a separate header file.
asynRecord
Removed the GOPT field. This is no longer necessary because the port
options are automatically read whenever connecting to a port. "special"
requests are now queued without changing the state of the record, using the
new duplicateAsynUser, memMalloc(), and memFree() methods. This means that
there is no longer a possibility of a special request being rejected because
the record is busy. It is no longer possible to cancel a special request.
asynGpib
- asynGpibPort:srqStatus returns asynStatus
- asynGpibPort:serialPoll returns asynStatus. It now only calls a
registered callback only if statusByte&0x40 is non zero.
devSupportGpib
- setEos is now a method.
- completeProcess is a new method. This was added to support synchronous
drivers.
- Failures for GPIBREADW|GPIBEFASTIW were not handled properly. This
could cause and assert failure. This is fixed.
drvAsynSerialPortFlush
Flushes input only.
asynInterposeEOS
The EOS read method now calls the low-level read method only once and
returns as many characters as the low-level method supplies. This makes the
EOS read semantics match those of the low-level serial and IP drivers.
drvVxi11
vxi11SetRpcTimeout - now handles fractions of a second properly
asynRecord
A new field has beem added, AQR (Abort Queue Request)
The semantics have been changed as follows: process is responsible for all
and only for I/O operations. Only I/O operations cause the alarm status and
severity to change. Special is responsible for all other operations performed
by asynRecord.
Release 3-2
Changed and obsolete features
- INCOMPATIBLE CHANGE -- The units of the
respond2Writes
field, if greater than 0, are now seconds
rather than milliseconds. This change was made so that all time values
set in the instrument support initialization routine are specified
uniformly in units of seconds. Very few instrument support files are
likely to be affected by this change
- The contents of asynRecDevDrv.dbd have been placed in asyn.dbd and
asynRecDevDrv.dbd has been removed. This allows applications to get
correct dbior reports and access to asynRecords by including any
low-level driver .dbd file.
- The drvAsynTCPPort driver has been renamed drvAsynIPPort since it now
supports both UDP and TCP protocols. The protocol is selected by adding a
"UDP" or "TCP" after the "hostname:port" in the drvAsynIPPortConfigure
command. A missing protocol is taken to be "TCP".
- Work around 'missing SPD' bug in HP E2050 GPIB/LAN adapter. SRQ
handling is much more robust on all supported hardware.
Major New Features
- National Instruments NI1014 VME GPIB interface is now supported.
- GPIB - All low level GPIB support (vxi11, gsip488, and ni1014) now
fully support the GPIB specific features defined by asynGpibDriver.h
- Implementation of asynTrace is more consistent across the low level
drivers.
- Added makeSupport script and template instrument support. Updated
tutorials to reflect these additions.
Release 3-1
Major New Features
Changed and obsolete features
- The drvGenericSerial driver has been split into drvAsynSerialPort and
drvAsynTCPPort drivers for local and remote serial ports, respectively.
End-of-string processing has been moved to an interposed interface.
- The diagnostic facilities previously provided by asynTrace.db have been
replaced with the much more general asynRecord.db
- All asynManager,asynCommon, and asynOctet methods except report now
return asynStatus. Methods that previously returned a different value now
have an additional argument for this value.
- Low-level driver read and write methods now return asynStatus and are
passed an additional argument through which they store the actual number
of characters read or written.
- The createSocket method in the asynSyncIO interface has been replaced
by openSocket. openSocket does not call asynSyncIO->connect(),
that must now be done by the caller.
- Removed code for "flush" from gpib drivers. The implementation
caused infinite loops on devices that speak when not spoken to.
- asynRecord
- asynOctetRecord has been renamed to asynRecord
- TIOM, TMSK, TSIZ, TFIL, AUCT, ENBL, CNCT, ERRS, TINP, NAWT fields
have been added
- Default values of OMAX and IMAX decreased from 512 to 80
- Options that are unknown for a device (e.g. baud on a Moxa terminal
server) are shown as Unknown.
- Many bug fixes and improvements in logic and functionality
Release 2-1
Major New Features
- Connection Management - A framework for connection management is
provided. It provides the ability to connect/disconnect to/from a port or
port,addr. It also provides enable/disable and autoConnect/noAutoConnect.
See the asynDriver for details.
- devAsyn - Generic device support for connect management for a specific
device.
- devAsynGeneric - Generic support for connection management and
traceing. This support dynamically attaches to a port,addr. Thus one set
of records and one medm display can be used for all devices connected to
an ioc.
- asynOctetRecord - A generic record and medm display that allows
interactive access to many asynDriver features.
- asynSyncIO - A synchronous interface to asynDriver. This can be used by
code, e.g. SNC programs, that are willing to wait instead of following an
asynchronous model.
Changed and obsolete features
- devAsynTrace is replaced by devAsyn and devAsynGeneric.
- asynManager.h
- disconnectDevice has been renamed to disconnect.
- The interface to low level drivers has been drastically modified in
order to support the new connection management features. See the
asynDriver documentation for details.
- asynGpib
- registerPort has additional arguments multiDevice and
autoConnect.
- setPortOption,getPortOption are setOption,getOption
Release 1-2
- Promote VXI-11 RPC definition files to vxi11 directory. Use rpcgen to
build RPC support files for targets for which this is possible.
- Run rpcgen on Solaris with 'multi-thread' flag.
- Use separate GPIB message/response buffer for each port instance.
- Use sscanf to convert GPIB stringin response.
- Fix race condition in GPIB finish routines.
Release 1-1
This release includes support for the following:
- asynTrace - A trace facility is now implemented.
- gsIP488 - The Greensprings Industry Pack IP488 is now supported
Modifications include:
- Added asynSetPortOption and asynGetPortOption to manipulate port
options.
- Changed serial support to use asynSetPortOption/asynGetPortOption.
- Added devGPIB GPIBCVTIO commmand type to allow custom conversion
routine to perform all I/O operations.
- Changed rules for return value from devGPIB custom conversion
routines.
- Added dbior support.
- Changed devGPIB to no longer cache EOS.
Release 1-0alpha2
Support Provided in addition to asynDriver and asynGpib
- devGpib - The Winans/Franksen gpib device support.
- vxi11 - Support for instruments that support the VXI-11 standard.
- drvGenericSerial - Support for devices connected to serial ports or to
Ethernet/Serial converter.
Future Support
- Other device support methods especially streams, devSerial, and
mpfSerial.
- NI1014 VME Gpib driver.
- Industry Pack IP488 Gpib driver.
- Successor to GI (GPIB Interact).
Testing
The vxi11 support has been tested on the following platforms: Solaris,
Linux (redhat 9), Darwin, Windows XP (Cygwin), and vxWorks. It has been
tested with the following vxi11 controllers:
- Agilent E2050A LAN/GPIB Gateway.
It's vxiName must start with "hpib" rather than "gpib".
- Agilent E5810A LAN/GPIB Gateway.
- Tektronix TDS3014B Scope.
When communicating with the Ethernet port it acts like a VXI-11.2
rather than a VXI-11.3 device. It seems to just accept any GPIB address.
SRQs did not work when connecting via the ethernet port but did when
communicating via a LAN/GPIB gateway.
The generic serial support has been tested with the following:
- xvWorks with a GreenSprings Octal UART Industry-Pack module on a VME
carrier.
- Linux and Windows XP (Cygwin) with PC hardware serial port
(/dev/ttyS0).
- Solaris hardware serial port (/dev/cua/a).
- Linux, Solaris, Darwin, vxWorks, and Windows XP (Cygwin) with a Moxa
NPort Ethernet/Serial converter.
Two Device Support modules have been converted from the 3.13 gpib support:
DG535 and TDS3014B Scope.