RELEASE_NOTES

R4.5.2:
    - Added support for systems with glibc 2.26+ (rhel9, ubuntu, etc.).
      libtirpc is now a required dependency of CPSW.
    - Added GitHub Actions CI/CD configuration
    - Fixed various warnings in the codebase
    - Added the ability to automatically detect HARCH. You no longer
      have to supply this on the command line.
    - Fixed build issue with SWIG
    - Fixed issues on newer versions of GNU/Make
    - Various Makefile improvements


R4.5.1:
    Update the cpsw python bindings to use our python 3.8 conda 
    environment. This fixes an issue where the cpswTreeGui was 
    reported to not launch properly on any RHEL 7 machines due 
    to a missing qt related shared library (libicui18n.so.) It 
    will now be found in the conda environment.
    
    - config.mak : Now points to v2.4 of our conda environment. This
    version is stable and cpsw should not need to be rebuilt even when
    we move on to higher versions of the environment.

R4.5.0: 

    Includes updates in R4.4.1-1.0.1

    Removed Buildroot-2016 targets from build.

    Added rhel7-x86_64 to the .gitignore file.

    Made IOError exception reporting messages useful.

    - src/cpsw_srp_addr.cc : Prints last timeout and number of retries

    - src/cpsw_sval.h : Added the failing path to getVal functions

    Updated the cpsw python bindings to support Python 3 only. Also
    sets unicode as the default encoding/decoding for handling text.

    - src/makefile : Set language_level for compilation to 3 (python)
 
    - src/pycpsw.pyx : Added cython directive to use unicode. Fixes
      an issue where a pycpsw client was failing due to using
      non-ascii characters.

    - src/pycpsw.* : Updated all compiled pycpsw files with the new
      versions generated by cython.


R4.4.2: (Does not include updates in R4.4.1-1.0.1)

    Update the env.slac.sh.in template to support the new buildroot
    version 2019.08.

    Add the buildroot-2016.11.1 targets to the list f ARCHES.

    rssi_bridge: remove infinite while loop from the CMover::threadBody().

R4.4.1-1.0.1:

    Made BadStatusError exception reporting messages useful.

    - config.mak: Added git tag extraction command and assigning tag to
      passed to code through marco

    - src/cpsw_api_user.h: Added new API function prototype returning string of
      current git tag

    - src/cpsw_debug.cc: Added new API function returning string of current
      git tag

    - src/cpsw_error.h: Added an exception status return method to the class

    - src/cpsw_sval.cc: Capture the exception of SRP bad status error, append
      the path information and throw the error again.

R4.4.1:

    src/makefile: Adding cpsw_stdio.h into list of headers as it needed
    by cpsw_error.h.

R4.4.0:

    config.mak: change default arches to buildroot-2019.08

    cpsw_api_builder.h: Remove enum keyword when using a typedef-ed enum.
    This was failing with gcc-8.3.0 on builroot-2019.08

    cpsw_preproc: use main yaml directory if yaml_dir is ""

    cpsw_yaml rework: provide more context in error messages;
    track unrecognized/unused YAML keys. Revamped cpsw_ypp.

    yaml_cpp python wrapper: added YAML::Node::size()

    Support loading YAML and building hierarchy without starting I/O.
	Added new 'startUp()' member function.

    Enhanced (auto-generated) 'git_version_string.h':
      - prefix all symbols as well as the header file name
        itself with a package prefix (cpsw/CPSW in our case).
      - define API version (= major version) in cpsw_api_user.h
        header.

R4.3.1:

    pycpsw.stamp had not been updated

R4.3.0:

    Support for a YAML_PATH env-var. This can list multiple
    directories where to look for YAML files. Useful, e.g.,
    to locate files provided by user or globally which do not
    reside in FW directory.

    Added IEntry::dump() to python wrapper. Print useful info,
    (in particular about networking in case of the root node).

R4.2.0:

    Changed default RSSI retransmission/cumulative-ack timeouts
    from 10/5ms to 100/50ms. Seems to mitigate problems when multiple
    RSSI connections share a network link/stack under heavy load.

    Made RSSI connection parameters (which are proposed to the server
    for negotiation) configurable (via YAML).

    Fixed RSSI reopen-delay. This was always reset to 0. FW does not
    like to be hammered with SYN requests -- it would just never respond.
    We work around this by backing off with an increasing delay.
    If FW is left alone for a while a reconnection succeeds.

    Ensure protocol module's modStartup()/modShutdown() are executed
	only once (the same module can be used by multiple communication
    ports).

    Added support for obtaining interface MTU in libTstAux; this
    is used by rssi_bridge to fragment larger messages.

R4.1.2:
    Removed R4.1.1 tag which had been forced.

    build with boost 1.64.0 and yaml-cpp-0.5.3_boost-1.64.0

    SequenceCommandImpl: a lot of existing YAML write '1' to a command
    in order to execute. Should really be '0' but was never checked by
    previous releases. With support for multiple sub-sequences the
    argument now has a meaning. For sake of backwards compatibility we
    accept any argument in case a sequence is 'one-dimensional'.

    SequenceCommandImpl: permit creation of a ScalVal_Base interface

    yaml_cpsw_merge (program): fixed -Y option

R4.1.0:
    Use python 3.6.1 by default.

    SequenceCommand now supports two-dimensional sequences, i.e.,
    a sequence of command sequences. This can be used to let the
    user pick a sequence at run-time. Handy in combination with
    an attached 'enum' menu. Note, this is accessible via the
    ScalVal_WO user API, not Command.

    Implemented new, more efficient handling of merge keys.

R4.0.0:
    Feature: added cpsw_fs_address which implements access to the underlying
    file-system. (E.g., char-devices).

    Feature: may now create ScalVal_WO interfaces - but writes are marked
    as non-cacheable.

	Feature: cpsw_entry/cpsw_entry_adapt: promoted 'singleInterfaceOnly'
    feature from static- to virtual method. Individual entries can now
    reject creation of multiple interfaces.  This feature is now settable
    from YAML.

    pycpsw BUGFIX: RuntimeError when IYamlFixup::findByName() didn't find a node

    SequenceCommand: now also recognizes 'system(<args>)' for executing
    native scripts, code etc.

    Internal read/write API rework.

    Merged 'swig/cython' branch. Major changes involve c++11 support
    and migration from boost::python to cython. All python wrappers
    have been migrated.

    This means that boost is no longer necessary (if c++11 is available).
    A few headers (lockfree) are still used but can be disabled in
    the configuration file (switch to a native but simple implementation
    which may or may not be less performant).

    API enhancement: added asynchronous 'getVal' + notification via callback.

R3.branch:
    BUGFIX: cpsw_path findByName() crashed when ".." crossed root

    Created a R3.branch tag prior to merging major updates

    The python wrapper is generated with CYTHON by default. Boost is
    still supported (in case the new cython wrapper makes problems).
    Experimental support for SWIG is also available. Eventually, however,
    BOOST and SWIG will be deprecated and phased out.

    Internal Modification: call open/close only on the adapters that
    perform I/O. This makes the python wrapper simpler.

    BUGFIX: stack overrun in udpsrv

    Feature: cpsw_mem_dev: support 'offset' property when mapping a
        file descriptor.

    Bugfix: Ipath::parent() implementation was wrong; caused segfault.
    (merged from R3.5.branch)

    Bugfix: cpsw_bufq.cc: If multiple threads sleep in
            CEventBufSync::getSlot() some may never wake up!

    FIX: There was a subtle change in the implementation of YAML
        maps in yaml-cpp v0.6.2: When a non-existing key is looked
        up with

            YAML::Node operator[](const Key &k);

        then an 'invisible' new entry is added to the map.
        We can iterate through the new map and won't see this new
        entry (unless it was explicitly created e.g., by an
        assignment:  'map[key] = value;'.

        This behaviour was already the same in 0.5.3. What has
        **changed** however, is that under 0.6.3 this lookup
        operation **breaks** existing iterators, i.e,

           YAML::const_iterator my_itr( map.begin() );
           YAML::const_iterator my_end( map.begin() );

           if ( ! map[nonexisting_key] ) {
               // lookup of non-existing key broke iterators
               // under 0.6.2 -- it used to work fine under
               // 0.5.3...
               while ( my_itr != my_end ) {
                   // !!!MAY SEGFAULT HERE!!!
               }
           }

        In order to perform a lookup which does not modify the
        map we must use ('const' attribute overload of operator)

           const YAML::Node operator[](const Key *k) const;

        which is IMHO very confusing and error-prone. Unfortunately
        the API lacks a 'find' member analogous to std::map's...

    Feature: Provide file/line info when loading YAML fails due
        to parser errors.

    Feature: When performing an RMW operation over SRP that spans
        multiple words then read back (up to a max.) multiple
        words in a single read operation.

    Feature: Support C++11; reduce dependency on boost if C++11
        is used. Boost is still used internally but not visible
        from the API.

    Feature: Support SRP 'posted' writes. This is now the default.
        However, the write mode can be set from YAML. Future API
        additions could override the default for each individual
        SRP operations. Posted writes should be just fine, however.
        Interspersed reads always serve as synchronization points,
        i.e., all writes and reads over a single SRP VC are issued
        (and executed on target) strictly in order.

    Feature: NetIODev supports 'rssiBridge' property. When set then
        CPSW contacts the bridge's RPC service to learn the TCP port
        serving <ipAddress>:<port> on the target.
        I.e., if the 'normal' YAML says

          ipAddr: 192.168.2.10
          ...
            UDP:
              port: 8198
            RSSI:

        and is changed into

          ipAddr:     192.168.2.10
          rssiBridge: cpu-b084-hp01
          ...
            UDP:
              port: 8198
            RSSI:

        then the code uses a RSSI bridge at cpu-b084-hp01 to
        proxy traffic to 192.168.2.10:8198 off that bridge.

        The RPC service takes care of remapping UDP to TCP
        ports in case multiple bridges are running (connecting
        to different targets).

    Feature: NetIODev supports 'socksProxy' property (SOCKS_PROXY env-
        var is also supported) for selecting a proxy.

	Feature: Added SOCKS support for TCP connection (code stolen from
	    my implementation for EPICS.

    Feature: rssi_bridge enhancements:
      - added '-u' option to control for individual ports whether RSSI
        is to be used or not (for bare UDP ports).
          -> -p <port> tunnels an UDP/RSSI connection via TCP
          -> -u <port> tunnels a bare UDP connection via TCP
      - added connection handler. UDP side is only connected once
        a TCP connection is accepted. The old behavior (UDP side is
        connected to FPGA immediately) is available via '-C' option.

        This feature (*without* -C) is useful as it allows the bridge
        to be started with a standard set of ports. It is then up to
        the remote peer (which has the YAML) to decide which ports
        to actually use.

    Merge:  FIX for depacketizer V2 (SOF bit sometimes not cleared
            in non-first fragments).

    Merge:  depacketizer V2 support (from master)

    Merge:  Set default for SRP retryCount to 0 if transport is RSSI
            or TCP

    Merge:
    CFreeList now supports allocate_shared() (single allocation
    from free-list)

    Convert IntFields with bitSize > 64 to be converted to
    (hex) strings without truncating them (when read as CString).

    Fixed MTU calculation for RSSI and DEPACK

    Support for native endianness (ScalVal)

    Bugfix: TDESTMux2: missing inintialization of class member causing segfault.

    Bugfix: IYamlFixup::findByName() corrupted YAML hierarchy.

    Bugfix: (in udpsrv, i.e., test code): incorrect use of lock guard
            lead to no mutex protection (in simulator only)!

    Bugfix: RSSI protocol module 'push' with absolute timeout would
            pop from underlying queue instead of pushing.

    Fix:    test driver for streams over unreliable transport should use
            some margin of acceptable errors. This was set to 22% (builder
            API) but when the same test was run with a YAML hierarchy the
            corresponding option was not set to relax the acceptable error
            margin. (Merged from R3.5.branch.)

R3.7.branch

	Feature: added 'getPath()', 'getConstPath()' to ICommand

R3.6.6

    Bugfix: cpsw_bufq.cc: If multiple threads sleep in
            CEventBufSync::getSlot() some may never wake up!

R3.6.5 (merged)

    Guard:  Reject newer YAML properties which require a more recent
            version of CPSW:
              depack/protocolVersion:
              rssiBridge
              socksProxy

R3.6.4

    Added i686 and zynq (arm) targets

R3.6.3

    Removed buildroot-2015 target

R3.7.branch

    Bugfix: path was clobbered (incorrect NELMS) during 'explore' if tail
            was an array.

    Bugfix: protocol stack builder always used depacketizer if no SRP

	Pycpsw: release GIL while blocking to read/write a stream.
            (hopefull it is OK and python doesn't alter the
            buffer state; the code we're executing with the GIL
            unlocked is strictly non-python, of course)

    Feature: block all signals in newly created threads.

    Bugfix: (jira ESLCOMMON-178) when loading an IntField config from
            YAML and the IntField has an enum menu then providing numerical
            values in the config file didn't work.


    Changed IYamlFixup; the callback now gets two nodes
    passed in. The root node of the CPSW hierarchy and
    the top node (which might be outside of the root)

    Also: the python method name was changed from 'fixup'
    to '__call__' (to match c== operator()).

R3.7.branch

    Feature: Added support for fragmentation (packetizer) of outgoing
            traffic.

    Protocol Stack: changed semantics of 'processOutput/processInput'.
            these can now 'edit' buffer chains in a more flexible
            manner.

    Feature: added 'emitNode' to yaml_cpp wrapper. Convert
    node hierarchy to string (which can be written to a file).

    Bugfix: proto_stack_builder::useDepack() should not set
    other params

    Moved 'getEncoding()' from IScalVal_Base to IVal_Base.

    Python: Stream.read() has an optional 'offset' argument
    (same as underlying IStream::read())

    MemDev: FIX - read(NULL) means that the user wants to
    know if data are available; must return nonzero.

    Added support for thread priorities. All internal threads
    in the protocol stack can be configured (from YAML) with
    a priority (see doc/README.yamlDefinition).

    New features: a 'NullDev' which is not backed by anything.
    Useful for testing/debugging because any YAML hierarchy
    can be loaded w/o need for hardware (or a lot or memory
    as with MemDev that covers a large address space).

    Python: a minimal wrapper for yaml-cpp was added; enough
    to support basic fixups.

    Python: Added YamlFixup so that a fixup (LoadYamlFile etc.)
    can be written in python. NOTE: this requires yaml-cpp
    python bindings which must be implemented/obtained elsewhere,
    i.e., they are NOT part of cpsw.

R3.6.1
	Makefile fixes

	Added more targets to .PHONY:
	Recurse 'test' into SUBDIRS, POSTBUILD_SUBDIRS
	Moved 'test' target to rules.mak
	Let top-level 'makefile' use 'rules.mak' & friends

R3.6.0
    Feature/Fix: PYTHON: instantiate Streams via a context manager;
             i.e., streams can only be used inside a 'with' block!
             *** NOTE *** this is a python interface change; it is
             no longer possible to read from a newly created stream
             (Stream.create() now returns a context manager)!
             Instead, you must read from the block of a 'with'
             statement:

                with Stream.create() as s:
                  s.read( buf )

    Feature: derive IStream from IVal_Base; allows to obtain
             basic properties from the stream interface.

R3.5.4	    4-May-2017	   Till Straumann (strauman)
    Bugfix: Path->toString() segfault
    UDP/TCP: ignore empty buffer chains (but don't deref!)
    Bugfix: when releasing a buffer our allocator never called the destructor
    Changed exceptions in cpsw_buf.cc from InternalError -> InvalidArgError

R3.5.3      14-Mar-2017    Till Straumann (strauman)
    Improved error message when reading config fails
    Use buffers getAvail() instead of getCapacity when reading RSSI header
    add getAvail to udpsrv_util's buffer implementation
    Bugfix: udpsrv's TCP handler
    cpsw_stream_tst should always use a TDEST muxer
    Bugfix: cannot collapse writes when the caller supplies bitmasks
    Bugfix: must not use header after buffer ownership is relinquished
    Bugfix: cpsw_event.cc - shared_pointer released prematurely

R3.5.2      08-Mar-2017    Till Straumann (strauman)
    TCP must not discard messages but wait for queue to drain
    Cleanup in config.mak
    Added ioQueSend() (blocking send with timeout)
    Use blocking send when a reliable channel is involved (TCP/RSSI)

R3.5.1      5-Mar-2017     H. Slepicka (slepicka)
    Changes on the package structure
        Move source code to src folder
    Changes on products name
        linux-x86_64 -> rhel6-x86_64
        linuxRT-xxxx -> buildroot-<version>-xxxx
    Changes on rules.mak file
        Add uninstall rule
        Include .html and other docs at the install rule
    Add top-level Makefile