epics tutorial asyn device/driver support epics seminar/workshop raja ramanna centre for advanced...

EPICS TutorialAsyn Device/Driver Support

EPICS Seminar/WorkshopRaja Ramanna Centre For Advanced Technology

Indore IndiaJanuary 27-30 2009

Presented by:Marty Kraimer

Based on Presentations b:Eric Norum and Dirk Zimoch

January 2009 EPICS Workshop RRCAT 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: http://epics.web.psi.ch/software/streamdevice/.


Overview of Tutorial

Device Support Driver Support AsynDriver Message Based Device Support

devGpib – briefly STREAMS


Overview of Device Support

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


Overview of Driver Support

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


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


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


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 Return 0 (to indicate success)

Asynchronous I/O Set PACT true Arrange some way have I/O done by another thread When I/O done complete record processing


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


DSET and DRVET

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;

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;


How does a record find its device support?

Through .dbd ‘device’ statements:


Syntax for INP or OUT

Syntax depends on addrType. Lets discuss two types VME_IO

#Ccard Ssignal @parm 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


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 follow @ AsynDriver has syntax

"@asyn(portName,addr,timeout) drvParams" STREAMS has the syntax

"@file protocol bus [address [parameters]]"


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


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 http://epaper.kek.jp/pc08/papers/wex03.pdf

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

http://epaper.kek.jp/pc08/papers/wex03.pdf


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


AsynDriver – Also just called ASYN

• What is it?• What does it do?• How does it do it?• How do I use it?


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.


Before ASYN – Message Based Device Support


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



• Each device support has its own set of low-level drivers

• All with different driver coverage



• Not possible to get all users to switch to one devXXX

• Many 10s of thousands of record instances

• 100s of device support modules



• 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


The solution - ASYN


The solution - ASYN

Cost Device support code must be rewritten


The solution - ASYN

Cost Device support code must be rewritten Drivers must be rewritten


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?


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


ASYN Status


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


ASYN Architecture

Device support (or SNL code, another driver, or non-EPICS software)

device device

Port (named object)

Port driver

addr=0 addr=1

Interfaces (named; pure virtual functions)

asynCommon (connect, report, …)

asynOctet (write, read, setInputEos,…)


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


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


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


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


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.


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


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.


AsynRecord medm screens


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


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

http://epics.web.psi.ch/software/streamdevice/


Example Protocol File

# This is an example protocol fileTerminator = CR LF;# Frequency is a float. use ai and ao recordsgetFrequency { out "FREQ?"; in "%f";}setFrequency { out "FREQ %f"; @init { getFrequency; }}# Switch is an enum, either OFF or ON, use bi and bo recordsgetSwitch { 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"}