This is a beta quality code drop of IGMPv3 and Source-Specific
Multicast for IPv4 in FreeBSD 8-CURRENT.
It is intended to be backportable to 7-STABLE at some stage.
VIMAGE and IFF_NEEDSGIANT are currently supported.

As of 2009-03-09, the code is committed to FreeBSD 8-CURRENT.

The bulk of the work lay in making it thread safe.
This code is believed to be solid with respect to lock ordering.

The state-change generation and socket-layer state machinery
is now believed correct, although this has not been proven.
Testing with simulated v2 and v3 queriers has been performed,
and manually verified with PCS.  WITNESS pass OK, no unexpected
lock-order reverals. Simulated SMP runs seem OK (2 cores, QEMU).

There may be some issues with recorded sources. It seems best at
this point to commit this to get wider coverage.

KNOWN BUGS:
 Userland:
  * ifmcstat kvm backend dumps core when attempting
    to print source lists with -v flag.
    Most likely this is in the RB-tree traversal, which is
    tricky to do with KVM as every pointer dereference requires
    an explicit KVM read. Stubbed out for now.

IMPLEMENTATION NOTES:
 * BSD RB-trees are used as the disjoint-set data structure.
   Differences in sets are represented as flags on each node
   at in_msource and ip_msource level. As state changes flow
   from socket layer to IGMP layer, reference counts of
   interested listeners are maintained for each source.
   The path is optimized for the ASM case.
 * The input path only supports up to 1 mbuf's worth of sources
   for a group-source query. The refactoring involved is not too hard,
   it just requires verification on a real SSM enabled network.
 * IGMPv3-Lite is not yet supported, adding support should be trivial.
 * Known LORs with this code:
  At CTR in in_joingroup(): Giant/in_multi_mtx
   Harmless. Only present with KTR enabled, for some reason
   kbdmux wants to take Giant for keyboard state update.
   --> jhb says it's a known issue w/KTR_VERBOSE.
 * VIMAGE issues:
  * .pr_init can no longer be reliably used with VIMAGE, due to the
    initialization order; therefore the init is refactored to use
    a module attach routine as per VIMAGE implementation docs.

OUTSTANDING TASKS:
test: with real queriers, i.e. XORP.
      PCS not working due to uart issues; need to simulate querier or
      deploy on real network. Ed Schouten aware of uart/tty issue.
test: igmpv2 compatibility. Believed correct, a sure test needs
      exposure on a network with multiple multicast listeners.
test: igmpv1 compatibility. Legacy, someone else can do it...
test: real hot if/detach at hardware level, to verify no panics.
      the code is careful to check interfaces still exist.
test: non-simulated SMP, 2 core minimum.

optimize: review if we need more inm_reap() calls.
optimize: review if we need more inm_clear_sources() calls.
optimize: use set symmetric difference loop where key spaces overlap,
          rather than performing lookup from RB root every time.

management: add an ifmcctl tool, if/when folk want MANET bits.
management: add per-interface igmp version tweak via sysctl.
redundant: igmp default version sysctl has no immediate effect
           on running interfaces, and should be a boot-time tunable.
           add the functionality to ifmcctl.

delivery: make code suitable for backport to 7-STABLE at most.
          p4: //depot/vendor/freebsd_7/... ?
optimize: eliminate netisr in 8-CURRENT when IFF_NEEDSGIANT obliterated.
optimize: when netisr goes away, remove VIMAGE race condition guards.