record interface documentation added
This commit is contained in:
@ -12,7 +12,312 @@
|
|||||||
<iframe src="nav.html" id="navleft"></iframe>
|
<iframe src="nav.html" id="navleft"></iframe>
|
||||||
<h1>Record API</h1>
|
<h1>Record API</h1>
|
||||||
|
|
||||||
<h2>Sorry, this documentation is still missing.</h2>
|
<a name="theory"></a>
|
||||||
|
<h2>Theory of Operation</h2>
|
||||||
|
<p>
|
||||||
|
<em>StreamDevice</em> implements the generic part of an EPICS device support.
|
||||||
|
However it cannot know the internals of a specific record type, such as the
|
||||||
|
.VAL or .RVAL fields or the .INP or .OUT links. It can only access a record
|
||||||
|
as dbCommon. Thus it is necessary to write an interface for each record type
|
||||||
|
which takes care of these details.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
A record interface consists of three functions, <code>readData()</code> and
|
||||||
|
<code>writeData()</code> and <code>initRecord()</code>.
|
||||||
|
</p>
|
||||||
|
The record interface also implements the device support structure for this
|
||||||
|
record type. Most of its functions will be generic <em>StreamDevice</em>
|
||||||
|
functions. The exception is <code>initRecord()</code>.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The name of the device support structure must have the form
|
||||||
|
<code>dev<var>recordtype</var>Stream</code> and the name of the record
|
||||||
|
interface source code file must be
|
||||||
|
<code>dev<var>recordtype</var>Stream.c</code> to work seamlessly with the
|
||||||
|
build system implemented in the Makefile of <em>StreamDevice</em>.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Finally add <code><var>recordtype</var></code> to the
|
||||||
|
<code>RECORDTYPES</code> variable in the file src/CONFIG_STREAM
|
||||||
|
and rebuild.
|
||||||
|
</p>
|
||||||
|
<a name="headers"></a>
|
||||||
|
<h3>Headers to Include</h2>
|
||||||
|
<p>
|
||||||
|
A record interface typically <code>#include</code>s the header file
|
||||||
|
for the supported record type, <code>"<var>recordtype</var>Record.h"</code>
|
||||||
|
and <code>"devStream.h"</code>.
|
||||||
|
For many record interfaces this is sufficient, but sometimes additional
|
||||||
|
header files may be needed.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<a name="functions"></a>
|
||||||
|
<h3>Functions to Implement</h2>
|
||||||
|
<p>
|
||||||
|
A record interface has to implement three functions:
|
||||||
|
</p>
|
||||||
|
<div class="indent"><code>
|
||||||
|
static long readData(dbCommon *record, format_t *format);
|
||||||
|
</code></div>
|
||||||
|
<div class="indent"><code>
|
||||||
|
static long writeData(dbCommon *record, format_t *format);
|
||||||
|
</code></div>
|
||||||
|
<div class="indent"><code>
|
||||||
|
static long initRecord(dbCommon *record);
|
||||||
|
</code></div>
|
||||||
|
|
||||||
|
<h4>writeData</h4>
|
||||||
|
<p>
|
||||||
|
The function <code>writeData()</code> is called whenever a
|
||||||
|
<a href="protocol.html#proto">protocol</a> needs
|
||||||
|
to handle a prining <a href="formats.html">format converter</a>
|
||||||
|
(without <a href="formats.html#redirection">redirection</a>),
|
||||||
|
typically in an <code>out</code> command.
|
||||||
|
It is also possible that <code>writeData()</code> is called for an input
|
||||||
|
record, e.g. when the <a href="formats.html#syntax"><code>=</code> flag</a>
|
||||||
|
is used in an <code>in</code> command.
|
||||||
|
Thus implement this function for input records as well.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The functions is called with a <code>dbCommon *record</code> argument,
|
||||||
|
which the function should cast to the specific record type to get
|
||||||
|
access to the record specific fields, in particular .VAL and .RVAL.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The second argument, <code>format_t *format</code>, contains information
|
||||||
|
about the format converter. The only field of interest in this argument
|
||||||
|
is <code>format->type</code> which specifies the data type of the format
|
||||||
|
conversion. Its value is one of <code>DBF_ULONG</code>,
|
||||||
|
<code>DBF_ULONG</code>, <code>DBF_ENUM</code>, <code>DBF_DOUBLE</code>,
|
||||||
|
or <code>DBF_STRING</code>.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <code>writeData()</code> function may access different fields depending
|
||||||
|
on <code>format->type</code>, e.g. .VAL for <code>DBF_DOUBLE</code> but
|
||||||
|
.RVAL for <code>DBF_LONG</code>.
|
||||||
|
It also may interpret the fields in a different way, e.g. cast to
|
||||||
|
<code>long</code> for <code>DBF_LONG</code> but to <code>unsigned long</code>
|
||||||
|
for <code>DBF_ULONG</code>.
|
||||||
|
This is typically done with a <code>switch(format->type)</code> statement.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The function may refuse to handle <code>format->type</code> values
|
||||||
|
that make no sense for the record type, e.g. <code>DBF_STRING</code> for a
|
||||||
|
record type that cannot handle strings. In that case the function should
|
||||||
|
return <code>ERROR</code>. It is a good idea to return <code>ERROR</code>
|
||||||
|
in the <code>default</code> part of the <code>switch</code> statement.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
<em>StreamDevice</em> provides a function to output a value from the record:
|
||||||
|
</p>
|
||||||
|
<div class="indent"><code>
|
||||||
|
long streamPrintf(dbCommon *record, format_t *format, ...);
|
||||||
|
</code></div>
|
||||||
|
<p>
|
||||||
|
Once the correct record field and type cast has been chosen, the
|
||||||
|
<code>writeData()</code> function calls
|
||||||
|
<code>return streamPrintf(record, format, value)</code> where the type of
|
||||||
|
value should match <code>field->type</code> (<code>long</code>,
|
||||||
|
<code>unsigned long</code>, <code>double</code>, or <code>char*</code>),
|
||||||
|
returning the result of that call.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
<b>Example:</b>
|
||||||
|
</p>
|
||||||
|
<pre>
|
||||||
|
static long writeData(dbCommon *record, format_t *format)
|
||||||
|
{
|
||||||
|
<var>recordtype</var>Record *rec = (<var>recordtype</var>Record *)record;
|
||||||
|
|
||||||
|
switch (format->type)
|
||||||
|
{
|
||||||
|
case DBF_ULONG:
|
||||||
|
case DBF_ENUM:
|
||||||
|
return streamPrintf(record, format, (unsigned long)rec->rval);
|
||||||
|
case DBF_LONG:
|
||||||
|
return streamPrintf(record, format, (long)rec->rval);
|
||||||
|
case DBF_DOUBLE:
|
||||||
|
return streamPrintf(record, format, rec->val);
|
||||||
|
default:
|
||||||
|
return ERROR;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<h4>readData</h4>
|
||||||
|
<p>
|
||||||
|
The arguments of this function are the same as for <code>writeData()</code>.
|
||||||
|
But this function stores a value into record fields depending on
|
||||||
|
<code>format->type</code>.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
<em>StreamDevice</em> provides two functions to receive a value;
|
||||||
|
</p>
|
||||||
|
<div class="indent"><code>
|
||||||
|
ssize_t streamScanf(dbCommon *record, format_t *format, void* value);
|
||||||
|
</code></div>
|
||||||
|
<div class="indent"><code>
|
||||||
|
ssize_t streamScanfN(dbCommon *record, format_t *format, void* value, size_t maxStringSize);
|
||||||
|
</code></div>
|
||||||
|
<p>
|
||||||
|
The argument <code>value</code> is a pointer to the variable where the value
|
||||||
|
is to be stored. Its type must match <code>field->type</code>
|
||||||
|
(<code>long*</code>, <code>unsigned long*</code>, <code>double*</code>, or
|
||||||
|
<code>char*</code>).
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <code>streamScanfN()</code> function is meant for strings and gets the
|
||||||
|
additional argument <code>maxStringSize</code> to specify the size of the
|
||||||
|
string buffer.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <code>streamScanf()</code> function is actually a macro calling
|
||||||
|
<code>streamScanfN()</code> with <code>MAX_STRING_SIZE</code> (=40) for
|
||||||
|
the last argument. For <code>field->type</code> values other than
|
||||||
|
<code>DBF_STRING</code>, this argument is ignored.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
In case of strings, these functions return the number of characters
|
||||||
|
actually stored (which may be less than <code>maxStringSize</code>).
|
||||||
|
Some record types may want to store this value into a field of the record.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The functions return <code>ERROR</code> on failure. In this case the
|
||||||
|
<code>readData()</code> function should return <code>ERROR</code> as well.
|
||||||
|
Otherwise the function should store the value received into the appropriate
|
||||||
|
record field.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
If <code>record->pact</code> is <code>true</code>, the function
|
||||||
|
should now return <code>OK</code> or <code>DO_NOT_CONVERT</code> (=2),
|
||||||
|
depending on wheter conversion from .RVAL to .VAL should be left to the
|
||||||
|
record or not.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
If <code>record->pact</code> is <code>false</code>, the record is curretly
|
||||||
|
executing the <code>@init</code> handler.
|
||||||
|
This typically only affects output records.
|
||||||
|
As the record is not processed by EPICS at this time, changes in fields would
|
||||||
|
not trigger monitor updates.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Also the record will not convert .RVAL to .VAL in this case, thus the
|
||||||
|
<code>readData()</code> function should now convert .RVAL
|
||||||
|
to .VAL as usually done by the record.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
In order to make monitors work properly, the <code>readData()</code> function
|
||||||
|
should then first call <code>recGblResetAlarms()</code> and then call
|
||||||
|
<code>db_post_events()</code> as needed. Usually the code
|
||||||
|
from the record support function <code>monitor()</code> needs to be copied.
|
||||||
|
Unfortunately the <code>monitor()</code> function of the record cannot be
|
||||||
|
called directly because it is <code>static</code>.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
<b>Example:</b>
|
||||||
|
</p>
|
||||||
|
<pre>
|
||||||
|
static long readData(dbCommon *record, format_t *format)
|
||||||
|
{
|
||||||
|
<var>recordtype</var>Record *rec = (<var>recordtype</var>Record *)record;
|
||||||
|
unsigned long rval;
|
||||||
|
unsigned short monitor_mask;
|
||||||
|
|
||||||
|
switch (format->type)
|
||||||
|
{
|
||||||
|
case DBF_ULONG:
|
||||||
|
case DBF_LONG:
|
||||||
|
case DBF_ENUM:
|
||||||
|
if (streamScanf(record, format, &rval) == ERROR) return ERROR;
|
||||||
|
rec->rval = rval;
|
||||||
|
if (record->pact) return OK;
|
||||||
|
/* emulate convertion to val */
|
||||||
|
rec->val = rval * rec->eslo + rec->eoff;
|
||||||
|
break;
|
||||||
|
case DBF_DOUBLE:
|
||||||
|
if (streamScanf(record, format, &rec->val) == ERROR) return ERROR;
|
||||||
|
break;
|
||||||
|
if (record->pact) return DO_NOT_CONVERT;
|
||||||
|
default:
|
||||||
|
return ERROR;
|
||||||
|
}
|
||||||
|
/* In @init handler, no processing, enforce monitor updates. */
|
||||||
|
monitor_mask = recGblResetAlarms(record);
|
||||||
|
if (rec->oraw != rec->rval)
|
||||||
|
{
|
||||||
|
db_post_events(record, &rec->rval, monitor_mask | DBE_VALUE | DBE_LOG);
|
||||||
|
rec->oraw = rec->rval;
|
||||||
|
}
|
||||||
|
if (!(fabs(rec->mlst - rec->val) <= rec->mdel))
|
||||||
|
{
|
||||||
|
monitor_mask |= DBE_VALUE;
|
||||||
|
ao->mlst = rec->val;
|
||||||
|
}
|
||||||
|
if (!(fabs(rec->alst - rec->val) <= rec->adel))
|
||||||
|
{
|
||||||
|
monitor_mask |= DBE_VALUE;
|
||||||
|
ao->alst = rec->val;
|
||||||
|
}
|
||||||
|
if (monitor_mask)
|
||||||
|
db_post_events(record, &rec->val, monitor_mask);
|
||||||
|
return OK;
|
||||||
|
}
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<h4>initRecord</h4>
|
||||||
|
<p>
|
||||||
|
The main purpose of this function is to pass the .INP or .OUT link to
|
||||||
|
<em>StreamDevice</em> for parsing and to make the two functions
|
||||||
|
<code>readData</code> and <code>writeData</code> known.
|
||||||
|
Often the only thing the <code>initRecord()</code> function does is to call
|
||||||
|
<code>streamInitRecord()</code> and return its result.
|
||||||
|
</p>
|
||||||
|
<div class="indent"><code>
|
||||||
|
long streamInitRecord(dbCommon *record, const struct link *ioLink,
|
||||||
|
streamIoFunction readData, streamIoFunction writeData);
|
||||||
|
</code></div>
|
||||||
|
<pre>
|
||||||
|
static long initRecord(dbCommon *record)
|
||||||
|
{
|
||||||
|
<var>recordtype</var>Record *rec = (<var>recordtype</var>Record *)record;
|
||||||
|
|
||||||
|
return streamInitRecord(record, &rec->out, readData, writeData);
|
||||||
|
}
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<h3>Device Support Structure</h3>
|
||||||
|
<p>
|
||||||
|
For most record types the device support structure contains 5 functions,
|
||||||
|
<code>report</code>, <code>init</code>, <code>init_record</code>,
|
||||||
|
<code>get_ioint_info</code>, and <code>read</code> or <code>write</code>.
|
||||||
|
Few other record typess, for examle ai and ao may have additional functions.
|
||||||
|
For most of these functions simply pass one of the provided
|
||||||
|
<em>StreamDevice</em> functions <code>streamReport</code>,
|
||||||
|
<code>streamInit</code>, <code>streamGetIoInitInfo</code>, and
|
||||||
|
<code>streamRead</code> or <code>streamWrite</code>.
|
||||||
|
Only for <code>init_record</code> pass your own
|
||||||
|
<code>initRecord</code> function. Then export the structure.
|
||||||
|
</p>
|
||||||
|
<pre>
|
||||||
|
struct {
|
||||||
|
long number;
|
||||||
|
DEVSUPFUN report;
|
||||||
|
DEVSUPFUN init;
|
||||||
|
DEVSUPFUN init_record;
|
||||||
|
DEVSUPFUN get_ioint_info;
|
||||||
|
DEVSUPFUN write;
|
||||||
|
} dev<var>recordtype</var>Stream = {
|
||||||
|
5,
|
||||||
|
streamReport,
|
||||||
|
streamInit,
|
||||||
|
initRecord,
|
||||||
|
streamGetIointInfo,
|
||||||
|
streamWrite
|
||||||
|
};
|
||||||
|
|
||||||
|
epicsExportAddress(dset,dev<var>recordtype</var>Stream);
|
||||||
|
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
|
||||||
<footer>
|
<footer>
|
||||||
@ -20,3 +325,4 @@ Dirk Zimoch, 2018
|
|||||||
</footer>
|
</footer>
|
||||||
</body>
|
</body>
|
||||||
</html>
|
</html>
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user