pvalink doc

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

documentation/ioc.rst

@@ -46,10 +46,14 @@ QSRV 2
 
 Beginning with PVXS 1.2.0 the functionality of `QSRV <https://epics-base.github.io/pva2pva>`_
 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

documentation/pvalink.rst

@@ -0,0 +1,169 @@
+.. _pvalink:
+
+PVA Links
+#########
+
+Since UNRELEASED
+
+JSON Reference
+==============
+
+A PVA link `JSON schema <pvalink-schema-0.json>`_ 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``.