diff --git a/documentation/Makefile b/documentation/Makefile index ebf8d27..969522e 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -16,7 +16,7 @@ clean: gen: ../include/pvxs/version.h doxygen $(PYTHON) -m sphinx -j auto -b html . html - cp qsrv2-schema-0.json html/ + cp pvalink-schema-0.json qsrv2-schema-0.json html/ gen: _image/nt_table1.svg gen: _image/nt_table2.svg diff --git a/documentation/ioc.rst b/documentation/ioc.rst index 1634397..fa05d55 100644 --- a/documentation/ioc.rst +++ b/documentation/ioc.rst @@ -46,10 +46,14 @@ QSRV 2 Beginning with PVXS 1.2.0 the functionality of `QSRV `_ is replicated in the ``pvxsIoc`` library. -Currently this feature preview is considered **alpha** level, with missing functionality. -In addition to linking in ``libpvxsIoc``, -users must **opt in** at runtime by setting ``$PVXS_QSRV_ENABLE=YES`` before ``iocInit()``. :: +Currently this feature preview is considered **beta** level with equivalent functionality. +It is recommended not to load both ``pvxsIoc.dbd`` and ``qsrv.dbd`` in the same IOC process. +However, if this is done. Users may opt out at runtime by setting +``$PVXS_QSRV_ENABLE=NO`` before ``iocInit()``. :: + + # Default with PVXS >= 1.3.0 + # Needed with PVXS 1.2.x epicsEnvSet("PVXS_QSRV_ENABLE", "YES") iocInit() @@ -162,4 +166,20 @@ and is a member of the "op" group (supported on POSIX targets and Windows). PVAccess Links ^^^^^^^^^^^^^^ -TODO... +Since PVXS UNRELEASED. + +When built against Base >= 7.0.1, support is enabled for PVAccess links +using JSON link support syntax. :: + + record(longin, "tgt") {} + record(longin, "src") { + field(INP, {pva:{pv:"tgt"}}) + } + +.. note: The "dbjlr" and "dbpvar" IOC shell command provide information about PVA links in a running IOC. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + pvalink diff --git a/documentation/pvalink.rst b/documentation/pvalink.rst new file mode 100644 index 0000000..3c9106a --- /dev/null +++ b/documentation/pvalink.rst @@ -0,0 +1,169 @@ +.. _pvalink: + +PVA Links +######### + +Since UNRELEASED + +JSON Reference +============== + +A PVA link `JSON schema `_ definition file is available. + +Default values for all keys. :: + + record(longin, "tgt") {} + record(longin, "src") { + field(INP, {pva:{ + pv:"tgt", + field:"", + local:false, + Q:4, + pipeline:false, + proc:none, + sevr:false, + time:false, + monorder:0, + retry:false, + always:false, + defer:false + }}) + } + +Certain keys are only relevant with certain link types. + ++----------+-------+--------+---------+ +| Key | Input | Output | Forward | ++==========+=======+========+=========+ +| pv | X | X | X | ++----------+-------+--------+---------+ +| field | X | X | X | ++----------+-------+--------+---------+ +| local | X | X | X | ++----------+-------+--------+---------+ +| proc | | X | X | ++----------+-------+--------+---------+ +| retry | | X | X | ++----------+-------+--------+---------+ +| atomic | X | | | ++----------+-------+--------+---------+ +| defer | X | | | ++----------+-------+--------+---------+ +| monorder | X | | | ++----------+-------+--------+---------+ +| pipeline | X | | | ++----------+-------+--------+---------+ +| Q | X | | | ++----------+-------+--------+---------+ +| sevr | X | | | ++----------+-------+--------+---------+ +| time | X | | | ++----------+-------+--------+---------+ +| always | | | | ++----------+-------+--------+---------+ + +``pv`` names the target PV in full. + +``field`` selects a sub-structure of the target PV. +By default ``""`` the top level structure is used. +If the target field is a Structure, then ``.value`` +and various NTScalar meta-data fields are used. +Otherwise, the the targeted field is used as the value +without any meta-data. + +``local`` set to require that ``pv`` reference a record in the local database. + +``Q`` requests a certain subscription queue depth. + +``pipeline`` selects per-subscription flow control. + +``proc`` may be set to: + +- ``null`` (default). Server selects ``"NPP"`` or ``"PP"`` behavior. +- ``true`` / ``"PP""``. Requests target recorded be "processed" after value update. +- ``false`` / ``"NPP"``. Requests only value update. +- ``"CP"`` Subscribes to target PV. Process this record on each update as well as (dis)connect event. +- ``"CPP"``. Equivalent to ``"CP"`` if ``SCAN=Passive``. Otherwise behaves like ``"NPP"``. + +``sevr`` controls if and how alarm state of target PV is applied to Maximize Severity. + +- ``"NMS"`` (default) Target PV severity is not considered. +- ``"MS"`` All target PV severities are considered. +- ``"MSI"`` Only ``INVALID`` severity is considered. +- ``"MSS"`` Currently equivalent to ``"MSI"``. + +``time`` If ``true`` (not default) and the selected field of the target PV has a ``timeStamp`` sub-structure, +then this time will be written to the record ``TIME`` field. +In almost all cases if will also be necessary to set ``field(TSE, "-2")``. + +``retry``. For an output link, and ``true`` (not default), then the most recent incomplete PUT +will be re-tried when the target PV (re)connects. + +``always``. Ignored. ``false`` (default). + +``atomic``. When ``true`` (not default) then ``"CP"`` and ``"CPP"`` link processing will +be done all related records locked (cf. ``dbLockMany()``). +If several records with ``atomic:true`` are linked to different structure fields of the same target this PV, +then all records will be locked together and all resulting processing will be atomic. + +``monorder`` the relative ordering (increasing) of processing of ``"CP"`` and ``"CPP"`` records linked to the same target PV. + +``defer``. If ``true`` (not default) this output link will only cache the value to be PUT, +but will not issue a network operation. +Can be used to update several structure fields in a single network PUT. + +Input Links +=========== + +Creating a ``pva`` link will result in a subscription being made to the target PV. +Updates will be accumulated in a local cache. +Link processing reads the most recent value/alarm/time from this cache. +While disconnected, a link will read the most recent value/time, with an ``INVALID`` alarm severity. :: + + record(longout, "src") { + field(INP, {pva:{pv:"target:pv"}}) + } + +To trigger record processing when a monitor update arrives, +add the ``proc:"CP"`` modifier. :: + + record(longout, "src") { + field(INP, {pva:{ + pv:"target:pv", + proc:"CP" + }}) + } + +Output Links +============ + +The default behavior of a ``pva`` output link is to write the link value into a local cache, +and then immediately flush that cache and into a network PUT operation. +``defer:true`` allows prevents a link from immediately flushing, +which allows changes to multiple fields to be combined into a single PUT (eg. writing to :ref:`grouppv`). + +By default, an output link will write the ``.value`` structure field of the target PV. +Any processing is at the discretion of the server. +(hint, look for ``pp(TRUE)`` or ``pp(FALSE)`` in ``*Record.dbd``) :: + + record(longout, "src") { + field(OUT, {pva:"target:pv"}) + } + +or equivalently: :: + + record(longout, "src") { + field(OUT, {pva:{ + "pv":"target:pv" + }}) + } + +Additionally, as with DB links, a link may request control of target processing +by setting the ``proc:`` key with ``true`` / ``"PP""``, or the opposite with +``false`` / ``"NPP"``. + +Forward Links +============= + +A ``pva`` forward link will send an empty PUT request (no field changes) to the target PV with ``proc:true``. +If the target PV is a record, then this is equivalent to a PUT of ``.PROC``.