V4 Link Support Tutorial - Revision history

MartyKraimer at 19:46, 3 November 2005

2005-11-03T19:46:11Z

Show changes

MartyKraimer at 19:48, 2 November 2005

2005-11-02T19:48:50Z

Show changes

MartyKraimer at 20:23, 1 November 2005

2005-11-01T20:23:00Z

Show changes

MartyKraimer: added discussion about analog conversion and special support for output records

2005-10-26T18:17:33Z

added discussion about analog conversion and special support for output records

Show changes

MartyKraimer at 19:29, 25 October 2005

2005-10-25T19:29:24Z

← Older revision		Revision as of 19:29, 25 October 2005
Line 141:		Line 141:
	}		}
	}		}
	The last example ~~attaches the link to~~ support for a VME Analog to Digital device.		The last example selects support for a VME Analog to Digital device.
	AiRecord aiMonitorExample = {		AiRecord aiMonitorExample = {
	...		...
Line 236:		Line 236:
	LinkResult get(Callback callback,Int16 data);		LinkResult get(Callback callback,Int16 data);
	LinkResult put(Callback callback,Int16 data);		LinkResult put(Callback callback,Int16 data);
	void getBounds(~~<type>~~ low, ~~<type>~~ high);		void getBounds(Int16 low, Int16 high);
	}		}
	In C++ would be:		In C++ would be:
	class LinkInt16 {		class LinkInt16 {
	public:		public:
	virtual LinkResult get(Callback &callback, int16_t *data) = 0;		virtual LinkResult get(Callback &callback, int16_t &data) = 0;
	virtual LinkResult put(Callback &callback, int16_t data) = 0;		virtual LinkResult put(Callback &callback, int16_t data) = 0;
			virtual void getBounds(int16_t &low, int16_t &high) = 0;
	};		};

Line 248:		Line 249:
	== Link and MonitorLink ==		== Link and MonitorLink ==

			All support <b>must</b> register interface <tt>Link</tt>
			and if it supports monitors interface <tt>MonitorLink</tt>.
	<b>NOTE: arguments and return types ignored for now</b>		<b>NOTE: arguments and return types ignored for now</b>
	interface Link {		interface Link {
Line 343:		Line 346:
	void getOutputEos(octet[] eos);		void getOutputEos(octet[] eos);
	}		}

			== asynDigital Support ==

	enum interruptReason {		enum interruptReason {
Line 385:		Line 390:
	LinkResult get(Callback callback,Int16 data);		LinkResult get(Callback callback,Int16 data);
	LinkResult put(Callback callback,Int16 data);		LinkResult put(Callback callback,Int16 data);
	void getBounds(~~<type>~~ low, ~~<type>~~ high);		void getBounds(Int16 low, Int16 high);
	}		}
	interface LinkArrayInt16 {		interface LinkArrayInt16 {
Line 394:		Line 399:
	LinkResult get(Callback callback,Int32 data);		LinkResult get(Callback callback,Int32 data);
	LinkResult put(Callback callback,Int32 data);		LinkResult put(Callback callback,Int32 data);
	void getBounds(~~<type>~~ low, ~~<type>~~ high);		void getBounds(Int32 low, Int32 high);
	}		}
	interface LinkArrayInt32 {		interface LinkArrayInt32 {
Line 403:		Line 408:
	LinkResult get(Callback callback,Int64 data);		LinkResult get(Callback callback,Int64 data);
	LinkResult put(Callback callback,Int64 data);		LinkResult put(Callback callback,Int64 data);
	void getBounds(~~<type>~~ low, ~~<type>~~ high);		void getBounds(Int64 low, Int64 high);
	}		}
	interface LinkArrayInt64 {		interface LinkArrayInt64 {
Line 410:		Line 415:
	}		}

	~~enum interruptReason {~~
	~~interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth~~
	}


	== Float Support ==		== Float Support ==
Line 459:		Line 460:
	It assumes that there is VME support of the form		It assumes that there is VME support of the form

	public class vme {		public class vme {
	static public short getShort(long addr);		static public short getShort(long addr);
	...		...
	}		}

	The link support would be something like:		The link support would be something like:
Line 471:		Line 472:
	addr = fromFactory;		addr = fromFactory;
	connected = false;		connected = false;
	// from the VME ~~initailze~~ vmeaddr and channel		// from the VME initialize vmeaddr and channel
	// details left to your imagination		// details left to your imagination
	}		}

MartyKraimer at 18:35, 25 October 2005

2005-10-25T18:35:13Z

Show changes

MartyKraimer at 15:17, 24 October 2005

2005-10-24T15:17:28Z

Show changes

MartyKraimer at 15:00, 4 October 2005

2005-10-04T15:00:44Z

← Older revision		Revision as of 15:00, 4 October 2005
Line 1:		Line 1:
	EPICS: IOC Link Support Tutorial ~~Sept 30~~ 2005		EPICS: IOC Link Support Tutorial Oct 04 2005

	----		----
Line 278:		Line 278:
	}		}
	== Process Link Support ==		== Process Link Support ==
	interface ~~ProcessLinkSupport~~<type> {		interface LinkProcess<type> {
	LinkWaitResult process(Callback callback);		LinkWaitResult process(Callback callback);
	}		}

MartyKraimer at 15:15, 30 September 2005

2005-09-30T15:15:05Z

Show changes

MartyKraimer at 19:26, 29 September 2005

2005-09-29T19:26:18Z

New page

EPICS: IOC Link Support Tutorial Sept 29 2005
<b>UNDER CONSTRUCTION</b>

----
= Overview =

The V4 link support is a replacement for V3
# DBF_DEVICE, DBF_INLINK, DBF_OUTLINK, and DBF_FWDLINK
# device DBD definition and device support
# driver DBD definition and driver support

The link support model is:
* For each link, record support defines a list of interfaces it can use for communicating with link support
* Link support registers the set of interfaces it implements

Link support has no knowledge of what record types are using it
and record support has no knowledge about link support other than the
interface it is using.

EPICS base defines a standard set of interfaces for link support.
The intention is that the set includes enough functionality such that
most link support can be implemented via just these interfaces.

The interfaces support all the functionality needed by Channel/Database access
and by the generic EPICS device support supplied by asynDriver.
Since asynDriver is intended as a framework for interfacing to most hardware,
this means that the interfaces supplied and used by base allows support
for most hardware. The support can communicate with the hardware
however it wants but must implement some set of the interfaces defined
by base.

This document gives a brief overview of the V4 link support model.

----
<center>
= Database Definitions For Links =
</center>

This section first reviews the DBD syntax related to link definitions.
It then gives a brief description of link related definitions in dbCommon.dbd

== Syntax ==

A record link has the syntax:
link(linkDirection,interface(string,...))
A link itself has the syntax:
link(linkDirection, choiceName, interfaceName, dataStructName)

where

; <tt>linkDirection</tt>
: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.

; <tt>interface</tt>
: This is a list of the interfaces that the record support understands.
; <tt>choiceName</tt>
: UTF-8 string that describes the choice

; <tt>interfaceName</tt>
: The name of an interface via which record support communicates with device support.

; <tt>dataStructName</tt>
: The name of a <tt>struct</tt> containing configuration information for the link support. Record support normally does not access this structure. Database configuration tools do prompt the user to assign values to the structure.

When a record instance is created the choiceName selects the support
to attach to a record link. The interfaceName must be one of the
interface names the record has listed as a valid type and linkDirection must be compatible
with the linkDirection the record type specified.

== Standard Definitions For Channel/Database Access ==

These are the database definitions defined in dbCommon are used by
the base supplied support for Channel/Database access.

=== Data Structures ===

The complete set of definitions are defined in "V4 DB RecordCommon".
struct(MonitorLinkData) {
field(pvname,string) { link}
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(InputLinkData) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(block,boolean)
field(inheritSeverity,boolean)
}
... also OutputLinkData and ProcessLinkData

A look at the fields shows that these are what is required to implement
the V4 semantics for Channel/Database access links.

=== Link Definitions ===

Link support is provided for
* input
** monitor support
** input support
* output
* process

For input and output The following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

"V4 DB RecordCommon" describes the complete set of link definitions
supplied by EPICS base. Some examples are:

link(process,processLink,ProcessLink,ProcessLinkData);

link(in,monitorLinkArrayOctet,LinkArrayOctet,MonitorLinkData);
link(in,inputLinkArrayOctet,LinkArrayOctet,InputLinkData);
link(out,outputLinkArrayOctet,LinkArrayOctet,OutputLinkData);

link(in,monitorLinkBoolean,LinkBoolean,MonitorLinkData);
...

link(in,monitorLinkInt16,LinkInt16,MonitorLinkData);
link(in,monitorLinkInt32,LinkInt32,MonitorLinkData);
link(in,monitorLinkInt64,LinkInt64,MonitorLinkData);
...

link(in,monitorLinkFloat32,LinkFloat32,MonitorLinkData);
link(in,monitorLinkFloat64,LinkFloat64,MonitorLinkData);
...

link(in,monitorLinkArrayString,LinkArrayString,MonitorLinkData);
link(in,inputLinkArrayString,LinkArrayString,InputLinkData);
link(out,outputLinkArrayString,LinkArrayString,OutputLinkData);

These are the link definitions for the Channel/Database access link
support supplied with base. The support registers support for processLink,
monitorLinkArrayOctet, ...

== asynDriver link support ==

These are definitions that are used by the standard EPICS device support
for asynDriver. Since asynDriver is a generic way of interfacing arbitrary
hardware support, this is a generic way of attaching links in records to
hardware.

=== Data Definitions ===
struct(AsynLinkData) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

=== link definitions ===

link(inout,asynInt32,LinkInt32,AsynLinkData)
link(in,asynInt32Average,LinkInt32,AsynLinkData)
link(in,asynInt32Monitor,LinkInt32,AsynLinkData)
link(inout,asynFloat64,LinkFloat64,AsynLinkData)
link(in,asynFloat64Average,LinkFloat64,AsynLinkData)
link(in,asynFloat64Monitor,LinkFloat64,AsynLinkData)
link(in,asynDigitalMonitor,AsynDigital,AsynLinkData)
link(inout,asynDigital,AsynDigital,AsynLinkData)
link(inout,asynInt32Array,LinkArrayInt32,AsynLinkData)
link(inout,asynFloat64Array,LinkArrayFloat64,AsynLinkData)
link(inout,asynOctet,AsynOctet,AsynLinkData)

This is the set of definitions for the standard EPICS device support implemented
by asynDriver. Although, at least for the first few V4 releases,
asynDriver will not be part of base, they are shown here because the
LinkInt32,... interface definitions are defined as part of base.
Again it is expected that almost all hardware support be created by
implementing a combination of these link interface definitions or
the interfaces implemented by Channel/Database access link support.
---
<center>
= Link Support =
</center>

== Overview ==
An arbitrary number of Link Support implementations can exist.
An implementation can be either soft support or support that communicates with
hardware.

Other link support can also be supplied.
New support should try very hard to implement the standard interfaces
supplied by EPICS base. These are the interfaces that the record types
supplied with base know how to use.

Soft support should try to implement the same interfaces implemented by
the Channel/Database access support supplied with base. The support
can, of course, define data structures for it's own use.
Implementing these interfaces means that nthe support will work for
the same set of record links as the Channel/Database access support.

Hardware support should, if possible, also implement the same interfaces
implemented by the Channel/Database access support.
Message based support may also have to implement the AsynOctet interface
but this interface is only used by a few record links.

This section describes the interfaces implemented by all link support
and then the standard interfaces used by the records supplied with base.

== Link and MonitorLink ==

interface Link {
void report(int16 level);
void cancel();
void destroy();
void initialize();
void connect();
void disconnect();
}

interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}

<tt>Link</tt> is an interface that must be implemented by every link
support.
An instance of this is connected to each DbfLink field.
The <tt>Link</tt> methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

<tt>MonitorLink</tt> is an interface that is implemented by link support that
supports monitors. An example is support for hardware interrupts.
The <tt>MonitorLink</tt> methods are:
* <tt>addMonitor</tt> - Add a monitor callback
* <tt>removeMonitor</tt> - Remove monitor

Normally record support does not need to call any of the Link
or MonitorLink methods since database access does this automatically.
For example if a link field is modified via a channel access put,
database access will call destroy before modifying the link
and initialize and connect after the link is modified.

== Definitions that apply to Process,Monitor,Input,and Output support ==
These are the definitions used by the Channel/Database access support
supplied with base. It is also used by the standard EPICS support from asyn.

enum LinkWaitResult {
linkNoop, // Nothing was done, e.g. link is null link
linkDone, // field was modified. No wait is necessary
linkWait, // waiting. can do additional procsssing
linkWaitBlock, // waiting. dont do additional processing until
}

interface Callback {
void done();
void failure();
}
== Process Link Support ==
interface ProcessLinkSupport<type> {
LinkWaitResult process(Callback callback);
}

== Octet Support ==
There is no support for octet but there is support for an array of octets.

interface LinkArrayOctet {
LinkWaitResult getWait(octet[] data,Callback callback);
LinkWaitResult putWait(octet[] data,Callback callback);
}

The data source must be an array of octets or the connect request will fail.

<b>GENERIC QUESTION</b> The data is passed as primitive or arrays of
primitive types. Should <tt>Dbf</tt> interfaces be used? Needs thought.

== asynOctet Support ==

This still needs more work. It attempts to reproduce the functionality
of V3 asynDriver.

interface AsynOctet {
LinkWaitResult write(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkWaitResult writeRaw(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkWaitResult read(Callback callback,
octet[] data, Int32 nbytesTransfered);
LinkWaitResult readRaw(Callback callback,
octet[] data, Int32 nbytesTransfered);
void flush();
void setInputEos(octet[] eos);
void getInputEos(octet[] eos);
void setOutputEos(octet[] eos);
void getOutputEos(octet[] eos);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}
struct asynDigitalInterrupt {
octet[] mask;
int32 addr;
Callback callback
}

interface AsynDigital {
LinkWaitResult write(octet[] value, octet[] mask);
LinkWaitResult read(octet[] value, octet[] mask);
void setInterrupt(octet[] mask, interruptReason reason);
void clearInterrupt(octet[] mask);
void getInterrupt(octet[] mask, interruptReason reason);
void registerInterruptUser(interruptCallbackUInt32Digital callback,
octet[] mask);
void cancelInterruptUser();
}

== Boolean Support ==
interface LinkBoolean {
LinkWaitResult getWait(Boolean data,Callback callback);
LinkWaitResult putWait(boolean data,Callback callback);
}
interface LinkArrayBoolean {
LinkWaitResult getWait(boolean[] data,Callback callback);
LinkWaitResult putWait(boolean[] data,Callback callback);
}

The data source must be a boolean or a string that contains a valid
boolean value.

== Integer Support ==

Support is available. for int16, int32, and int64.
This section uses the Java generic syntax, e.g. <type>. In this
section <type> must be int16, int32, or int64.

interface Link<type> {
LinkWaitResult getWait(<type> data,Callback callback);
LinkWaitResult putWait(<type> data,Callback callback);
void getBounds(<type> low, <type> high);
}
interface LinkArray<type> {
LinkWaitResult getWait(<type>[] data,Callback callback);
LinkWaitResult putWait(<type>[] data,Callback callback);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}

== Float Support ==

Support is available. for float32 and float64.
This section uses the Java generic syntax, e.g. <type>. In this
section <type> must be float32 or float64.

interface Link<type> {
LinkWaitResult getWait(<type> data,Callback callback);
LinkWaitResult putWait(<type> data,Callback callback);
}
interface LinkArray<type> {
LinkWaitResult getWait(<type>[] data,Callback callback);
LinkWaitResult putWait(<type>[] data,Callback callback);
}

== String Support ==
interface LinkString {
LinkWaitResult getWait(string data,Callback callback);
LinkWaitResult putWait(string data,Callback callback);
}
interface LinkArrayString {
LinkWaitResult getWait(string[] data,Callback callback);
LinkWaitResult putWait(string[] data,Callback callback);
}

The data source must be a string.

----
<center>
= Example - VME ADC support =
</center>
== DBD definitions ==
The following struct is defined for configuration information.
struct VMEADC {
field(a16 int16)
field(a32 int32)
field(channel int16)
}
The following link definition is defined:
link(in,myAdcSupport,LinkInt32,VMEADC)

This allows record instance definitions like:
AiRecord aiExample = {
...
input = myAdcSupport{a16=0x0010;channel=1}
...
}

The link support would be something like:

class AdcSupport : public Link LinkInt32 {
public:
AdcSupport(VMEADCData fromFactory) : data(fromFactory) connected(false)
{
// from the VMEADC initailze vmeaddr and channel
}

// Link methods
void report(int16_t level)
{
printf("AdcSupport a16 %x channel %d\n",a16,channel);
}
void cancel() {} // nothing to do
void destroy() {delete this};
void initialize()
{
// make sure we can access a16
}
void connect() {connected = true}
void disconnect() {connected = false}

// LinkInt32 methods
LinkWaitResult getWait(int32_t *data,Callback callback)
{
*data = (int32_t)vmeaddr[1];
return linkDone;
}
LinkWaitResult putWait(int32_t *data,Callback callback)
{
throw CantWriteAdc;
}
void getBounds(int32_t *low, int32_t *high)
{
// assume 16 bit unipolor adc
*low = 0; *high = 0xffff;
}
private:
VMEADCData data;
uint16_t *vmeaddr;
int channel;
bool connected;
}