
SolarCapture Release Notes
==========================

 This package is a GA release of SolarCapture 1.6.9.

 Refer to the README and SolarCapture User Guide (SF-108469-CD) for more
 information, usage and installation instructions.

 Check the copy of the Release Notes on https://support.solarflare.com for
 any late-breaking updates.


New Features in v1.6.9
----------------------
1) Updated Xilinx copyright notices

2) Beginning with v1.6.9, SolarCapture Pro supports XtremeScale 8000
   series Plus and X2 Plus adapters, without requiring the purchase of a
   separate AppFlex product activation key. 7000 series adapters are no longer
   supported.

3) Support for RHEL8.2


Features removed in v1.6.9
--------------------------
1) Removed Snort DAQ bindings


Known Issues in v1.6.9
----------------------

1) When using a vlan only filter to capture
  a. Multicast packets that match the filter are captured and also
     delivered to the kernel (if it wants them).
  b. Unicast packets with destination MAC equal to the port's MAC address
     are not captured.

2) Ethertype filters do not match IPv4 or IPv6 protocols.  (This is a
   limitation of the adapter firmware rather than of SolarCapture).

3) IP protocol filters do not match UDP and TCP protocols.  (This is a
   limitation of the adapter firmware rather than of SolarCapture).

4) Pools using file backed memory, like those exposed via the shm_export and
   shm_broadcast nodes, will not detect that they are using huge pages unless
   the pool attribute require_huge_pages has been set to 1. This issue can
   manifest itself when sharing a VI pool using huge pages with the
   shm_export or shm_broadcast nodes. In this case the pool will not be
   correctly marked as having huge pages and solar capture will fail to dma map
   the memory resulting in the following error

   sc_pkt_pool_blob_dma_map: WARN: ef_memreg_alloc failed (rc=-28 errno=28 intf=enp1s0f1/enp1s0f1 len=0x1428800 map_len=0x10000)
   ERROR: errno=28 from core/sc_pkt_pool.c:811 in sc_pkt_pool_blob_add():
   sc_pkt_pool_blob_add: ERROR: p0 failed to DMA map (buf_size=1792 n=1050624 inline=1 huge=0,0 netifs=1)

   Setting the attribute require_huge_pages to 1 on the VI will resolve the
   issue.


New Features in v1.6.6
----------------------
1) Support for Arista 48bit timestamp format on 7280 series switches.
   New arista_ts fields "ts_format", "ts_src_mac", "replacement_src_mac".

   7280 series switches may be configured to emit packet timestamps in 48bit or
   64bit formats.  By default the timestamp will be encapsulated in an L2
   header.  With the 48bit format there is an option to replace the ethernet
   header's source MAC field with the timestamp instead of adding an L2 header.

   Note: The old 64bit format is DEPRECATED in SolarCapture.  48bit is now the
   default format for 7280 series switches if ts_format is not specified.

   Examples:
    arista_ts="switch_model=7280;ts_format=48bit"
    arista_ts="switch_model=7280;ts_format=48bit;ts_src_mac=1;strip_ticks=0"
    arista_ts="switch_model=7280;ts_format=48bit;ts_src_mac=1;strip_ticks=0;\\
               replacement_src_mac=aa:bb:cc:dd:ee:ff"

   Refer to the node API documentation's sc_arista_ts section or use
   solar_capture help arista_ts for more information.

2) Support for Arista-Metamako TLVs in cpacket footer.
   New cpacket_ts field "is_metamako".

   Examples:
    cpacket_ts="is_metamako=1"
    strip_fcs=0 cpacket_ts="keep_cpacket_footer=1;is_metamako=1"

   Refer to the node API documentation's sc_cpacket_ts section or use
   solar_capture help cpacket_ts for more information.

3) X2 series NIC support.

4) RX event merging support for Medford adapters. New attribute "rx_merge".
   Use solar_capture_doc attr rx_merge for more information.

5) Bug fixes: Please refer to the ChangeLog for details.


New Features in v1.6.5
----------------------
1) Bug fixes: Several bugs have been fixed, please refer to the ChangeLog
   for details.


New Features in v1.6.4
----------------------
1) Arista 7280 series switch support.  New arista_ts field "switch_model"
   to specify which Arista timestamping protocol to decode.  Currently
   supported options are 7150 (default) and 7280.  Other options for arista_ts
   depend on which protocol is being decoded.

   Examples:
     - arista_ts="kf_ip_dest=0.0.0.0;kf_eth_dhost=00:00:00:00:00:00"
         7150 protocol, identical behavior to previous versions
     - arista_ts="switch_model=7150;kf_ip_dest=0.0.0.0;kf_eth_dhost=00:00:00:00:00:00"
         7150 protocol, same as above but switch_model explicitly set
     - arista_ts="switch_model=7280;strip_ticks=0"
         7280 protocol, strip_ticks turned off.

   Refer to the node API documentation's sc_arista_ts section or use
   solar_capture help arista_ts for more information.

2) Bug fixes: Several bugs have been fixed, please refer to the ChangeLog
   for details.


New Features in v1.6.3
----------------------
1) 8000-series support: This release provides support for SolarFlare's new
   8000-series adapters.

2) Signed rpms: The rpms in this release are digitally signed by SolarFlare.
   To verify the rpms:
   1. Download SolarFlare's certifcates (SF-117279-LS: Solarflare RPM
      Signing Keys) from https://support.solarflare.com.
   2. Unzip the contents and follow the instructions in the readme.
   3. Verify the rpms' signatures using `rpm -v --checksig package.rpm`.

3) Documentation: Added examples of how to customise libpcap bindings.

4) Bug fixes: Many bugs have been fixed, please refer to the ChangeLog
   for details.


New Features in v1.6.0
----------------------

1) Documentation: This release expands the C bindings documentation to
   cover all public APIs.  Built-in nodes are also now documented.  This
   documentation is included in the SolarCapture packages in HTML form and
   can be downloaded as a PDF (SF-115721-CD) from support.solarflare.com.

2) Shared memory: Shared memory allows the transfer of packets between two
   or more SolarCapture processes (solar_balancer, solar_capture,
   solar_libpcap, custom applications) via a shared memory channel.  This
   mechanism supports fanout, and can be used to decouple different parts
   of a processing pipeline.

3) TCP tunnels: Tunnel nodes allow the transfer of packets between two
   SolarCapture processes via a TCP socket.  Each tunnel supports multiple
   input and output links, so that control and data-paths can be
   multiplexed together.  Tunnel nodes allow packets to be streamed to
   other hosts, and allow SolarCapture processing to be distributed over
   multiple hosts.

4) Load balancing: The new solar_balancer utility offers active flow-aware
   load balancing.  It distributes flows to consumers over the new shared
   memory channels.  Consumers can use the C bindings, libpcap or DAQ.

5) Packets with the cPacket trailer can now be decoded with the
   'cpacket_ts' option or sc_cpacket_ts node.

6) A 'postrotate_command' option is supported, to allow a command to be
   executed after each file rotation.

7) New filters on ethertype and IP protocol are supported, subject to
   restrictions (see known issues below).  You may need to upgrade adapter
   firmware to enable these new filter types.

8) Many bugs have been fixed.  Please see the ChangeLog for a complete
   list.

9) There are numerous other improvements: More flexibility, new APIs,
   improved performance, more built-in nodes.  Please see the ChangeLog and
   User Guides for details.


New Features in v1.3.1
----------------------

This section summarises the main features added since the 1.3.0 release.
Refer to the ChangeLog for a full list of bug fixes and other changes.

1) Performance improvements in the core, libpcap and Snort DAQ.

2) Support for forwarding packets at very high rates with packed-stream
   mode.

3) Much improved documentation for the C API, installed at
   /usr/share/doc/solar_capture-$version/c_api.

4) Create directories (if needed) for output files.  This is particularly
   useful when using file rotation and putting output files into
   directories that include the time in their names.

5) Support for RHEL7 (requires OpenOnload-201502 or later).
   Support for RHEL5 is dropped.
   Support for Ubuntu 12.04 LTS, Ubuntu 14.04 LTS and Ubuntu 14.10;
   the release package now includes ".deb" files.
   Refer to INSTALL-deb.txt for installation instructions on Ubuntu.


Known Issues in v1.3.1
----------------------

1) The "require_huge_pages" and "request_huge_pages" attributes only take
   effect on kernel versions 2.6.32 and newer.  On older kernels, the
   attributes are ignored.

2) Packed-stream mode is only supported on kernel versions 2.6.32 and newer.

3) Setting EF_VI_PD_FLAGS in the environment results in a failure if the
   vi_mode attribute is set to "auto" (default) or "packed_stream".

4) If traffic is to be captured from an adapter other than an AOE while
   solar_aoed is running, vi_mode must be set to "normal" or
   "packed_stream".

5) If sfptpd is not running when using hardware timestamps, it is possible for
   all packets to have identical timestamps.  The solution is to start sfptpd.

6) Apparmor, if running, blocks operation of solar_libpcap.
   To use solar_libpcap, apparmor must be disabled or an apparmor profile for
   solar_libpcap must be created.


New Features in v1.3.0
----------------------

This section summarises the main features added since the 1.2.2
release:

1) A new capture-packed-stream firmware variant is now supported.  This allows
   for line rate capture on 7000 series adapters.  Packed stream mode is enabled
   by default in SolarCapture if the capture-packed-stream firmware variant is
   loaded.  This behaviour can be controlled by using the new "vi_mode"
   attribute.

2) Egress capture is now supported on 7000 series adapters.  This adds to
   existing support for egress capture on AOE adapters.

3) SolarCapture threads can operate in interrupt driven mode as well as busy
   waiting.  To select between these, two new command line options have been
   added: capture_busy_wait and writeout_busy_wait.

4) A new packet playback tool called solar_replay has been added.  This allows
   packets from a file in pcap format to be replayed through a Solarflare
   adapter interface with flexible control over replay speed and bandwidth.

5) On 7000 series adapters, SolarCapture can be configured to capture packets
   while preserving the frame check sequence (FCS).

6) A Snort DAQ is included in the package.  This supports the read-file, passive
   and inline modes.

7) Added a new environment variable SC_PCAP_RECV_BATCH to control polling rate
   when using solar_libpcap.

8) solar_capture_doc has been added to help document SolarCapture.  Currently it
   documents all attributes that can be set via SC_ATTR.

9) solar_capture can now accept a config_file option, which specifies a file
   containing a list of arguments, one per line.


New Features in v1.2.2
----------------------

1) Added a new environment variable SC_PCAP_NANOSEC=1 to select nanosecond
   precision when using the libpcap bindings.  This is an alternative to
   using the pcap_set_tstamp_precision() call.  NB. The application using
   libpcap must separately be configured to expect nanosecond precision.


New Features in v1.2.1
----------------------

This section summarises the main features added since the 1.2.0
release:

1) The SolarCapture AOE package has been updated to include
   OpenOnload-201310-u2.

2) Disk capture performance has been improved.

3) A new configuration item for AOE SolarCapture allows balancing of
   transmission buffer space (RHD buffer) across the number of RHD channels
   actually being used.

4) Updated libpcap in solar_libpcap to v1.5.3.
   The following libpcap APIs are now supported:
     pcap_set_tstamp_type()       -- used to request h/w timestamps
     pcap_set_tstamp_precision()  -- used to request nanosec precision

5) New syntax for enabling Arista hardware timestamps.  Instead of:

     solar_capture ... "sc_arista_ts:kf_ip_dest=224.1.2.3;kf_eth_dhost=..."

   instead do:

     solar_capture ... "arista_ts=kf_ip_dest=224.1.2.3"

   If using multicast for the keyframe IP address, you no longer need to
   specify the mac address (kf_eth_dhost).

   When using this new syntax solar_capture will automatically install a
   stream filter to capture the keyframes if needed.

6) Arista hardware timestamps can now be used with multiple capture cores,
   provided that a Flareon (or future) adapter is used.


New Features in v1.2.0
----------------------

This section summarises the main features added since the 1.0.2
release:

1) libpcap support
 - applications using the libpcap API can link against SolarCapturePro
 and capture and/or inject packets.

2) Hardware timestamp support for the SFN7000-series and AOE adapters
 - SolarCapturePro can utilise the hardware receive timestamps

3) Support for software based filtering.
 - SolarCapturePro can filter packets in software using user-provided
 filters in the BPF syntax.

4) "Sniff" mode
 - On suitable hardware (7000-series and AOE) SolarCapturePro can
 capture packets without stealing them from regular receivers

5) Improved diagnostics and statistics
 - solar_capture_monitor can show packet rate, bandwidth and Arista
 timestamping statistics.

6) AOE support
 * Capturing in sniff and steal modes.
 * Richer filtering specification.
 * Capture of rx and tx on both ports.
 * 2Gb of buffering per capture point.
 * Loss-less delivery to the host CPU.
 * Hardware timestamps.

7) Application Clustering
 - spread capture load across a set of VIs so that multiple
 threads/processes on different CPUs can cooperate to process it.



Support
-------

 Please contact your local Solarflare support representative or email
 <support@solarflare.com>.


Copyright
---------

 (c) Copyright 2015 – 2019 Xilinx, Inc. All rights reserved.
 Please see "Software_License_Agreement_click for SolarCapture Pro.doc"
 for terms of use.
