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

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/. January 2009 EPICS Workshop RRCAT

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

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

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

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

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

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

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

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

How does a record find its device support?  Through .dbd ‘device’ statements: January 2009 EPICS Workshop RRCAT

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 January 2009 EPICS Workshop RRCAT

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]]" January 2009 EPICS Workshop RRCAT

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

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 January 2009 EPICS Workshop RRCAT

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

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

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

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

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

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

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

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

The solution - ASYN January 2009 EPICS Workshop RRCAT

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

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

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

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

ASYN Status January 2009 EPICS Workshop RRCAT

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

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

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

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

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

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

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

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

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

AsynRecord medm screens January 2009 EPICS Workshop RRCAT

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

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

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