Initial commit
* First commit of the Shortcut Forwarding Engine
* New files, short form FAQ and kernel patches.
diff --git a/README b/README
new file mode 100644
index 0000000..dd0fd2f
--- /dev/null
+++ b/README
@@ -0,0 +1,121 @@
+Shortcut Forwarding Engine
+--------------------------
+
+Welcome to "Shortcut" :-)
+
+Here's a quick FAQ:
+
+
+Q) What is Shortcut?
+
+A) Shortcut is an in-Linux-kernel IP packet forwarding engine. It's designed
+to offer very high speed IP packet forwarding based on IP connection tracking.
+It's dramatically faster than the standard netfilter-based NAT forwarding path
+but is designed to synchronise state back to netfilter/conntrack so that it
+doesn't need to deal with all of the complexities of special cases.
+
+
+Q) What versions of IP does it support?
+
+A) The current version only supports IPv4 but will be extended to support IPv6 in
+the future.
+
+
+Q) What transport protocols does it support?
+
+A) TCP and UDP. It also knows enough about ICMP to spot ICMP error messages
+related to TCP and UDP and handle things accordingly.
+
+
+Q) Is there a design spec for this software?
+
+A) Not at the moment. I'll write one when I get more time. The code is
+intended to be a good tutorial though - it's very heavily commented. If you
+find yourself reading something and not understanding it then I take that to
+mean I've probably not done a sufficently good job of explaining what it's
+doing in the comments. Let me know - I will try to fix it :-)
+
+
+Q) Why was it written?
+
+A) It was written as a demonstration of what can be done to provide high
+performance forwarding inside the kernel. There were two initial motivations:
+
+1) To provide a platform to enable research into how QoS analysis systems can
+offload work and avoid huge Linux overheads.
+
+2) To provide a tool to investigate the behaviour of various processors, SoCs
+and software sets so that we can characterize and design new network processor
+SoCs.
+
+
+Q) How much faster is it than the Linux kernel forwarding path?
+
+A) At the time of pushing this to github it's been tested on a QCA AP135.
+This has a Scorpion (QCA Scopion, not the QMC one :-)) SoC, QCA9550. The
+SoC's processor is a MIPS74K running at 720 MHz and with a DDR2 memory
+subsystem that offers a peak of 600 MT/s (16-bit transfers).
+
+Running IPv4 NAT forwarding of UDP between the board's 2 GMAC ports and
+using a SmartBits 200 as a traffic generator Linux is able to forward 70k PPS.
+Once the SFE code is invoked this will increase to 350k PPS!
+
+There's also a slightly hacky mode which causes SFE to bypass the Linux
+bridge layer, but this isn't really ready for use because it doesn't have
+sufficient MAC address checks or integration of statistics back to the
+Ethernet bridge, but that runs at 436k PPS.
+
+
+Q) Are there any diagnostics?
+
+A) Yes, this is a research tool after all! There's a complex way to do this
+that's more general purpose and a simple one - here's the simple one:
+
+ mknod /dev/sfe c 253 0
+
+The file /dev/sfe is an XML-ish output and provides details of all the
+network connections currently being offloaded. It also reports the numbers
+of packets that took various "exception" paths within the code. In addition
+it provides a summary of the number of connections, attempts to accelerate
+connections, cancel accelerations, etc. It also reports the numbers of
+packets that were forwarded and not forwarded by the engine and has some
+stats on the effectiveness of the hashing algorithm it uses.
+
+
+Q) How does the code interact with Linux?
+
+A) There are two minor patches required to make this software run with
+Linux. These are currently against a 3.3.8 kernel. The first adds a
+hook to allow packets to be extracted out, while the second exposes a
+state variable inside netfilter that's necessary to enable TCP sequence
+and ACK checking within the offload path. Note that this specific
+patch is against the QCA QSDK patched version of 3.3.8 - there's a
+slightly braindead "performance" patch in that kernel, courtesy of the
+OpenWrt community that makes the Linux forwarding path slightly faster
+at the expense of losing functionality :-(
+
+Once these are applied and the module is loaded then everything else
+is automatic :-) The patches are in this git repo.
+
+
+Q) Isn't that patch to dev.c a gross hack?
+
+A) Yes it is and no, it's not thread safe. Fixing this is on my "to do"
+list.
+
+
+Q) Are any of the pieces reused from other projects?
+
+A) Yes! Some of the forwarding concepts are reused from the Ubicom Network
+Accelerator that morphed into part of the Akronite NSS. This code has all
+been substantially changed though to accomodate Linux's needs.
+
+There are also some pieces that I borrowed from the QCA "FastNAT" software
+written by Xiaoping Fan <xfan@qca.qualcomm.com>. Xiaoping's code was the
+first actual demonstration within QCA that this in-kernel concept could yield
+signficant performance gains.
+
+
+Enjoy!
+Dave Hudson <dhudson@qti.qualcomm.com>
+