EPICS Tutorial Device and Driver Support EPICS Meeting

EPICS Tutorial Device and Driver Support EPICS Meeting INFN October 15 -17 2008 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 asyn. Driver EPICS Meeting April 2007 at DESY Hamburg Germany Go to EPICS home page and look MEETINGS References IOC Application Developer's Guide Describes device and driver support in detail Asyn. Driver See the latest release of base for links to above two documents STREAMS: http: //epics. web. psi. ch/software/streamdevice/. INFN October 13 -17 2008 EPICS Tutorial Device/Driver 2

Overview of Tutorial Device Support Driver Support Asyn. Driver Message Based Device Support dev. Gpib – briefly STREAMS INFN October 13 -17 2008 EPICS Tutorial Device/Driver 3

Overview of Device Support Attached to INP or OUT field of a record. Type. 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 INFN October 13 -17 2008 EPICS Tutorial Device/Driver 4

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 asyn. Driver and STREAMS do NOT use DRVET This talk has no further discussion of Driver Support New support should not use it. Do something like asyn. Driver or STREAMS INFN October 13 -17 2008 EPICS Tutorial Device/Driver 5

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 (*init. Record)(struct … *precord); long (*get. Io. Int. Info)(…); … read/write and other routines as required }; aidset DSET for ai. Record adds two methods: read and special_linconv aodset DSET for ao. Record 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 INFN October 13 -17 2008 EPICS Tutorial Device/Driver 6

DSET - init. Record long init. Record(struct … *precord); Called by ioc. Init() 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 INFN October 13 -17 2008 EPICS Tutorial Device/Driver 7

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 INFN October 13 -17 2008 EPICS Tutorial Device/Driver 8

Device Database Definition The IOC discovers device support from entries in. dbd files device(rec. Type, addr. Type, dset. Name, ”dtype. Name”) addr. Type is one of AB_IO BITBUS_IO CAMAC_IO GPIB_IO INST_IO RF_IO VME_IO VXI_IO dset. Name is the name of the C Device Support Entry Table (DSET) By convention name indicates record and hardware type: device(ai, GPIB_IO, dev. Aidg 535, "dg 535") device(bi, VME_IO, dev. Bi. Xy 240, "XYCOM-240") INFN October 13 -17 2008 EPICS Tutorial Device/Driver 9

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; INFN October 13 -17 2008 EPICS Tutorial Device/Driver 10

How does a record find its device support? ��� Through. dbd ‘device’ statements: INFN October 13 -17 2008 EPICS Tutorial Device/Driver 11

Syntax for INP or OUT Syntax depends on addr. Type. Lets discuss two types VME_IO #Ccard Ssignal @parm example is “#C 0 S 1” 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 asyn. Driver and by STREAMS INFN October 13 -17 2008 EPICS Tutorial Device/Driver 12

Comments about Address Type addr. Type is one of AB_IO BITBUS_IO INST_IO RF_IO CAMAC_IO GPIB_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 @ Asyn. Driver has syntax "@asyn(port. Name, addr, timeout) drv. Params" STREAMS has the syntax "@file protocol bus [address [parameters]]" INFN October 13 -17 2008 EPICS Tutorial Device/Driver 13

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 Examples VME modules – Many are supported. Use existing support. Event Generator/Receiver Support Hardware and thus software evolved. Started at APS. I think latest is Diamond version. Just use it. INFN October 13 -17 2008 EPICS Tutorial Device/Driver 14

Support for Newly Purchased Hardware Look in Module Support at APS Send Message to tech-talk (Even if in module support!!) See if syn. Apps 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 asyn. Driver. If no support found implement an ASYN port driver!!! Rest of talk describes asyn. Driver and STREAMS Emphasis is on message based devices BUT asyn. Driver is also appropriate for register based devices. No need to implement device support Connection management Diagnostic information via asyn. Trace INFN October 13 -17 2008 EPICS Tutorial Device/Driver 15

Asyn. Driver – Also just called ASYN • • What is it? What does it do? How does it do it? How do I use it? INFN October 13 -17 2008 EPICS Tutorial Device/Driver 16

What is asyn. Driver? asyn. Driver: 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. INFN October 13 -17 2008 EPICS Tutorial Device/Driver 17

Before ASYN – Message Based Device Support INFN October 13 -17 2008 EPICS Tutorial Device/Driver 18

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 INFN October 13 -17 2008 EPICS Tutorial Device/Driver 19

Before ASYN – Duplication of effort • Each device support has its own set of low-level drivers • All with different driver coverage INFN October 13 -17 2008 EPICS Tutorial Device/Driver 20

Before ASYN – Duplication of effort • Not possible to get all users to switch to one dev. XXX • Many 10 s of thousands of record instances • 100 s of device support modules INFN October 13 -17 2008 EPICS Tutorial Device/Driver 21

Before ASYN – Duplication of effort • R 3. 14 makes the situation a whole lot worse: • Adds another dimension to the table – multiple architectures vx. Works, POSIX (Linux, Solaris, OS X), Windows, RTEMS INFN October 13 -17 2008 EPICS Tutorial Device/Driver 22

The solution - ASYN INFN October 13 -17 2008 EPICS Tutorial Device/Driver 23

The solution - ASYN Cost Device support code must be rewritten INFN October 13 -17 2008 EPICS Tutorial Device/Driver 24

The solution - ASYN Cost Device support code must be rewritten Drivers must be rewritten INFN October 13 -17 2008 EPICS Tutorial Device/Driver 25

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? INFN October 13 -17 2008 EPICS Tutorial Device/Driver 26

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 INFN October 13 -17 2008 EPICS Tutorial Device/Driver 27

ASYN Status INFN October 13 -17 2008 EPICS Tutorial Device/Driver 28

ASYN Status Asyn. Driver supports Serial Vxi 11 and gpib Internet – IP client and server Register and message based devices STREAMS – Protocol file for message based devices Can be used with asyn. Driver Syn. Apps has LOTS of support Hardware types Motors Analog and Digital IO Etc Industry Pack. All or most hardware support is now via asyn. Driver INFN October 13 -17 2008 EPICS Tutorial Device/Driver 29

ASYN Architecture Device support (or SNL code, another driver, or non-EPICS software) Interfaces (named; asyn. Common (connect, report, …) pure virtual functions) asyn. Octet (write, read, set. Input. Eos, …) Port (named object) Port driver addr=0 device INFN October 13 -17 2008 addr=1 device EPICS Tutorial Device/Driver 30

Examples Ports Agilent E 5810: A GPIB controller that implements the VXI 11 RPC Protocol Port. Name is Internet address addr is gpib address Serial Port: local serial port. Support for vx. Works, 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 – syn. Apps has support for many controllers VME module Not much support now but certainly possible PCI module Again not much support but certainly possible INFN October 13 -17 2008 EPICS Tutorial Device/Driver 31

ASYN Components - asyn. Manager 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 INFN October 13 -17 2008 EPICS Tutorial Device/Driver 32

ASYN Components - Interface asyn. Common 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 INFN October 13 -17 2008 EPICS Tutorial Device/Driver 33

ASYN Components – Interface asyn. Octet 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 INFN October 13 -17 2008 EPICS Tutorial Device/Driver 34

ASYN Components – Other device interfaces Asyn. Gpib – Adds gpib specific methods to asyn. Octet asyn. Int 32 Analog IO and other uses. Asyn. UInt 32 Digital IO asyn. Float 64 asyn. Int 8 Array, . . . asyn. Float 64 Array Arrays of standard types. . Can define your own but then must implement device support. INFN October 13 -17 2008 EPICS Tutorial Device/Driver 35

ASYN Components : asyn. Trace Asyn. Trace 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 INFN October 13 -17 2008 EPICS Tutorial Device/Driver 36

ASYN Components: asyn. Record 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. asyn. Octet: write one string, read one string Is all you need for simple devices. But not really all that you want. INFN October 13 -17 2008 EPICS Tutorial Device/Driver 37

Asyn. Record medm screens INFN October 13 -17 2008 EPICS Tutorial Device/Driver 38

Message Based Device Support A message based device Accepts a command as an ASCII string Responds with an ASCII string Can get complicated. dev. Gpib is device support for message based devices. Long history – Started in early 1990 s Now supports gpib, vxi 11, serial Requires some C code. Still useful for special cases. STREAMS Was developed by Dirk at the same time as asyn. Driver Found out about each other at an EPICS meeting Now can use asyn. Driver to talk to hardware User creates an ASCII protocol file. No code!!! Use it!!! INFN October 13 -17 2008 EPICS Tutorial Device/Driver 39

Stream Device support for standard records and asyn. Octet ports. Suitable for medium complicated protocols and string parsing. Communication protocol is specified in plain text file Big difference to dev. Gpib: 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. Stream. Device is not part of the asyn. Driver package. See: epics. web. psi. ch/software/streamdevice INFN October 13 -17 2008 EPICS Tutorial Device/Driver 40

Example Protocol File # This is an example protocol file Terminator = CR LF; # Frequency is a float. use ai and ao records get. Frequency { out "FREQ? "; in "%f"; } set. Frequency { out "FREQ %f"; @init { get. Frequency; } } # Switch is an enum, either OFF or ON, use bi and bo records get. Switch { out "SW? "; in "SW %{OFF|ON}"; } set. Switch { out "SW %{OFF|ON}"; @init { get. Switch; } } # Connect a stringout record to this to get # a generic command interface. # After processing finishes, the record contains the reply. debug { Extra. Input = Ignore; out "%s"; in "%39 c" } INFN October 13 -17 2008 EPICS Tutorial Device/Driver 41