wwbump.txt -- PayloadPlus(tm) equivalent to ACE 'bump-in-the-wire' code
from Chapter 26 of *Network Systems Design Using Network Processors*
by Douglas Comer. Example PayloadPlus code written by Dale E. Parson,
Agere Systems, December, 2002, with suggestions from Dan Wang,
Ed Walters and Rob Munoz.

Files:
    ce_sed_null.asl	Null stream editor ASL script.
    ce_tm_null.asl	Null traffic manager ASL script.
    ce_ts_null.asl	Null traffic shaper ASL script.
    wwbump.fpl		Main example FPL classification & counting code.
    wwbump.txt		This file.

The ASL scripts are null because there is no packet modification,
traffic policing or traffic management in the bump-in-the-wire
example. Most of the work occurs in the Fast Pattern Processor (FPP),
using the program in wwbump.fpl.

WWBUMP.FPL: This section outlines the code in wwbump.fpl.
The file contains about 43 lines of FPL code, not counting
#include and #define lines, and about 10 lines of the latter.

FPL can classify each Ethernet frame independently from other
Ethernet frames -- there are no inter-frame or inter-packet
dependencies in the bump-in-the-wire example -- so both Pass 1
and Pass 2 employ multiple contexts (i.e., "hardware threads")
to process distinct Ethernet frames concurrently. The FPP
programmer specifies the number of hardware contexts to allocate
to Pass 1 versus Pass 2 in configuration file wwbump.xml,
but otherwise concurrent classification is transparent to
the programmer.

FPP PASS 1:

Pass 1 functions "Assemble," "EtherBlock" and "input2output" assemble
Ethernet blocks forwarded from the two input framers into complete Ethernet 
frames. Assemble passes an end-of-frame flag to EtherBlock,
which queues the blocks for FPP Pass 2. EtherBlock uses function
input2output to map the input port value from the register housing the
$portNumber variable to local variable "did" (Destination ID).
The fQueueEof operation sends the assembled Ethernet frame to Pass 2;
the final "$did:24" argument to fQueueEof sends the DID to Pass 2
processing via the latter's $tag register, here #defined as symbolic
name OUTPORTDID.

FPP Pass 2:

Classification occurs in Pass 2 against a complete Ethernet frame,
matched as a bit stream by the FPL field-matching constants
that appear as the first tokens in several so-called "tree functions"
in wwbump.fpl. A tree function begins with one or more data patterns
to match against the incoming bit stream, optionally followed
by zero or more imperative operations known as "flow instructions."
A function composed strictly of flow instructions is a "flow
function." It does not perform pattern-directed matching.

Pass 2 begins with flow function "EthFrame" that skips over the
Ethernet destination and source MAC addresses. The "fSkip(96)"
operation does not discard packet bits; it simply skips inspecting
them as part of classification processing, thereby moving
further into the bit stream.

EthFrame then invokes "EthFrameDemux" to classify web-destined TCP/IP
packets versus other types of Ethernet frames, counting the former.
Upon completion of EthFrameDemux, EthFrame skips any additional
classification via the "fSkipToEnd" operation; it then supplies
the OUTPORTDID, received in the $tag register from Pass 1, as
the first argument of the "fTransmit" operation to transmit its
classification result (along with the Ethernet frame itself)
to the Routing Switch Processor (RSP). The Agere Scripting Language
(ASL) scripts for the RSP are empty because the RSP advances the frame
to the port determined by fTransmit's first argument without modification,
traffic management or traffic shaping.

The first variant of EthFrameDemux matches the frame to an IP-
over-Ethernet packet (pattern ETH_IP as defined in Chapter 26).
A successful match leads to invocation of function "IPv4Pkt" that
matches the Internet Protocol layer of the Ethernet frame.
Subsequent code in wwbump.fpl matches specific protocol
layers -- IP, TCP and WWW -- within function layers that have a
one-to-one correspondence with the protocol layers they match.

The second variant of EthFrameDemux matches any Ethernet frame
not matched by the first variant, i.e., any frame that is not
an IP packet, and returns to EthFrame without counting or
otherwise classifying the frame further. Subsequent tree functions
in wwbump.fpl follow this pattern, defining one variant that matches
the desired patterns and proceeds, and a second variant that
matches other data and returns without further classification.
FPP pattern matching always selects the most specific function
variant that matches the data, regardless of the order of
definition of the function variants.

IPv4Pkt matches IP Version 4. For any frame that matches, IPv4Pkt
extracts the four-bit IP header length field using the
"fExtract" flow instruction for extracting leading bit strings
from the bit stream. It saves this length in local variable "$hdrlen,"
skips 64 bits of additional IP header fields, extracts the next
level protocol identifier (e.g., TCP, UDP or ICMP) into variable
"$proto," skips IP header checksum and address fields, computes
the number of bits to skip for optional IP header fields,
skips these bits ("opt_bits" is typically 0), then invokes
"IPv4Demux" to decompose the IP packet to the next layer.

On a successful match of IPT_TCP as defined in Chapter 26,
IPv4Demux invokes "Tcp" to decompose the TCP packet. This
function skips the TCP source port number, then it invokes tree
function "TcpDstPortDemux" to perform final classification.
This function matches the destination TCP port against value
TCP_WWW as defined in Chapter 26, and if successful, it increments
the web packet counter in location WEBCOUNTER of ASI memory (i.e., in RAM).

Default error-handling function "PassError" discards any
error-generating packets by transmitting them to destination
ID 0. There were no error-triggering conditions in the test runs.
