openonload-beta20100730 Release Notes
=====================================

 This release is a BETA release.  It contains known bugs as well as unknown
 ones, and is not suitable for use in production systems.

 These release notes describe the major new features, and known limitations
 and bugs.


----------------------------------------
802.1Q VLANs
------------

 Status: Feature complete.  Testing in progress.

 Traffic passed over a VLAN interface over a Solarflare port is
 accelerated.

 VLANs over bonded interfaces are not yet supported.  They may work, but
 are entirely untested.


----------------------------------------
Bonding / Teaming
-----------------

 Status: Basics working.  Incomplete.  Known bugs.

 Traffic passed over certain types of bonded interfaces is accelerated.

 What is accelerated?
  - Bonds containing only SFC interfaces.
  - Bond mode 1 (active_backup) and mode 4 (LACP).
  - Bond xmit_hash_policy is layer2.

 Caveats: 
  - 2.6.16 kernels and later only, bonding module v3.0.0 and later only.
  - Kernel must have sysfs support.
  - Other hash policies coming soon.
  - balance_xor (mode 2) coming soon.
  - Mixing SFC interfaces with non-SFC in a bond may cause problems.
  - The IP_MULTICAST_IF option is not yet supported for bonded interfaces.
  - The IP_PKTINFO option does not work with bonded interfaces yet.
  - ARP replies do not make it into the Onload control plane promptly when
     bonds are used.  This can cause initially poor performance and some
     TX loss.  Fix in progress.

 Notes:
  - Bonds that are accelerated should be accompanied by a message in the
    system log:
       [onload] Accelerating bond0 using OpenOnload

  - If a bond cannot be accelerated, there will be a message like this:
       [onload] Not accelerating bond0 using OpenOnload

  - Turn on debug logging for bonding:
       echo 0x20001 >/sys/module/onload/parameters/oo_debug_bits

  - All bonding support can be removed at compile time by setting
    CI_CFG_TEAMING to 0 in src/include/ci/internal/transport_config_opt.h

  - The EF_TEAMING configuration option does not currently do anything.


----------------------------------------
Epoll
-----

 Status: Should work for many apps.  Known bugs.

 The epoll interfaces are now accelerated at user-level.  This is
 particularly valuable in applications that enable spinning (EF_POLL_USEC),
 since a user-level implementation is necessary to avoid interrupts and
 jitter, and minimise latency.

 poll() is likely to give superior performance in most cases, because the
 epoll interface requires locking in order to protect its internal state.

 Known bugs & limitations:
  - Files are removed from the epoll set when the file descriptor is
    closed, rather than when the last reference to the file goes away.

  - Scalability when there are large numbers of sockets is currently poor.

  - Deadlock is possible if a process fork()s concurrently with invoking
    epoll calls.

 Notes:
  - This feature can be disabled at runtime with EF_UL_EPOLL=0.

  - epoll support can be removed at compile time by setting
    CI_CFG_USERSPACE_EPOLL to 0 in
    src/include/ci/internal/transport_config_opt.h


----------------------------------------
Other notes
-----------

 There is some performance regression in this beta release.  This will be
 addressed before the full release.

 Testing has been limited to RHEL5 64-bit so far.  Other distros and
 kernels may work, but no guarantees.  (Of course, we don't actually
 guarantee that it will work on RHEL5 either.  See above!)