epics/pvxs
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc

Browse Source
This commit is contained in:
Michael Davidsaver
2025-08-08 16:43:24 -07:00
parent de12bc181e
commit 3727052991
7 changed files with 56 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/building.rst
+1 -1
View File
@@ -103,4 +103,4 @@ Add the pvxs library as a dependency to your executable or library. eg. ::
libevent will be automatically added for linking.
For those interested, this is accomplished with the logic found in
"cfg/CONFIG_PVXS_MODULE".
``$(INSTALL_LOCATION)/cfg/CONFIG_PVXS_MODULE``.
documentation/conf.py
+20 -3
View File
@@ -17,10 +17,26 @@
# sys.path.insert(0, os.path.abspath('.'))
import time
import os
def git_date():
from subprocess import check_output
try:
return check_output(['git','log', '-n1','--format=%cs']).decode('ascii')
except Exception as e:
print(f'Unable to find Git revision date: {e}')
return time.strftime('%Y-%m-%d')
def git_describe():
from subprocess import check_output
try:
return check_output(['git','describe','--tags']).decode('ascii')
except Exception as e:
print(f'Unable to find Git revision: {e}')
return None # fallback
def read_version(fmt):
import os, re
parts = {}
with open(os.path.join('..','configure','CONFIG_PVXS_VERSION'), 'r') as F:
for line in F:
@@ -36,11 +52,12 @@ copyright = time.strftime('%Y Michael Davidsaver and Osprey DCS LLC')
author = 'Michael Davidsaver'
# The short X.Y version
version = read_version('{PVXS_MAJOR_VERSION}.{PVXS_MINOR_VERSION}')
version = git_describe() or read_version('{PVXS_MAJOR_VERSION}.{PVXS_MINOR_VERSION}.{PVXS_MAINTENANCE_VERSION}')
print("VERSION", version)
# The full version, including alpha/beta/rc tags
release = read_version('{PVXS_MAJOR_VERSION}.{PVXS_MINOR_VERSION}.{PVXS_MAINTENANCE_VERSION}')
release = version
today = git_date()
# -- General configuration ---------------------------------------------------
documentation/example.rst
+1 -1
View File
@@ -2,7 +2,7 @@ Examples
========
Example are built, but not installed.
They can be found under example/O.\*
They can be found under ``example/O.*``
Latest versions https://github.com/epics-base/pvxs/blob/master/example/
documentation/index.rst
+19 -13
View File
@@ -1,13 +1,9 @@
PVXS client/server for PVA Protocol
===================================
This module provides a library (libpvxs.so or pvxs.dll) and a set of
CLI utilities acting as PVAccess protocol client and/or server.
PVXS is functionally equivalent to the
`pvDataCPP <https://github.com/epics-base/pvDataCPP>`_ and
`pvAccessCPP <https://github.com/epics-base/pvAccessCPP>`_ modules,
which it hopes to eventually supplant (Ok, the author hopes).
This module provides a low-level PVAccess protocol :ref:`clientapi`, :ref:`serverapi`,
a set of CLI utilities,
as well as high-level integration with the EPICS IOC Process Database (aka. :ref:`qsrv2`)
- VCS: https://github.com/epics-base/pvxs
- Docs: https://epics-base.github.io/pvxs
@@ -15,46 +11,56 @@ which it hopes to eventually supplant (Ok, the author hopes).
- :ref:`contrib`
Dependencies
------------
* A C++11 compliant compiler
* GCC >= 4.8
* Visual Studio >= 2015 / 12.0'
* Visual Studio >= 2015 / 12.0
* clang
* `EPICS Base <https://epics-controls.org/resources-and-support/base/>`_ >=3.15.1
* `libevent <http://libevent.org/>`_ >=2.0.1 (Optionally bundled)
* (optional) `CMake <https://cmake.org/>`_ >=3.10, only needed when building bundled libevent
See :ref:`building` for details.
Download
--------
Releases are published to https://github.com/epics-base/pvxs/releases.
See :ref:`relpolicy` for details.
Getting Started
---------------
See :ref:`building`, and :ref:`includepvxs`.
With QSRV2 included, all local database records will be served via PVA.
For most user IOCs, no further action is necessary.
Contents
--------
.. toctree::
:maxdepth: 3
:caption: Contents:
overview
netconfig
example
building
cli
ioc
value
client
server
ioc
util
details
releasenotes
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
This document describes version |release| and earlier.
documentation/ioc.rst
+9 -6
View File
@@ -1,5 +1,7 @@
.. _iocintegration:
IOC Integration
###############
===============
.. code-block:: c++
@@ -9,12 +11,13 @@ IOC Integration
The separate ``pvxsIoc`` library exists to run a PVXS server as part of an IOC.
See also :ref:`includepvxs`.
IOC Integration respects the **$PVXS_LOG** as well as the **$EPICS_PVA\*** environment variables.
IOC Integration respects the **$PVXS_LOG** as well as the **$EPICS_PVA\*** environment variables
to configure :ref:`logconfig`.
Changes to this environment variable are possible prior to
calling ``*_registerRecordDeviceDriver(pdbbase)``.
IOC shell
^^^^^^^^^
---------
The ``pvxsIoc`` library adds several IOC shell functions which apply to all PVs
served by the Integrated PVA server.
@@ -35,18 +38,18 @@ served by the Integrated PVA server.
May be requested when reporting a bug.
Adding custom PVs to Server
^^^^^^^^^^^^^^^^^^^^^^^^^^^
---------------------------
.. doxygenfunction:: pvxs::ioc::server
.. _qsrv2:
QSRV 2
######
======
Beginning with PVXS 1.2.0 the functionality of `QSRV <https://epics-base.github.io/pva2pva>`_
is replicated in the ``pvxsIoc`` library.
As of 1.3.0 this feature preview is considered **beta** level with equivalent functionality.
As of 1.4.0 QSRV2 is considered to be a complete replacement.
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
documentation/overview.rst
+4 -4
View File
@@ -93,7 +93,7 @@ Comparison with pvDataCPP
-------------------------
The data component (`pvxs::Value`) of PVXS corresponds with the `pvDataCPP <https://github.com/epics-base/pvDataCPP>`_ module.
It also incorporates parts of the `normativeTypesCPP <https://github.com/epics-base/normativeTypesCPP>`_ module (cf. `ntapi`).
It also incorporates parts of the `normativeTypesCPP <https://github.com/epics-base/normativeTypesCPP>`_ module (cf. :ref:`ntapi`).
The most obvious difference in the design of pvData vs. PVXS is that the "class PVField" hierarchy is replaced
with the single `pvxs::Value` class.
@@ -187,7 +187,7 @@ Testing for changed fields
^^^^^^^^^^^^^^^^^^^^^^^^^^
While the PVA protocol is based around the idea of transferring partial updates
to some structure fields, the PVField container classes don't incorporate this.
to some structure fields, the PVField container classes do not incorporate this.
Instead, it is necessary to handle an separate BitSet object provided alongside each PVStructure.
With PVXS, tracking of changed (or valid) fields is built into the Value class.
@@ -331,11 +331,11 @@ Comparison with pvAccessCPP
---------------------------
The client and server components of PVXS are heavily influenced by the `pvac <http://epics-base.github.io/pvAccessCPP/group__pvac.html>`_ and `pvas <http://epics-base.github.io/pvAccessCPP/group__pvas.html>`_ APIs of pvAccessCPP.
eg. the analog of pvac::ClientProvider is `pvxs::client::Context`, while pvas::Server and pvas::SharedPV correspond with `pvxs::server::Server` and `pvxs::server::SharedPV`.
eg. the analog of pvac::ClientProvider is `pvxs::client::Context`, while pvas::Server and ``pvas::SharedPV`` correspond with `pvxs::server::Server` and `pvxs::server::SharedPV`.
The principle practical difference is that PVXS uses functors where the other APIs using interface classes.
For example, sub-classing pvac::ClientChannel::GetCallback to provide a getDone() callback.
For example, sub-classing ``pvac::ClientChannel::GetCallback`` to provide a getDone() callback.
.. code-block:: c++
documentation/util.rst
+2
View File
@@ -1,6 +1,8 @@
Misc
====
.. _logconfig:
Logging
-------