diff --git a/documentation/areaDetectorDoc.html b/documentation/areaDetectorDoc.html index 048dd39..ecc9cc1 100755 --- a/documentation/areaDetectorDoc.html +++ b/documentation/areaDetectorDoc.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - areaDetector: EPICS Area Detector Support + areaDetector: EPICS software for area detectors @@ -32,24 +32,25 @@
  • paramAttribute
  • asynNDArrayDriver
    • -
  • Detector drivers +
    • +
  • Detector drivers
    • -
  • Plugins

    @@ -146,8 +147,8 @@

  • 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.
    • +
  • asyn. asyn is a + module that provides interthread messaging services, including queueing and callbacks.

    • In particular it is possible to eliminate layers 4-6 in the architecture shown in @@ -201,7 +202,11 @@ They inherit from the asynPortDriver base C++ class 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. The + supported interfaces, and registering the required interrupt sources. It also provides + a parameter library for int, double, and string parameters indexed by the enum values + defined in the driver. The parameter library provides methods to write and read + the parameter values, and to perform callbacks to registered clients when a parameter + value has changed. The asynPortDriver class documentation describes this class in detail.

    @@ -235,45 +240,114 @@ NDAttribute

    The NDAttribute is a class for linking metadata to an NDArray. An NDattribute has - a name, description, data type, value, source type and source information. Attributes are - identified by their names, which are case-insensitive. There - are methods to set and get the information for an attribute. - The - NDAttribute class documentation describes this class in detail. + a name, description, data type, value, source type and source information. Attributes + are identified by their names, which are case-insensitive. There are methods to + set and get the information for an attribute.

    +

    + It is useful to define some conventions for attribute names, so that plugins or + data analysis programs can look for a specific attribute. The following are the + attribute conventions used in current plugins:

    + + + + + + + + + + + + + + + + + + + + + +
    + Conventions for standard attribute names
    + Attribute name + Description + Data type
    + ColorMode + "Color mode" + int (NDColorMode_t)
    + BayerPattern + "Bayer pattern" + int (NDBayerPattern_t)
    +

    + Attribute names are case-insensitive in the areaDetector software, but external + software may not be case-insensitive so the attribute names should generally be + used exactly as they appear above. For attributes not in this table a good convention + would be to use the corresponding driver parameter without the leading ND or AD, + and with the first character of every "word" of the name starting with upper case. + For example, the standard attribute name for ADManufacturer should be "Manufacturer", + ADNumExposures should be "NumExposures", etc.

    +

    + The NDAttribute class documentation + describes this class in detail.

    NDAttributeList

    - The NDAttributeList implements a linked list of NDAttribute objects. - NDArray objects contain an NDAttributeList which is how attributes are associated with - an NDArray. There are methods to add, delete and search for NDAttribute objects in an - NDAttributeList. Each attribute in the list must have a unique name, which is case-insensitive. - The - NDAttributeList class documentation describes this class in detail. + The NDAttributeList implements a linked list of NDAttribute objects. NDArray objects + contain an NDAttributeList which is how attributes are associated with an NDArray. + There are methods to add, delete and search for NDAttribute objects in an NDAttributeList. + Each attribute in the list must have a unique name, which is case-insensitive. +

    +

    + When NDArrays are copied with the NDArrayPool methods the attribute list is also + copied. +

    +

    + IMPORTANT NOTE: When a new NDArray is allocated using NDArrayPool::alloc() the behavior + of any existing attribute list on the NDArray taken from the pool is determined + by the value of the global variable eraseNDAttributes. By default the + value of this variable is 0. This means that when a new NDArray is allocated from + the pool its attribute list is not cleared. This greatly improves + efficiency in the normal case where attributes for a given driver are defined once + at initialization and never deleted. (The attribute values may + of course be changing.) It eliminates allocating and deallocating attribute memory + each time an array is obtained from the pool. It is still possible to add new attributes + to the array, but any existing attributes will continue to exist even if they are + ostensibly cleared e.g. asynNDArrayDriver::readNDAttributesFile() is called again. + If it is desired to eliminate all existing attributes from NDArrays each time a + new one is allocated then the global variable eraseNDAttributes should + be set to 1. This can be done at the iocsh prompt with the command:

    + 
    +    var eraseNDAttributes 1
+
    +

    + The NDAttributeList + class documentation describes this class in detail.

    PVAttribute

    - The PVAttribute class is derived from NDAttribute. It obtains its value by monitor callbacks from an EPICS PV, - and is thus used to associate current the value of any EPICS PV with an NDArray. - The - PVAttribute class documentation describes this class in detail. + The PVAttribute class is derived from NDAttribute. It obtains its value by monitor + callbacks from an EPICS PV, and is thus used to associate current the value of any + EPICS PV with an NDArray. The + PVAttribute class documentation describes this class in detail.

    paramAttribute

    - The paramAttribute class is derived from NDAttribute. It obtains its value from the current value - of a driver or plugin parameter. The paramAttribute class is typically used when it is important to have - the current value of the parameter and the value of a corresponding PVAttribute might not be current because the - EPICS PV has not yet updated. - The - paramAttribute class documentation describes this class in detail. + The paramAttribute class is derived from NDAttribute. It obtains its value from + the current value of a driver or plugin parameter. The paramAttribute class is typically + used when it is important to have the current value of the parameter and the value + of a corresponding PVAttribute might not be current because the EPICS PV has not + yet updated. The paramAttribute + class documentation describes this class in detail.

    asynNDArrayDriver

    asynNDArrayDriver inherits from asynPortDriver. It implements the asynGenericPointer - functions, for NDArray objects. This is the class from which both plugins and area + functions for NDArray objects. This is the class from which both plugins and area detector drivers are indirectly derived. The asynNDArrayDriver class documentation describes this class in detail.

    @@ -294,10 +368,9 @@
  • Access: Read-write (r/w) or read-only (r/o).
  • drvUser string: The string used to look up the parameter in the driver through the drvUser interface. This string is used in the EPICS database file for - generic asyn device support to associate a record with a particular parameter. It is - also used to associate a paramAttribute - with a driver parameter in the XML file - that is read by asynNDArrayDriver::readNDAttributesFile
    • + generic asyn device support to associate a record with a particular parameter. It + is also used to associate a + paramAttribute with a driver parameter in the XML file that is read by asynNDArrayDriver::readNDAttributesFile
  • EPICS record name: The name of the record in ADBase.template. Each record name begins with the two macro parameters $(P) and $(R). In the case of read/write parameters there are normally two records, one for writing the value, and a second, @@ -814,7 +887,7 @@ r/o - Rate at which arrays are being acquired. Computed in the ADBase.template database. + Rate at which arrays are being acquired. Computed in the ADBase.template database. N/A @@ -834,10 +907,10 @@ r/w - The name of an XML file defining the PVAttributes and paramAttributes to be - added to each NDArray by this driver or plugin. The format of the XML file is described - in the documentation for - asynNDArrayDriver::readNDAttributesFile(). + The name of an XML file defining the PVAttributes and paramAttributes to be added + to each NDArray by this driver or plugin. The format of the XML file is described + in the documentation for + asynNDArrayDriver::readNDAttributesFile(). ND_ATTRIBUTES_FILE @@ -871,7 +944,8 @@ ADDriver

    ADDriver inherits from asynNDArrayDriver. This is the class from which area detector - drivers are directly derived. The + drivers are directly derived. It provides parameters and methods that are specific + to area detectors, while asynNDArrayDriver is a general NDArray driver. The ADDriver class documentation describes this class in detail.

    @@ -1313,17 +1387,17 @@ r/w - Start (1) or stop (0) image acquisition. This is an EPICS busy - record that does not process its forward link until acquisition is complete. Clients - should write 1 to the Acquire record to start acquisition, and wait for Acquire - to go to 0 to know that acquisition is complete. + Start (1) or stop (0) image acquisition. This is an EPICS busy record that does + not process its forward link until acquisition is complete. Clients should write + 1 to the Acquire record to start acquisition, and wait for Acquire to go to 0 to + know that acquisition is complete. ACQUIRE - $(P)$(R)Acquire
    + $(P)$(R)Acquire
    $(P)$(R)Acquire_RBV - busy
    + busy
    bi @@ -1635,44 +1709,56 @@

    Guidelines and rules for drivers

    -

    The following are guidelines and rules for writing areaDetector drivers

    +

    + The following are guidelines and rules for writing areaDetector drivers

    MEDM screens

    +

    + The following is the top-level MEDM screen that provides links to the screens for + most of the detectors and plugins that areaDetector supports. This screen is useful + for testing, and as a source for copying related-display menus to be placed in application-specific + MEDM screens. +

    +
    +

    + ADTop.adl

    + ADTop.png

    The following is the MEDM screen that provides access to the parameters in asynNDArrayDriver.h and ADDriver.h through records in ADBase.template. This is a top-level MEDM screen @@ -1687,7 +1773,7 @@ ADBase.png

    The following is the MEDM screen that provides access to the file-related parameters - in ADStdDriverParams through records in NDFile.template. This screen is for use + in asynNDArrayDriver.h through records in NDFile.template. This screen is for use with detector drivers that directly implement file I/O.

    @@ -1696,12 +1782,12 @@ NDFile.png

    The following is the MEDM screen that provides access to the EPICS shutter parameters - in ADStdDriverParams through records in ADBase.template. This screen allows one - to define the EPICS PVs to open the shutter, close the shutter, and determine the - shutter status. The values of these PVs for open and close drive and status can - also be defined. Note that in many cases the same PV will be used for open and close - drive, but in some cases (e.g. APS safety shutters) different PVs are used for open - and close. + in ADDriver.h through records in ADBase.template. This screen allows one to define + the EPICS PVs to open the shutter, close the shutter, and determine the shutter + status. The values of these PVs for open and close drive and status can also be + defined. Note that in many cases the same PV will be used for open and close drive, + but in some cases (e.g. APS safety shutters) different PVs are used for open and + close.