1. Asyn Device/Driver Support
EPICS Tutorial
Asyn Device/Driver Support
EPICS Seminar/Workshop
Raja Ramanna Centre For Advanced Technology
Indore India
January
Presented by:
Marty Kraimer
Based on Presentations b:
Eric Norum and Dirk Zimoch

2. Acknowledgements and References
This talk is based on the following talks:
Eric Norum - USPAS 2007 EPICS Course
Device Support
ASYN Device Support Framewok
Go to EPICS home page and look for Documents/Training
Dirk Zimoch -
Introduction to asynDriver
EPICS Meeting April 2007 at DESY Hamburg Germany
Go to EPICS home page and look MEETINGS
Marty Kraimer INFN 2008
References
IOC Application Developer's Guide
Describes device and driver support in detail
AsynDriver
See the latest release of base for links to above two documents
STREAMS:
January 2009
EPICS Workshop RRCAT

3. Overview of Tutorial Device Support Driver Support AsynDriver
Message Based Device Support
devGpib – briefly
STREAMS
January 2009
EPICS Workshop RRCAT

4. Overview of Device Support
Attached to INP or OUT field of a recordType. DTYP identifies support
Understands record type. Directly accesses field of a record.
Connects to hardware, other records, etc.
EPICS base provides soft support.
Constant, database, and channel access links.
EPICS base does NOT provide any hardware support
DSET (Device Support Entry Table) is interface
Implemented by device support
Called by record support
January 2009
EPICS Workshop RRCAT

5. Overview of Driver Support
Optional – Device Support can directly talk to hardware
Normally does not know about records
DRVET (Driver Entry Table)‏
Implemented by driver
Called by device support
asynDriver and STREAMS do NOT use DRVET
This talk has no further discussion of Driver Support
New support should not use it.
Do something like asynDriver or STREAMS
January 2009
EPICS Workshop RRCAT

6. DSET (Device Support Entry Table)‏
A C structure containing pointers to functions
Content dependent upon record type
Each device support defines a DSET with pointers to its own functions
A DSET structure declaration looks like:
struct dset {
long number;
long (*report)(int level);
long (*initialize)(int pass);
long (*initRecord)(struct … *precord);
long (*getIoIntInfo)(…);
… read/write and other routines as required };
aidset DSET for aiRecord adds two methods: read and special_linconv
aodset DSET for aoRecord adds methods write_ao and special_linconv
...
number specifies number of pointers (often 5 or 6)‏
A NULL is given when an optional routine is not implemented
DSET structures and functions are usually declared static
January 2009
EPICS Workshop RRCAT

7. DSET - initRecord long initRecord(struct … *precord);
Called by iocInit() once for each record with matching DTYP
Optional routine, but usually supplied
Routines often
Validate the INP or OUTP field
Verify that addressed hardware is present
Allocate device-specific storage for the record
Each record contains a void *dpvt pointer for this purpose
Program device registers
Set record-specific fields needed for conversion to/from engineering units
January 2009
EPICS Workshop RRCAT

8. DSET - read/write long read(struct … *precord);
long write(struct … *precord);
Called when record is processed
Perform (or initiate) the I/O operation:
Synchronous input
Copy value from hardware into precord->rval
Return 0 (to indicate success)‏
Synchronous output
Copy value from precord->rval to hardware
Asynchronous I/O
Set PACT true
Arrange some way have I/O done by another thread
When I/O done complete record processing
January 2009
EPICS Workshop RRCAT

9. Device Database Definition
The IOC discovers device support from entries in .dbd files
device(recType,addrType,dsetName,”dtypeName”)‏
addrType is one of
AB_IO BITBUS_IO CAMAC_IO GPIB_IO
INST_IO RF_IO VME_IO VXI_IO
dsetName is the name of the C Device Support Entry Table (DSET)‏
By convention name indicates record and hardware type:
device(ai, GPIB_IO, devAidg535, "dg535")‏
device(bi, VME_IO, devBiXy240, "XYCOM-240")‏
Starting with 3.14
When make is done in application src directory o.<arch>/app_registerRecordDeviceDriver.cpp generated
Code generated from .dbd files
Registers support code
January 2009
EPICS Workshop RRCAT

10. DSET and DRVET
typedef long (*DEVSUPFUN)(); /* ptr to device support function*/
typedef struct dset { /* device support entry table */
long number; /*number of support routines*/
DEVSUPFUN report; /*print report*/
DEVSUPFUN init; /*init support layer*/
DEVSUPFUN init_record; /*init device for particular record*/
DEVSUPFUN get_ioint_info; /* get io interrupt information*/
/*other functions are record dependent*/
/* normally methods like read, write*/
}dset;
typedef long (*DRVSUPFUN) (); /* ptr to driver support function*/
typedef struct drvet { /* driver entry table */
long number; /*number of support routines*/
DRVSUPFUN report; /*print report*/
DRVSUPFUN init; /*init support*/
/*other functions are device dependent*/
}drvet;
January 2009
EPICS Workshop RRCAT

11. How does a record find its device support?

Through .dbd ‘device’ statements:
January 2009
EPICS Workshop RRCAT

12. Syntax for INP or OUT
Syntax depends on addrType. Lets discuss two types
VME_IO
#Ccard example is “#C0 S1”
card - the card number of associated hardware module.
signal - signal on card
parm - An arbitrary character string: Optional and device specific.
INST_IO
@parm
Parm – An arbitrary character string
It will be seen that INST_IO is used by asynDriver and by STREAMS
January 2009
EPICS Workshop RRCAT

13. Comments about Address Type
addrType is one of
AB_IO BITBUS_IO CAMAC_IO GPIB_IO
INST_IO RF_IO VME_IO VXI_IO
Hindsight shows that this was not a good idea
What about PCI, USB, etc. ?
Doubt that a new facility would use BITBUS_IO or AB_IO
What about an Industry Pack GPIB Module? gpib->ip->vme
Just what is RF_IO? Even sounds like a special case.
New support should only use INST_IO
Only defines “optional information”, which must
AsynDriver has syntax
drvParams"
STREAMS has the syntax
protocol bus [address [parameters]]"
January 2009
EPICS Workshop RRCAT

14. Brief History Original EPICS defined only DSET and DRVET
Support for new hardware required new device support
What record types?
Only device support or device and driver support?
If asynchronous support required, e.g. Serial and gpib, then must provide thread to perform actual IO.
Must prevent simultaneous access by multiple records.
For interrupts must support method dset.getintinfo.
Result was lots of support where each did it's own thing
January 2009
EPICS Workshop RRCAT

15. Existing Support
VME modules – Many are supported. Use existing support.
J-PARC, KEK, Riken, SSRF make extensive use of network devices
Many ideas similar to asynDriver
Provides device support
Implement driver for specific device
Embeded Linux/EPICS system
Event Generator/Receiver Support
Hardware and thus Software evolved
Original development at ANL/APS
See sourceforge.net
EPICS applications
mrfEventSystem
Also see mrf.fi (Micro Research Finland) for hardware
January 2009
EPICS Workshop RRCAT

16. Support for Newly Purchased Hardware
Look in Module Support at APS
Send Message to tech-talk (Even if in module support!!)‏
See if synApps has support. It has LOTS of support.
If message based device (gpib or network or serial) create a STREAMS protocol file and use STREAMS together with asynDriver.
If no support found implement an ASYN port driver!!!
Rest of talk describes asynDriver and STREAMS
Emphasis is on message based devices
BUT asynDriver is also appropriate for register based devices.
No need to implement device support
Connection management
Diagnostic information via asynTrace
January 2009
EPICS Workshop RRCAT

17. AsynDriver – Also just called ASYN
What is it?
What does it do?
How does it do it?
How do I use it?
January 2009
EPICS Workshop RRCAT

18. What is asynDriver?
asynDriver: A general purpose facility for interfacing device specific code to low level drivers.
What does that mean?
It is not a driver. It is a driver framework: Interface definitions and a collection of utilities.
What does it define?
Interfaces to different classes (not brands) of hardware.
What does it provide?
Functionalities common to all (or many) drivers.
Device support for many record types
Originally only support for asynchronous message based devices like serial or gpib.
Now supports:
Message and register based devices
Synchronous and asynchronous devices
Too late to change the name.
January 2009
EPICS Workshop RRCAT

19. Before ASYN – Message Based Device Support
January 2009
EPICS Workshop RRCAT

20. Before ASYN – Duplication of effort
Each device support has its own asynchronous I/O Dispatcher
All with different degrees of support for message concurrency and connection management
January 2009
EPICS Workshop RRCAT

21. Before ASYN – Duplication of effort
Each device support has its own set of low-level drivers
All with different driver coverage
January 2009
EPICS Workshop RRCAT

22. Before ASYN – Duplication of effort
Not possible to get all users to switch to one devXXX
Many 10s of thousands of record instances
100s of device support modules
January 2009
EPICS Workshop RRCAT

23. Before ASYN – Duplication of effort
R3.14 makes the situation a whole lot worse:
Adds another dimension to the table – multiple architectures
vxWorks, POSIX (Linux, Solaris, OS X), Windows, RTEMS
January 2009
EPICS Workshop RRCAT

24. The solution - ASYN
January 2009
EPICS Workshop RRCAT

25. The solution - ASYN Cost Device support code must be rewritten
January 2009
EPICS Workshop RRCAT

26. The solution - ASYN Cost Device support code must be rewritten
Drivers must be rewritten
January 2009
EPICS Workshop RRCAT

27. The solution - ASYN Cost Device support code must be rewritten
Drivers must be rewritten
Hmmm….sounds like, “Be reasonable, do it my way”.
Have we just added another column to the ‘problem’ figure?
January 2009
EPICS Workshop RRCAT

28. The solution - ASYN Cost Device support code must be rewritten
Drivers must be rewritten
Hmmm….sounds like, “Be reasonable, do it my way”
Have we just added another column to the ‘problem’ figure?
Benefit
Rewrite driver once – works with *all* types of device support
Drivers are now an O(1) problem rather than an O(n) problem
Several drivers done – O(0) problem
Common Connection Management
January 2009
EPICS Workshop RRCAT

29. ASYN Status
January 2009
EPICS Workshop RRCAT

30. ASYN Status AsynDriver supports Serial Vxi11 and gpib
Internet – IP client and server
Register and message based devices
STREAMS – Protocol file for message based devices
Can be used with asynDriver
SynApps has LOTS of support
Hardware types
Motors
Analog and Digital IO
Etc
Industry Pack.
All or most hardware support is now via asynDriver
January 2009
EPICS Workshop RRCAT

31. ASYN Architecture Interfaces (named; pure virtual functions)‏
Device support (or SNL code, another driver, or non-EPICS software)‏
Interfaces (named; pure virtual functions)‏
asynCommon (connect, report, …)‏
asynOctet (write, read, setInputEos,…)‏
Port (named object)
Port driver
addr=0
addr=1
device
device
January 2009
EPICS Workshop RRCAT

32. Examples Ports
Agilent E5810: A GPIB controller that implements the VXI11 RPC Protocol
PortName is Internet address
addr is gpib address
Serial Port: local serial port. Support for vxWorks, RTEMS, linux, windows
Normally only single addr but could be multi-drop serial
Terminal Server: network accessible serial posts. Example is MOXA.
Industry Pack
Many IP modules are supported: analog, digital, motor, gpib, etc.
Motor Controller – synApps has support for many controllers
VME module
Not much support now but certainly possible
PCI module
Again not much support but certainly possible
January 2009
EPICS Workshop RRCAT

33. ASYN Components - asynManager
Provides thread for each communication interface
All driver code executes in the context of this thread
Provides connection management
Driver code reports connect/disconnect events
Queues requests for work
Non-blocking – can be called by scan tasks
User-supplied callback code run in worker-thread context makes calls to driver
Driver code executes in a single-threaded synchronous environment
For non-blocking drivers it provides mutual exclusion
Handles registration
Low level drivers register themselves
The single-threaded synchronous environment makes driver development much easier
No fussing with mutexes
No need to set up I/O worker threads
January 2009
EPICS Workshop RRCAT

34. ASYN Components - Interface asynCommon
A group of methods provided by all drivers:
Report
Connect
Disconnect
Set option
Get option
Options are defined by low-level drivers
e.g., serial port rate, parity, stop bits, handshaking
January 2009
EPICS Workshop RRCAT

35. ASYN Components – Interface asynOctet
Driver or interposed processing layer
Methods for communicating with Message Based devices.
Read
Write
Set end-of-string character(s)‏
Get end-of-string character(s)‏
All that’s needed for
serial ports
‘telnet-style’ TCP/IP devices
Most gpib communication
January 2009
EPICS Workshop RRCAT

36. ASYN Components – Other device interfaces
AsynGpib – Adds gpib specific methods to asynOctet
asynInt32
Analog IO and other uses.
AsynUInt32Digital
Digital IO
asynFloat64
asynInt8Array,...asynFloat64Array
Arrays of standard types.
...
Can define your own but then must implement device support.
January 2009
EPICS Workshop RRCAT

37. ASYN Components : asynTrace
AsynTrace is a general purpose diagnostic facility
Trace mask determines what is reported
Error, driver, device, filter, flow
IO Trace mask determines how data is displayed
nodata, ascii, escape, hex
January 2009
EPICS Workshop RRCAT

38. ASYN Components: asynRecord
Special record type that can understands several asyn interfaces.
Can connect to different ports at run-time.
Can change any setting of supported interfaces types.
Is a good debug tool.
Access to options including tracing.
Comes with set of medm screens for different interfaces.
Can only handle simple devices:
e.g. asynOctet: write one string, read one string
Is all you need for simple devices.
But not really all that you want.
January 2009
EPICS Workshop RRCAT

39. AsynRecord medm screens
January 2009
EPICS Workshop RRCAT

40. Message Based Device Support
A message based device
Accepts a command as an ASCII string
Responds with an ASCII string
Can get complicated.
devGpib is device support for message based devices.
Long history – Started in early 1990s
Now supports gpib, vxi11, serial
Requires some C code.
Still useful for special cases.
STREAMS
Was developed by Dirk at the same time as asynDriver
Found out about each other at an EPICS meeting
Now can use asynDriver to talk to hardware
User creates an ASCII protocol file. No code!!!
Use it!!!
January 2009
EPICS Workshop RRCAT

41. Stream Device Device support for standard records and asynOctet ports.
Suitable for medium complicated protocols and string parsing.
Communication protocol is specified in plain text file
Big difference to devGpib: No need to recompile anything to support new device.
String formatting and parsing similar to printf/scanf, but with more converters, e.g. bitfield, BCD, enum, raw, …
Checksum support.
StreamDevice is not part of the asynDriver package.
See: epics.web.psi.ch/software/streamdevice
January 2009
EPICS Workshop RRCAT

42. Example Protocol File # This is an example protocol file
Terminator = CR LF;
# Frequency is a float. use ai and ao records
getFrequency {
out "FREQ?"; in "%f"; }
setFrequency {
out "FREQ %f";
@init { getFrequency; }
# Switch is an enum, either OFF or ON, use bi and bo records
getSwitch {
out "SW?"; in "SW %{OFF|ON}";
setSwitch {
out "SW %{OFF|ON}";
@init { getSwitch; }
# Connect a stringout record to this to get
# a generic command interface.
# After processing finishes, the record contains the reply.
debug {
ExtraInput = Ignore;
out "%s"; in "%39c"
January 2009
EPICS Workshop RRCAT