From 3596a65afceeca24aa5a64af67b2804eb0fe192c Mon Sep 17 00:00:00 2001 From: Michael Davidsaver Date: Fri, 13 Mar 2020 21:59:37 -0700 Subject: [PATCH] doc --- documentation/building.rst | 50 +++++++------------------------------- documentation/details.rst | 30 +++++++++++++++++++++++ documentation/index.rst | 1 + 3 files changed, 40 insertions(+), 41 deletions(-) create mode 100644 documentation/details.rst diff --git a/documentation/building.rst b/documentation/building.rst index cbc24a3..07ffef0 100644 --- a/documentation/building.rst +++ b/documentation/building.rst @@ -3,22 +3,14 @@ Building from Source Begin be fetching all needed source. :: - git clone https://github.com/mdavidsaver/pvxs.git + git clone --recursive https://github.com/mdavidsaver/pvxs.git git clone --branch 7.0 https://github.com/epics-base/epics-base.git - # omit if installing libevent from RPM or DEB package - wget https://github.com/libevent/libevent/releases/download/release-2.1.11-stable/libevent-2.1.11-stable.tar.gz Prepare the PVXS source tree: :: cat < pvxs/configure/RELEASE.local EPICS_BASE=\$(TOP)/../epics-base EOF - # omit if installing libevent from RPM or DEB package - cat < pvxs/configure/CONFIG_SITE.local - USR_CPPFLAGS += -I$PWD/libevent-install/include - USR_LDFLAGS += -L$PWD/libevent-install/lib - USR_LDFLAGS += -Wl,-rpath,$PWD/libevent-install/lib - EOF Install or build libevent >=2.0 @@ -34,20 +26,13 @@ On Debian/Ubuntu. :: apt-get install libevent2-dev -To build from source on a \*NIX host: :: +To build from source (Requires `CMake `_): :: - tar -xzf libevent-2.1.11-stable.tar.gz - (cd libevent-2.1.11-stable \ - && ./configure --prefix $PWD/../libevent-install \ - && make install) + make -C pvxs/bundle libevent # implies .$(EPICS_HOST_ARCH) -Alternately, building from source with CMake. -On Windows this is possible with `CMake `_ and `Git Bash shell `_ installed. :: +For additional archs: eg. :: - tar -xzf libevent-2.1.11-stable.tar.gz - (cd libevent-2.1.11-stable \ - && cmake -DCMAKE_INSTALL_PREFIX:DIR=$PWD/../usr .. \ - && cmake --build . --target install) + make -C pvxs/bundle libevent.linux-x86_64-debug Build Base and PVXS: :: @@ -60,26 +45,9 @@ of PVXS, or building on a new host. :: make -C pvxs runtests Cross-compiling libevent2 -------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^ -libevent may be built with either autotools (aka. configure script) or CMake. -On Linux cross compiling with autotools is likely easest, and is well documented elsewhere. -The basic recipe is to add a target triple (eg. x86_64-w64-mingw32): :: +The bundled libevent may be built for some cross compile targets. +Currently only cross mingw. :: - ./configure --host= ... - -It is then necessary to each build to a different prefix (eg. "$PWD/libevent-install" above) -and configure these differently in "pvxs/configure/CONFIG_SITE.local". -eg. with a mingw cross build. :: - - tar -xzf libevent-2.1.11-stable.tar.gz - (cd libevent-2.1.11-stable && ./configure --prefix $PWD/../libevent-host && make install) - (cd libevent-2.1.11-stable && ./configure --host=--host=x86_64-w64-mingw32 --prefix $PWD/../libevent-mingw && make install) - cat < pvxs/configure/CONFIG_SITE.local - USR_CPPFLAGS_linux-x86_64 += -I$PWD/libevent-host/include - USR_LDFLAGS_linux-x86_64 += -L$PWD/libevent-host/lib - USR_LDFLAGS_linux-x86_64 += -Wl,-rpath,$PWD/libevent-host/lib - USR_CPPFLAGS_windows-x64-mingw += -I$PWD/libevent-mingw32/include - USR_LDFLAGS_windows-x64-mingw += -L$PWD/libevent-mingw32/lib - USR_LDFLAGS_windows-x64-mingw += -Wl,-rpath,$PWD/libevent-mingw32/lib - EOF + make -C pvxs/bundle libevent.windows-x64-mingw diff --git a/documentation/details.rst b/documentation/details.rst new file mode 100644 index 0000000..f6b0e0b --- /dev/null +++ b/documentation/details.rst @@ -0,0 +1,30 @@ +Notes +===== + +Misc. notes on design and Implementation. + +* All Server and client Context instances listening on the same UDP port# within a process + will share a single UDP socket. + +* The UDP local multicast fanout aspect of the PVA protocol is not implemented. + +* Client UDP search retry follows a linear backoff starting from 1 second + and stepping to 30 seconds. cf. bucketInterval and nBuckets in client.cpp. + +* To level UDP search traffic, search retry may delay a PV for an extra + bucket if the difference in the number of PVs in the desired and subsequent + buckets is too large. + +* Client Context::hurryUp() expires the search bucket timer immediately, + saving up to bucketInterval seconds. + +* Each Value refers points to a pair of FieldDesc and FieldStorage in arrays + of the same. Value::operator[] steps around in these arrays. + +* There is a hidden StructTop which holds the FieldStorage array and holds + a shared_ptr to the FieldDesc array to join ownership of the two. + +* TCP connection buffering will read up to tcp_readahead (cf. conn.h) bytes + while waiting for a complete header. After a header is received, + the larger of tcp_readahead or the message body length is buffered. + diff --git a/documentation/index.rst b/documentation/index.rst index b59a1f8..c2b1003 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -26,6 +26,7 @@ Dependencies server util example + details Indices and tables