EPICSWIKI - User contributions [en]

RRM 3-14 Common

2013-02-28T19:33:28Z

EricNorum:

[[RRM 3-14|EPICS Record Reference Manual]]

== Fields Common to Many Record Types ==

=== Introduction ===

This chapter describes input and output fields that are common to multiple record types. These fields have the same meaning whenever they are used.

=== Input Records ===

==== Common Fields ====

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to obtain input. For soft analog records it can be a constant, a database link, or a channel access link.<TR>
<TD>DTYP<TD>Device Type<TD>DTYP specifies the name of the device support module that will input values. Each record type has its own set of device support routines. If a record type does not have any associated device support, DTYP is meaningless.<TR>
<TD>RVAL<TD>Raw Value<TD>Whenever possible this field contains the raw data value exactly as it is obtained from the hardware or from the associated device driver and before it undergoes any conversions. The <CODE>Soft Channel</CODE> device support module reads values directly into VAL, bypassing this field.<TR>
<TD>VAL<TD>Value<TD>This is the record's final value, after any needed conversions have been performed.<TR>
<TD>SIMM<TD>Simulation Mode<TD>This field has either the value YES or NO. By setting this field to YES, the record can be switched into simulation mode of operation. While in simulation mode, input will be obtained from SIOL instead of INP.<TR>
<TD>SIML<TD>Simulation Mode Location<TD>This field can be a constant, a database link, or a channel access link. If SIML is a database or channel access link, then SIMM is read from SIML. If SIML is a constant link then SIMM is initialized with the constant value but can be changed via dbPuts.<TR>
<TD>SVAL<TD>Simulation Value<TD>This is the record's input value, in engineering units, when the record is switched into simulation mode, i.e. when SIMM is set to YES.<TR>
<TD>SIOL<TD>Simulation Value Location<TD>This field can be a constant, a database link, or a channel access link. If SIOL is a database or channel access link, then SVAL is read from SIOL. If SIOL is a constant link then SVAL is initialized with the constant value but can be changed via dbPuts.<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>When this record is in simulation mode, it will be put into alarm with this severity and a status of SIMM.
</TABLE>

==== Device Input ====

A device input routine normally returns one of the following values to its associated record support routine:

* 0: Success and convert. The input value is in RVAL. The record support module is expected to compute VAL from RVAL.
* 2: Success, but don't convert. The device support module can specify this value if it does not want any conversions. It might do this for two reasons:
** A hardware error is detected (in this case, it should also raise an alarm condition).
** The device support routine reads values directly into the VAL field and then sets UDF to FALSE.

==== Soft Input ====

In almost all cases, two special device support modules are provided: Soft Channel and Raw Soft Channel. Both allow INP to be a constant, a database link, or a channel access link. The Soft Channel device support module reads input directly into the VAL field and specifies that no conversion of any type should be performed. Thus, it allows the record to hold values corresponding to the C data type of the VAL field. Note that for soft input, RVAL is not used. The Raw Soft Channel support module reads input into RVAL and asks that any specified conversions be performed.

The device support read routine normally calls recGblGetLinkValue() which performs the following steps:

* If the INP link type is CONSTANT recGblGetLinkValue() does nothing and returns with a status of zero.
* If the INP link type is DB_LINK, then dbGetLink() is called to obtain a new input value. If dbGetLink returns an error, a LINK_ALARM with a severity of INVALID_ALARM is raised. RecGblGetLinkValue() returns the status returned by dbGetLink().
* If the INP link type is CA_LINK, then dbCaGetLink() is called to obtain a new input value. If dbCaGetLink() returns an error, a LINK alarm with a severity of INVALID is raised. RecGblGetLinkValue() returns the status of dbCaGetLink().

If the return status of recGblGetLinkValue() is zero and the INP link type is not CONSTANT, then UDF is set to FALSE. The device support read routine normally returns the status of recGblGetLinkValue.

==== Simulation Mode ====

An input record can be switched into simulation mode of operation by setting the value of SIMM to YES or RAW. During simulation, the record will be put into alarm with a severity of SIMS and a status of SIMM_ALARM. While in simulation mode, input values will be read from SIOL instead of INP:
-- (SIMM = NO?) INP (if supported and directed by device support, -> RVAL -- convert -> VAL), (else -> VAL)
/
SIML -> SIMM
\
-- (SIMM = YES?) SIOL -> SVAL -> VAL
\
-- (SIMM = RAW?) SIOL -> SVAL -> RVAL -- convert -> VAL

A record can be switched into simulation mode of operation by setting the value of SIMM to YES. During simulation, the record will be put into alarm with a severity of SIMS and a status of SIMM_ALARM. While in simulation mode, input values, in engineering units, will be obtained from SIOL instead of INP. Also, while the record is in simulation mode, there will be no raw value conversion and no calls to device support when the record is processed.

Normally input records contain a private readValue() routine which performs the following steps:

* If PACT is TRUE, the device support read routine is called, status is set to its return code, and readValue returns.
* Call recGblGetLinkValue() to get a new value for SIMM if SIML is a DB_LINK or a CA_LINK.
* Check value of SIMM.
* If SIMM is NO, then call the device support read routine, set status to its return code, and return.
* If SIMM is YES, then call recGblGetLinkValue to read the input value from SIOL into SVAL. If success, then set VAL to SVAL and UDF to FALSE and set status to 2 (don't convert) if input record supports conversion. If SIMS is greater than zero, set alarm status to SIMM and severity to SIMS. Set status to the return code from recGblGetLinkValue and return.
* If SIMM is RAW, then call recGblGetLinkValue to read the input value from SIOL into SVAL. If success, then set RVAL to SVAL and UDF to FALSE and set status to 0 (convert) if input record supports conversion. If SIMS is greater than zero, set alarm status to SIMM and severity to SIMS. Set status to the return code from recGblGetLinkValue and return.
* IF SIMM is not YES, NO or RAW, a SOFT alarm with a severity of INVALID is raised, and return status is set to -1.

=== Output Records ===

==== Common Fields ====

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>OUT<TD>Output Link<TD>This field is used by the device support routines to decide where to send output. For soft records, it can be a constant, a database link, or a channel access link. If the link is a constant, the result is no output.<TR>
<TD>DTYP<TD>Device Type<TD>DTYP specifies the name of the device support module that will receive values. Each record type has its own set of device support routines. If a record type does not have any associated device support, DTYP is meaningless.<TR>
<TD>VAL<TD>Value<TD>This is the desired value before any conversions to raw output have been performed.<TR>
<TD>OVAL<TD>Output Value<TD>OVAL is used to decide when to invoke monitors. Archive and value change monitors are invoked if OVAL is not equal to VAL. If a record type needs to make adjustments, OVAL is used to enforce the maximum rate of change limit before converting the desired value to a raw value.<TR>
<TD>RVAL<TD>Raw Value<TD>Whenever possible this is the actual value sent to the hardware itself or to the associated device driver.<TR>
<TD>RBV<TD>Read Back Value<TD>Whenever possible this is the actual read back value obtained from the hardware itself or from the associated device driver.<TR>
<TD>DOL<TD>Desired Output Location (an Input Link)<TD>DOL can be a constant, a database link, or a channel access link. There is no device support associated with DOL. If DOL is a database or channel access link and OMSL is closed_loop, then VAL is obtained from DOL.<TR>
<TD>OMSL<TD>Output Mode Select<TD>This field has either the value "supervisory" or "closed_loop". DOL is used to determine VAL only if OMSL has the value "closed_loop". By setting this field the record can be switched between supervisory and closed loop mode of operation. While in closed loop mode, the VAL field cannot be set via dbPuts.<TR>
<TD>OIF<TD>Output Full or Incremental (analog output record only)<TD>This field, which is only used when input is obtained from DOL, determines if the value obtained from DOL is an increment to add to the current VAL or is the actual VAL desired.<TR>
<TD>SIMM<TD>Simulation Mode<TD>This field has either the value YES or NO. By setting this field to YES, the record can be switched into simulation mode of operation. While in simulation mode, output will be written to SIOL instead of OUT.<TR>
<TD>SIML<TD>Simulation Mode Location<TD>This field can be a constant, a database link, or a channel access link. If SIML is a database or channel access link, then SIMM is read from SIML. If SIML is a constant link then SIMM is initialized with the constant value but can be changed via dbPuts.<TR>
<TD>SIOL<TD>Simulation Value Location<TD>This field can be a constant, a database link, or a channel access link. If SIOL is a database or channel access link, then the output value is written to SIOL. If this link is a constant, the result is no output.<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>When this record is in simulation mode, it will be put into alarm with this severity and a status of SIMM_ALARM.<TR>
<TD>IVOA<TD>Invalid Alarm Output Action<TD>Whenever the record is put into INVALID alarm severity IVOA specifies an action. IVOA can be one of the following actions: Continue normally, Don't drive outputs, Set output equal to IVOV<TR>
<TD>IVOV<TD>Invalid Alarm Output Value, In Engineering Units<TD>When new severity has been set to INVALID alarm and IVOA is "Set output equal to IVOV", then, VAL is set to IVOV and converted to RVAL before device support is called.
</TABLE>

==== Soft Output ====

Normally two soft output device support modules are provided Soft and Raw Soft. Both allow the output link OUT to be a constant, a database link, or a channel access link. It is normally meaningless to use constant output links. The Soft support module writes output from the value associated with OVAL or VAL (if OVAL does not exist). The Raw Soft Channel support module writes the value associated with the RVAL field after conversion has been performed.

The device support write routine normally calls recGblPutLinkValue which performs the following steps:

* If the OUT link type is CONSTANT recGblPutLinkValue does nothing and returns with a status of zero.
* If the OUT link type is DB_LINK, then dbPutLink is called to write the current value. If dbPutLink returns an error, a LINK_ALARM with a severity of INVALID_ALARM is raised. RecGblPutLinkValue returns the status of dbPutLink.
* If the OUT link type is CA_LINK, then dbCaPutLink is called to write the current value. If dbCaPutLink returns an error, a LINK_ALARM with a severity of INVALID_ALARM is raised. RecGblPutLinkValue returns the status of dbCaPutLink.

The device support write routine normally returns the status of recGblPutLinkValue.

==== Output Mode Select ====

The fields DOL and OMSL are used to allow the output record to be part of a closed loop control algorithm. OMSL is meaningful only if DOL refers to a database or channel access link. It can have the values SUPERVISORY or CLOSED_LOOP. If the mode is SUPERVISORY, then nothing is done to VAL. If the mode is CLOSED_LOOP and the record type does not contain an OIF field, then each time the record is processed, VAL is set equal to the value obtained from the location referenced by DOL. If the mode is CLOSED_LOOP in record types with an OIF field and OIF is Full, VAL is set equal to the value obtained from the location referenced by DOL; if OIF is Incremental VAL is incremented by the value obtained from DOL.

==== Simulation Mode ====

An output record can be switched into simulation mode of operation by setting the value of SIMM to YES. During simulation, the record will be put into alarm with a severity of SIMS and a status of SIMM_ALARM. While in simulation mode, output values, in engineering units, will be written to SIOL instead of OUT. However, the output values are never converted.
Also, while the record is in simulation mode, there will be no calls to device support during record processing.

Normally output records contain a private writeValue() routine which performs the following steps:

* If PACT is TRUE, the device support write routine is called, status is set to its return code, and readValue returns.
* Call recGblGetLinkValue to get a new value for SIMM if SIML is a DB_LINK or a CA_LINK.
* Check value of SIMM.
* If SIMM is NO, then call the device support write routine, set status to its return code, and return.
* If SIMM is YES, then call recGblPutLinkValue to write the output value from VAL or OVAL to SIOL. Set alarm status to SIMM and severity to SIMS, if SIMS is greater than zero. Set status to the return code from recGblPutLinkValue and return.
* If SIMM not one of the above, a SOFT alarm with a severity of INVALID is raised, and return status is set to -1.

==== Invalid Alarm Output Action ====

Whenever an output record is put into INVALID alarm severity, IVOA specifies an action to take. The record support process routine for each output record contains code which performs the following steps.

* If new severity is less than INVALID, then call writeValue:
* Else do the following:
** If IVOA is CONTINUE, then call writeValue.
** If IVOA is NO_OUTPUT, then do not write output.
** If IVOA is OUTPUT_IVOV, then set VAL to IVOV, call convert if necessary, and then call writeValue.
** If IVOA not one of the above, an error message is generated.

----

EPICS Record Reference Manual - 19 MAY 1998

RRM 3-14 Analog Input

2012-03-15T15:44:17Z

EricNorum:

[[RRM 3-14|EPICS Record Reference Manual]]

= ai - Analog Input =

The normal use for this record type is to obtain an analog value from hardware and then convert it to engineering units. Most device support modules obtain values from hardware. The record supports alarm limits, conversion to engineering units, smoothing, and graphics and control limits.

Two soft device modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. The first module reads values directly into VAL. The second reads values into RVAL. These values are then converted just like raw values obtained from hardware device support modules. If soft device support with a constant INP link is chosen, then the VAL field can be modified via dbPuts.

== Parameter Fields ==

The fields fall into the following groups of parameters:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scanning Parameters ===

The analog input record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read and Convert Parameters ===

These parameters determine where the record gets its input and how it converts the raw signal to engineering units. For records that obtain input from devices or that use the Raw Soft Channel device support, the device support routines will return the value of this device into the RVAL field. Unless the LINR conversion field specifies NO CONVERSION, the proper conversion algorithm will be performed and the resulting value will be placed in the VAL field.

A further explanation of these fields follows.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>[[RRM 3-14 Menu Choices#menuConvert|menuConvert]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>DOUBLE<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SMOO<TD>Smoothing Factor<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

As stated in the introduction to this chapter, what is entered in the INP field of the analog input record determines its run-time behavior. For an analog record that obtains its value from hardware, the address of the I/O card must appear in the INP field, and the name of the device support module must appear in the device type field (DTYP). See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. Be aware that the format differs between types of cards. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

The INP field can also specify a constant value, a channel access link, or a database link. When configured with a constant value, the record's VAL field is initialized with the value given to the field and the VAL field can be changed using dbPuts. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on database and channel access links.

When INP is a constant, a database link, or a channel access link either one of two soft device support modules, Raw Soft Channel or Soft Channel, must be specified in DTYP field. See [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on how these device support modules work.

==== Conversion Related Fields ====

The LINR field determines if a conversion is performed and which conversion algorithm is used to convert the raw value (RVAL). No conversions are performed if the Soft Channel device support module is used. For other records that use other device support modules, the LINR field determines what adjustments or conversions are made on the raw value. The LINR field specifies either LINEAR, NO CONVERSION, or the name of a breakpoint table, such as typeKdegC. LINEAR specifies a linear conversion; NO CONVERSION, no conversion at all; and a breakpoint table, a breakpoint conversion. Note that the EGUF, EGUL, EOFF, and ESLO fields are not used when a breakpoint table or NO CONVERSION is specified.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database for records that use LINEAR conversions. They are used by device support to calculate the values for EOFF and ESLO. See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support from EGUF and EGUL if LINR specifies LINEAR; the user must set these directly if LINR specifies SLOPE. Used only when LINR is LINEAR or SLOPE.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
<TD>SMOO<TD>A value between 1 and 0 specified by the user, with 0 meaning no smoothing and 1 meaning ultimate smoothing (in fact, the data value will never change). See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on what this field does. It is used for all records but <CODE>Soft Channel</CODE> records.
</TABLE>

The record processing routine performs the following algorithm for all records except those that use the Soft Channel device support routine. Be aware that step 3 is performed only when the record specifies LINEAR:

: 1. Val= RVAL + ROFF

: 2. Val = Val * ASLO + AOFF

If the conversion algorithm is LINEAR, the raw value is converted via the equation:

: 3. val = val * ESLO + EOFF

If the conversion is via a breakpoint table, the new value is obtained.

The next step is to apply the following smoothing algorithm:

: 4. if SMOO is 0 or INIT is True, VAL = val

: 5. else VAL = val * (1 - SMOO) + Previous_value * SMOO<blockquote>This implements a first-order infinite impulse response (IIR) digital filter with z-plane pole at SMOO. The equivalent continuous-time filter time constant τ, is<br/>τ = -T / ln(SMOO)<br/>where T is the time between record processing.</blockquote>
Since VAL is now defined, the last step is to set UDF to FALSE.

For a complete explanation on conversion parameters, see [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]]. To see how Raw Soft Channel device support uses these parameters, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog input either textually or graphically. EGU is a string of up to 16 characters describing the units that the analog input measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-14 dbCommon#Miscellaneous Fields|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm state for analog inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Hihi Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters===

These parameters are used to determine when to send monitors placed on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the appropriate deadband. If these fields have a value of zero, everytime the value changes, a monitor will be triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-Time Parameters and Simulation Mode Parameters ===

These parameters are used by the run-time code for processing the analog input. They are not configurable by the user, but many can be modified after initialization. They represent the current state of the analog input. Many of them are used to process the analog input more efficiently.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitors on the VAL field.

The PBRK field contains a pointer to the breakpoint table specified in the LINR field (if any). The LBRK field indicates the name of the last breakpoint table used (if any).

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ORAW<TD>Old Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarm Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Last Archiver Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Last Value Change Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog input in the simulation mode. See [[RRM 3-14 Common#Simulation Mode|Fields Common to Many Record Types]] for more information on these fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices#menuSimm|menuSimm]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double, all of which are used for the monitor parameters.

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read_ai() routine is defined. If either does not exist, an error message is issued and processing is terminated.

INIT is then set to TRUE.

If device support includes init_record, it is called.

==== process ====

See next section.

==== special ====

The only special processing for analog input records is SPC_LINCONV, which is invoked whenever any of the fields LINR, EGUF or EGUL is changed and LINR is LINEAR.

If the device support routine special_linconv exists, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

Fills in the values of the structure valueDes so that they refer to VAL.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-14 Common#Input Records|Input Records]] for details.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# PACT is then set to TRUE, TIME is set to tslocaltime and the return status value of readValue is checked. convert is called only if status is 0. If status is 2, then convert is not called, but status is reset to 0.
# Perform conversion if necessary: After conversions (if any), UDF is set to FALSE.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set. It also honors the alarm hysteresis factor (HYST). Thus the value must change by more than HYST before the alarm status and severity is lowered.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT to FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each analog input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw analog input value whenever read_ai is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=5>See [[RRM 3-14 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value<TD>This field is used by device support only if it obtains a value already converted to engineering units. See RVAL below.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO and EOFF. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>It is the responsibility of the device support routine to give this field a value. If the device support routine obtains a value already in engineering units, it should place the value in VAL and return a value of 2.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report (FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record (precord)

This routine is optional. If provided, it is called by the record support init_record routine.

==== get_ioint_info ====

get_ioint_info (int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== read_ai ====

read_ai(precord)

This routine must provide a new input value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call read_ai.

Because PACT is still TRUE read_ai knows that this is a request to retrieve the data obtained by the previous call. When finished, read_ai should set PACT to FALSE and return one the following values:

: 0: Success. A new raw value is placed in RVAL. convert will be called.

: 2: Success, but don't call convert. This is useful if read_ai obtains a value already converted to engineering units or in the event a hardware failure is detected.

: Other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever any of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly. The record support sets EOFF to EGUL before calling this routine, which is the very common case when RAWL is zero below.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar ADC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK or CA_LINK.

==== Soft Channel ====

This module places a value directly in VAL. read_ai always returns a value of 2, which means that no conversion will ever be attempted.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_ai calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-14 Common#Soft Input|Soft Input]] for details.

If the return status of recGblGetLinkValue is zero, then read_ai sets UDF to FALSE. The status of recGblGetLinkValue is returned.

If soft support is chosen, the following fields become meaningless: LINR, EGUF, EGUL, EOFF, ESLO, ROFF, AOFF, ASLO, and SMOO. The read_ai routine always returns a value of 2 which means don't convert.

==== Raw Soft Channel ====

This module is like the previous except that it places its value in RVAL and read_ai returns a value of 0. Thus the record processing routine will convert the raw value in the normal way.

If raw soft support is chosen, the fields EGUF and EGUL become meaningless. ESLO and EOFF can be set manually and will be used when LINR is LINEAR.

RRM 3-14 Analog Input

2012-03-15T15:36:00Z

EricNorum:

[[RRM 3-14|EPICS Record Reference Manual]]

= ai - Analog Input =

The normal use for this record type is to obtain an analog value from hardware and then convert it to engineering units. Most device support modules obtain values from hardware. The record supports alarm limits, conversion to engineering units, smoothing, and graphics and control limits.

Two soft device modules <CODE>Soft Channel</CODE> and <CODE>Raw Soft Channel</CODE> are provided to obtain input via database or channel access links or via dbPutField or dbPutLink requests. The first module reads values directly into VAL. The second reads values into RVAL. These values are then converted just like raw values obtained from hardware device support modules. If soft device support with a constant INP link is chosen, then the VAL field can be modified via dbPuts.

== Parameter Fields ==

The fields fall into the following groups of parameters:

* scan parameters
* read and convert parameters
* operator display parameters
* alarm parameters
* monitor parameters
* run-time parameters

=== Scanning Parameters ===

The analog input record has the standard fields for specifying under what circumstances the record will be processed. These fields are listed in [[RRM 3-14 dbCommon#Scan Fields|Scan Fields]]. In addition, [[RRM 3-14 Concepts#Scanning Specification|Scanning Specification]] explains how these fields are used. Note that I/O event scanning is only supported for those card types that interrupt.

=== Read and Convert Parameters ===

These parameters determine where the record gets its input and how it converts the raw signal to engineering units. For records that obtain input from devices or that use the Raw Soft Channel device support, the device support routines will return the value of this device into the RVAL field. Unless the LINR conversion field specifies NO CONVERSION, the proper conversion algorithm will be performed and the resulting value will be placed in the VAL field.

A further explanation of these fields follows.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>VAL<TD>Value Field<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>INP<TD>Input Link<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>DTYP<TD>Device Type<TD>DEVCHOICE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>LINR<TD>Type of Conversion<TD>[[RRM 3-14 Menu Choices#menuConvert|menuConvert]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>RVAL<TD>Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>Yes<TD>Yes<TR>
<TD>ROFF<TD>Raw Value Offset<TD>LONG<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUF<TD>Engineering Units Full<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>EGUL<TD>Engineering Units Low<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>AOFF<TD>Adjustment Offset<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ASLO<TD>Adjustment Slope<TD>DOUBLE<TD>Yes<TD>1<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>ESLO<TD>Slope for Linear Conversions<TD>DOUBLE<TD>Yes<TD>1<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>EOFF<TD>Offset for Linear Conversions<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>SMOO<TD>Smoothing Factor<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

==== Input Specification ====

As stated in the introduction to this chapter, what is entered in the INP field of the analog input record determines its run-time behavior. For an analog record that obtains its value from hardware, the address of the I/O card must appear in the INP field, and the name of the device support module must appear in the device type field (DTYP). See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on the format of hardware addresses. Be aware that the format differs between types of cards. You can see a list of the device support modules currently supported at the user's local site by using the dbst utility in R3.13.

The INP field can also specify a constant value, a channel access link, or a database link. When configured with a constant value, the record's VAL field is initialized with the value given to the field and the VAL field can be changed using dbPuts. See [[RRM 3-14 Concepts#Address Specification|Address Specification]] for information on database and channel access links.

When INP is a constant, a database link, or a channel access link either one of two soft device support modules, Raw Soft Channel or Soft Channel, must be specified in DTYP field. See [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter for more on how these device support modules work.

==== Conversion Related Fields ====

The LINR field determines if a conversion is performed and which conversion algorithm is used to convert the raw value (RVAL). No conversions are performed if the Soft Channel device support module is used. For other records that use other device support modules, the LINR field determines what adjustments or conversions are made on the raw value. The LINR field specifies either LINEAR, NO CONVERSION, or the name of a breakpoint table, such as typeKdegC. LINEAR specifies a linear conversion; NO CONVERSION, no conversion at all; and a breakpoint table, a breakpoint conversion. Note that the EGUF, EGUL, EOFF, and ESLO fields are not used when a breakpoint table or NO CONVERSION is specified.

<TABLE BORDER="1">
<TD>EGUF<TD rowspan=2>The user must calculate these fields when configuring the database for records that use LINEAR conversions. They are used by device support to calculate the values for EOFF and ESLO. See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on how to calculate these fields.<TR>
<TD>EGUL<TR>
<TD>AOFF<TD rowspan=2>These fields are adjustment parameters for the raw output values. They are applied to the raw output value after conversion from engineering units.<TR>
<TD>ASLO<TR>
<TD>ESLO<TD rowspan=2>Computed by device support from EGUF and EGUL if LINR specifies LINEAR; the user must set these directly if LINR specifies SLOPE. Used only when LINR is LINEAR or SLOPE.<TR>
<TD>EOFF<TR>
<TD>ROFF<TD>Deprecated. New device supports should not set this to anything other than 0. It was used to offset raw value. For backwards compatibility, it is still added to the raw value (RVAL) when value is converted.<TR>
<TD>SMOO<TD>A value between 1 and 0 specified by the user, with 0 meaning no smoothing and 1 meaning ultimate smoothing (in fact, the data value will never change). See [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]] for more information on what this field does. It is used for all records but <CODE>Soft Channel</CODE> records.
</TABLE>

The record processing routine performs the following algorithm for all records except those that use the Soft Channel device support routine. Be aware that step 3 is performed only when the record specifies LINEAR:

: 1. Val= RVAL + ROFF

: 2. Val = Val * ASLO + AOFF

If the conversion algorithm is LINEAR, the raw value is converted via the equation:

: 3. val = val * ESLO + EOFF

If the conversion is via a breakpoint table, the new value is obtained.

The next step is to apply the following smoothing algorithm:

: 4. if SMOO is 0 or INIT is True, VAL = val

: 5. else VAL = val * (1 - SMOO) + Previous_value * SMOO<br/>This implements a first-order infinite impulse response (IIR) digital filter with z-plane pole at SMOO. The equivalent continuous-time filter time constant is<br/>τ = -T / ln(SMOO)<br/>where T is the time between record processing.
Since VAL is now defined, the last step is to set UDF to FALSE.

For a complete explanation on conversion parameters, see [[RRM 3-14 Concepts#Conversion Specification|Conversion Specification]]. To see how Raw Soft Channel device support uses these parameters, see [[#Device Support For Soft Records|Device Support For Soft Records]] in this chapter.

=== Operator Display Parameters ===

These parameters are used to present meaningful data to the operator. They display the value and other parameters of the analog input either textually or graphically. EGU is a string of up to 16 characters describing the units that the analog input measures. It is retrieved by the get_units record support routine.

The HOPR and LOPR fields set the upper and lower display limits for the VAL, HIHI, HIGH, LOW, and LOLO fields. Both the get_graphic_double and get_control_double record support routines retrieve these fields.

The PREC field determines the floating point precision with which to display VAL. It is used whenever the get_precision record support routine is called.

See [[RRM 3-14 dbCommon#Miscellaneous Fields|Fields Common to All Record Types]] for more on the record name (NAME) and description (DESC) fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>EGU<TD>Engineering Units<TD>STRING [16]<TD>Yes<TD>null<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>HOPR<TD>High Operating Range<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>LOPR<TD>Low Operating Range<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>PREC<TD>Display Precision<TD>SHORT<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>NAME<TD>Record Name<TD>STRING [29]<TD>Yes<TD>0<TD>Yes<TD>No<TD>No<TD> <TR>
<TD>DESC<TD>Description<TD>STRING [29]<TD>Yes<TD>Null<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Alarm Parameters ===

The possible alarm state for analog inputs are the SCAN, READ, and limit alarms. The SCAN and READ alarms are called by the record or device support routines.

The limit alarms are configured by the user in the HIHI, LOLO, HIGH, and LOW fields using numerical values. For each of these fields, there is a corresponding severity field which can be either NO_ALARM, MINOR, or MAJOR. See [[RRM 3-14 Concepts#Alarm Specification|Alarm Specification]] for a complete explanation of alarms and these fields. [[RRM 3-14 dbCommon#Alarm Fields|Alarm Fields]] lists other fields related to alarms that are common to all record types.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>HIHI<TD>Hihi Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOLO<TD>Lolo Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HIGH<TD>High Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LOW<TD>Low Alarm Limit<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HHSV<TD>Hihi Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LLSV<TD>Lolo Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HSV<TD>High Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>LSV<TD>Low Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>Yes<TR>
<TD>HYST<TD>Alarm Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Monitor Parameters===

These parameters are used to determine when to send monitors placed on the VAL field. The monitors are sent when the value field exceeds the last monitored field by the appropriate deadband. If these fields have a value of zero, everytime the value changes, a monitor will be triggered; if they have a value of -1, everytime the record is scanned, monitors are triggered. The ADEL field is used by archive monitors and the MDEL field for all other types of monitors. See [[RRM 3-14 Concepts#Monitor Specification|Monitor Specification]] for a complete explanation of monitors.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ADEL<TD>Archive Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>MDEL<TD>Monitor, i.e. value change, Deadband<TD>DOUBLE<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

=== Run-Time Parameters and Simulation Mode Parameters ===

These parameters are used by the run-time code for processing the analog input. They are not configurable by the user, but many can be modified after initialization. They represent the current state of the analog input. Many of them are used to process the analog input more efficiently.

The ORAW field is used to decide if monitors should be triggered for RVAL when monitors are triggered for VAL. The LALM, MLST, and ALST fields are used to implement the hysteresis factors for monitors on the VAL field.

The PBRK field contains a pointer to the breakpoint table specified in the LINR field (if any). The LBRK field indicates the name of the last breakpoint table used (if any).

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>ORAW<TD>Old Raw Value<TD>LONG<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>LALM<TD>Last Alarm Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>ALST<TD>Last Archiver Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>MLST<TD>Last Value Change Monitor Trigger Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>INIT<TD>Initialize<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No<TR>
<TD>PBRK<TD>Address of Breakpoint Table<TD>NOACCESS<TD>No<TD>4<TD>No<TD>No<TD>No<TD> <TR>
<TD>LBRK<TD>Last Breakpoint<TD>SHORT<TD>No<TD>0<TD>Yes<TD>No<TD>No<TD>No
</TABLE>

The following fields are used to operate the analog input in the simulation mode. See [[RRM 3-14 Common#Simulation Mode|Fields Common to Many Record Types]] for more information on these fields.

<TABLE BORDER="1">
<TH>Field<TH>Summary<TH>Type<TH>DCT<TH>Initial<TH>Access<TH>Modify
<TH>Rec Proc Monitor<TH>PP<TR>
<TD>SIOL<TD>Simulation Value Location<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>SVAL<TD>Simulation Value<TD>DOUBLE<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIML<TD>Simulation Mode Location<TD>INLINK<TD>Yes<TD>0<TD>No<TD>No<TD>N/A<TD>No<TR>
<TD>SIMM<TD>Simulation Mode<TD>[[RRM 3-14 Menu Choices#menuSimm|menuSimm]]<TD>No<TD>0<TD>Yes<TD>Yes<TD>No<TD>No<TR>
<TD>SIMS<TD>Simulation Mode Alarm Severity<TD>[[RRM 3-14 Menu Choices#menuAlarmSevr|menuAlarmSevr]]<TD>Yes<TD>0<TD>Yes<TD>Yes<TD>No<TD>No
</TABLE>

== Record Support ==

=== Record Support Routines ===

The following are the record support routines that would be of interest to an application developer. Other routines are the get_units, get_precision, get_graphic_double, and get_control_double, all of which are used for the monitor parameters.

==== init_record ====

This routine initializes SIMM with the value of SIML if SIML type is CONSTANT link or creates a channel access link if SIML type is PV_LINK. SVAL is likewise initialized if SIOL is CONSTANT or PV_LINK.

This routine next checks to see that device support is available and a device support read_ai() routine is defined. If either does not exist, an error message is issued and processing is terminated.

INIT is then set to TRUE.

If device support includes init_record, it is called.

==== process ====

See next section.

==== special ====

The only special processing for analog input records is SPC_LINCONV, which is invoked whenever any of the fields LINR, EGUF or EGUL is changed and LINR is LINEAR.

If the device support routine special_linconv exists, it is called.

INIT is set TRUE. This causes PBRK, LBRK, and smoothing to be re-initialized.

==== get_value ====

Fills in the values of the structure valueDes so that they refer to VAL.

==== get_alarm_double ====

Sets the following values:

upper_alarm_limit = HIHI
upper_warning_limit = HIGH
lower_warning_limit = LOW
lower_alarm_limit = LOLO

=== Record Processing ===

Routine process implements the following algorithm:

# Check to see that the appropriate device support module exists. If it doesn't, an error message is issued and processing is terminated with the PACT field set to TRUE. This ensures that processes will no longer be called for this record. Thus error storms will not occur.
# readValue is called. See [[RRM 3-14 Common#Input Records|Input Records]] for details.
# If PACT has been changed to TRUE, the device support read routine has started but has not completed writing the new value. In this case, the processing routine merely returns, leaving PACT TRUE.
# PACT is then set to TRUE, TIME is set to tslocaltime and the return status value of readValue is checked. convert is called only if status is 0. If status is 2, then convert is not called, but status is reset to 0.
# Perform conversion if necessary: After conversions (if any), UDF is set to FALSE.
# Check alarms: This routine checks to see if the new VAL causes the alarm status and severity to change. If so, NSEV, NSTA and LALM are set. It also honors the alarm hysteresis factor (HYST). Thus the value must change by more than HYST before the alarm status and severity is lowered.
# Check to see if monitors should be invoked:
#* Alarm monitors are invoked if the alarm status or severity has changed.
#* Archive and value change monitors are invoked if ADEL and MDEL conditions are met.
#* Monitors for RVAL are checked whenever other monitors are invoked.
#* NSEV and NSTA are reset to 0.
# Scan forward link if necessary, set PACT and INIT to FALSE, and return.

== Device Support ==

=== Fields Of Interest To Device Support ===

Each analog input record must have an associated set of device support routines. The primary responsibility of the device support routines is to obtain a new raw analog input value whenever read_ai is called. The device support routines are primarily interested in the following fields:

<TABLE BORDER="1">
<TH>Name<TH>Summary<TH>Description<TR>
<TD>PACT<TD>Processing Active<TD rowspan=5>See [[RRM 3-14 dbCommon|Fields Common to All Record Types]] for an explanation of these fields.<TR>
<TD>DPVT<TD>Device Private<TR>
<TD>UDF<TD>VAL Undefined<TR>
<TD>NSEV<TD>New Alarm Severity<TR>
<TD>NSTA<TD>New Alarm Status<TR>
<TD>VAL<TD>Value<TD>This field is used by device support only if it obtains a value already converted to engineering units. See RVAL below.<TR>
<TD>INP<TD>Input Link<TD>This field is used by the device support routines to locate its input.<TR>
<TD>EGUF<TD>Engineering Units Full<TD rowspan=2>These fields are used to calculate ESLO and EOFF. Note that these fields correspond to the high and low hardware limits.<TR>
<TD>EGUL<TD>Engineering Unit Low<TR>
<TD>ESLO<TD>Slope<TD rowspan=2>These fields are used for linear conversions from raw to engineering units. The device support routines must calculate these fields unless they obtain values already in engineering units.<TR>
<TD>EOFF<TD>Offset<TR>
<TD>RVAL<TD>Raw Value<TD>It is the responsibility of the device support routine to give this field a value. If the device support routine obtains a value already in engineering units, it should place the value in VAL and return a value of 2.
</TABLE>

=== Device Support Routines ===

Device support consists of the following routines:

==== report ====

report (FILE fp, paddr)

Not currently used.

==== init ====

init()

This routine is called once during IOC initialization.

==== init_record ====

init_record (precord)

This routine is optional. If provided, it is called by the record support init_record routine.

==== get_ioint_info ====

get_ioint_info (int cmd,struct dbCommon *precord,IOSCANPVT *ppvt)

This routine is called by the ioEventScan system each time the record is added or deleted from an I/O event scan list. cmd has the value (0,1) if the record is being (added to, deleted from) an I/O event list. It must be provided for any device type that can use the ioEvent scanner.

==== read_ai ====

read_ai(precord)

This routine must provide a new input value. Asynchronous device support routines will return with PACT set to TRUE. If PACT is TRUE, the process routine will just return and not continue processing. When the asynchronous routine completes, it can call process which will again call read_ai.

Because PACT is still TRUE read_ai knows that this is a request to retrieve the data obtained by the previous call. When finished, read_ai should set PACT to FALSE and return one the following values:

: 0: Success. A new raw value is placed in RVAL. convert will be called.

: 2: Success, but don't call convert. This is useful if read_ai obtains a value already converted to engineering units or in the event a hardware failure is detected.

: Other: Error.

==== special_linconv ====

special_linconv(precord,after)

This routine is called whenever any of the fields LINR, EGUF, EGUL or ROFF is modified. To support linear conversion, EOFF and ESLO must be set accordingly. The record support sets EOFF to EGUL before calling this routine, which is the very common case when RAWL is zero below.

A useful formula for calculating EOFF and ESLO is this one:

EOFF = (RAWF * EGUL - RAWL * EGUF) / (RAWF - RAWL)
ESLO = (EGUF - EGUL) / (RAWF - RAWL)

Here, RAWL and RAWF are the lowest resp. highest possible raw value. For instance, a 16 bit bipolar ADC might have RAWL=-0x7fff, RAWF=0x7fff.

=== Device Support For Soft Records ===

Two soft device support modules Soft Channel and Raw Soft Channel are provided for input records not related to actual hardware devices. The INP link type must be either CONSTANT, DB_LINK or CA_LINK.

==== Soft Channel ====

This module places a value directly in VAL. read_ai always returns a value of 2, which means that no conversion will ever be attempted.

If the INP link type is constant, then the constant value is stored into VAL by init_record, and UDF is set to FALSE. If the INP link type is PV_LINK, then dbCaAddInlink is called by init_record.

read_ai calls recGblGetLinkValue to read the current value of VAL. See [[RRM 3-14 Common#Soft Input|Soft Input]] for details.

If the return status of recGblGetLinkValue is zero, then read_ai sets UDF to FALSE. The status of recGblGetLinkValue is returned.

If soft support is chosen, the following fields become meaningless: LINR, EGUF, EGUL, EOFF, ESLO, ROFF, AOFF, ASLO, and SMOO. The read_ai routine always returns a value of 2 which means don't convert.

==== Raw Soft Channel ====

This module is like the previous except that it places its value in RVAL and read_ai returns a value of 0. Thus the record processing routine will convert the raw value in the normal way.

If raw soft support is chosen, the fields EGUF and EGUL become meaningless. ESLO and EOFF can be set manually and will be used when LINR is LINEAR.

How do I get EPICS applications to work with a Mac OS X firewall

2011-10-05T16:19:28Z

EricNorum:

For OS X 10.6 (Snow Leopard) and up
*Start the System Preferences application
*Select the "Security & Privacy" pane
*Select the "Firewall" tab
*Open the lock to allow changes
*Ensure that the firewall is on
*Click the "Advanced…" button
*Add your EPICS applications (e.g. caRepeater, caget, camonitor, caput, StripTool, edm, soft IOCs, etc.) to the list and set the firewall to "Allow incoming connections" to them

How do I get EPICS applications to work with a Mac OS X firewall

2011-10-05T16:18:46Z

EricNorum:

For OS X 10.6 (Snow Leopard) and up
*Start the System Preferences application
*Select the "Security & Privacy" pane
*Select the "Firewall" tab
*Open the lock to allow changes
*Ensure that the firewall is on
*Click the 'Advanced…" button
*Add your EPICS applications (e.g. caRepeater, caget, camonitor, caput, StripTool, edm, soft IOCs, etc.) to the list and set the firewall to "Allow incoming connections" to them

How do I get EPICS applications to work with a Mac OS X firewall?

2011-10-05T16:17:21Z

EricNorum:

These instructions apply to OS X 10.6 and higher

* Start the System Preferences application
* Select the "Security & Privacy" pane
* Select the "Firewall" tab
* Open the lock to allow changes
* Ensure that the firewall is on
* Click the 'Advanced…" button
* Add your EPICS applications (e.g. caRepeater, caget, camonitor, caput, StripTool, edm, soft IOCs, etc.) to the list and set the firewall to "Allow incoming connections" to them

HowTo Documents

2011-10-05T16:14:24Z

EricNorum: /* Applications */

This is a directory of various How-To documents written by members of the EPICS collaboration. Contributions to this page are most welcome!

=== EPICS Base on Different Architectures and Operating Systems ===

* [http://www.aps.anl.gov/epics/base/RTEMS/tutorial/ Getting Started with EPICS on RTEMS]
* [[HowToPC104|Getting Started with R3.14.7 on a PC104 running Linux]]
* [[How To Port EPICS to a new OS/Architecture]]
* [[How To Use Posix Thread Priority Scheduling under Linux]]

=== Drivers and Device Support ===

* [http://www.aps.anl.gov/epics/modules/soft/asyn/HowToDoSerial_StreamDevice.html How To Do Serial (using Asyn Driver and StreamDevice)]
* [http://www.aps.anl.gov/epics/modules/soft/asyn/R4-15/HowToDoSerial/tutorial.pdf How To Do Serial (using Asyn Driver and devGPIB)]
* [http://www.aps.anl.gov/epics/modules/soft/asyn/BeginnerGuideToASYN-VXI11.pdf Beginners Guide to using VXI-11 (with Asyn Driver)]
* [[How to make your EPICS driver operating system independent]]
* [[How To Write Device Support that uses Asyn Driver]] ''(Incomplete!)''
* [[How to use GPIB ports with linux-gpib and StreamDevice]]

=== Applications ===

* [[Common Database patterns]]
* [[How To Install Channel Archiver On Scientific Linux]]
* [[What PV Save and Restore Tools are available]]
* [[How to Add a New Breakpoint Table]]
* [["Best Practice" Guidelines]]
* [[How do I get EPICS applications to work with a Mac OS X firewall?]]

=== Infrastructure and Other Stuff ===

* [[How To Set Up a Linux Box as an IOC Boot Server]]
* [[How To Set Up a Mirror of the EPICS Web Site]]
* [[How to Set Up a Soft IOC Framework on Linux]]
* [[How to Set Up Console Access and Logging for VME and Soft IOCs]]
* [[How to Set Up NAL (Nagios Alarm Handler) to monitor an EPICS network]]

=== Collaboration Stuff ===

* [[How to run an EPICS Collaboration Meeting]]

"Best Practice" Guidelines

2011-08-24T22:59:44Z

EricNorum:

== "Best Practice" Guidelines for Developers ==
This document presents some guidelines that have been found useful. Please add your own suggestions!

=== Support Modules ===
* If your IOC application source directory contains '.c' files you should '''definitely''' consider moving them to a support module (either existing or new). A big problem in the past has been the proliferation of similar or identical '.c' files among multiple IOC applications. Help stamp out this practice now! To a lesser degree you should consider doing the same for any sequence programs in your application although these tend to be much more application-specific and thus impractical to move to a support module.
* Use <tt>/''path_to_base_bin''/makeBaseApp.pl -t support</tt> to create a new support module. If you're writing a new message-based instrument support module <tt>/''path_to_asyn_bin''/makeSupport.pl -t streamSCPI</tt> is a good place to start.
* Nothing within the support 'modules' directory tree should be an 'App'. Nothing within the 'ioc' applications directory tree should be anything but an 'App'.

=== Device Support ===
* All message-based devices (with any expected lifetime) should be converted to use ASYN. If you are starting from existing devGpib support see [http://www.aps.anl.gov/epics/modules/soft/asyn/R4-10/gpibCoreConversion/conversionNotes.html these guidelines for conversion]. If you are starting on brand-new support see [http://www.aps.anl.gov/epics/modules/soft/asyn/R4-10/HowToDoSerial/tutorial.html these notes] or have a look at the [http://epics.web.psi.ch/software/streamdevice/ stream device support].
* Support for a particular device should be in its own support module.

=== Database Files ===
* Support modules and IOC applications should install all .db files into their <top>/db directory. When an application uses a .db file from a support module that file may be copied from the support module <top>/db directory to the IOC application <top>/db directory. This is done by adding lines like<br><tt>DB_INSTALLS += $(ASYN)/db/asynRecord.db</tt><br>to the application <top>/''appName''/Db/Makefile. This allows all the .db files needed by an application to be found in a single location.
* Template files that are part of support modules do not need to be copied to your application Db source directory. The build system knows to look in support module db directories for template files.

=== Application Makefile ===
* Add support module .dbd files to your application using the Makefile<br><tt>''xxxxxx''_DBD += ''yyyyy''.dbd</tt><br>mechanism.

=== st.cmd ===
* Expansion of substitution/template files should be performed at build-time on the host rather than at application startup on the IOC.
* '''vxWorks only''' --- The '''ld''' command to load the application executable code must not use vxWorks shell redirection since this may break the commands later in the script. Change lines like<br><tt>ld < libpm.munch</tt><br>into<br><tt>ld 0,0, "libpm.munch"</tt>

=== Autosave/restore ===
* The autosave/restore support module provides several diagnostic PVs. One of the most important of these is a PV which indicates the success or failure of autosave operations. An infrastructure monitoring system can check this PV and provide warnings about problems. All applications which use autosave/restore should include these PVs.<br>To add the PVs to an application:
# Add the following line to the <top>/''appName''/Db/Makefile<br><tt>DB_INSTALLS += $(AUTOSAVE)/asApp/Db/save_restoreStatus.db</tt>
# If you're using the IOC shell, add the following lines to the st.cmd script (before iocInit)<br><tt>save_restoreSet_status_prefix($(IOC))<br>dbLoadRecords(db/save_restoreStatus.db,P=$(IOC))</tt><br>If you're using the vxWorks shell to read the startup script the command must either specify the IOC name explicitly<br><tt>save_restoreSet_status_prefix("iocxxxxx")<br>dbLoadRecords("db/save_restoreStatus.db","P=iocxxxxx")</tt><br>or use iocshCmd to parse the lines<br><tt>iocshCmd("save_restoreSet_status_prefix($(IOC))")<br>iocshCmd("dbLoadRecords(db/save_restoreStatus.db,P=$(IOC))")</tt>

"Best Practice" Guidelines

2011-08-24T22:59:07Z

EricNorum:

HowTo Documents

2011-08-24T22:31:06Z

EricNorum: /* Applications */

This is a directory of various How-To documents written by members of the EPICS collaboration. Contributions to this page are most welcome!

=== EPICS Base on Different Architectures and Operating Systems ===

* [http://www.aps.anl.gov/epics/base/RTEMS/tutorial/ Getting Started with EPICS on RTEMS]
* [[HowToPC104|Getting Started with R3.14.7 on a PC104 running Linux]]
* [[How To Port EPICS to a new OS/Architecture]]

=== Drivers and Device Support ===

* [http://www.aps.anl.gov/epics/modules/soft/asyn/HowToDoSerial_StreamDevice.html How To Do Serial (using Asyn Driver and StreamDevice)]
* [http://www.aps.anl.gov/epics/modules/soft/asyn/R4-15/HowToDoSerial/tutorial.pdf How To Do Serial (using Asyn Driver and devGPIB)]
* [http://www.aps.anl.gov/epics/modules/soft/asyn/BeginnerGuideToASYN-VXI11.pdf Beginners Guide to using VXI-11 (with Asyn Driver)]
* [[How to make your EPICS driver operating system independent]]
* [[How To Write Device Support that uses Asyn Driver]] ''(Incomplete!)''
* [[How to use GPIB ports with linux-gpib and StreamDevice]]

=== Applications ===

* [[Common Database patterns]]
* [[How To Install Channel Archiver On Scientific Linux]]
* [[What PV Save and Restore Tools are available]]
* [[How to Add a New Breakpoint Table]]
* [["Best Practice" Guidelines]]

=== Infrastructure and Other Stuff ===

* [[How To Set Up a Linux Box as an IOC Boot Server]]
* [[How To Set Up a Mirror of the EPICS Web Site]]
* [[How to Set Up a Soft IOC Framework on Linux]]
* [[How to Set Up Console Access and Logging for VME and Soft IOCs]]
* [[How to Set Up NAL (Nagios Alarm Handler) to monitor an EPICS network]]

=== Collaboration Stuff ===

* [[How to run an EPICS Collaboration Meeting]]

How to make your EPICS driver operating system independent

2009-01-30T15:44:18Z

EricNorum:

=How to make your EPICS driver operating system independent=

'''W. Eric Norum et. al.'''

==Introduction==

The following table shows the changes made to some existing drivers to allow them to be used on systems other than vxWorks. Note that it is a very preliminary start at a set of conversion instructions. There's still no `cookbook' document to guide you, but many drivers can be converted without doing much more than applying the translations shown. A technique that I've found works well is to first change all the <code>#include</code> statements that mention vxWorks header files to their OSI equivalents, then enter a compile-edit cycle until all compile errors have been eliminated.

==Conversions==

{| border="1" cellpadding="3"
! align="CENTER" | '''vxWorks'''
! align="CENTER" | '''OSI'''
|-
| <code>#include <vxWorks.h></code>
|-
| <code>#include <stdlib.h></code>
| <code>#include <epicsStdlib.h></code>
|-
| <code>#include <stdio.h></code>
| <code>#include <epicsStdioRedirect.h></code>
|-
| <code>#include <iosLib.h></code>
|-
| <code>#include <taskLib.h></code>
| <code>#include <epicsThread.h></code>
|-
| <code>#include <memLib.h></code>
|-
| <code>#include <rebootLib.h></code>
| <code>#include <epicsExit.h></code>
|-
| <code>#include <intLib.h></code>
| <code>#include <epicsInterrupt.h></code>
|-
| <code>#include <wdLib.h></code>
| <code>#include <epicsTimer.h></code>
|-
| <code>#include <lstLib.h></code>
| <code>#include <ellLib.h></code>
|-
| <code>#include <vme.h></code>
| <code>#include <devLib.h></code>
|-
| <code>#include <sysLib.h></code>
|-
| <code>#include <iv.h></code>
|-
|
| <code>#include <epicsExport.h></code>
<code>#include <iocsh.h></code>
|-
| <code>ERROR</code>
| <code>-1</code>
|-
| <code>OK</code>
| <code>0</code>
|-
| valign="TOP" | <code>#include <semLib.h></code>
SEM_ID flag = semBCreate(SEM_Q_PRIORITY, SEM_EMPTY);
semGive(flag);
semTake(flag, WAIT_FOREVER);
| valign="TOP" | <code>#include <epicsEvent.h></code>
epicsEventId flag = epicsEventMustCreate(epicsEventEmpty);
epicsEventSignal(flag);
epicsEventMustWait(flag);
|-
| valign="TOP" | <code>#include <semLib.h></code>
SEM_ID Lock = semMCreate(SEM_Q_PRIORITY);
semTake(Lock, WAIT_FOREVER);
semGive(Lock);
| valign="TOP" | <code>#include <epicsMutex.h></code>
epicsMutexId Lock = epicsMutexMustCreate();
epicsMutexLock(Lock);
epicsMutexUnlock(Lock);
|-
| valign="TOP" | <code>taskDelay(1)</code>
| valign="TOP" | To generate a `short' delay:
epicsThreadSleep(0.001)
This works because the operating system specific layer ensures a delay of at least one system clock tick for epicsThreadSleep arguments greater than 0.
|-
| valign="TOP" | <code>taskDelay(30)</code>
| valign="TOP" | Much old code assumes a 60 Hz vxWorks system clock. On such systems the equivalent for the command shown would be:
epicsThreadSleep(0.5)
Of course, other code may assumes a 50 Hz or 100 Hz system clock rate. You can
find out what your system clock rate is using epicsThreadSleepQuantum(), which returns the clock period in seconds.
|-
| <code>taskSuspend(0)</code>
| <code>epicsThreadSuspendSelf()</code>
|-
| valign="TOP" | <pre>intConnect(INUM_TO_IVEC(irqVector),
irqHandler, pLink)</pre>
| valign="TOP" | <pre>devConnectInterruptVME(irqVector,
irqHandler, pLink)</pre>
|-
| <code>sysIntEnable(IrqLevel)</code>
| <code>devEnableInterruptLevelVME(IrqLevel)</code>
|-
| valign="TOP" | <pre>sysBusToLocalAdrs(VME_AM_SUP_SHORT_IO,
(char*)CardAddress, (char**)&ErLink[Card].pEr)</pre>
| valign="TOP" | <pre>devRegisterAddress("apsEr", atVMEA16,
CardAddress, 0x40, (void*)&ErLink[Card].pEr)</pre>
|-
| <code>vxMemProbe(pReg, READ, sizeof(short), &value)</code>
| <code>devReadProbe(sizeof(short), pReg, &value)</code>
|-
| <code>vxMemProbe(pReg,WRITE,sizeof(short), &value)</code>
| <code>devWriteProbe(sizeof(short), pReg, &value)</code>
|-
| <code>key = intLock()</code>
| <code>key = epicsInterruptLock()</code>
|-
| <code>intUnlock(key)</code>
| <code>epicsInterruptUnlock(key)</code>
|-
| valign="TOP" | <pre>#include <wdLib.h>
#include <sysLib.h>
WDOG_ID wd = wdCreate();
wdStart(wd, delay * sysClkRateGet(),
(FUNCPTR) wdCallback, (int) arg);</pre>
| valign="TOP" | <pre>#include <epicsTimer.h>
#include <epicsThread.h>
epicsTimerQueueId tq = epicsTimerQueueAllocate(1,
epicsThreadPriorityScanLow);
epicsTimerId wd = epicsTimerQueueCreateTimer(tq,
wdCallback, (void *) arg);
epicsTimerStartDelay(wd, delay);</pre>

If the watchdog timer is being used only to invoke timed callbacks it may be possible to eliminate the watchdog timer completely and just use callbackRequestDelayed instead. If the timed callbacks are being used only for invoking record processing things are even simpler – just use callbackRequestProcessCallbackDelayed.
|-
| <code>rebootHookAdd((FUNCPTR)ErRebootFunc)</code>
| <code>epicsAtExit(ErRebootFunc, NULL)</code>
|-
| valign="TOP" | <pre>#include <fast_lock.h>
FAST_LOCK lock;
FASTLOCKINIT(&mzconf[card].lock);
FASTLOCKFREE(&mzconf[card].lock);
FASTLOCK(&mzconf[card].lock);
FASTUNLOCK(&mzconf[card].lock);</pre>
| valign="TOP" | You'll have to use your judgement here. If the section of code being protected is quick (less than a few microseconds) it's reasonable to simply disable interrupts while the code is active. In this case you can remove the 'lock' variable and the init/free operations and then add a local 'key' variable and replace the lock/unlock operations with epicsInterruptLock/Unlock operations. If the section of code being protected is longer you'll have to convert the FASTLOCK to an EPICS mutex.
|-
| <code>taskSpawn(...)</code>
| <code>epicsThreadCreate(...)</code>
You should consider rewriting the driver to use the "worker thread" environment provided by the ASYN package. This is likely to result in a shorter, simpler, and more robust driver.
|}

==Some other changes==

* Some R3.13 record support database definitions explicitly mention all fields rather than including dbCommon.dbd. This can cause problems with FAST_LOCK. The solution is to add <code>include "dbCommon.dbd"</code> at the beginning of the file in question and to remove all entries for the fields provided by dbCommon.dbd.
* You should set up IOC shell command registrations for all `configure' functions and for any other commands you may need to call from the IOC shell. Here's an example of a fairly complex configuration command:
<nowiki>
/*
* IOC shell command registration
*/
#include <iocsh.h>
static const iocshArg vtr10012ConfigArg0 = { "card",iocshArgInt};
static const iocshArg vtr10012ConfigArg1 = { "VME A16 offset",iocshArgInt};
static const iocshArg vtr10012ConfigArg2 = { "VME memory offset",iocshArgInt};
static const iocshArg vtr10012ConfigArg3 = { "interrupt vector",iocshArgInt};
static const iocshArg vtr10012ConfigArg4 = { "interrupt level",iocshArgInt};
static const iocshArg vtr10012ConfigArg5 = { "use DMA",iocshArgInt};
static const iocshArg vtr10012ConfigArg6 = { "nchannels",iocshArgInt};
static const iocshArg vtr10012ConfigArg7 = { "kilosamplesPerChan",iocshArgInt};
static const iocshArg *vtr10012ConfigArgs[] = {
&vtr10012ConfigArg0, &vtr10012ConfigArg1, &vtr10012ConfigArg2,
&vtr10012ConfigArg3, &vtr10012ConfigArg4, &vtr10012ConfigArg5,
&vtr10012ConfigArg6,&vtr10012ConfigArg7};
static const iocshFuncDef vtr10012ConfigFuncDef =
{"vtr10012Config",8,vtr10012ConfigArgs};
static void vtr10012ConfigCallFunc(const iocshArgBuf *args)
{
vtr10012Config(args[0].ival, args[1].ival, args[2].ival,
args[3].ival, args[4].ival, args[5].ival,
args[6].ival, args[7].ival);
}

/*
* This routine is called before multitasking has started, so there's
* no race condition in the test/set of firstTime.
*/
static void
drvVtr10012RegisterCommands(void)
{
static int firstTime = 1;
if (firstTime) {
iocshRegister(&vtr10012ConfigFuncDef,vtr10012ConfigCallFunc);
firstTime = 0;
}
}
epicsExportRegistrar(drvVtr10012RegisterCommands);</nowiki>
You must also provide a corresponding registrar statement in a <code>.dbd</code> file:
registrar(drvVtr10012RegisterCommands)
* If your driver provides functions that are referred to by name from database files you must:
** <code>#include <registryFunction.h></code>
** Add an <code>epicsExportFunction()</code> statement for each such function.
** Add a corresponding <code>function</code> statement in a <code>.dbd</code> file.

==Additional Information==

The procedure for converting a support module from R3.13 to R3.14 is described in the [http://www.aps.anl.gov/epics/base/R3-14/8-docs/ConvertingR3.13AppsToR3.14.html Converting R3.13 Apps to R3.14] document.

How to make your EPICS driver operating system independent

2009-01-30T14:50:03Z

EricNorum:

=How to make your EPICS driver operating system independent=

'''W. Eric Norum et. al.'''

==Introduction==

The following table shows the changes made to some existing drivers to allow them to be used on systems other than vxWorks. Note that it is a very preliminary start at a set of conversion instructions. There's still no `cookbook' document to guide you, but many drivers can be converted without doing much more than applying the translations shown. A technique that I've found works well is to first change all the <code>#include</code> statements that mention vxWorks header files to their OSI equivalents, then enter a compile-edit cycle until all compile errors have been eliminated.

==Conversions==

{| border="1" cellpadding="3"
! align="CENTER" | '''vxWorks'''
! align="CENTER" | '''OSI'''
|-
| <code>#include <vxWorks.h></code>
|-
| <code>#include <stdlib.h></code>
| <code>#include <epicsStdlib.h></code>
|-
| <code>#include <stdio.h></code>
| <code>#include <epicsStdioRedirect.h></code>
|-
| <code>#include <iosLib.h></code>
|-
| <code>#include <taskLib.h></code>
| <code>#include <epicsThread.h></code>
|-
| <code>#include <memLib.h></code>
|-
| <code>#include <rebootLib.h></code>
| <code>#include <epicsExit.h></code>
|-
| <code>#include <intLib.h></code>
| <code>#include <epicsInterrupt.h></code>
|-
| <code>#include <wdLib.h></code>
| <code>#include <epicsTimer.h></code>
|-
| <code>#include <lstLib.h></code>
| <code>#include <ellLib.h></code>
|-
| <code>#include <vme.h></code>
| <code>#include <devLib.h></code>
|-
| <code>#include <sysLib.h></code>
|-
| <code>#include <iv.h></code>
|-
|
| <code>#include <epicsExport.h></code>
<code>#include <iocsh.h></code>
|-
| <code>ERROR</code>
| <code>-1</code>
|-
| <code>OK</code>
| <code>0</code>
|-
| valign="TOP" | <code>#include <semLib.h></code>
SEM_ID flag = semBCreate(SEM_Q_PRIORITY, SEM_EMPTY);
semGive(flag);
semTake(flag, WAIT_FOREVER);
| valign="TOP" | <code>#include <epicsEvent.h></code>
epicsEventId flag = epicsEventMustCreate(epicsEventEmpty);
epicsEventSignal(flag);
epicsEventMustWait(flag);
|-
| valign="TOP" | <code>#include <semLib.h></code>
SEM_ID Lock = semMCreate(SEM_Q_PRIORITY);
semTake(Lock, WAIT_FOREVER);
semGive(Lock);
| valign="TOP" | <code>#include <epicsMutex.h></code>
epicsMutexId Lock = epicsMutexMustCreate();
epicsMutexLock(Lock);
epicsMutexUnlock(Lock);
|-
| valign="TOP" | <code>taskDelay(1)</code>
| valign="TOP" | To generate a `short' delay:
epicsThreadSleep(0.001)
This works because the operating system specific layer ensures a delay of at least one system clock tick for epicsThreadSleep arguments greater than 0.
|-
| valign="TOP" | <code>taskDelay(30)</code>
| valign="TOP" | Much old code assumes a 60 Hz vxWorks system clock. On such systems the equivalent for the command shown would be:
epicsThreadSleep(0.5)
Of course, other code may assumes a 50 Hz or 100 Hz system clock rate. You can
find out what your system clock rate is using epicsThreadSleepQuantum(), which returns the clock period in seconds.
|-
| <code>taskSuspend(0)</code>
| <code>epicsThreadSuspendSelf()</code>
|-
| valign="TOP" | <pre>intConnect(INUM_TO_IVEC(irqVector),
irqHandler, pLink)</pre>
| valign="TOP" | <pre>devConnectInterruptVME(irqVector,
irqHandler, pLink)</pre>
|-
| <code>sysIntEnable(IrqLevel)</code>
| <code>devEnableInterruptLevelVME(IrqLevel)</code>
|-
| valign="TOP" | <pre>sysBusToLocalAdrs(VME_AM_SUP_SHORT_IO,
(char*)CardAddress, (char**)&ErLink[Card].pEr)</pre>
| valign="TOP" | <pre>devRegisterAddress("apsEr", atVMEA16,
CardAddress, 0x40, (void*)&ErLink[Card].pEr)</pre>
|-
| <code>vxMemProbe(pReg, READ, sizeof(short), &value)</code>
| <code>devReadProbe(sizeof(short), pReg, &value)</code>
|-
| <code>vxMemProbe(pReg,WRITE,sizeof(short), &value)</code>
| <code>devWriteProbe(sizeof(short), pReg, &value)</code>
|-
| <code>key = intLock()</code>
| <code>key = epicsInterruptLock()</code>
|-
| <code>intUnlock(key)</code>
| <code>epicsInterruptUnlock(key)</code>
|-
| valign="TOP" | <pre>#include <wdLib.h>
#include <sysLib.h>
WDOG_ID wd = wdCreate();
wdStart(wd, delay * sysClkRateGet(),
(FUNCPTR) wdCallback, (int) arg);</pre>
| valign="TOP" | <pre>#include <epicsTimer.h>
#include <epicsThread.h>
epicsTimerQueueId tq = epicsTimerQueueAllocate(1,
epicsThreadPriorityScanLow);
epicsTimerId wd = epicsTimerQueueCreateTimer(tq,
wdCallback, (void *) arg);
epicsTimerStartDelay(wd, delay);</pre>

If the watchdog timer is being used only to invoke timed callbacks it may be possible to eliminate the watchdog timer completely and just use callbackRequestDelayed instead.
|-
| <code>rebootHookAdd((FUNCPTR)ErRebootFunc)</code>
| <code>epicsAtExit(ErRebootFunc, NULL)</code>
|-
| valign="TOP" | <pre>#include <fast_lock.h>
FAST_LOCK lock;
FASTLOCKINIT(&mzconf[card].lock);
FASTLOCKFREE(&mzconf[card].lock);
FASTLOCK(&mzconf[card].lock);
FASTUNLOCK(&mzconf[card].lock);</pre>
| valign="TOP" | You'll have to use your judgement here. If the section of code being protected is quick (less than a few microseconds) it's reasonable to simply disable interrupts while the code is active. In this case you can remove the 'lock' variable and the init/free operations and then add a local 'key' variable and replace the lock/unlock operations with epicsInterruptLock/Unlock operations. If the section of code being protected is longer you'll have to convert the FASTLOCK to an EPICS mutex.
|-
| <code>taskSpawn(...)</code>
| <code>epicsThreadCreate(...)</code>
You should consider rewriting the driver to use the "worker thread" environment provided by the ASYN package. This is likely to result in a shorter, simpler, and more robust driver.
|}

==Some other changes==

* Some R3.13 record support database definitions explicitly mention all fields rather than including dbCommon.dbd. This can cause problems with FAST_LOCK. The solution is to add <code>include "dbCommon.dbd"</code> at the beginning of the file in question and to remove all entries for the fields provided by dbCommon.dbd.
* You should set up IOC shell command registrations for all `configure' functions and for any other commands you may need to call from the IOC shell. Here's an example of a fairly complex configuration command:
<nowiki>
/*
* IOC shell command registration
*/
#include <iocsh.h>
static const iocshArg vtr10012ConfigArg0 = { "card",iocshArgInt};
static const iocshArg vtr10012ConfigArg1 = { "VME A16 offset",iocshArgInt};
static const iocshArg vtr10012ConfigArg2 = { "VME memory offset",iocshArgInt};
static const iocshArg vtr10012ConfigArg3 = { "interrupt vector",iocshArgInt};
static const iocshArg vtr10012ConfigArg4 = { "interrupt level",iocshArgInt};
static const iocshArg vtr10012ConfigArg5 = { "use DMA",iocshArgInt};
static const iocshArg vtr10012ConfigArg6 = { "nchannels",iocshArgInt};
static const iocshArg vtr10012ConfigArg7 = { "kilosamplesPerChan",iocshArgInt};
static const iocshArg *vtr10012ConfigArgs[] = {
&vtr10012ConfigArg0, &vtr10012ConfigArg1, &vtr10012ConfigArg2,
&vtr10012ConfigArg3, &vtr10012ConfigArg4, &vtr10012ConfigArg5,
&vtr10012ConfigArg6,&vtr10012ConfigArg7};
static const iocshFuncDef vtr10012ConfigFuncDef =
{"vtr10012Config",8,vtr10012ConfigArgs};
static void vtr10012ConfigCallFunc(const iocshArgBuf *args)
{
vtr10012Config(args[0].ival, args[1].ival, args[2].ival,
args[3].ival, args[4].ival, args[5].ival,
args[6].ival, args[7].ival);
}

/*
* This routine is called before multitasking has started, so there's
* no race condition in the test/set of firstTime.
*/
static void
drvVtr10012RegisterCommands(void)
{
static int firstTime = 1;
if (firstTime) {
iocshRegister(&vtr10012ConfigFuncDef,vtr10012ConfigCallFunc);
firstTime = 0;
}
}
epicsExportRegistrar(drvVtr10012RegisterCommands);</nowiki>
You must also provide a corresponding registrar statement in a <code>.dbd</code> file:
registrar(drvVtr10012RegisterCommands)
* If your driver provides functions that are referred to by name from database files you must:
** <code>#include <registryFunction.h></code>
** Add an <code>epicsExportFunction()</code> statement for each such function.
** Add a corresponding <code>function</code> statement in a <code>.dbd</code> file.

==Additional Information==

The procedure for converting a support module from R3.13 to R3.14 is described in the [http://www.aps.anl.gov/epics/base/R3-14/8-docs/ConvertingR3.13AppsToR3.14.html Converting R3.13 Apps to R3.14] document.

How to make your EPICS driver operating system independent

2006-10-19T16:37:27Z

EricNorum: /* Some other changes */

=How to make your EPICS driver operating system independent=

'''W. Eric Norum'''

==Introduction==

The following table shows the changes made to some existing drivers to allow them to be used on systems other than vxWorks. Note that it is a very preliminary start at a set of conversion instructions. There's still no `cookbook' document to guide you, but many drivers can be converted without doing much more than applying the translations shown. A technique that I've found works well is to first change all the <code>#include</code> statements that mention vxWorks header files to their OSI equivalents, then enter a compile-edit cycle until all compile errors have been eliminated.

==Conversions==

{| border="1" cellpadding="3"
! align="CENTER" | '''vxWorks'''
! align="CENTER" | '''OSI'''
|-
| <code>#include <vxWorks.h></code>
|-
| <code>#include <stdlib.h></code>
| <code>#include <epicsStdlib.h></code>
|-
| <code>#include <stdio.h></code>
| <code>#include <epicsStdioRedirect.h></code>
|-
| <code>#include <iosLib.h></code>
|-
| <code>#include <taskLib.h></code>
| <code>#include <epicsThread.h></code>
|-
| <code>#include <memLib.h></code>
|-
| <code>#include <rebootLib.h></code>
| <code>#include <epicsExit.h></code>
|-
| <code>#include <intLib.h></code>
| <code>#include <epicsInterrupt.h></code>
|-
| <code>#include <lstLib.h></code>
|-
| <code>#include <vme.h></code>
| <code>#include <devLib.h></code>
|-
| <code>#include <sysLib.h></code>
|-
| <code>#include <iv.h></code>
|-
|
| <code>#include <epicsExport.h></code>
<code>#include <iocsh.h></code>
|-
| <code>ERROR</code>
| <code>-1</code>
|-
| <code>OK</code>
| <code>0</code>
|-
| valign="TOP" | <code>#include <semLib.h></code>
SEM_ID flag = semBCreate(SEM_Q_PRIORITY, SEM_EMPTY);
semGive(flag);
semTake(flag, WAIT_FOREVER);
| valign="TOP" | <code>#include <epicsEvent.h></code>
epicsEventId flag = epicsEventMustCreate(epicsEventEmpty);
epicsEventSignal(flag);
epicsEventMustWait(flag);
|-
| valign="TOP" | <code>#include <semLib.h></code>
SEM_ID Lock = semMCreate(SEM_Q_PRIORITY);
semTake(Lock, WAIT_FOREVER);
semGive(Lock);
| valign="TOP" | <code>#include <epicsMutex.h></code>
epicsMutexId Lock = epicsMutexMustCreate();
epicsMutexLock(Lock);
epicsMutexUnlock(Lock);
|-
| valign="TOP" | <code>taskDelay(1)</code>
| valign="TOP" | To generate a `short' delay:
epicsThreadSleep(0.001)
This works because the operating system specific layer ensures a delay of at least one system clock tick for epicsThreadSleep arguments greater than 0.
|-
| valign="TOP" | <code>taskDelay(30)</code>
| valign="TOP" | Much old code assumes a 60 Hz vxWorks system clock. On such systems the equivalent for the command shown would be:
epicsThreadSleep(0.5)
Of course, other code may assumes a 50 Hz or 100 Hz system clock rate. You can
find out what your system clock rate is using epicsThreadSleepQuantum(), which returns the clock period in seconds.
|-
| <code>taskSuspend(0)</code>
| <code>epicsThreadSuspendSelf()</code>
|-
| valign="TOP" | <code>intConnect(INUM_TO_IVEC(IrqVector), IrqHandler, pLink)</code>
| valign="TOP" | <code>devConnectInterruptVME(IrqVector, IrqHandler, pLink)</code>
|-
| <code>sysIntEnable(IrqLevel)</code>
| <code>devEnableInterruptLevelVME(IrqLevel)</code>
|-
| valign="TOP" | <code>sysBusToLocalAdrs(VME_AM_SUP_SHORT_IO, (char*)CardAddress, (char**)&ErLink[Card].pEr)</code>
| valign="TOP" | <code>devRegisterAddress("apsEr", atVMEA16, CardAddress, 0x40, (void*)&ErLink[Card].pEr)</code>
|-
| <code>vxMemProbe(pReg, READ, sizeof(short), &value)</code>
| <code>devReadProbe(sizeof(short), pReg, &value)</code>
|-
| <code>vxMemProbe(pReg,WRITE,sizeof(short), &value)</code>
| <code>devWriteProbe(sizeof(short), pReg, &value)</code>
|-
| <code>key = intLock()</code>
| <code>key = epicsInterruptLock()</code>
|-
| <code>intUnlock(key)</code>
| <code>epicsInterrupUnlock(key)</code>
|-
| <code>rebootHookAdd((FUNCPTR)ErRebootFunc)</code>
| <code>epicsAtExit(ErRebootFunc, NULL)</code>
|-
| valign="TOP" | <code>#include <fast_lock.h></code>
FAST_LOCK lock;
FASTLOCKINIT(&mzconf[card].lock);
FASTLOCKFREE(&mzconf[card].lock);
FASTLOCK(&mzconf[card].lock);
FASTUNLOCK(&mzconf[card].lock);
| valign="TOP" | You'll have to use your judgement here. If the section of code being protected is quick (less than a few microseconds) it's reasonable to simply disable interrupts while the code is active. In this case you can remove the 'lock' variable and the init/free operations and then add a local 'key' variable and replace the lock/unlock operations with epicsInterruptLock/Unlock operations. If the section of code being protected is longer you'll have to convert the FASTLOCK to an EPICS mutex.
|-
| <code>taskSpawn(...)</code>
| <code>epicsThreadCreate(...)</code>
You should consider rewriting the driver to use the "worker thread" environment provided by the ASYN package. This is likely to result in a shorter, simpler, and more robust driver.
|}

==Some other changes==

* Some R3.13 record support database definitions explicitly mention all fields rather than including dbCommon.dbd. This can cause problems with FAST_LOCK. The solution is to add <code>include "dbCommon.dbd"</code> at the beginning of the file in question and to remove all entries for the fields provided by dbCommon.dbd.
* You should set up IOC shell command registrations for all `configure' functions and for any other commands you may need to call from the IOC shell. Here's an example of a fairly complex configuration command:
<nowiki>
/*
* IOC shell command registration
*/
#include <iocsh.h>
static const iocshArg vtr10012ConfigArg0 = { "card",iocshArgInt};
static const iocshArg vtr10012ConfigArg1 = { "VME A16 offset",iocshArgInt};
static const iocshArg vtr10012ConfigArg2 = { "VME memory offset",iocshArgInt};
static const iocshArg vtr10012ConfigArg3 = { "interrupt vector",iocshArgInt};
static const iocshArg vtr10012ConfigArg4 = { "interrupt level",iocshArgInt};
static const iocshArg vtr10012ConfigArg5 = { "use DMA",iocshArgInt};
static const iocshArg vtr10012ConfigArg6 = { "nchannels",iocshArgInt};
static const iocshArg vtr10012ConfigArg7 = { "kilosamplesPerChan",iocshArgInt};
static const iocshArg *vtr10012ConfigArgs[] = {
&vtr10012ConfigArg0, &vtr10012ConfigArg1, &vtr10012ConfigArg2,
&vtr10012ConfigArg3, &vtr10012ConfigArg4, &vtr10012ConfigArg5,
&vtr10012ConfigArg6,&vtr10012ConfigArg7};
static const iocshFuncDef vtr10012ConfigFuncDef =
{"vtr10012Config",8,vtr10012ConfigArgs};
static void vtr10012ConfigCallFunc(const iocshArgBuf *args)
{
vtr10012Config(args[0].ival, args[1].ival, args[2].ival,
args[3].ival, args[4].ival, args[5].ival,
args[6].ival, args[7].ival);
}

/*
* This routine is called before multitasking has started, so there's
* no race condition in the test/set of firstTime.
*/
static void
drvVtr10012RegisterCommands(void)
{
static int firstTime = 1;
if (firstTime) {
iocshRegister(&vtr10012ConfigFuncDef,vtr10012ConfigCallFunc);
firstTime = 0;
}
}
epicsExportRegistrar(drvVtr10012RegisterCommands);</nowiki>
You must also provide a corresponding registrar statement in a <code>.dbd</code> file:
registrar(drvVtr10012RegisterCommands)
* If your driver provides functions that are referred to by name from database files you must:
** <code>#include <registryFunction.h></code>
** Add an <code>epicsExportFunction()</code> statement for each such function.
** Add a corresponding <code>function</code> statement in a <code>.dbd</code> file.

==Additional Information==

The procedure for converting a support module from R3.13 to R3.14 is described in the [http://www.aps.anl.gov/epics/base/R3-14/8-docs/ConvertingR3.13AppsToR3.14.html Converting R3.13 Apps to R3.14] document.

==Acknowledgments==

* Peter Denison (Diamond) for getting me started on this document and for useful suggestions.
* Steve Shoaf and Nick DiMonte (ANL) for some early conversions.
* Andrew Johnson for 'wikifying' the contents and setting up this page.

----
Eric Norum 2006-08-17

How to make your EPICS driver operating system independent

2006-08-18T18:44:42Z

EricNorum: /* Conversions */

=How to make your EPICS driver operating system independent=

'''W. Eric Norum'''

==Introduction==

The following table shows the changes made to some existing drivers to allow them to be used on systems other than vxWorks. Note that it is a very preliminary start at a set of conversion instructions. There's still no `cookbook' document to guide you, but many drivers can be converted without doing much more than applying the translations shown. A technique that I've found works well is to first change all the <code>#include</code> statements that mention vxWorks header files to their OSI equivalents, then enter a compile-edit cycle until all compile errors have been eliminated.

==Conversions==

{| border="1" cellpadding="3"
! align="CENTER" | '''vxWorks'''
! align="CENTER" | '''OSI'''
|-
| <code>#include <vxWorks.h></code>
|-
| <code>#include <stdlib.h></code>
| <code>#include <epicsStdlib.h></code>
|-
| <code>#include <stdio.h></code>
| <code>#include <epicsStdioRedirect.h></code>
|-
| <code>#include <iosLib.h></code>
|-
| <code>#include <taskLib.h></code>
| <code>#include <epicsThread.h></code>
|-
| <code>#include <memLib.h></code>
|-
| <code>#include <rebootLib.h></code>
| <code>#include <epicsExit.h></code>
|-
| <code>#include <intLib.h></code>
| <code>#include <epicsInterrupt.h></code>
|-
| <code>#include <lstLib.h></code>
|-
| <code>#include <vme.h></code>
| <code>#include <devLib.h></code>
|-
| <code>#include <sysLib.h></code>
|-
| <code>#include <iv.h></code>
|-
|
| <code>#include <epicsExport.h></code>
<code>#include <iocsh.h></code>
|-
| <code>ERROR</code>
| <code>-1</code>
|-
| <code>OK</code>
| <code>0</code>
|-
| valign="TOP" | <code>#include <semLib.h></code>
SEM_ID flag = semBCreate(SEM_Q_PRIORITY, SEM_EMPTY);
semGive(flag);
semTake(flag, WAIT_FOREVER);
| valign="TOP" | <code>#include <epicsEvent.h></code>
epicsEventId flag = epicsEventMustCreate(epicsEventEmpty);
epicsEventSignal(flag);
epicsEventMustWait(flag);
|-
| valign="TOP" | <code>#include <semLib.h></code>
SEM_ID Lock = semMCreate(SEM_Q_PRIORITY);
semTake(Lock, WAIT_FOREVER);
semGive(Lock);
| valign="TOP" | <code>#include <epicsMutex.h></code>
epicsMutexId Lock = epicsMutexMustCreate();
epicsMutexLock(Lock);
epicsMutexUnlock(Lock);
|-
| valign="TOP" | <code>taskDelay(1)</code>
| valign="TOP" | To generate a `short' delay:
epicsThreadSleep(0.001)
This works because the operating system specific layer ensures a delay of at least one system clock tick for epicsThreadSleep arguments greater than 0.
|-
| valign="TOP" | <code>taskDelay(30)</code>
| valign="TOP" | Much old code assumes a 60 Hz vxWorks system clock. On such systems the equivalent for the command shown would be:
epicsThreadSleep(0.5)
Of course, other code may assumes a 50 Hz or 100 Hz system clock rate...
|-
| <code>taskSuspend(0)</code>
| <code>epicsThreadSuspendSelf()</code>
|-
| valign="TOP" | <code>intConnect(INUM_TO_IVEC(IrqVector), IrqHandler, pLink)</code>
| valign="TOP" | <code>devConnectInterruptVME(IrqVector, IrqHandler, pLink)</code>
|-
| <code>sysIntEnable(IrqLevel)</code>
| <code>devEnableInterruptLevelVME(IrqLevel)</code>
|-
| valign="TOP" | <code>sysBusToLocalAdrs(VME_AM_SUP_SHORT_IO, (char*)CardAddress, (char**)&ErLink[Card].pEr)</code>
| valign="TOP" | <code>devRegisterAddress("apsEr", atVMEA16, CardAddress, 0x40, (void*)&ErLink[Card].pEr)</code>
|-
| <code>vxMemProbe(pReg, READ, sizeof(short), &value)</code>
| <code>devReadProbe(sizeof(short), pReg, &value)</code>
|-
| <code>vxMemProbe(pReg,WRITE,sizeof(short), &value)</code>
| <code>devWriteProbe(sizeof(short), pReg, &value)</code>
|-
| <code>key = intLock()</code>
| <code>key = epicsInterruptLock()</code>
|-
| <code>intUnlock(key)</code>
| <code>epicsInterrupUnlock(key)</code>
|-
| <code>rebootHookAdd((FUNCPTR)ErRebootFunc)</code>
| <code>epicsAtExit(ErRebootFunc, NULL)</code>
|-
| valign="TOP" | <code>#include <fast_lock.h></code>
FAST_LOCK lock;
FASTLOCKINIT(&mzconf[card].lock);
FASTLOCKFREE(&mzconf[card].lock);
FASTLOCK(&mzconf[card].lock);
FASTUNLOCK(&mzconf[card].lock);
| valign="TOP" | You'll have to use your judgement here. If the section of code being protected is quick (less than a few microseconds) it's reasonable to simply disable interrupts while the code is active. In this case you can remove the 'lock' variable and the init/free operations and then add a local 'key' variable and replace the lock/unlock operations with epicsInterruptLock/Unlock operations. If the section of code being protected is longer you'll have to convert the FASTLOCK to an EPICS mutex.
|-
| <code>taskSpawn(...)</code>
| <code>epicsThreadCreate(...)</code>
You should consider rewriting the driver to use the "worker thread" environment provided by the ASYN package. This is likely to result in a shorter, simpler, and more robust driver.
|}

==Some other changes==

* Some R3.13 record support database definitions explicitly mention all fields rather than including dbCommon.dbd. This can cause problems with FAST_LOCK. The solution is to add <code>include "dbCommon.dbd"</code> at the beginning of the file in question and to remove all entries for the fields provided by dbCommon.dbd.
* You should set up IOC shell command registrations for all `configure' functions and for any other commands you may need to call from the IOC shell. Here's an example of a fairly complex configuration command:
<nowiki>
/*
* IOC shell command registration
*/
#include <iocsh.h>
static const iocshArg vtr10012ConfigArg0 = { "card",iocshArgInt};
static const iocshArg vtr10012ConfigArg1 = { "VME A16 offset",iocshArgInt};
static const iocshArg vtr10012ConfigArg2 = { "VME memory offset",iocshArgInt};
static const iocshArg vtr10012ConfigArg3 = { "interrupt vector",iocshArgInt};
static const iocshArg vtr10012ConfigArg4 = { "interrupt level",iocshArgInt};
static const iocshArg vtr10012ConfigArg5 = { "use DMA",iocshArgInt};
static const iocshArg vtr10012ConfigArg6 = { "nchannels",iocshArgInt};
static const iocshArg vtr10012ConfigArg7 = { "kilosamplesPerChan",iocshArgInt};
static const iocshArg *vtr10012ConfigArgs[] = {
&vtr10012ConfigArg0, &vtr10012ConfigArg1, &vtr10012ConfigArg2,
&vtr10012ConfigArg3, &vtr10012ConfigArg4, &vtr10012ConfigArg5,
&vtr10012ConfigArg6,&vtr10012ConfigArg7};
static const iocshFuncDef vtr10012ConfigFuncDef =
{"vtr10012Config",8,vtr10012ConfigArgs};
static void vtr10012ConfigCallFunc(const iocshArgBuf *args)
{
vtr10012Config(args[0].ival, args[1].ival, args[2].ival,
args[3].ival, args[4].ival, args[5].ival,
args[6].ival, args[7].ival);
}

/*
* This routine is called before multitasking has started, so there's
* no race condition in the test/set of firstTime.
*/
static void
drvVtr10012RegisterCommands(void)
{
static int firstTime = 1;
if (firstTime) {
iocshRegister(&vtr10012ConfigFuncDef,vtr10012ConfigCallFunc);
firstTime = 0;
}
}
epicsExportRegistrar(drvVtr10012RegisterCommands);</nowiki>
You must also provide a corresponding registrar statement in a <code>.dbd</code> file:
registrar(drvVtr10012RegisterCommands)
* If your driver provides functions that are referred to by name from database files you must:
** <code>#include <registryFunction.h></code>
** Add an <code>epicsExportFuncion()</code> statement for each such function.
** Add a corresponding <code>function</code> statement in a <code>.dbd</code> file.

==Additional Information==

The procedure for converting a support module from R3.13 to R3.14 is described in the [http://www.aps.anl.gov/epics/base/R3-14/8-docs/ConvertingR3.13AppsToR3.14.html Converting R3.13 Apps to R3.14] document.

==Acknowledgments==

* Peter Denison (Diamond) for getting me started on this document and for useful suggestions.
* Steve Shoaf and Nick DiMonte (ANL) for some early conversions.
* Andrew Johnson for 'wikifying' the contents and setting up this page.

----
Eric Norum 2006-08-17

How to make your EPICS driver operating system independent

2006-08-18T18:42:48Z

EricNorum: /* Acknowledgments */

=How to make your EPICS driver operating system independent=

'''W. Eric Norum'''

==Introduction==

The following table shows the changes made to some existing drivers to allow them to be used on systems other than vxWorks. Note that it is a very preliminary start at a set of conversion instructions. There's still no `cookbook' document to guide you, but many drivers can be converted without doing much more than applying the translations shown. A technique that I've found works well is to first change all the <code>#include</code> statements that mention vxWorks header files to their OSI equivalents, then enter a compile-edit cycle until all compile errors have been eliminated.

==Conversions==

{| border="1" cellpadding="3"
! align="CENTER" | '''vxWorks'''
! align="CENTER" | '''OSI'''
|-
| <code>#include <vxWorks.h></code>
|-
| <code>#include <stdlib.h></code>
| <code>#include <epicsStdlib.h></code>
|-
| <code>#include <stdio.h></code>
| <code>#include <epicsStdioRedirect.h></code>
|-
| <code>#include <iosLib.h></code>
|-
| <code>#include <taskLib.h></code>
| <code>#include <epicsThread.h></code>
|-
| <code>#include <memLib.h></code>
|-
| <code>#include <rebootLib.h></code>
| <code>#include <epicsExit.h></code>
|-
| <code>#include <intLib.h></code>
| <code>#include <epicsInterrupt.h></code>
|-
| <code>#include <lstLib.h></code>
|-
| <code>#include <vme.h></code>
| <code>#include <devLib.h></code>
|-
| <code>#include <sysLib.h></code>
|-
| <code>#include <iv.h></code>
|-
| <code>#include <epicsExport.h></code>
|-
| <code>#include <iocsh.h></code>
|-
| <code>ERROR</code>
| <code>-1</code>
|-
| <code>OK</code>
| <code>0</code>
|-
| valign="TOP" | <code>#include <semLib.h></code>
SEM_ID flag = semBCreate(SEM_Q_PRIORITY, SEM_EMPTY);
semGive(flag);
semTake(flag, WAIT_FOREVER);
| valign="TOP" | <code>#include <epicsEvent.h></code>
epicsEventId flag = epicsEventMustCreate(epicsEventEmpty);
epicsEventSignal(flag);
epicsEventMustWait(flag);
|-
| valign="TOP" | <code>#include <semLib.h></code>
SEM_ID Lock = semMCreate(SEM_Q_PRIORITY);
semTake(Lock, WAIT_FOREVER);
semGive(Lock);
| valign="TOP" | <code>#include <epicsMutex.h></code>
epicsMutexId Lock = epicsMutexMustCreate();
epicsMutexLock(Lock);
epicsMutexUnlock(Lock);
|-
| valign="TOP" | <code>taskDelay(1)</code>
| valign="TOP" | To generate a `short' delay:
epicsThreadSleep(0.001)
This works because the operating system specific layer ensures a delay of at least one system clock tick for epicsThreadSleep arguments greater than 0.
|-
| valign="TOP" | <code>taskDelay(30)</code>
| valign="TOP" | Much old code assumes a 60 Hz vxWorks system clock. On such systems the equivalent for the command shown would be:
epicsThreadSleep(0.5)
Of course, other code may assumes a 50 Hz or 100 Hz system clock rate...
|-
| <code>taskSuspend(0)</code>
| <code>epicsThreadSuspendSelf()</code>
|-
| valign="TOP" | <code>intConnect(INUM_TO_IVEC(IrqVector), IrqHandler, pLink)</code>
| valign="TOP" | <code>devConnectInterruptVME(IrqVector, IrqHandler, pLink)</code>
|-
| <code>sysIntEnable(IrqLevel)</code>
| <code>devEnableInterruptLevelVME(IrqLevel)</code>
|-
| valign="TOP" | <code>sysBusToLocalAdrs(VME_AM_SUP_SHORT_IO, (char*)CardAddress, (char**)&ErLink[Card].pEr)</code>
| valign="TOP" | <code>devRegisterAddress("apsEr", atVMEA16, CardAddress, 0x40, (void*)&ErLink[Card].pEr)</code>
|-
| <code>vxMemProbe(pReg, READ, sizeof(short), &value)</code>
| <code>devReadProbe(sizeof(short), pReg, &value)</code>
|-
| <code>vxMemProbe(pReg,WRITE,sizeof(short), &value)</code>
| <code>devWriteProbe(sizeof(short), pReg, &value)</code>
|-
| <code>key = intLock()</code>
| <code>key = epicsInterruptLock()</code>
|-
| <code>intUnlock(key)</code>
| <code>epicsInterrupUnlock(key)</code>
|-
| <code>rebootHookAdd((FUNCPTR)ErRebootFunc)</code>
| <code>epicsAtExit(ErRebootFunc, NULL)</code>
|-
| valign="TOP" | <code>#include <fast_lock.h></code>
FAST_LOCK lock;
FASTLOCKINIT(&mzconf[card].lock);
FASTLOCKFREE(&mzconf[card].lock);
FASTLOCK(&mzconf[card].lock);
FASTUNLOCK(&mzconf[card].lock);
| valign="TOP" | You'll have to use your judgement here. If the section of code being protected is quick (less than a few microseconds) it's reasonable to simply disable interrupts while the code is active. In this case you can remove the 'lock' variable and the init/free operations and then add a local 'key' variable and replace the lock/unlock operations with epicsInterruptLock/Unlock operations. If the section of code being protected is longer you'll have to convert the FASTLOCK to an EPICS mutex.
|-
| <code>taskSpawn(...)</code>
| <code>epicsThreadCreate(...)</code>
You should consider rewriting the driver to use the "worker thread" environment provided by the ASYN package. This is likely to result in a shorter, simpler, and more robust driver.
|}

==Some other changes==

* Some R3.13 record support database definitions explicitly mention all fields rather than including dbCommon.dbd. This can cause problems with FAST_LOCK. The solution is to add <code>include "dbCommon.dbd"</code> at the beginning of the file in question and to remove all entries for the fields provided by dbCommon.dbd.
* You should set up IOC shell command registrations for all `configure' functions and for any other commands you may need to call from the IOC shell. Here's an example of a fairly complex configuration command:
<nowiki>
/*
* IOC shell command registration
*/
#include <iocsh.h>
static const iocshArg vtr10012ConfigArg0 = { "card",iocshArgInt};
static const iocshArg vtr10012ConfigArg1 = { "VME A16 offset",iocshArgInt};
static const iocshArg vtr10012ConfigArg2 = { "VME memory offset",iocshArgInt};
static const iocshArg vtr10012ConfigArg3 = { "interrupt vector",iocshArgInt};
static const iocshArg vtr10012ConfigArg4 = { "interrupt level",iocshArgInt};
static const iocshArg vtr10012ConfigArg5 = { "use DMA",iocshArgInt};
static const iocshArg vtr10012ConfigArg6 = { "nchannels",iocshArgInt};
static const iocshArg vtr10012ConfigArg7 = { "kilosamplesPerChan",iocshArgInt};
static const iocshArg *vtr10012ConfigArgs[] = {
&vtr10012ConfigArg0, &vtr10012ConfigArg1, &vtr10012ConfigArg2,
&vtr10012ConfigArg3, &vtr10012ConfigArg4, &vtr10012ConfigArg5,
&vtr10012ConfigArg6,&vtr10012ConfigArg7};
static const iocshFuncDef vtr10012ConfigFuncDef =
{"vtr10012Config",8,vtr10012ConfigArgs};
static void vtr10012ConfigCallFunc(const iocshArgBuf *args)
{
vtr10012Config(args[0].ival, args[1].ival, args[2].ival,
args[3].ival, args[4].ival, args[5].ival,
args[6].ival, args[7].ival);
}

/*
* This routine is called before multitasking has started, so there's
* no race condition in the test/set of firstTime.
*/
static void
drvVtr10012RegisterCommands(void)
{
static int firstTime = 1;
if (firstTime) {
iocshRegister(&vtr10012ConfigFuncDef,vtr10012ConfigCallFunc);
firstTime = 0;
}
}
epicsExportRegistrar(drvVtr10012RegisterCommands);</nowiki>
You must also provide a corresponding registrar statement in a <code>.dbd</code> file:
registrar(drvVtr10012RegisterCommands)
* If your driver provides functions that are referred to by name from database files you must:
** <code>#include <registryFunction.h></code>
** Add an <code>epicsExportFuncion()</code> statement for each such function.
** Add a corresponding <code>function</code> statement in a <code>.dbd</code> file.

==Additional Information==

The procedure for converting a support module from R3.13 to R3.14 is described in the [http://www.aps.anl.gov/epics/base/R3-14/8-docs/ConvertingR3.13AppsToR3.14.html Converting R3.13 Apps to R3.14] document.

==Acknowledgments==

* Peter Denison (Diamond) for getting me started on this document and for useful suggestions.
* Steve Shoaf and Nick DiMonte (ANL) for some early conversions.
* Andrew Johnson for 'wikifying' the contents and setting up this page.

----
Eric Norum 2006-08-17

How to make your EPICS driver operating system independent

2006-08-18T18:41:55Z

EricNorum: /* Conversions */

=How to make your EPICS driver operating system independent=

'''W. Eric Norum'''

==Introduction==

The following table shows the changes made to some existing drivers to allow them to be used on systems other than vxWorks. Note that it is a very preliminary start at a set of conversion instructions. There's still no `cookbook' document to guide you, but many drivers can be converted without doing much more than applying the translations shown. A technique that I've found works well is to first change all the <code>#include</code> statements that mention vxWorks header files to their OSI equivalents, then enter a compile-edit cycle until all compile errors have been eliminated.

==Conversions==

{| border="1" cellpadding="3"
! align="CENTER" | '''vxWorks'''
! align="CENTER" | '''OSI'''
|-
| <code>#include <vxWorks.h></code>
|-
| <code>#include <stdlib.h></code>
| <code>#include <epicsStdlib.h></code>
|-
| <code>#include <stdio.h></code>
| <code>#include <epicsStdioRedirect.h></code>
|-
| <code>#include <iosLib.h></code>
|-
| <code>#include <taskLib.h></code>
| <code>#include <epicsThread.h></code>
|-
| <code>#include <memLib.h></code>
|-
| <code>#include <rebootLib.h></code>
| <code>#include <epicsExit.h></code>
|-
| <code>#include <intLib.h></code>
| <code>#include <epicsInterrupt.h></code>
|-
| <code>#include <lstLib.h></code>
|-
| <code>#include <vme.h></code>
| <code>#include <devLib.h></code>
|-
| <code>#include <sysLib.h></code>
|-
| <code>#include <iv.h></code>
|-
| <code>#include <epicsExport.h></code>
|-
| <code>#include <iocsh.h></code>
|-
| <code>ERROR</code>
| <code>-1</code>
|-
| <code>OK</code>
| <code>0</code>
|-
| valign="TOP" | <code>#include <semLib.h></code>
SEM_ID flag = semBCreate(SEM_Q_PRIORITY, SEM_EMPTY);
semGive(flag);
semTake(flag, WAIT_FOREVER);
| valign="TOP" | <code>#include <epicsEvent.h></code>
epicsEventId flag = epicsEventMustCreate(epicsEventEmpty);
epicsEventSignal(flag);
epicsEventMustWait(flag);
|-
| valign="TOP" | <code>#include <semLib.h></code>
SEM_ID Lock = semMCreate(SEM_Q_PRIORITY);
semTake(Lock, WAIT_FOREVER);
semGive(Lock);
| valign="TOP" | <code>#include <epicsMutex.h></code>
epicsMutexId Lock = epicsMutexMustCreate();
epicsMutexLock(Lock);
epicsMutexUnlock(Lock);
|-
| valign="TOP" | <code>taskDelay(1)</code>
| valign="TOP" | To generate a `short' delay:
epicsThreadSleep(0.001)
This works because the operating system specific layer ensures a delay of at least one system clock tick for epicsThreadSleep arguments greater than 0.
|-
| valign="TOP" | <code>taskDelay(30)</code>
| valign="TOP" | Much old code assumes a 60 Hz vxWorks system clock. On such systems the equivalent for the command shown would be:
epicsThreadSleep(0.5)
Of course, other code may assumes a 50 Hz or 100 Hz system clock rate...
|-
| <code>taskSuspend(0)</code>
| <code>epicsThreadSuspendSelf()</code>
|-
| valign="TOP" | <code>intConnect(INUM_TO_IVEC(IrqVector), IrqHandler, pLink)</code>
| valign="TOP" | <code>devConnectInterruptVME(IrqVector, IrqHandler, pLink)</code>
|-
| <code>sysIntEnable(IrqLevel)</code>
| <code>devEnableInterruptLevelVME(IrqLevel)</code>
|-
| valign="TOP" | <code>sysBusToLocalAdrs(VME_AM_SUP_SHORT_IO, (char*)CardAddress, (char**)&ErLink[Card].pEr)</code>
| valign="TOP" | <code>devRegisterAddress("apsEr", atVMEA16, CardAddress, 0x40, (void*)&ErLink[Card].pEr)</code>
|-
| <code>vxMemProbe(pReg, READ, sizeof(short), &value)</code>
| <code>devReadProbe(sizeof(short), pReg, &value)</code>
|-
| <code>vxMemProbe(pReg,WRITE,sizeof(short), &value)</code>
| <code>devWriteProbe(sizeof(short), pReg, &value)</code>
|-
| <code>key = intLock()</code>
| <code>key = epicsInterruptLock()</code>
|-
| <code>intUnlock(key)</code>
| <code>epicsInterrupUnlock(key)</code>
|-
| <code>rebootHookAdd((FUNCPTR)ErRebootFunc)</code>
| <code>epicsAtExit(ErRebootFunc, NULL)</code>
|-
| valign="TOP" | <code>#include <fast_lock.h></code>
FAST_LOCK lock;
FASTLOCKINIT(&mzconf[card].lock);
FASTLOCKFREE(&mzconf[card].lock);
FASTLOCK(&mzconf[card].lock);
FASTUNLOCK(&mzconf[card].lock);
| valign="TOP" | You'll have to use your judgement here. If the section of code being protected is quick (less than a few microseconds) it's reasonable to simply disable interrupts while the code is active. In this case you can remove the 'lock' variable and the init/free operations and then add a local 'key' variable and replace the lock/unlock operations with epicsInterruptLock/Unlock operations. If the section of code being protected is longer you'll have to convert the FASTLOCK to an EPICS mutex.
|-
| <code>taskSpawn(...)</code>
| <code>epicsThreadCreate(...)</code>
You should consider rewriting the driver to use the "worker thread" environment provided by the ASYN package. This is likely to result in a shorter, simpler, and more robust driver.
|}

==Some other changes==

* Some R3.13 record support database definitions explicitly mention all fields rather than including dbCommon.dbd. This can cause problems with FAST_LOCK. The solution is to add <code>include "dbCommon.dbd"</code> at the beginning of the file in question and to remove all entries for the fields provided by dbCommon.dbd.
* You should set up IOC shell command registrations for all `configure' functions and for any other commands you may need to call from the IOC shell. Here's an example of a fairly complex configuration command:
<nowiki>
/*
* IOC shell command registration
*/
#include <iocsh.h>
static const iocshArg vtr10012ConfigArg0 = { "card",iocshArgInt};
static const iocshArg vtr10012ConfigArg1 = { "VME A16 offset",iocshArgInt};
static const iocshArg vtr10012ConfigArg2 = { "VME memory offset",iocshArgInt};
static const iocshArg vtr10012ConfigArg3 = { "interrupt vector",iocshArgInt};
static const iocshArg vtr10012ConfigArg4 = { "interrupt level",iocshArgInt};
static const iocshArg vtr10012ConfigArg5 = { "use DMA",iocshArgInt};
static const iocshArg vtr10012ConfigArg6 = { "nchannels",iocshArgInt};
static const iocshArg vtr10012ConfigArg7 = { "kilosamplesPerChan",iocshArgInt};
static const iocshArg *vtr10012ConfigArgs[] = {
&vtr10012ConfigArg0, &vtr10012ConfigArg1, &vtr10012ConfigArg2,
&vtr10012ConfigArg3, &vtr10012ConfigArg4, &vtr10012ConfigArg5,
&vtr10012ConfigArg6,&vtr10012ConfigArg7};
static const iocshFuncDef vtr10012ConfigFuncDef =
{"vtr10012Config",8,vtr10012ConfigArgs};
static void vtr10012ConfigCallFunc(const iocshArgBuf *args)
{
vtr10012Config(args[0].ival, args[1].ival, args[2].ival,
args[3].ival, args[4].ival, args[5].ival,
args[6].ival, args[7].ival);
}

/*
* This routine is called before multitasking has started, so there's
* no race condition in the test/set of firstTime.
*/
static void
drvVtr10012RegisterCommands(void)
{
static int firstTime = 1;
if (firstTime) {
iocshRegister(&vtr10012ConfigFuncDef,vtr10012ConfigCallFunc);
firstTime = 0;
}
}
epicsExportRegistrar(drvVtr10012RegisterCommands);</nowiki>
You must also provide a corresponding registrar statement in a <code>.dbd</code> file:
registrar(drvVtr10012RegisterCommands)
* If your driver provides functions that are referred to by name from database files you must:
** <code>#include <registryFunction.h></code>
** Add an <code>epicsExportFuncion()</code> statement for each such function.
** Add a corresponding <code>function</code> statement in a <code>.dbd</code> file.

==Additional Information==

The procedure for converting a support module from R3.13 to R3.14 is described in the [http://www.aps.anl.gov/epics/base/R3-14/8-docs/ConvertingR3.13AppsToR3.14.html Converting R3.13 Apps to R3.14] document.

==Acknowledgments==

* Peter Denison (Diamond) for getting me started on this document and for useful suggestions.
* Steve Shoaf and Nick DiMonte (ANL) for some early conversions.

----
Eric Norum 2006-08-17