From 879cb1033b59c2b17e6a256ca8244bbdcddd1f25 Mon Sep 17 00:00:00 2001 From: Michael Davidsaver Date: Thu, 9 Apr 2020 14:04:25 -0700 Subject: [PATCH] doc --- documentation/building.rst | 25 +++++++++++++++ documentation/cli.rst | 62 ++++++++++++++++++++++++++++++++++++++ documentation/details.rst | 54 +++++++++++++++++++++++++++++++++ documentation/index.rst | 25 +++++++++++---- 4 files changed, 160 insertions(+), 6 deletions(-) create mode 100644 documentation/cli.rst diff --git a/documentation/building.rst b/documentation/building.rst index 90a0d7e..8dc9dce 100644 --- a/documentation/building.rst +++ b/documentation/building.rst @@ -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 < 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. diff --git a/documentation/cli.rst b/documentation/cli.rst new file mode 100644 index 0000000..6fc52a0 --- /dev/null +++ b/documentation/cli.rst @@ -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 `_ 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:". + +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 ...". diff --git a/documentation/details.rst b/documentation/details.rst index f6b0e0b..f5c4f42 100644 --- a/documentation/details.rst +++ b/documentation/details.rst @@ -1,3 +1,57 @@ +.. _reportbug: + +Reporting a Bug +=============== + +Before reporting a bug, please check to see if this issue has already been `reported `_. + +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 `_ 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 ===== diff --git a/documentation/index.rst b/documentation/index.rst index 2277287..0545aa6 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -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 `_ 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 `_ and +`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 `_ 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 `_ >=3.15.1 * `libevent `_ >=2.0.1 * (optional) `CMake `_ >=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