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
2020-04-09 14:04:25 -07:00
parent 6f39d9ae7c
commit 879cb1033b
4 changed files with 160 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/building.rst
+25
View File
@@ -1,3 +1,5 @@
.. _building:
Building from Source
====================
@@ -42,6 +44,11 @@ Build PVXS: ::
make -C pvxs
.. _runtests:
Running Tests
^^^^^^^^^^^^^
It is recommended to run automatic unittests when building a new (to you) version
of PVXS, or building on a new host. ::
@@ -54,3 +61,21 @@ The bundled libevent may be built for some cross compile targets.
Currently only cross mingw. ::
make -C pvxs/bundle libevent.windows-x64-mingw
Including PVXS in your application
==================================
Including PVXS in an application/IOC using the EPICS Makefiles is straightforward.
Add PVXS to the application configure/RELEASE or RELEASE.local file. ::
cat <<EOF > configure/RELEASE.local
PVXS=/path/to/your/build/of/pvxs
EOF
Then add the pvxs library as a dependency to your executable or library. eg. ::
PROD_IOC += myioc
...
myioc_LIBS += pvxs
libevent will be automatically added for linking.
documentation/cli.rst
+62
View File
@@ -0,0 +1,62 @@
Command Line Tools
==================
A basic set of command line tools are currently provided to facilitate testing and development.
End users should prefer the CLI tools from the `pvAccessCPP <https://github.com/epics-base/pvAccessCPP>`_ module
for day to day use.
* pvxcall - analogous to pvcall
* pvxget - analogous to pvget
* pvxinfo - analogous to pvinfo
* pvxmonitor - analogous to pvmonitor or "pvget -m"
* pvxput - analogous to pvput
* pvxvct - UDP search/beacon Troubleshooting tool.
Troubleshooting with Virtual Cable Tester
-----------------------------------------
The "pvxvct" executable is capable of listening for UDP searches from PVA clients,
and/or UDP beacons from PVA servers.
Together with "pvxget" they can be used to investigate communications issues.
On the host with the PVA server (IOC or otherwise),
run the following to listen for searches. ::
$ pvxvct -C -P my:random:test:pvname
While this is running, switch to the host where the PVA client resides
and run ::
$ pvxget my:random:test:pvname
If all goes well, the pvxvct process should print several lines
as search requests are received. eg. ::
$ pvxvct -C -P my:random:test:pvname
2020-04-09T19:37:01.146272170 INFO pvxvct 192.168.1.1:47357 Searching for:
2020-04-09T19:37:01.146442772 INFO pvxvct "my:random:test:pvname"
...
Note that pvxvct does not use the $EPICS_PVA* environment variables
and by default listens on "0.0.0.0:5076". Sites using a non-default
port will need to add "-B 0.0.0.0:<port>".
If searches are not seen, then investigate client configuration
($EPICS_PVA_* environment variables), and firewall settings.
If searches are seen, then switch to "pvxget -d ..." and a real PV name.
The output will be very verbose. Look for lines like the following: ::
$ pvxget -d my:real:pv:name
...
2020-04-09T19:44:46.064937960 DEBUG pvxs.client.io UDP search Rx 53 from 192.168.1.1:5076
2020-04-09T19:44:46.064947396 DEBUG pvxs.client.io Search reply for my:real:pv:name
2020-04-09T19:44:46.065151400 DEBUG pvxs.client.io Connecting to 192.168.1.1:5075
2020-04-09T19:44:46.065200101 DEBUG pvxs.client.io Connected to 192.168.1.1:5075
...
2020-04-09T19:44:46.067255960 DEBUG pvxs.client.io Server 192.168.1.1:5075 accepts auth
Repeat with "pvxinfo" in place of "pvxget".
If the "accepts auth" line is seen, but no subsequent error message,
then see `reportbug` and attach the output of "pvxget -d ...".
documentation/details.rst
+54
View File
@@ -1,3 +1,57 @@
.. _reportbug:
Reporting a Bug
===============
Before reporting a bug, please check to see if this issue has already been `reported <https://github.com/mdavidsaver/pvxs/issues>`_.
When composing a new report, please run the included automatic tests "make runtests" and mention the results.
It is enough to mention "All tests successful." if this is so. (see `runtests`)
`Bug reports <https://github.com/mdavidsaver/pvxs/issues>`_ should always include:
* EPICS Base version or VCS commit
* PVXS module version or VCS commit
* libevent version or VCS commit (running "pvxget -V" shows these)
* EPICS host and target archs. (eg. "linux-x86_64")
* Host OS name and version (eg. run "cat /etc/issue")
* Compiler name and version (eg. run "gcc --version")
* The values of any $EPICS_PVA* environment variables which are set.
* Any local/site modifications to PVXS or libevent
* Concise instructions for reproducing the issue.
Additional information which may be relevant:
* Number of network interfaces if more than one.
* Whether clients and/or servers are on the same host or diffrent hosts.
* Whether clients and/or servers are in the same subnet or different subnets
* Whether network traffic crosses between virtual machine(s) and physical host(s).
* Firewall rules on UDP traffic to/from port 5075 or TCP connections to port 5074
* Any local/site modifications to EPICS Base
.. _contrib:
Contributing
============
The recommended path for including changes is through [Pull Request](https://github.com/mdavidsaver/pvxs/pulls).
When changing c++ code please do:
* Indent with 4 spaces. No hard tabs. UNIX style EoL.
* Try to maintain the style of surrounding code.
* Include meaningful code comments where reasonable.
but do not:
* Add any c++ global constructors or destructors in the pvxs library. (Ok in tools, examples, or tests)
When committing changes please do:
* Include a commit message
* Break up changes into multiple commits where reasonable
* Include whitespace only changes as seperate commits
Notes
=====
documentation/index.rst
+19 -6
View File
@@ -1,22 +1,34 @@
PVXS client/server for PVA Protocol
===================================
The canonical version of this page is https://mdavidsaver.github.io/pvxs
Versioned source can be found at https://github.com/mdavidsaver/pvxs
where `issues <https://github.com/mdavidsaver/pvxs/issues>`_ should be reported.
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 equivilant to the
`pvDataCPP <https://github.com/epics-base/pvDataCPP>`_ and
`pvAccessCPP <https://github.com/epics-base/pvAccessCPP>`_ modules,
which it hopes to eventually surplant (Ok, the author hopes).
The canonical version of this page is https://mdavidsaver.github.io/pvxs
Versioned source can be found at https://github.com/mdavidsaver/pvxs ,
which is also where `issues <https://github.com/mdavidsaver/pvxs/issues>`_ should be reported.
See `reportbug`.
Also `contrib` if you are so inclined.
Dependencies
* A C++11 compliant compiler like GCC >= 4.8 or Visual Studio 2015 (12.0)
* A C++11 compliant compiler
* GCC >= 4.8
* Visual Studio >= 2015 (>= 12.0)
* `EPICS Base <https://epics-controls.org/resources-and-support/base/>`_ >=3.15.1
* `libevent <http://libevent.org/>`_ >=2.0.1
* (optional) `CMake <https://cmake.org/>`_ >=3.1, only needed when building bundled libevent
See `building` for details.
Status
------
This module is considered feature complete, but is not yet making releases.
@@ -25,6 +37,7 @@ This module is considered feature complete, but is not yet making releases.
:caption: Contents:
building
cli
value
client
server