lin-epics-modules/ADAndor
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Removed asynPortDriver documentation, now in asyn; fixed HTML errors

Browse Source 
git-svn-id: https://subversion.xor.aps.anl.gov/synApps/areaDetector/trunk@8463 dc6c5ff5-0b8b-c028-a01f-ffb33f00fc8b
This commit is contained in:
rivers
2009-02-16 17:58:58 +00:00
parent bf626fe272
commit 68b5226dfe
1 changed files with 10 additions and 269 deletions
Download Patch File Download Diff File Expand all files Collapse all files

279
documentation/areaDetectorDoc.html
View File

@@ -1,6 +1,9 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>areaDetector: EPICS Area Detector Support</title>
<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
</head>
<body>
<div style="text-align: center">
@@ -182,272 +185,10 @@
Detector drivers and plugins are asyn port drivers, meaning that they implement
one or more of the standard asyn interfaces. They register themselves as interrupt
sources, so that they do callbacks to registered asyn clients when values change.
asynPortDriver is a base C++ class that handles all of the details of registering
the port driver, registering the supported interfaces, and registering the required
interrupt sources.
</p>
<p>
Drivers and plugins each need to support a number of parameters that control their
operation and provide status information. Most of these can be treated as 32-bit
integers, 64-bit floats, or strings. When the new value of a parameter is sent to
a driver, (e.g. detector binning in the X direction) from an asyn client (e.g. an
EPICS record), then the driver will need to take some action. It may change some
other parameters in response to this new value (e.g. image size in the X direction).
The sequence of operations in the driver can be summarized as
</p>
<ol>
<li>New parameter value arrives, or new data arrives from detector.</li>
<li>Change values of one or more parameters.</li>
<li>For each parameter whose value changes set a flag noting that it changed.</li>
<li>When operation is complete, call the registered callbacks for each changed parameter.</li>
</ol>
<p>
asynPortDriver provides methods to simplify the above sequence, which must be implemented
for each of the many parameters that the driver supports. Each parameter is assigned
a number, which is the value in the pasynUser-&gt reason field that asyn clients
pass to the driver when reading or writing that parameter. asynPortDriver maintains
a table of parameter values, associating each parameter number with a data type
(integer, double, or string), caching the current value, and maintaining a flag
indicating if a value has changed. Drivers use asynPortDriver methods to read the
current value from the table, and to set new values in the table. There is a method
to call all registered callbacks for values that have changed since callbacks were
last done.
</p>
<p>
The following are the public definitions in the asynPortDriver class:
</p>
<pre>#define asynCommonMask 0x00000001
#define asynDrvUserMask 0x00000002
#define asynOptionMask 0x00000004
#define asynInt32Mask 0x00000008
#define asyUInt32DigitalMask 0x00000010
#define asynFloat64Mask 0x00000020
#define asynOctetMask 0x00000040
#define asynInt8ArrayMask 0x00000080
#define asynInt16ArrayMask 0x00000100
#define asynInt32ArrayMask 0x00000200
#define asynFloat32ArrayMask 0x00000400
#define asynFloat64ArrayMask 0x00000800
#define asynGenericPointerMask 0x00001000
class asynPortDriver {
public:
asynPortDriver(const char *portName, int maxAddr, int paramTableSize, int interfaceMask, int interruptMask);
virtual ~asynPortDriver();
virtual asynStatus getAddress(asynUser *pasynUser, const char *functionName, int *address);
virtual asynStatus findParam(asynParamString_t *paramTable, int numParams, const char *paramName, int *param);
virtual asynStatus readInt32(asynUser *pasynUser, epicsInt32 *value);
virtual asynStatus writeInt32(asynUser *pasynUser, epicsInt32 value);
virtual asynStatus getBounds(asynUser *pasynUser, epicsInt32 *low, epicsInt32 *high);
virtual asynStatus readFloat64(asynUser *pasynUser, epicsFloat64 *value);
virtual asynStatus writeFloat64(asynUser *pasynUser, epicsFloat64 value);
virtual asynStatus readOctet(asynUser *pasynUser, char *value, size_t maxChars,
size_t *nActual, int *eomReason);
virtual asynStatus writeOctet(asynUser *pasynUser, const char *value, size_t maxChars,
size_t *nActual);
virtual asynStatus readInt8Array(asynUser *pasynUser, epicsInt8 *value,
size_t nElements, size_t *nIn);
virtual asynStatus writeInt8Array(asynUser *pasynUser, epicsInt8 *value,
size_t nElements);
virtual asynStatus doCallbacksInt8Array(epicsInt8 *value,
size_t nElements, int reason, int addr);
virtual asynStatus readInt16Array(asynUser *pasynUser, epicsInt16 *value,
size_t nElements, size_t *nIn);
virtual asynStatus writeInt16Array(asynUser *pasynUser, epicsInt16 *value,
size_t nElements);
virtual asynStatus doCallbacksInt16Array(epicsInt16 *value,
size_t nElements, int reason, int addr);
virtual asynStatus readInt32Array(asynUser *pasynUser, epicsInt32 *value,
size_t nElements, size_t *nIn);
virtual asynStatus writeInt32Array(asynUser *pasynUser, epicsInt32 *value,
size_t nElements);
virtual asynStatus doCallbacksInt32Array(epicsInt32 *value,
size_t nElements, int reason, int addr);
virtual asynStatus readFloat32Array(asynUser *pasynUser, epicsFloat32 *value,
size_t nElements, size_t *nIn);
virtual asynStatus writeFloat32Array(asynUser *pasynUser, epicsFloat32 *value,
size_t nElements);
virtual asynStatus doCallbacksFloat32Array(epicsFloat32 *value,
size_t nElements, int reason, int addr);
virtual asynStatus readFloat64Array(asynUser *pasynUser, epicsFloat64 *value,
size_t nElements, size_t *nIn);
virtual asynStatus writeFloat64Array(asynUser *pasynUser, epicsFloat64 *value,
size_t nElements);
virtual asynStatus doCallbacksFloat64Array(epicsFloat64 *value,
size_t nElements, int reason, int addr);
virtual asynStatus readGenericPointer(asynUser *pasynUser, void *pointer);
virtual asynStatus writeGenericPointer(asynUser *pasynUser, void *pointer);
virtual asynStatus doCallbacksGenericPointer(void *pointer, int reason, int addr);
virtual asynStatus drvUserCreate(asynUser *pasynUser, const char *drvInfo,
const char **pptypeName, size_t *psize);
virtual asynStatus drvUserGetType(asynUser *pasynUser,
const char **pptypeName, size_t *psize);
virtual asynStatus drvUserDestroy(asynUser *pasynUser);
virtual void report(FILE *fp, int details);
virtual asynStatus connect(asynUser *pasynUser);
virtual asynStatus disconnect(asynUser *pasynUser);
virtual asynStatus setIntegerParam(int index, int value);
virtual asynStatus setIntegerParam(int list, int index, int value);
virtual asynStatus setDoubleParam(int index, double value);
virtual asynStatus setDoubleParam(int list, int index, double value);
virtual asynStatus setStringParam(int index, const char *value);
virtual asynStatus setStringParam(int list, int index, const char *value);
virtual asynStatus getIntegerParam(int index, int * value);
virtual asynStatus getIntegerParam(int list, int index, int * value);
virtual asynStatus getDoubleParam(int index, double * value);
virtual asynStatus getDoubleParam(int list, int index, double * value);
virtual asynStatus getStringParam(int index, int maxChars, char *value);
virtual asynStatus getStringParam(int list, int index, int maxChars, char *value);
virtual asynStatus callParamCallbacks();
virtual asynStatus callParamCallbacks(int list, int addr);
virtual void reportParams();
char *portName;
int maxAddr;
paramList **params;
epicsMutexId mutexId;
/* The asyn interfaces this driver implements */
asynStandardInterfaces asynStdInterfaces;
/* asynUser connected to ourselves for asynTrace */
asynUser *pasynUserSelf;
};
</pre>
<p>
A brief explanation of the methods and data in this class is provided here. Users
should look at the example driver (simDetector) and plugins provided with areaDetector
for examples of how this class is used.
</p>
<pre> asynPortDriver(const char *portName, int maxAddr, int paramTableSize, int interfaceMask, int interruptMask);
</pre>
<p>
This is the constructor for the class.
</p>
<ul>
<li><code>portName</code> is the name of the asyn port for this driver or plugin.</li>
<li><code>maxAddr</code> is the maximum number of asyn addresses that this driver
supports. This number returned by the <code>pasynManager-&gt getAddr()</code> function.
Typically it is 1, but some plugins (e.g. NDPluginROI) support values &gt 1. This
controls the number of parameter tables that are created.</li>
<li><code>parmTableSize</code> is the maximum number of parameters that this driver
or plugin supports. This controls the size of the parameter tables.</li>
<li><code>interfaceMask</code> is a mask with each bit defining which asyn interfaces
this driver or plugin supports. The bit mask values are defined in asynPortDriver.h,
e.g. <code>asynInt32Mask</code>.</li>
<li><code>interruptMask</code> is a mask with each bit defining which of the asyn
interfaces this driver or plugin supports can generate interrupts. The bit mask
values are defined in asynPortDriver.h, e.g. <code>asynInt8ArrayMask</code>.</li>
</ul>
<pre> virtual asynStatus getAddress(asynUser *pasynUser, const char *functionName, int *address);
</pre>
<p>
Returns the value from pasynManager-&gt getAddr(pasynUser,...). Returns an error
if the address is not valid, e.g. &gt= this-&gt maxAddr.
</p>
<pre> virtual asynStatus readInt32(asynUser *pasynUser, epicsInt32 *value);
virtual asynStatus readFloat64(asynUser *pasynUser, epicsFloat64 *value);
virtual asynStatus readOctet(asynUser *pasynUser, char *value, size_t maxChars,
size_t *nActual, int *eomReason);
</pre>
<p>
These methods are called by asyn clients to return the current cached value for
the parameter indexed by pasynUser-&gt reason in the parameter table defined by
<code>getAddress()</code>. Derived classed typically do not need to implement these
methods.
</p>
<pre> virtual asynStatus writeInt32(asynUser *pasynUser, epicsInt32 value);
virtual asynStatus writeFloat64(asynUser *pasynUser, epicsFloat64 value);
virtual asynStatus writeOctet(asynUser *pasynUser, const char *value, size_t maxChars,
size_t *nActual);
</pre>
<p>
These methods are called by asynClients to set the new value of a parameter. The
implementation of these methods in asynPortDriver copies the parameter into a cached
location for use by the asynRead(Int32, Float64, and Octet) methods. Most drivers
will provide their own implementations of these methods to do driver-dependent operations
when there is a new value of the parameter.
</p>
<pre>
virtual asynStatus readXXXArray(asynUser *pasynUser, epicsInt8 *value,
size_t nElements, size_t *nIn);
virtual asynStatus writeXXXArray(asynUser *pasynUser, epicsInt8 *value,
size_t nElements);
virtual asynStatus doCallbacksXXXArray(epicsInt8 *value,
size_t nElements, int reason, int addr);
virtual asynStatus readGenericPointer(asynUser *pasynUser, void *handle);
virtual asynStatus writeGenericPointer(asynUser *pasynUser, void *handle);
virtual asynStatus doCallbacksGenericPointer(void *handle, int reason, int addr);
</pre>
<p>
where XXX=(Int8, Int16, Int32, Float32, or Float64). The readXXX and writeXXX methods
only have stub methods that return an error in asynPortDriver, so they must be implemented
in the derived classes if the corresponding interface is used. They are not pure
virtual functions so that the derived class need not implement the interface if
it is not used. The doCallbacksXXX methods in asynPortDriver call any registered
asyn clients on the corresponding interface if the <code>reason</code> and <code>addr</code>
values match. It typically does not need to be implemented in derived classes.
</p>
<pre>
virtual asynStatus findParam(asynParamString_t *paramTable, int numParams, const char *paramName, int *param);
virtual asynStatus drvUserCreate(asynUser *pasynUser, const char *drvInfo,
const char **pptypeName, size_t *psize);
virtual asynStatus drvUserGetType(asynUser *pasynUser,
const char **pptypeName, size_t *psize);
virtual asynStatus drvUserDestroy(asynUser *pasynUser);
</pre>
<p>
drvUserCreate must be implemented in derived classes that use the parameter facilities
of asynPortDriver. The <code>findParam</code> method is a convenience function that
searches an array of {enum, string} structures and returns the enum (parameter number)
matching the string. This is typically used in the implementation of <code>drvUserCreate</code>
in derived classes. <code>drvUserGetType</code> and <code>drvUserDestroy</code>
typically do not need to be implemented in derived classes.
</p>
<pre>
virtual void report(FILE *fp, int details);
virtual asynStatus connect(asynUser *pasynUser);
virtual asynStatus disconnect(asynUser *pasynUser);
</pre>
<p>
The <code>report</code> function prints information on registered interrupt clients
if details &gt 0, and prints parameter table information if details &gt 5. It is
typically called by the implementation of <code>report</code> in derived classes
before or after they print specific information about themselves. <code>connect</code>
and <code>disconnect</code> call <code>pasynManager-&gt exceptionConnect</code>
and <code>pasynManager-&gt exceptionDisconnect</code> respectively. Derived classes
may or may not need to implement these functions.
</p>
<pre>
virtual asynStatus setIntegerParam(int index, int value);
virtual asynStatus setIntegerParam(int list, int index, int value);
virtual asynStatus setDoubleParam(int index, double value);
virtual asynStatus setDoubleParam(int list, int index, double value);
virtual asynStatus setStringParam(int index, const char *value);
virtual asynStatus setStringParam(int list, int index, const char *value);
virtual asynStatus getIntegerParam(int index, int * value);
virtual asynStatus getIntegerParam(int list, int index, int * value);
virtual asynStatus getDoubleParam(int index, double * value);
virtual asynStatus getDoubleParam(int list, int index, double * value);
virtual asynStatus getStringParam(int index, int maxChars, char *value);
virtual asynStatus getStringParam(int list, int index, int maxChars, char *value);
virtual asynStatus callParamCallbacks();
virtual asynStatus callParamCallbacks(int list, int addr);
</pre>
<p>
The <code>setXXXParam</code> methods set the value of a parameter in the parameter
table in the object. If the value is different from the previous value of the parameter
they also set the flag indicating that the value has changed. The <code>getXXXParam</code>
methods return the current value of the parameter. There are two versions of the
<code>setXXXParam</code> and <code>getXXXParam</code> methods, one with a <code>list</code>
argument, and one without. The one without uses <code>list=0</code>, since there
is often only a single parameter list (i.e. if maxAddr=1). The <code>callParamCallbacks</code>
methods call back any registered clients for parameters that have changed since
the last time <code>callParamCallbacks</code> was called. The version of <code>callParamCallbacks</code>
with no arguments uses the first parameter list and matches asyn address=0. There
is a second version of <code>callParamCallbacks</code> that takes an argument specifying
the parameter list number, and the asyn address to match.
They inherit from the <a href="http://www.aps.anl.gov/epics/modules/soft/asyn">asynPortDriver
base C++ class</a> that is provided in the asyn module. That base class handles
all of the details of registering the port driver, registering the supported interfaces,
and registering the required interrupt sources.
</p>
<h3 id="NDArray">
NDArray</h3>
@@ -549,7 +290,7 @@ public:
<li><code>size</code> is the number of elements in this dimension.</li>
<li><code>offset</code> is the starting element in this dimension relative to the
first element of the detector in unbinned units. If a selected region of the detector
is being read, then this value may be &gt 0. The offset value is cumulative, so
is being read, then this value may be &gt;0. The offset value is cumulative, so
if a plugin such as NDPluginROI further selects a subregion, the offset is relative
to the first element in the detector, and not to the first element of the region
passed to NDPluginROI.</li>
@@ -741,7 +482,7 @@ public:
<li><code>writeGenericPointer</code> This method currently does nothing. Derived classes
must implement this method as required.</li>
<li><code>report</code> This method calls the report function in the asynPortDriver
base class. It then calls the NDArrayPool->report() method if details &gt 5.</li>
base class. It then calls the NDArrayPool->report() method if details &gt;5.</li>
</ul>
<h3 id="ADDriver">
ADDriver</h3>