-
@@ -101,37 +121,335 @@ The architecture of the areaDetector module is shown in Figure 1.
- A State-Notation-Language (SNL) program,
pilatusROI.st. - This program implements all of the logic for acquiring images, reading - the TIFF files, computing ROIs, and making the data available to EPICS. - - Database files,
pilatusROI.template, pilatusROI_N.template. - These databases - contain almost no "logic" with no links between records in the database. - Some of the records use "streamDevice" for communication with camserver. Other - records are simply variables which channel access clients and the State - Notation Language (SNL) program use. - - A streamDevice protocol file,
pilatusROI.protocol. - This file defines the protocol used for - communicating with camserver. - - Autosave request files,
pilatusROI_settings.req, pilatusROI_N_settings.req. - These files define the EPICS PVs - that will be automatically saved and restored when the EPICS IOC is restarted, so that - state information is preserved. - - MEDM screens,
pilatusROI.adl, - pilatus8ROIs.adl, pilatusROI_waveform.adl. These screens are - used to control image acquisition, and definition and display of ROI data. - - An IDL display program,
epics_image_display.profor displaying the images - as they are sent to EPICS. This program is also available as a pre-built IDL ".sav" file - that can be run for free under the IDL Virtual Machine. - - SPEC macros that use the ROI counts as spec counters. These work in both conventional - step scanning mode, and also in - trajectory scanning mode - with the Newport MM4005 and XPS motor controllers. +
- Layer 1. This is the layer that allows user written code to + communicate with the hardware. + It is usually provided by the detector vendor. It may consist of a library or DLL, + of a socket protocol to a driver, a Microsoft COM interface, etc. +
- Layer 2. This is the driver that is written for the area detector application to + control a particular detector. It is normally written in C++ and inherits from the + ADDriverBase class. It uses the standard asyn interfaces for control and status + information. Each time it receives a new data array it passes it as an NDArray object + to all Layer 3 clients that have registered for callbacks. This is the only code that + needs to be written to implement a new detector. Existing drivers range from + 650 to 950 lines of code. +
- Layer 3. Code running at this level is called a "plug-in". This code registers with a + driver for a callback whenever there is a new data array. The existing plugins implement + file saving (NDPluginFile), region-of-interest (ROI) calculations (NDPluginROI), + and conversion of detector data to standard EPICS array types for use by + Channel Access clients (NDPluginStdArrays). Plugins are normally written in C++ and + inherit from NDPluginBase. Existing plugins range from 280 to 550 lines + of code. +
- Layer 4. This is standard asyn device support that comes with the EPICS asyn module. +
- Layer 5. These are standard EPICS records, and EPICS database (template) files that + define records to communicate with drivers at Layer 2 and plugins at Layer 3. +
- Layer 6. These are EPICS channel access clients, such as MEDM that communicate with + the records at Layer 5. There is a free IDL client that can display images using + EPICS waveform and other records communicating with the NDPluginStdArrays plugin + at Layer 3.
- libCom. libCom from EPICS base provides operating-system independent functions for + threads, mutexes, etc. +
- asyn. asyn is a module that provides interthread messaging services, including queueing + and callbacks. +
- New parameter value arrives, or new data arrives from detector. +
- Change values of one or more parameters. +
- For each parameter whose value changes set a flag noting that it changed. +
- When operation is complete, call the registered callbacks for each changed parameter. +
Figure 1. Architecture of areaDetector module.
-
-
-
+
+The plugin architecture is very powerful, because plugins can be reconfigured at run-time. For example +the NDPluginStdArrays can switch from getting its array data from a detector driver to an NDPluginROI +plugin. That way it will switch from displaying the entire detector to whatever sub-region the ROI +driver has selected. Any Channel Access clients connected to the NDPluginStdArrays driver +will automatically switch to displaying this subregion. +Similarly, the NDPluginFile plugin can be switched at run-time from saving the entire image to saving +a selected ROI, just by changing its input source. +
+The use of plugins is optional, and it is only plugins that require the driver to make the +image data available. If there are no plugins being used then EPICS can be used simply +to control the detector, without accessing the data itself. This is most useful when +the vendor API has the ability to save the data to a file. +
+What follows is a detailed description of the software, working from the bottom up. +Most of the code is object oriented, and written in C++. The parts of the code that depend +on anything from EPICS except libCom and asyn have been kept in in separate C files, so that +it is easy to build applications that do not run as part of an EPICS IOC. +
+
+ asynParamBase
+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 +
-
+
The following is the definition of the asynParamBase class: +
+class asynParamBase {
+public:
+ asynParamBase(const char *portName, int maxAddr, int paramTableSize, int interfaceMask, int interruptMask);
+ 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 readHandle(asynUser *pasynUser, void *handle);
+ virtual asynStatus writeHandle(asynUser *pasynUser, void *handle);
+ virtual asynStatus doCallbacksHandle(void *handle, 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 *pasynUser;
+};
+
+
+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.
+
++ asynParamBase(const char *portName, int maxAddr, int paramTableSize, int interfaceMask, int interruptMask); ++This is the constructor for the class. +
-
+
portNameis the name of the asyn port for this driver or plugin. +maxAddris the maximum number of asyn addresses that this driver or plugin supports. + This number returned by thepasynManager-> getAddr()function. Typically it is 1, but some + plugins (e.g. NDPluginROI) support values > 1. This controls the number of parameter + tables that are created. +parmTableSizeis the maximum number of parameters that this driver or plugin supports. + This controls the size of the parameter tables. +interfaceMaskis a mask with each bit defining which asyn interfaces this driver + or plugin supports. + The bit mask values are defined in asynParamBase.h, e.g.asynInt32Mask. +interruptMaskis 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 asynParamBase.h, e.g.asynInt8ArrayMask. +
+
+ virtual asynStatus getAddress(asynUser *pasynUser, const char *functionName, int *address); ++Returns the value from pasynManager-> getAddr(pasynUser,...). +Returns an error if the address is not valid, e.g. >= this-> maxAddr. + +
+ 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); ++These methods are called by asyn clients to return the current cached value for the +parameter indexed by pasynUser-> reason in the parameter table defined by
getAddress().
+Derived classed typically do not need to implement these methods.
+
++
+ 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); ++These methods are called by asynClients to set the new value of a parameter. These +methods only have stub methods that return an error in asynParamBase, 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. + +
+
+ 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 readHandle(asynUser *pasynUser, void *handle); + virtual asynStatus writeHandle(asynUser *pasynUser, void *handle); + virtual asynStatus doCallbacksHandle(void *handle, int reason, int addr); ++where XXX=(Int8, Int16, Int32, Float32, or Float64). +The readXXX and writeXXX methods only have stub methods that return an error in asynParamBase, 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 asynParamBase +call any registered asyn clients on the corresponding interface if the
reason
+and addr values match. It typically does not need to be implemented in derived classes.
+
++
+ 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); ++drvUserCreate must be implemented in derived classes that use the parameter facilities of asynParamBase. +The
findParam 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 drvUserCreate in derived classes. drvUserGetType and
+drvUserDestroy typically do not need to be implemented in derived classes.
+
++
+ virtual void report(FILE *fp, int details); + virtual asynStatus connect(asynUser *pasynUser); + virtual asynStatus disconnect(asynUser *pasynUser); ++The
report function prints information on registered interrupt clients if details > 0, and prints
+parameter table information if details > 5. It is typically called by the implementation of
+report in derived classes before or after
+they print specific information about themselves. connect and disconnect call
+pasynManager-> exceptionConnect and pasynManager-> exceptionDisconnect respectively.
+Derived classes may or may not need to implement these functions.
+
++
+ 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); ++The
setXXXParam 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 getXXXParam
+methods return the current value of the parameter. There are two versions of the
+setXXXParam and getXXXParam methods, one with a list
+argument, and one without. The one without uses list=0, since there
+is often only a single parameter list (i.e. if maxAddr=1). The callParamCallbacks
+methods call back any registered clients for parameters that have changed since the last
+time callParamCallbacks was called. The version of callParamCallbacks
+with no arguments uses the first parameter list and matches asyn address=0. There is a
+second version of callParamCallbacks that takes an argument specifying the parameter list
+number, and the asyn address to match.
+
+