Tightly coupled scalar and boolean processor

RELATED APPLICATIONS

0001The present patent application is a continuation of, and claims priority from, U.S. patent application Ser. No. 10/748,311, entitled “Multiple Consumer-Multiple Producer Rings”, filed Dec. 29, 2003, which is in turn a continuation of U.S. patent application Ser. No. 10/059,770, entitled “Cumulative Status of Arithmetic Operations”, filed Jan. 28, 2002, now U.S. Pat. No. 6,701,338; which is, in turn, a continuation of, and claims priority to, U.S. patent application Ser. No. 09/283,662, entitled “Programmable System for Processing a Partitioned Network Infrastructure”, filed Apr. 1, 1999, now U.S. Pat. No. 6,421,730; which is, in turn, a continuation of, and claims priority to, U.S. patent application Ser. No. 09/097,858, entitled “Packet Processing System including a Policy Engine having a Classification Unit” filed Jun. 15, 1998, now U.S. Pat. No. 6,157,955.

0002The subject patent application is related to U.S. patent application Ser. No. 10/100,746, entitled “Multiple Consumer—Multiple Producer Rings”, filed Mar. 18, 2002, now U.S. Pat. No. 6,625,689; and U.S. patent application Ser. No. 10/084,815, entitled “Programmable System for Processing a Partitioned Network Infrastructure” filed Feb. 27, 2002, now U.S. Pat. No. 6,859,841. The patent application is also related to U.S. patent application Ser. No. 09/282,790, entitled “Platform Permitting Execution of Multiple Network Infrastructure Applications”, filed Mar. 31, 1999, and issued as U.S. Pat. No. 6,401,117.

BACKGROUND

0003The present application generally relates to computer networks and, more particularly, an embodiment relates to a tightly coupled scalar and Boolean processor.

0004Computer networks have become a key part of the corporate infrastructure. Organizations have become increasingly dependent on intranets and the Internet and are demanding much greater levels of performance from their network infrastructure. The network infrastructure is being viewed: (1) as a competitive advantage; (2) as mission critical; (3) as a cost center. The infrastructure itself is transitioning from 10 Mb/s (megabits per second) capability to 100 Mb/s capability. Soon, infrastructure capable of 1 Gb/s (gigabits per second) will start appearing on server connections, trunks and backbones. As more and more computing equipment gets deployed, the number of nodes within an organization has also grown. There has been a doubling of users, and a ten-fold increase in the amount of traffic every year.

0005Network infrastructure applications monitor, manage and manipulate network traffic in the fabric of computer networks. The high demand for network bandwidth and connectivity has led to tremendous complexity and performance requirements for this class of application. Traditional methods of dealing with these problems are no longer adequate.

0006Several sophisticated software applications that provide solutions to the problems encountered by the network manager have emerged. The main areas for such applications are Security, Quality of Service (QoS)/Class of Service (CoS) and Network Management. Examples are: Firewalls; Intrusion Detection; Encryption; Virtual Private Networks (VPN); enabling services for ISPs (load balancing and such); Accounting; Web billing; Bandwidth Optimization; Service Level Management; Commerce; Application Level Management; Active Network Management

0007There are three conventional ways in which these applications are deployed:

0008(1) On general purpose computers.

0009(2) Using single function boxes.

0010(3) On switches and routers.

0011It is instructive to examine the issues related to each of these deployment techniques.

1. General Purpose Computers

0012General Purpose computers, such as PCs running NT/Windows or workstations running Solaris/HP-UX, etc. are a common method for deploying network infrastructure applications. The typical configuration consists of two or more network interfaces each providing a connection to a network segment. The application runs on the main processor (Pentium/SPARC etc.) and communicates with the Network Interface Controller (NIC) card either through (typically) the socket interface or (in some cases) a specialized driver “shim” in the operating system (OS). The “shim” approach allows access to “raw” packets, which is necessary for many of the packet oriented applications. Applications that are end-point oriented, such as proxies can interface to the top of the IP (Internet Protocol) or other protocol stack.

0013The advantages of running the application on a general purpose computer include: a full development environment; all the OS services (IPC, file system, memory management, threads, I/O etc); low cost due to ubiquity of the platform; stability of the APIs; and assurance that performance will increase with each new generation of the general purpose computer technology.

0014There are, however, many disadvantages of running the application on a general purpose computer. First, the I/O subsystem on a general purpose computer is optimized to provide a standard connection to a variety of peripherals at reasonable cost and, hence, reasonable performance. 32b/33 MHz PCI (“Peripheral Connection Interface”, the dominant I/O connection on common general purpose platforms today) has an effective bandwidth in the 50-75 MB/s range. While this is adequate for a few interfaces to high performance networks, it does not scale. Also, there is significant latency involved in accesses to the card. Therefore, any kind of non-pipelined activity results in a significant performance impact.

0015Another disadvantage is that general purpose computers do not typically have good interrupt response time and context switch characteristics (as opposed to real-time operating systems used in many embedded applications). While this is not a problem for most computing environments, it is far from ideal for a network infrastructure application. Network infrastructure applications have to deal with network traffic operating at increasingly higher speeds and less time between packets. Small interrupt response times and small context switch times are very necessary.

0016Another disadvantage is that general purpose platforms do not have any specialized hardware that assist with network infrastructure applications. With rare exception, none of the instruction sets for general purpose computers are optimized for network infrastructure applications.

0017Another disadvantage is that, on a general purpose computer, typical network applications are built on top of the TCP/IP stack. This severely limits the packet processing capability of the application.

0018Another disadvantage is that packets need to be pulled into the processor cache for processing. Cache fills and write backs become a severe bottleneck for high bandwidth networks.

0019Finally, general purpose platforms use general purpose operating systems (OS's). These operating systems are generally not known for having quick reboots on power-cycle or other wiring-closet appliance oriented characteristics important for network infrastructure applications.

2. Fixed-Function Appliances

0020There are a couple of different ways to build single function appliances. The first way is to take a single board computer, add in a couple of NIC cards, and run an executive program on the main processor. This approach avoids some of the problems that a general purpose OS brings, but the performance is still limited to that of the base platform architecture (as described above).

0021A way to enhance the performance is to build special purpose hardware that performs functions required by the specific application very well. Therefore, from a performance standpoint, this can be a very good approach.

0022There are, however, a couple of key issues with special function appliances. For example, they are not expandable by their very nature. If the network manager needs a new application, he/she will need to procure a new appliance. Contrast this with loading a new application on a desktop PC. In the case of a PC, a new appliance is not needed with every new application.

0023Finally, if the solution is not completely custom, it is unlikely that the solution is scalable. Using a PC or other single board computer as the packet processor for each location at which that application is installed is not cost-effective.

3. Switches and Routers

0024Another approach is to deploy a scaled down version of an application on switches and routers which comprise the fabric of the network. The advantages of this approach are that: (1) no additional equipment is required for the deployment of the application; and (2) all of the segments in a network are visible at the switches.

0025There are a number of problems with this approach.

0026One disadvantage is that the processing power available at a switch or router is limited. Typically, this processing power is dedicated to the primary business of the switch/router—switching or routing. When significant applications have to be run on these switches or routers, their performance drops.

0027Another disadvantage is that not all nodes in a network need to be managed in the same way. Putting significant processing power on all the ports of a switch or router is not cost-effective.

0028Another disadvantage is that, even if processing power became so cheap as to be deployed freely at every port of a switch or router, a switch or router is optimized to move frames/packets from port to port. It is not optimized to process packets, for applications.

0029Another disadvantage is that a typical switch or router does not provide the facilities that are necessary for the creation and deployment of sophisticated network infrastructure applications. The services required can be quite extensive and porting an application to run on a switch or router can be very difficult.

0030Finally, replacing existing network switching equipment with new versions that support new applications can be difficult.

BRIEF DESCRIPTION OF THE DRAWINGS

0031<figref idref="DRAWINGS">FIG. 1</figref> is a block diagram of a system in accordance with the present invention.

0032<figref idref="DRAWINGS">FIG. 2</figref> is a block diagram showing packet flow according to an embodiment of the present invention.

0033<figref idref="DRAWINGS">FIG. 3</figref> is a Policy Engine ASIC block diagram according to the present invention.

0034<figref idref="DRAWINGS">FIG. 4</figref> is a sample system-level block diagram related to the present invention.

0035<figref idref="DRAWINGS">FIG. 5</figref> shows a ring array in memory related to the present invention.

0036<figref idref="DRAWINGS">FIG. 6</figref> shows an RX Ring Structure related to the present invention.

0037<figref idref="DRAWINGS">FIG. 7</figref> shows a receive buffer format related to the present invention.

0038<figref idref="DRAWINGS">FIG. 8</figref> shows a TX Ring Structure related to the present invention.

0039<figref idref="DRAWINGS">FIG. 9</figref> shows a transmit buffer format related to the present invention.

0040<figref idref="DRAWINGS">FIG. 10</figref> shows a reclassify ring structure related to the present invention.

0041<figref idref="DRAWINGS">FIG. 11</figref> shows a Crypto Ring and COM[<b>4</b>:<b>0</b>] Rings Structure related to the present invention.

0042<figref idref="DRAWINGS">FIG. 12</figref> shows a DMA Ring Structure related to the present invention.

0043<figref idref="DRAWINGS">FIG. 13</figref> is a classification engine block diagram related to the present invention.

0044<figref idref="DRAWINGS">FIG. 14</figref> is a pipeline timing diagram for the classification engine related to the present invention.

0045<figref idref="DRAWINGS">FIG. 15</figref> is an application structure diagram related to the present invention.

0046<figref idref="DRAWINGS">FIG. 16</figref> is a diagram showing an Action Classification Engine (ACE) related to the present invention.

0047<figref idref="DRAWINGS">FIG. 17</figref> shows a cascade of ACEs related to the present invention.

0048<figref idref="DRAWINGS">FIG. 18</figref> shows a system architecture related to the present invention.

0049<figref idref="DRAWINGS">FIG. 19</figref> shows an application deploying six ACEs related to the present invention.

DETAILED DESCRIPTION

0050Network infrastructure applications generally contain both time-critical and non-time-critical sections. The non-time-critical sections generally deal with setup, configuration, user interface and policy management. The time-critical sections generally deal with policy enforcement. The policy enforcement piece generally has to run at network speeds. The present invention pertains to an efficient architecture for policy enforcement that enables application of complex policy at network rates.

0051<figref idref="DRAWINGS">FIG. 1</figref> shows a Network Infrastructure Application, called Application <b>2</b>, being deployed on an Application Processor (AP) <b>4</b> running a standard operating system. The policy enforcement section of the Application <b>2</b>, called Wire Speed Policy <b>3</b> runs on the Policy Engine (PE) <b>6</b>. The Policy Engine <b>6</b> transforms the inbound Packet Stream <b>8</b> into the outbound Packet Stream <b>10</b> per the Wire Speed Policy <b>3</b>. Communications from the Application Processor <b>4</b> to the Policy Engine <b>6</b>, in addition to the Wire Speed Policy <b>3</b>, consists of control, policy modifications and packet data as desired the Application <b>2</b>. Communication from the Policy Engine <b>3</b> to the Application Processor <b>4</b> consists of status, exception conditions and packet data as desired by the Application <b>2</b>.

0052In a preferred embodiment of a Policy Engine (PE) according to the present invention, the PE provides a highly programmable platform for classifying network packets and implementing policy decisions about those packets at wire speed. Certain embodiments provide two Fast Ethernet ports and implement a pipelined dataflow architecture with store-and-forward. Packets are run through a Classification Engine (CE) which executes a programmed series of hardware assist operations such as chained field comparisons and generation of checksums and hash table pointers, then are handed to a microprocessor (“Policy Processor” or PP) for execution of policy decisions such as Pass, Drop, Enqueue/Delay, (de/en)capsulate, and (de/en)crypt based on the results from the CE. Some packets which require higher level processing may be sent to the host computer system (“Application Processor” or AP). (See <figref idref="DRAWINGS">FIG. 4</figref>.) An optional cryptographic (“Crypto”) Processor is provided for accelerating such functions as encryption and key management.

0053Third-party applications such as firewalls, rate shaping, QoS/CoS, network management and others can be implemented to take advantage of this three-tiered approach to filtering packets. Support for easy encapsulation without copies combined with encryption support allows for VPNs (“Virtual Private Networks”) and other applications that require security services.

0054A large parity-protected synchronous DRAM (SDRAM) buffer memory is provided, along with a PCI interface that is used for communication with the host (AP) and potentially for peer-to-peer communication among Policy Engines, e.g. for applications which route and switch.

0055In certain embodiments the Policy Engine ASIC can be used on a PCI card both for application software development and for use in a PC or workstation as a two interface product, and can also be used in a multiple-segment appliance with a plurality of PE's along with an embedded Application Processor for a stand-alone product.

0056In certain embodiments, when used in an appliance, the PE's reside on PCI segments connected together through a plurality of PCI-to-PCI bridges which connect to the host PCI bus on the Application Processor. The PCI bus is 64-bit for all agents in order to provide sufficient bandwidth for applications which route or switch.

0057A sample system level block diagram is shown in <figref idref="DRAWINGS">FIG. 4</figref>.

0058<figref idref="DRAWINGS">FIG. 4</figref> shows an application processor <b>302</b> which contains a host interface <b>304</b> to a PCI bus <b>324</b>. Fanout of the PCI bus <b>324</b> to a larger number of loads is accomplished with PCI-to-PCI Bridge devices <b>306</b>, <b>308</b>, <b>310</b>, and <b>312</b>; each of those controls an isolated segment on a “child” PCI bus <b>326</b>, <b>328</b>, <b>330</b>, and <b>332</b> respectively. On three of these isolated segments <b>326</b>, <b>328</b>, and <b>330</b> is a number of Policy Engines <b>322</b>; each Policy Engine <b>322</b> connects to two Ethernet ports <b>320</b> which connects the Policy Engine <b>322</b> to a network segment.

0059One of the PCI-to-PCI Bridges <b>312</b> controls child PCI bus <b>322</b>, which provides the Application Processor <b>302</b> with connection to standard I/O devices <b>314</b> and optionally to PCI expansion slots <b>316</b> into which additional PCI devices can be connected.

0060In a smaller configuration of the preferred embodiment of the invention the number of Policy Engines <b>322</b> does not exceed the maximum load allowed on a PCI bus <b>324</b>; in that case the PCI-to-PCI bridges <b>306</b>, <b>308</b>, and <b>310</b> are eliminated and up to four Policy Engines <b>322</b> are connected directly to the host PCI bus <b>324</b>, each connecting also to two Ethernet ports <b>320</b>. This smaller configuration may still have the PCI-to-PCI Bridge <b>312</b> present to isolate Local I/O <b>314</b> and expansion slots <b>316</b> from the PCI bus <b>324</b>, or the Bridge <b>312</b> may also be eliminated and the devices <b>314</b> and expansion <b>316</b> may also be connected directly to the host PCI bus <b>324</b>.

I. Packet Flow

0061In certain embodiments, the PE utilizes two Fast Ethernet MAC's (Media Access Controllers) with IEEE 802.3 standard Media Independent Interface (“MII”) connections to external physical media (PHY) devices which attach to Ethernet segments. Each Ethernet MAC receives packets into buffers addressed by buffer pointers obtained from a producer-consumer ring and then passes the buffer (that is, passes the buffer pointer) to a Classification Engine for processing, and from there to the Policy Processor. The “buffer pointer” is a data structure comprising the address of a buffer and a software-assigned “tag” field containing other information about that buffer. The “buffer pointer” is a fundamental unit of communication among the various hardware and software modules comprising a PE. From the PP, there are many paths the packet can take, depending on what the application(s) running on the PP decide is the proper disposition of that packet. It can be transmitted, sent to Crypto, delayed in memory, passed through a Classification Engine again for further processing, or copied from the PE's memory over the PCI bus to the host's memory or to a peer device's memory, using the DMA engine. The PP may also gather statistics on that packet into records in a hash table or in general memory. A pointer to the buffer containing both the packet and data structures describing that packet is passed around among the various modules.

0062The PP may choose to drop a packet, to modify the contents of the packet, or to forward the packet to the AP or to a different network segment over the PCI Bus (e.g. for routing.) The AP or PP can create packets of its own for transmission. A 3rd-party NIC (Network Interface Card) on the PCIbus can use the PE memory for receiving packets, and the PP and AP can then cooperate to feed those packets into the classification stream, effectively providing acceleration for packets from arbitrary networks. When doing so, adjacent 2 KB buffers can be concatenated to provide buffers of any size needed for a particular protocol.

0063<figref idref="DRAWINGS">FIG. 2</figref> illustrates packet flow according to certain embodiments of the present invention. Each box represents a process which is applied to a packet buffer and/or the contents of a packet buffer <b>620</b> as shown in <figref idref="DRAWINGS">FIG. 7</figref>. The buffer management process involves buffer allocation <b>102</b> and the recovery of retired buffers <b>118</b>. When buffer allocation <b>102</b> into an RX Ring <b>402</b> or <b>404</b> occurs, the Policy Processor <b>244</b> enqueues a buffer pointer into the RX Ring <b>402</b> or <b>404</b> and thus allocates the buffer <b>620</b> to the receive MAC <b>216</b> or <b>230</b>, respectively. Upon receiving a packet, the RX MAC controller <b>220</b> or <b>228</b> uses the buffer pointer at the entry in the RX ring structure of <figref idref="DRAWINGS">FIG. 6</figref> which is pointed to by MFILL <b>516</b> to identify a 2 KB section of memory <b>260</b> that it can use to store the newly received packet. This process of receiving a packet and placing it into a buffer <b>620</b> is represented by physical receive <b>104</b> in <figref idref="DRAWINGS">FIG. 2</figref>.

0064The RX MAC controller <b>220</b> or <b>228</b> increments the MFILL pointer <b>516</b> modulo ring size to signal that the buffer <b>620</b> whose pointer is in the RX Ring <b>402</b> or <b>404</b> has been filled with a new packet <b>610</b> and <b>612</b> plus receive status <b>600</b> and <b>602</b>. The Ring Translation Unit <b>264</b> detects a difference between MFILL <b>516</b> and MCCONS <b>514</b> and signals to the classification engine <b>238</b> or <b>242</b>, respectively, for RX Ring <b>402</b> or <b>404</b>, that a newly received packet is ready for processing. The Classification Engine <b>238</b> or <b>242</b> applies Classification <b>106</b> to that packet and creates a description of the packet which is placed in the packet buffer software area <b>614</b>, then increments MCCONS <b>514</b> to indicate that it has completed classification <b>106</b> of that packet. The Ring Translation Unit <b>264</b> detects a difference between MCCONS <b>514</b> and MPCONS <b>512</b> and signals to the Policy Processor <b>244</b> that a classified packet is ready for action processing <b>108</b>.

0065The Policy Processor <b>244</b> obtains the buffer pointer from the ring location pointed to by <b>512</b> by dequeueing that pointer from the RX Ring <b>402</b> or <b>404</b>, and executes application-specific action code <b>108</b> to determine the disposition of the packet. The action code <b>108</b> may choose to send the packet to an Ethernet Transmit MAC <b>218</b> or <b>234</b> by enqueueing the buffer pointer on a TX Ring <b>406</b> or <b>408</b>, respectively; the packet may or may not have been modified by the action code <b>108</b> prior to this. Alternatively the action code <b>108</b> may choose to send the packet to the attached cryptographic processor (Crypto) <b>246</b> for encryption, decryption, compression, decompression, security key management, parsing of IPSEC headers, or other associated functions; this entire bundle of functions is described by Crypto <b>112</b>. Alternatively the action code <b>108</b> may choose to copy the packet to a PCI peer <b>322</b> or <b>314</b> or <b>316</b>, or to the host memory <b>330</b>, both paths being accomplished by the process <b>114</b> of creating a DMA descriptor as shown in Table 3 and then enqueuing the pointer to that descriptor into DMA Ring <b>418</b> by writing that pointer to DMA_PROD <b>1116</b>, which triggers the DMA Unit <b>210</b> to initiate a transfer. Alternatively the action code <b>118</b> can choose to temporarily enqueue the packet for delay <b>110</b> in memory <b>260</b> that is managed by the action code <b>118</b>. Finally, the action code <b>108</b> can choose to send a packet for further classification <b>106</b> on any of the Classification Engines <b>208</b>, <b>212</b>, <b>238</b>, or <b>242</b>, either because the packet has been modified or because there is additional classification which can be run on the packet which the action code <b>108</b> can command the Classification process <b>106</b> to execute via flags in the RX Status Word <b>600</b>, through the buffer's software area <b>614</b>, or by use of tag bits in the 32-bit buffer pointer reserved for that use.

0066Packets can arrive at the classification process <b>106</b> from additional sources besides physical receive <b>104</b>. Classification <b>106</b> may receive a packet from the output of the Crypto processing <b>112</b>, from the Application Processor <b>302</b> or from a PCI peer <b>322</b> or <b>314</b> or <b>316</b>, or from the application code <b>108</b>.

0067Packets can arrive at the action code <b>108</b> from classification <b>106</b>, from the Application Processor <b>302</b>, from a PCI peer <b>322</b> or <b>314</b> or <b>316</b>, from the output of the Crypto processing <b>112</b>, and from a delay queue <b>110</b>. Additionally the action code <b>108</b> can create a packet. The disposition options for these packets are the same as those described for the receive path, above.

0068The Crypto processing <b>112</b> can receive a packet from the Policy Processor <b>244</b> as described above. The Application Processor <b>302</b> or a PCI peer <b>322</b> or <b>314</b> or <b>316</b> can also enqueue the pointer to a buffer onto the Crypto Ring <b>420</b> to schedule that packet for Crypto processing <b>112</b>.

0069The TX MAC <b>218</b> or <b>234</b> transmits packets whose buffer pointer have been enqueued on the TX Ring <b>406</b> or <b>408</b>, respectively. Those pointers may have been enqueued by the action code <b>106</b> running on the Policy Processor <b>244</b>, by the Crypto processing <b>112</b>, by the Application Processor <b>302</b>, or by a PCI peer <b>322</b> or <b>314</b> or <b>316</b>. When the TX MAC controller <b>222</b> or <b>232</b> has retired a buffer either by successfully transmitting the packet it contains, or abandoning the transmit due to transmit termination conditions, it will optionally write back TX status <b>806</b> and TX Timestamp <b>808</b> if programmed to do so, then will increment MTCONS <b>714</b> to indicate that this buffer <b>840</b> has been retired. The Ring Translation Unit <b>264</b> detects that there is a difference between MTCONS <b>714</b> and MTRECOV <b>712</b> and signals to the Policy Processor <b>244</b> that the TX Ring <b>406</b> or <b>408</b> has at least one retired buffer to recover; this triggers the buffer recovery process <b>118</b>, which will dequeue the buffer pointer from the TX ring <b>406</b> or <b>408</b> and either send the buffer pointer to Buffer Allocation <b>102</b> or will add the recovered buffer to a software-managed free list for later use by Buffer Allocation <b>102</b>.

0070It is also possible for a device in the PCI expansion slot <b>316</b> to play the role defined for the attached Crypto processor <b>246</b> performing crypto processing <b>112</b> via DMA<b>114</b> in this flow.

00001. Communication and Buffer Management

0071In certain embodiments, the buffer memory consists of 16 to 128 MB of parity-protected SDRAM. It is used for packet buffers, for code and data structures for the microprocessor, as a staging area for Classification Engine microcode loading, and for buffers used in communicating with the AP and other PCI agents. The following uses of memory are defined by the architecture of the Policy Engine: <ul id="ul0001" list-style="none"><li id="ul0001-0001" num="0000"><ul id="ul0002" list-style="none"><li id="ul0002-0001" num="0072"> Buffer Pointer rings for RX_MAC_A, RX_MAC_B, TX_MAC_A, TX_MAC_B (where “RX” denotes “receive”, “TX” denotes “transmit”, and “_A” and “_B” indicate which instance of the MAC is being described.) </li><li id="ul0002-0002" num="0073"> A pool of 2 KB-aligned buffers used for holding packets that are being processed in this chip as well as information about those packets; larger buffers can be created by concatenating these 2 KB buffers if needed for processing larger packets from other media. </li><li id="ul0002-0003" num="0074"> “Reclassification” pointer rings for each of the four Classification Engines; these are used to schedule packets for processing on that CE, when the classification of the packet is being scheduled by an agent other than an RX MAC. </li><li id="ul0002-0004" num="0075"> A ring containing pointers to DMA descriptors used to schedule transfers using the DMA engine; data copies between PCI and memory in either direction are scheduled by enqueuing descriptor pointers on this ring. </li><li id="ul0002-0005" num="0076"> A pool of memory allocated for use as DMA descriptors. </li><li id="ul0002-0006" num="0077"> A pointer ring for scheduling packets for processing on the Crypto unit. </li><li id="ul0002-0007" num="0078"> An area that contains instructions for the microprocessor, including the boot sequence. </li><li id="ul0002-0008" num="0079"> An area for staging microcode to be loaded into the control store of the four Classification Engines. </li><li id="ul0002-0009" num="0080"> Page tables for the Policy Processor MMU </li><li id="ul0002-0010" num="0081"> 16 words dedicated to mailbox communications; writes to these words from the PCIbus also set the corresponding mailbox bit in the mailbox status register which signals to the processor that the indicated mailbox has a new message. </li><li id="ul0002-0011" num="0082"> A pool of 2 KB buffers that belong to the AP and are used for scheduling transmits of packets that have been handed to the AP for processing or that originate at the AP. In addition to these uses, parts of the memory may be allocated to the applications running on the PP for storing data such as local variables, counters, hash tables and the data structures they contain, AP to PP and PP to AP application-level communications areas, external coprocessor communication and transmit buffers, etc. </li></ul></li></ul>

0083The Policy Engine takes advantage of the fact that buffers are 2 KB-aligned, and has the hardware ignore the lower 11 bits of each buffer base pointer, thus enabling software to use those pointer bits as tags.

0084A simple and lightweight mechanism for buffer allocation and recovery is provided. Hardware support for atomic enqueue and dequeue of buffers through producer-consumer rings, along with detection of completed (retired) buffers enables buffer management in only a few instructions. In the realtime executive loop run on the PP, a short section is devoted to reclaimation of free buffers into the free list from those rings which indicate to the PP that they have retired buffers available for recovery. The RX pools of allocated, empty buffers maintained in the RX Rings can be replenished from the freelist each time a filled, classified RX buffer is dequeued from that ring, thus maintaining the pool size. A simple linked list of buffers or other method well-known to those versed in the art can be used to implement a software-managed freelist from which to feed the pools.

0085In order to support atomic enqueueing/dequeueing of buffer pointers and of DMA descriptor pointers, a standard memory-based producer/consumer ring structure is supported in hardware for many purposes (as represented by the circle-with-arrow symbols in <figref idref="DRAWINGS">FIG. 3</figref>). In most cases one or more of the consumers is also a producer for the next consumer, so the rings have a series of index pointers which chase each other in sequence; for example the MAC RX Rings have a Produce Pointer for the allocation of empty buffers, a MAC FILL Pointer for the RXMAC to consume empty buffers and produce full buffers, a Classification Engine Consume Pointer for the CE to consume freshly received buffers and to produce classified buffers, and a Policy Processor Consume Pointer for the PP to consume classified packets as shown in <figref idref="DRAWINGS">FIG. 6</figref>. The leading producer accesses the ring through an “enqueue” register, and the end consumer accesses the ring through a “dequeue” register, obviating the need for mutexes (mutual exclusion locks) or (slow) memory accesses in managing shared ring structures. Interim consumer-producers fetch a buffer pointer through a ring index, then increment that index later to signal that they have finished processing the referenced buffer and that it is available for the next consumer.

0086This serialized multiple-producer/multiple-consumer ring structure allows for one ring to support a compelled series of steps with much less hardware than would be required to support a separate FIFO between each producer and consumer, and eliminates the need for each consumer-producer to write pointers to the next ring; every cycle saved in a real-time system such as this can be significant.

0087Hardware detects when there is a difference between a producer's ring index and the ring index for the next consumer in that communication sequence, and signals to the consumer that there is at least one buffer pointer in its ring for processing; thus the presence of work to do wakes up the associated unit, implementing a dataflow architecture through the use of hardware-managed rings.

0088Ring overflow, underflow, and threshold conditions are detected and reported to the ring users and the PP as appropriate.

00002. Memory and Ring Translated Memory

00892.1 Memory

0090Main memory in the preferred embodiment consists of up to 128 MB of synchronous DRAM (SDRAM) in two DIMM's (Dual In-line Memory Modules) or one double-sided DIMM. Detecting the presence of the DIMMs and their attributes uses the standard Serial Presence Detect interface, using the SPD register to manage accesses to the serial PROM. (The same interface is used to access a serial PROM containing MAC addresses, ASIC configuration parameters, and manufacturing information.) Depending on the size of DIMM's installed, memory might not be contiguous; each socket is allocated 64 MB of address space, and will alias within that 64 MB space if a smaller DIMM is used. Alternatively one 128 MB DIMM is supported, in one socket only.

00912.2 Ring Translated Memory

0092The pointer rings associated with various units are simply a region of memory which is accessed through a translation unit. The translation unit implements the rings as a base register (which is used to assign an arbitrary memory location to be used for the rings) plus a set of index registers which each point to an array entry relative to the base address. Reads and writes to the address associated with a particular index register actually access memory at the ring entry pointed to by that index register; that is, such accesses are indirect. Some index registers are automatically incremented after an access (for atomic enqueue and dequeue operations), issued by leading producers or end consumers while others are incremented specifically by their owner (generally an interim consumer-producer) to indicate that the referenced buffer has been processed and is now available for the next consumer down the chain. Pairs of pointers have a producer-consumer relationship, and a difference between them indicates to the consumer that there is work to do; that difference is detected in hardware and is signaled to the appropriate unit.

0093There are 15 rings in the preferred embodiment, each 4 KB in size (1K entries of 4 bytes each); the 60 KB array of 15 rings resides on a 64 KB boundary in memory. The base of this array is pointed to by the Ring Base Register. The rings themselves are not accessed directly; instead they appear to the users as a set of “registers” which are read or written to access the entries in memory that are pointed to by the associated index register. For addressing purposes each ring is assigned a number, which is used as an index both into the array in memory and into the Ring Translation Unit (RTU) register map.

0094Writes to a ring will cause the data (which is generally a buffer pointer, or in the case of the DMA Ring, a pointer to a DMA descriptor) to be stored at the location in memory pointed to by [(RingArray[Ring #])+(RTU index register used)], and then that index register is incremented modulo ring size. Reads from a ring will return the data (buffer pointer or descriptor pointer) pointed to by [(RingArray[Ring #])+(RTU index register used)]; if that register is an auto-increment register then it will increment modulo ring size after the read operation. A read attempted via a consumer index register which matches its corresponding produce pointer (that is, there was no work to do) will return zero and the index pointer will not increment. Registers which are not auto-increment are incremented explicitly by that register's owner when the referenced buffer has been processed; the increment is done via a hardware signal, not by register access.

0095Ring underflow/overflow and near-empty/near-full threshold status (as appropriate) are reported through the CRISIS register to the PP and the AP.

II. Policy Engine

0096<figref idref="DRAWINGS">FIG. 3</figref> shows a Policy Engine ASIC block diagram according to certain embodiments of the present invention.

0097The ASIC <b>290</b> contains an interface <b>206</b> to an external RISC microprocessor which is known as the Policy Processor <b>244</b>. Internal to the RISC Processor Interface <b>206</b> are registers for all units in the ASIC <b>290</b> to signal status to the RISC Processor <b>244</b>.

0098There is an interface <b>204</b> to a host PCI Bus <b>280</b> which is used for movement of data into and out of the memory <b>260</b>, and is also used for external access to control registers throughout the ASIC <b>290</b>. The DMA unit <b>210</b> is the Policy Engine <b>322</b>'s agent for master activity on the PCI bus <b>280</b>. Transactions by DMA <b>210</b> are scheduled through the DMA Ring <b>418</b>. The Memory Controller <b>240</b> receives memory access requests from all agents in the ASIC and translates them to transactions sent to the Synchronous DRAM Memory <b>260</b>. Addresses issued to the Memory Controller <b>240</b> will be translated by the Ring Translation Unit <b>264</b> if address bit <b>27</b> is a ‘1’, or will be used untranslated by the memory controller <b>240</b> to access memory <b>260</b> if address bit <b>27</b> is a ‘0’. Untranslated addresses are also examined by the Mailbox Unit <b>262</b> and if the address matches the memory address of one of the mailboxes the associated mailbox status bit is set if the transaction is a write, or cleared if the transaction is a read. In addition to the dedicated rings in the Ring Translation Unit <b>264</b> which are described here, the Ring Translation Unit also implements 5 general-purpose communications rings COM[<b>4</b>:<b>0</b>] <b>226</b> which software can allocate as desired. The memory controller <b>240</b> also implements an interface to serial PROMs <b>270</b> for obtaining information about memory configuration, MAC addresses, board manufacturing information, Crypto Daughtercard identification and other information.

0099The ASIC contains two Fast Ethernet MACs MAC_A and MAC_B. Each contains a receive MAC <b>216</b> or <b>230</b>, respectively, with associated control logic and an interface to the memory unit <b>220</b> or <b>228</b>, respectively; and a transmit MAC <b>218</b> or <b>234</b> respectively with associated control logic and an interface to the memory unit <b>222</b> or <b>232</b>, respectively. Also associated with each MAC is an RMON counter unit <b>224</b> or <b>236</b>, respectively, which counts certain aspects of all packets received and transmitted in support of providing the Ethernet MIB as defined in Internet Engineering Task Force (IETF) standard RFC <b>1213</b> and related RFC's.

0100RX_A Ring <b>402</b> is used by RX MAC_A controller <b>220</b> to obtain empty buffers and to pass filled buffers to Classification Engine <b>238</b>. Similarly RX_B Ring <b>404</b> is used by RX MAC_B controller <b>228</b> to obtain empty buffers and to pass filled buffers to Classification Engine <b>242</b>. TX_A Ring <b>406</b> is used to schedule packets for transmission on TX MAC_A <b>218</b>, and TX_B Ring <b>408</b> is used to schedule packets for transmission on TX MAC_B <b>234</b>.

0101There are four Classification Engines <b>208</b>, <b>212</b>, <b>238</b>, and <b>242</b> which are microprogrammed processors optimized for the predicate analysis associated with packet filtering. The classification engines are described in <figref idref="DRAWINGS">FIG. 13</figref>. Packets are scheduled for processing by these engines through the use of the Reclassify Rings <b>412</b>, <b>416</b>, <b>410</b>, and <b>414</b> respectively, plus the RX MAC controllers MAC_A <b>220</b> and MAC_B <b>228</b> can schedule packets for processing by Classification Engines <b>238</b> and <b>242</b>, respectively, through use of the RX Rings <b>402</b> and <b>404</b>, respectively.

0102There is Crypto Processor Interface <b>202</b> which enables attachment of an encryption processor <b>246</b>. The RISC Processor <b>244</b> can issue reads and writes to the Crypto Processor <b>246</b> through this interface, and the Crypto Processor <b>246</b> can access SDRAM <b>260</b> and control and status registers internal to the interface <b>202</b> through use of interface <b>202</b>.

0103A Timestamp counter <b>214</b> is driven by a stable oscillator <b>292</b> and is used by the RX MAC logic <b>220</b> and <b>228</b>, the TX MAC logic <b>222</b> and <b>232</b>, the Classification Engines <b>208</b>, <b>212</b>, <b>238</b>, and <b>242</b>, the Crypto Processor <b>246</b>, and the Policy Processor <b>244</b> to obtain timestamps during processing of packets.

0104Preferably, the Policy Engine Units have the following characteristics:

00001. PCI Interface

0000<ul id="ul0003" list-style="none"><li id="ul0003-0001" num="0000"><ul id="ul0004" list-style="none"><li id="ul0004-0001" num="0105"> 33 MHz operation. </li><li id="ul0004-0002" num="0106"> 32/64-bit data path. </li><li id="ul0004-0003" num="0107"> 32-bit addressing both as a target and as an initiator. </li><li id="ul0004-0004" num="0108"> Initiator and Target interface. </li><li id="ul0004-0005" num="0109"> One interrupt output. </li><li id="ul0004-0006" num="0110"> Up to 32-byte bursts as a master; up to 32-byte bursts to memory (BAR<b>0</b>) as a target (disconnects on 32-byte boundaries), single data-phase operations as a target for Register (BAR<b>1</b>) and Ring Translation Unit (BAR<b>2</b>) spaces. </li><li id="ul0004-0007" num="0111"> Single configuration space for the entire device. <br /> 2. RISC Processor Interface </li><li id="ul0004-0008" num="0112"> Interface to external SA-110 StrongARM processor, running the bus at ASIC core clock or half core clock as programmed in the Processor Control and Status Register. </li><li id="ul0004-0009" num="0113"> Handles all transaction types for PIO's (reads and writes of I/O registers), cache fills/spills, and non-cached memory accesses. </li><li id="ul0004-0010" num="0114"> Low- and high-priority interrupt signals, driven by enabled bits of PISR and PCSR. </li><li id="ul0004-0011" num="0115"> Boots from main memory; an external agent must initialize memory, download local initialization code etc, and release processor reset to enable operation. </li><li id="ul0004-0012" num="0116"> Support for remap of the trap/reset vector to any location in PE Memory. <br /> 3. Classification Engine </li><li id="ul0004-0013" num="0117"> Microcoded engine for accelerating comparisons and hash lookups. </li><li id="ul0004-0014" num="0118"> Runs a set of comparisons on fields extracted from 32-bit words within a packet to offload processor. </li><li id="ul0004-0015" num="0119"> Operations can be on fields in the packet, or on pairs of result bits from previous comparisons. </li><li id="ul0004-0016" num="0120"> Produces a result vector of one bit result for each comparison or for each boolean operation on pairs of bits in the vector (selected bits of which are then stored in a data structure in the 2 KB packet buffer). </li><li id="ul0004-0017" num="0121"> Can also execute one or more hash lookups on one or more tables based on keys extracted from the packet. Optimized for linked list chasing through the use of non-blocking loads and speculative fetch of the next record; searches of hash tables implementing conflict resolution by chaining are thus accelerated. The hash lookup results are also stored in the packet buffer in memory. </li><li id="ul0004-0018" num="0122"> Arbitrary fields can be extracted from the packet and returned in the packet's data structure to the PP. Arbitrary computation on extracted fields and result vector bits which yield multi-bit results can also be done in the CE, and the results returned to the PP in the data structure. </li><li id="ul0004-0019" num="0123"> The above computations could also incorporate operands found in hash table records found during the above hash searches. </li><li id="ul0004-0020" num="0124"> The contents of hash table records found using keys extracted from the packet can be updated with results of computations such as those described above. </li><li id="ul0004-0021" num="0125"> Supports fast TCP/IP checksum calculation via use of the “split-add” unit. </li><li id="ul0004-0022" num="0126"> Decisions and branches are supported. </li><li id="ul0004-0023" num="0127"> Comparisons, extractions and computations, and hashing are run speculatively before the packet is handed to the Policy Processor; if the code on the PP (the Action section of the application) needs to run rules against the packet, the comparisons are done and ready for it to use, with single-bit decisions (“predicate analysis results”) for each policy to apply. Similarly, if the Action code needs to compute or extract information about the packet, the results of that computation are already available in the packet's data structure. </li><li id="ul0004-0024" num="0128"> Packets are scheduled for classification from both the RX MAC ring and a reclassification ring for the “Inbound” CEs, from a reclassification ring alone for “Outbound” CEs. <br /> 4. Ethernet MACs </li><li id="ul0004-0025" num="0129"> Standard 10/100 Mbit ILEEE 802.3u-compliant MAC with MII interface to external PHY. </li><li id="ul0004-0026" num="0130"> Each RX MAC has support for a single unicast address match, multicast hash filter, broadcast packets, and promiscuous mode. </li><li id="ul0004-0027" num="0131"> Serial MII management interface to PHY. </li><li id="ul0004-0028" num="0132"> RX MAC inserts packets along with receive status into 2 KB-aligned buffers, with the packet aligned so that the IP header is on a 32-bit boundary; keeping the receive buffer ring replenished with empty buffers is the only processor interaction with the MAC (i.e. there is no run-time device driver needed for the MAC). </li><li id="ul0004-0029" num="0133"> Transmit MAC follows a ring of buffer pointers; scheduling of transmit buffers from any source is supported through a register which makes enqueuing atomic, thus allowing multiple masters to schedule transmits without mutexes. </li><li id="ul0004-0030" num="0134"> Mode bit for PASS or DROP of bad ethernet packets (CRC errors etc). </li><li id="ul0004-0031" num="0135"> Hardware counters to support RMON ETHER statistics gathering. </li><li id="ul0004-0032" num="0136"> MACs operate on 2.5 MHZ/25 MHz RXCLK and TXCLK from the external Fast Ethernet PHY, each has its own clock domain and a synchronizing interface to the ASIC core. <br /> 5. Memory Controller </li><li id="ul0004-0033" num="0137"> Manages up to two DIMMs of SDRAM. </li><li id="ul0004-0034" num="0138"> Aggressively schedules two banks independently for high performance. </li><li id="ul0004-0035" num="0139"> Arbitrates among many agents; priorities are: </li><li id="ul0004-0036" num="0140"> 1) MAC_A, MAC_B ping-pong (top prio); internal to each MAC, the TX and RX units arbitrate locally for the MAC's memory interface, with ping-pong priority </li><li id="ul0004-0037" num="0141"> 2) Round-robin priority among PP, CE_AI, CE_AO, CE_BI, CE_BO, DMA, PCI_Target, Crypto <ul id="ul0005" list-style="none"><li id="ul0005-0001" num="0142"> Supports different speed grades of SDRAM, programmable timing. </li><li id="ul0005-0002" num="0143"> Parity generation and checking. </li><li id="ul0005-0003" num="0144"> Serial Presence Detect (SPD) interface. </li><li id="ul0005-0004" num="0145"> Contains the Ring Translation Unit for mapping Ring accesses to Memory addresses. </li><li id="ul0005-0005" num="0146"> Contains the Mailbox address-matching and status unit. <br /> 6. DMA Engine </li></ul></li><li id="ul0004-0038" num="0147"> Can be used by PP, Crypto, and also by the host (Application Processor) and PCI peer devices. </li><li id="ul0004-0039" num="0148"> Moves word-aligned bursts of data between SDRAM and PCIbus. </li><li id="ul0004-0040" num="0149"> Data is transferred between memory and PCI in byte lane order, for endian-neutral transfers of byte streams. See “Endianness” in Section 8. </li><li id="ul0004-0041" num="0150"> Each DMA is controlled by a 16-byte descriptor; the initiator first constructs a descriptor, then enqueues a pointer to that descriptor on the DMA Ring to schedule the transfer. </li><li id="ul0004-0042" num="0151"> Atomic enqueueing is supported to eliminate locks when scheduling DMAs. </li><li id="ul0004-0043" num="0152"> At completion of each DMA, the unit can optionally set one of 8 status bits in the PISR (Processor Interrupt Status Register) or one of 8 status bits in the HISR (Host Interrupt Status Register), as indicated in the descriptor. </li><li id="ul0004-0044" num="0153"> DMA engine ignores lower 11 bits of the SDRAM address, using a separate “buffer offset” instead. This is to support the buffer tag field in the buffer pointer used by software. </li><li id="ul0004-0045" num="0154"> Descriptor is defined in “DMA Command Queue and Descriptors” in Section 6. </li><li id="ul0004-0046" num="0155"> PCI command code is carried in the descriptor for flexibility. <br /> 7. Crypto Control </li><li id="ul0004-0047" num="0156"> PE ASIC hosts a 32-bit PCI bus for connecting to the Crypto coprocessor(s), with two external request/grant pairs and two interrupt inputs. PP can directly access devices on this bus. </li><li id="ul0004-0048" num="0157"> 4 BAR's (“Base Address Registers”, which are part of the PCI standard) are supported: BAR<b>0</b> for Memory, BAR<b>1</b> for access to the ring status bits, BAR<b>2</b> for access to the rings, and BAR<b>3</b> for prefetched access to Memory. </li><li id="ul0004-0049" num="0158"> Packets are scheduled for encryption by placing a Crypto descriptor in a data structure in the packet buffer in memory, then enqueueing the pointer to that buffer in the Crypto Ring. (Communication Ring <b>4</b> is also available for similar use with a second coprocessor.) </li><li id="ul0004-0050" num="0159"> The Crypto chip will detect queue-not-empty by polling the CSTAT (Crypto Status Register) register and will dequeue the buffer pointer at the head of the queue for processing. Two rings are available so that up to two devices can be supported for this function. </li><li id="ul0004-0051" num="0160"> After processing a packet, the Crypto chip will write the results back to memory and then enqueue the buffer pointer on the specified destination ring (for further classification, for examination on the PP, for DMA to a target on the PCI bus, or for transmit.) <br /> 8. Mailbox Unit </li><li id="ul0004-0052" num="0161"> Monitors 16 word-sized mailboxes in memory space. </li><li id="ul0004-0053" num="0162"> On address match, sets(clears) the status bit in the Mailbox Status Register associated with the word written(read). Selected status bits contribute to a Mailbox Attention status bit in the PISR. <br /> 9. Ring Translation Unit </li><li id="ul0004-0054" num="0163"> Base pointer to a 64 KB region of memory (only the first 60 KB are used, 4 KB remainder is available for other use). </li><li id="ul0004-0055" num="0164"> Maintains 15 rings as memory arrays of 1K 32-bit entries each. </li><li id="ul0004-0056" num="0165"> Reads and writes to rings through the RTU are mapped to locations in these arrays. </li><li id="ul0004-0057" num="0166"> Some index registers auto-increment, others are incremented by their owner. </li><li id="ul0004-0058" num="0167"> Delta between producer-consumer index pairs is detected in hardware. Any delta is signaled to the consumer indicating that there is work to do. </li><li id="ul0004-0059" num="0168"> 10 of the rings have specific assignment as shown in <figref idref="DRAWINGS">FIG. 3</figref>. </li><li id="ul0004-0060" num="0169"> 5 general-purpose rings COM[<b>4</b>:<b>0</b>] are provided for software to allocate as desired; expected use includes a freelist for DMA descriptors and a freelist of buffers for the AP or peers to use, messages-in to the PP, and others. COM<b>4</b> can optionally be used as a second Crypto ring. </li><li id="ul0004-0061" num="0170"> Overflow/underflow and threshold conditions are detected and reported through the CRISIS register in the Policy Processor interface. <br /> 10. Global TIMER </li><li id="ul0004-0062" num="0171"> 32-bit up-counter driven from an external, asynchronous clock source. </li><li id="ul0004-0063" num="0172"> Counts at 1 uS in bit <b>3</b> (leaving room for finer granularity in future higher speed implementations.) Counter rolls over approximately every 536.87 seconds. </li><li id="ul0004-0064" num="0173"> Status bit in PISR/HISR sets on every transition (high-low and low-high) in bit[<b>30</b>] to simplify software extension of the timer value. </li><li id="ul0004-0065" num="0174"> An Ethernet crystal (buffered copy) is used as the clock source since it is the most stable timebase available. Runs at 25 MHz. </li><li id="ul0004-0066" num="0175"> In multi-PE implementations, all PE's receive the same clock source to avoid relative drift in timestamps. In systems using multiple PCI cards each containing a PE they each receive a local, non-aligned clock. </li><li id="ul0004-0067" num="0176"> Used by MACs, Classification Engines, and PP for marking events; used for monitoring performance and packet arrival order as needed. <br /> 11. Serial PROM </li><li id="ul0004-0068" num="0177"> Support for a 24C02 256-byte serial PROM at serial address 0x7; the memory DIMMs are at addresses 0x0 and 0x1 for slots <b>0</b> and <b>1</b> (if supported). </li><li id="ul0004-0069" num="0178"> PROM at 0x7 contains two MAC addresses, full/half-speed control indication for the processor bus, manufacturing information, and other configuration and tracking information. </li><li id="ul0004-0070" num="0179"> Additional devices on the SPD bus include a Crypto Daughtercard IDPROM at address 0x6, and a thermal sensor at address 0x4. </li></ul></li></ul>

III. Data Structures

00001. Ring Array in Memory

0180The 15 rings are packed into a 60 KB array aligned on a 64 KB boundary in memory. The RING_BASE register points to the start of this array. Each ring is 4 KB in size and can hold up to 1K entries of 32 bits each.

0181<figref idref="DRAWINGS">FIG. 5</figref> illustrates a ring array in memory.

0182The Ring Translation Unit (RTU) <b>264</b> manages 15 arrays in memory <b>260</b> for communication purposes. Each ring actually consists of 1024 32-bit entries in memory for a total of 4 KB per ring, along with index registers and logic for detecting differences between the index register for a producer and the index register for the associated consumer, which is reported to that consumer as an indication that there is work for it to do. Various near-full-threshold, near-empty-threshold, full, and empty conditions are detected as appropriate to each ring and are reported to the ring users and to the Policy Processor <b>244</b> as appropriate. The RTU <b>264</b> translates Ring accesses into both a memory <b>260</b> access at a translated address, and in some cases into commands to increment specific index pointers after completing that memory access. Each ring is assigned a number for mapping purposes, and that number is used to index into the array of memory <b>260</b> in which the rings are implemented. The index registers are incremented modulo 4 KB so that FIFO behavior is achieved. Each index register contains one more significant bit than is used for addressing, so that a full ring can be differentiated from an empty ring.

0183A Ring Base Register <b>400</b> selects the location in memory <b>260</b> of the base of the 64 KB-aligned array <b>440</b> represented in <figref idref="DRAWINGS">FIG. 5</figref>. The structure is an array of arrays; there is an array of 15 rings indexed by the ring number, and each of those rings is a 4 KB array of 1024 32-bit entries indexed by various index registers used by different agents.

0184RX_A Ring <b>402</b> and RX_B Ring <b>404</b> implement the structure described in <figref idref="DRAWINGS">FIG. 6</figref>, and are associated with the receive streams from RX MAC_A <b>220</b> and RX MAC_B <b>228</b> respectively. TX_A Ring <b>406</b> and TX_B Ring <b>408</b> implement the structure of <figref idref="DRAWINGS">FIG. 8</figref>, and are associated with the transmit MACs <b>222</b> and <b>232</b> respectively. The Reclassify Rings <b>410</b>, <b>412</b>, <b>414</b>, and <b>416</b> are used to schedule packets for classification on Classification Engines <b>238</b>, <b>208</b>, <b>242</b>, and <b>212</b> respectively, and implement the structure shown in <figref idref="DRAWINGS">FIG. 10</figref>.

0185DMA Ring <b>418</b> is used to schedule descriptor pointers for consumption by DMA Unit <b>210</b>, and implements the structure shown in <figref idref="DRAWINGS">FIG. 12</figref>. Crypto Ring <b>420</b> is used to schedule buffers for processing on the Crypto Processor <b>246</b> and implements the structure shown in <figref idref="DRAWINGS">FIG. 11</figref>. The five general purpose communication rings COM[<b>4</b>:<b>0</b>] are available for assignment by software and also implement the structure shown in <figref idref="DRAWINGS">FIG. 11</figref>.

00002. RX Buffer Pointer Ring and Produce/Consume Pointers

0186A ring of buffer pointers resides in the memory for each RX MAC. Associated with this ring are produce and consume index pointers for the various users of these buffers to access specific rings. The Policy Processor allocates free, empty buffers to the MAC by writing them to the associated MPROD address in the Ring Translation Unit (RTU), which writes the buffer address into the ring and increments the MPROD pointer modulo ring size. The RX MAC chases that pointer with the MFILL index which is used to find the next available empty buffer. That pointer is chased by MCCONS which is used by the Classification Engine to identify the next packet to run the classification microcode on. The PP uses a status bit in the PISR to see that there is at least one classified packet to process, then reads the ring through MPCONS in the RTU to identify the next buffer that the PP needs to process.

0187<figref idref="DRAWINGS">FIG. 6</figref> shows an RX Ring Structure related to certain embodiments of the present invention. There are two RX Rings <b>402</b> and <b>404</b>. Each is located in the Ring Array in memory <b>260</b>. Each has four index registers associated with it. <figref idref="DRAWINGS">FIG. 6</figref> shows the ring as an array in memory with lower addresses to the top and higher addresses to the bottom of the picture.

0188The ring's base address <b>510</b> is a combination of the Ring Base Register <b>400</b> and the ring number which is used to index into the Ring Array <b>440</b> as shown in <figref idref="DRAWINGS">FIG. 5</figref>. Two instances of the set of four index registers MPCONS <b>512</b>, MCCONS <b>514</b>, MFILL <b>516</b>, and MPROD <b>518</b> are used to provide an offset from the RX Ring Base <b>510</b> of the particular ring <b>402</b> or <b>404</b>, each of which is a 4 KB array <b>520</b>.

0189MPROD <b>518</b> is the lead producer index for this ring. The Policy Processor <b>244</b> or the Application Processor <b>302</b> enqueues buffer pointers into the RX Ring <b>402</b> or <b>404</b> by writing the buffer pointer to the RTU's enqueue address for the particular ring <b>402</b> or <b>404</b>, which causes the RTU to write the buffer pointer to the location in memory <b>260</b> referenced by MPROD <b>518</b>, and then to increment MPROD <b>518</b> modulo the ring size of 4096 bytes. This process allocates an empty buffer to the RX MAC MAC_A or MAC_B associated with ring <b>402</b> or <b>404</b> respectively.

0190MPROD <b>518</b> and MFILL <b>516</b> have a producer-consumer relationship. Any time there is a difference between the value of MPROD <b>518</b> and MFILL <b>516</b>, the RTU <b>264</b> signals to the associated RX MAC MAC_A or MAC_B that it has empty buffers available. The region <b>506</b> in the RX Ring <b>402</b> or <b>404</b> represents one or more valid, empty buffers that have been allocated to the associated RX MAC by enqueueing the pointers to those buffers.

0191When the RX MAC MAC_A or MAC_B receives a packet, it obtains the buffer pointer referenced by its associated MFILL pointer <b>516</b> by reading from the RTU's MFILL address and then writes the packet and associated RX Status <b>600</b> and RX Timestamp <b>602</b> into the buffer pointed to by that buffer pointer. When the RX_MAC has successfully received a packet and has finished transferring it into the buffer, it increments the index MFILL <b>516</b> by a hardware signal to the RTU which causes the RTU to increment MFILL <b>516</b> modulo the ring size of 4096 bytes. MFILL <b>516</b> and MCCONS <b>514</b> have a producer-consumer relationship; when the RTU <b>264</b> detects a difference between the value of MFILL <b>516</b> and MCCONS <b>514</b> it signals to that ring's associated Classification Engine <b>238</b> or <b>242</b> that it has a freshly received packet to process. The region <b>504</b> in the ring array contains the buffer pointers to one or more full, unclassified buffers that the RX MAC has passed to the associated Classification Engine.

0192The Classification Engine <b>238</b> or <b>242</b> receives a signal if the RTU <b>264</b> detects full, unclassified packets in RX Ring <b>402</b> or <b>404</b>, respectively. When the dispatch microcode on that CE <b>238</b> or <b>242</b> tests the ring status and sees this signal from the RTU <b>264</b>, that CE <b>238</b> or <b>242</b> obtains the buffer pointer by reading from the RTU's MCCONS address for that ring. When the CE <b>238</b> or <b>242</b> has finished processing that buffer and has written all results back to memory <b>260</b>, it signals to the RTU <b>264</b> to increment its associated MCCONS index <b>514</b>. Upon receiving this signal the RTU <b>264</b> increments MCCONS <b>514</b> modulo the ring size of 4096 bytes. By sending the signal, the CE <b>238</b> or <b>242</b> has indicated that it is done processing that packet and that the packet is available for the consumer, which is action code <b>108</b> running on the Policy Processor <b>244</b>. The region <b>502</b> contains the buffer pointers for one or more full, classified packets that the Classification Engine has passed to the Action Code <b>108</b>.

0193MCCONS <b>514</b> and MPCONS <b>512</b> have a producer-consumer relationship. When the CE <b>238</b> or <b>242</b> has produced a full, classified packet then that packet is available for consumption by the action code <b>108</b>. The RTU detects when there is a difference between the values of MCCONS <b>514</b> and MPCONS <b>512</b> and signals this to the Policy Processor <b>244</b> through a status register in the Processor Interface <b>206</b>. The Policy Processor <b>224</b> monitors this register, and when dispatch code on the Policy Processor <b>224</b> determines that it is ready to process a full, classified packet it dequeues the buffer pointer of that packet from the RX Ring <b>402</b> or <b>404</b>, as appropriate, by reading the RTU's dequeue address for that ring. This read causes the RTU to return to the Policy Processor <b>244</b> the buffer pointer referenced by that ring's MPCONS index <b>512</b>, and then to increment MPCONS <b>512</b> modulo the ring size of 4096 bytes. The act of dequeueing the buffer pointer means that the pointer no longer has any meaning in the RX ring. The contents of the ring in locations between MPCONS <b>512</b> and MPROD <b>518</b> have no meaning, and are indicated by the Invalid regions <b>500</b> and <b>508</b>. Since this is a ring structure which wraps, <b>500</b> and <b>508</b> are actually the same region; in the figure shown, due the current values of the ring index pointers <b>512</b>, <b>514</b>, <b>516</b>, and <b>518</b> the Invalid regions <b>500</b> and <b>508</b> happens to wrap across the start and end of the array containing this ring, but it should be obvious to one skilled in the art that under normal circumstances these ring index pointers can have different values and any of regions <b>502</b>, <b>504</b>, or <b>506</b> could also be region which wraps around the end and beginning of the array <b>520</b>.

00002.1 RX Buffer Structure

0194The receive data buffer is a 2 KB structure which contains an Ethernet packet and information about that packet. A substantially similar format is used for transmitting the packet, as indicated in <figref idref="DRAWINGS">FIG. 8</figref>. The packet offset from the base of the buffer is designed so that upon receive the Ether header is offset by two bytes into a word, thus aligning the IP header on a word (32-bit) boundary. Enough space is left before the packet so that encapsulation/encryption headers (e.g., up to 40 bytes for a standard IPv6 header plus AH and ESP) can be inserted for encapsulation of the packet without copying the packet, by just copying the Ethernet header up to make space and then inserting the encapsulation headers. The total pad size is 112 Bytes; if more is needed then the Crypto Coprocessor can realign the packet when writing it back.

0195The RX MAC can be programmed to either drop bad packets or receive them normally; if the latter, then error status is also shown in the buffer RX status field.

0196<figref idref="DRAWINGS">FIG. 7</figref> illustrates the receive buffer format.

0197A packet is passed around the system by placing it into a packet buffer <b>620</b> and then passing the 2 KB-aligned buffer pointer among units via pointer rings implemented by the RTU <b>264</b>. The RX Status and Transmit Command Word <b>600</b> is always located at the word pointed to by the 2 KB-aligned buffer pointer. All hardware in the Policy Engine <b>322</b> is designed to assume that a buffer pointer is 2 KB-aligned and to ignore bits [<b>10</b>:<b>0</b>], which allows software to use bits [<b>10</b>:<b>0</b>] of the buffer pointer to carry software tag information associated with that buffer.

0198Upon receiving a packet the RX MAC <b>220</b> or <b>228</b> places that packet at an offset of (130) bytes from the beginning of a buffer <b>620</b>, and writes zero to the bytes at byte offset (128) and (129) from the beginning of that buffer; these two bytes are called the Ethernet Header Pad <b>618</b>. The packet consists of the (14)-byte Ethernet header <b>610</b> and the payload <b>612</b> of the Ethernet packet, which are stored contiguously in the buffer <b>620</b>. The reason for inserting the Ethernet Header Pad is to force protocol headers encapsulated in the Ethernet packet to be word (32-bit) aligned for ease in further processing; encapsulated protocols such as IP, TCP, UDP etc have word-oriented formats.

0199The RX MAC control logic <b>220</b> or <b>228</b> then writes the RX Status Word <b>600</b> into the buffer <b>620</b> at an offset of (0) from the start of the buffer, and an RX Timestamp <b>602</b> as a 32-bit word at byte offset (4) from the start of the buffer <b>620</b>. The RX Status Word has the format shown in Table 1. The timestamp is the value obtained from the Timestamp Register <b>214</b> at the time the RX status <b>600</b> is written to the buffer <b>620</b>. The TX Status Word <b>604</b> and the TX Timestamp <b>606</b> are not written at this time, but those locations covering the two 32-bit words at offsets of 8 and 12 bytes, respectively, from the start of the buffer <b>620</b> are reserved for later use by the TX MAC controllers <b>222</b> and <b>232</b>.

0200The format for the RX Status word in Table 1 is such that it can be used directly as a TX Command Word without modification; the fields LENGTH and PKT_OFFSET have the same meaning in both formats. The RX MAC controller <b>220</b> or <b>228</b> subtracts (4) bytes from the Ethernet packet's length before storing the LENGTH field in the RX Status Word <b>600</b> such that the (4-byte) Ethernet CRC is not counted in LENGTH, so that the buffer can be handed to a TX MAC <b>222</b> or <b>232</b> without need for the Policy Processor <b>244</b> modifying the contents of the buffer.

0201Pad Space <b>608</b> is left before the start of the packet <b>610</b> and <b>612</b> in buffer <b>620</b> to support the addition of encapsulating protocol headers without copying the entire packet. Up to (112) bytes of encapsulation header(s) can be inserted simply by copying the ethernet header <b>610</b> (and possibly an associated SNAP encapsulation header in the start of payload <b>612</b>) upwards into the Pad Space <b>608</b> by the number of bytes necessary to make room for the inserted headers, which are then written into the location that was opened up for them in areas <b>608</b>, <b>610</b>, and <b>612</b> as needed. If more than (112) bytes of encapsulation header are being inserted then the entire payload <b>612</b> must be copied to a different location in the buffer to make room for the inserted headers.

0202The per-packet software data structure <b>614</b> is used by the classification <b>106</b>, action code <b>108</b>, encryption processing <b>112</b>, the host <b>302</b> and PCI peers <b>322</b>, <b>314</b>, and <b>316</b> to carry information about the packet that is carried in the buffer <b>620</b>. The location of the software data structure <b>614</b> and the sizes of the packet header <b>610</b> and packet payload <b>612</b>, as well as the total size of the packet buffer <b>620</b> are not hard limits in the preferred embodiment. The 2 KB-alignment of the RX status word <b>600</b> and RX Timestamp are enforced by the hardware; but packets from other sources and also from other media besides Ethernet can be injected into the classification flow of <figref idref="DRAWINGS">FIG. 2</figref> as follows. The SOURCE field of the RX status word <b>600</b> as shown in Table 1 has only a few reserved codes; the rest can be assigned by software to identify packets from other sources and also from other media which do not share the packet format or packet size of Ethernet. By software convention larger buffers can be assigned by grouping contiguous 2 KB buffers together and treating them as one buffer; the pointer to this larger buffer <b>602</b> will still be 2 KB-aligned and the RX Status Word <b>600</b> and RX Timestamp <b>602</b> will still reside at that location in the buffer. The packet area <b>610</b> and <b>612</b> can be made arbitrarily large to accommodate a packet from a different medium. The location of the software data structure <b>614</b> can be moved downwards as the larger payload space is allocated. Alternatively the software can choose to allocate buffers so that they have space before the 2 KB-aligned RX Status Word <b>600</b>, and carry the software data structure <b>614</b> above the RX Status Word <b>600</b> rather than below the Payload <b>612</b> as shown in <figref idref="DRAWINGS">FIG. 7</figref>. The advantage of this second approach is that the location of the software data structure is always known to be at a fixed location relative to the RX Status Word <b>600</b>, rather than having that location be a variable depending on different media and the resulting variations in the size of the packet payload <b>612</b>.

0203The section marked “Available for software use” contains transient per-packet information such as the result vector and hash pointers output by the Classification Engine, a command descriptor for the Crypto Unit, buffer reference counts, an optional pointer to an extension buffer, and any other data structures that the software defines. “TX Status/TX Timestamp” is optionally written by the transmit MAC if it is programmed to do so; that field contains garbage after an RX.

0204The “RX Timestamp” field contains the 32-bit value of the chip's TIMER register at the time that the packet was successfully received (approximately the time of receipt of the end of packet) and the RX_STATUS field was written. The “RX Status” field is one 32-bit word with the following format:

0205Note throughout this document that bit [<b>31</b>] is the left (most significant) bit of a 32-bit word, and bit [<b>0</b>] is right (least significant). “MCSR” mentioned in Table 1, below, is the MAC Control and Status Register. <tables id="TABLE-US-00001" num="1"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="364PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 1</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Ethernet RX Status Word and TX Command Word Format</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="28PT" align="center" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="280PT" align="left" /><tbody valign="top"><row><entry>Bits</entry><entry>Field</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>[31]</entry><entry>BAD_PKT</entry><entry>Summary error bit; set if any of [30:27, 15:14] is set, which can only happen if the MAC is</entry></row><row><entry /><entry /><entry>programmed to receive bad frames.</entry></row><row><entry>[30]</entry><entry>CRC_ERR</entry><entry>Ethernet frame had incorrect CRC and (MCSR[RCV_BAD]==1) for this MAC.</entry></row><row><entry>[29]</entry><entry>RUNT</entry><entry>Ethernet frame was smaller than legal and (MCSR[RCV_BAD]==1) for this MAC</entry></row><row><entry>[28]</entry><entry>GIANT</entry><entry>Ethernet frame was larger than legal and (MCSR[RCV_BAD]==1) for this MAC</entry></row><row><entry>[27]</entry><entry>PREAMB_ERR</entry><entry>Invalid preamble and (MCSR[RCV_BAD]==1) for this MAC. This error is associated with</entry></row><row><entry /><entry /><entry>some previous event, not with the current packet.</entry></row><row><entry>[26:16]</entry><entry>LENGTH</entry><entry>For RX, number of bytes in the Ethernet frame including the Ethernet header but not including</entry></row><row><entry /><entry /><entry>the Ethernet CRC. For TX, length of packet, including CRC if (MCSR[CRC_EN]==0)</entry></row><row><entry>[15]</entry><entry>DRBL_ERR</entry><entry>Odd number of nibbles received (dribble) and (MCSR[RCV_BAD]==1) for this MAC</entry></row><row><entry>[14]</entry><entry>CODE_ERR</entry><entry>4b/5b encoding error and (MCSR[RCV_BAD]==1) for this MAC</entry></row><row><entry>[13]</entry><entry>BCAST</entry><entry>The received packet was a broadcast packet (destination address is all 1's)</entry></row><row><entry>[12]</entry><entry>MCAST</entry><entry>The received packet was a multicast packet and was passed by the multicast hash filter</entry></row><row><entry>[11:08]</entry><entry>SOURCE</entry><entry>This indicates the source of the packet or other source as marked later by software. If the packet</entry></row><row><entry /><entry /><entry>was generated at a RX MAC then this field is 0x0 for MAC_A or 0x1 for MAC_B.</entry></row><row><entry>[07:00]</entry><entry>PKT_OFFSET</entry><entry>This is the byte offset from the beginning of the packet buffer to the first byte of the Ethernet</entry></row><row><entry /><entry /><entry>header. Other agents may choose to move this offset in order to encapsulate the IP packet or to</entry></row><row><entry /><entry /><entry>strip of encapsulation headers. The CE, PP, and AP all use this offset when accessing the frame</entry></row><row><entry /><entry /><entry>in this buffer. The RX MAC will always write a value of 0x82 into this field, indicating that the</entry></row><row><entry /><entry /><entry>Ethernet Frame was received into the buffer starting at byte offset 130 from the start of the</entry></row><row><entry /><entry /><entry>buffer.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> The same packet buffer format is used for encryption and transmission; for those uses the only meaningful fields are LENGTH, PKT_OFFSET and the contents of the Ethernet frame found at that offset; plus for encryption the encryption descriptor included in the “Software” area in the buffer. <br /> 3. TX Buffer Pointer Rings and Producer/Consumer Pointers

0206A packet gets scheduled for transmission by enqueueing the address of the buffer onto the pointer queue for that transmit MAC, by writing it to MTPROD in the RTU (MAC A and MAC B each have their own ring and associated registers). Any time the produce pointer is not equal to the consume pointer for that ring, the associated MAC will be notified that there is at least one packet to transmit and will follow the pointer to obtain the next buffer to deal with. When the packet has been retired the TX controller will write back status if configured to do so, then increment the consume pointer and continue to the next buffer (if any.)

0207The recover pointer is used to track retired buffers (either successfully transmitted or abandoned due to transmit termination conditions) for return to the buffer pool, or possibly for a retransmit attempt; the PP is signaled by the RTU that there is a delta between MTCONS and MTRECOV, and then reads the Ring through the RTU register MTRECOV to get the pointer to the next buffer to recover. MTPROD, MTCONS, and MTRECOV are duplicated for each instance of a transmit MAC.

0208<figref idref="DRAWINGS">FIG. 8</figref> illustrates the TX Ring Structure according to certain embodiments of the present invention.

0209The TX Rings <b>406</b> and <b>408</b> have substantially the same structure as the RX Rings described previously. The fundamental differences are that there is one fewer interim producer-consumer using this ring, and that this ring is assigned for a different function with different agents using it. Each ring <b>406</b> and <b>408</b> is a 4096-byte array <b>720</b> in memory <b>260</b>.

0210A packet is scheduled for transmit on the TX MACs <b>222</b> or <b>232</b> by enqueuing a pointer to the buffer containing the packet onto TX Ring <b>406</b> or <b>408</b>, respectively. The buffer pointer is enqueued onto <b>406</b> or <b>408</b> by any agent, by writing the buffer pointer to the RTU <b>264</b> enqueue address for that ring. The RTU <b>264</b> writes the buffer pointer to the location in memory <b>260</b> referenced by the MTPROD index register <b>716</b>, and then increments MTPROD <b>716</b> modulo the ring size of 4096 bytes. There is a producer-consumer relationship between MTPROD <b>716</b> and MTCONS <b>714</b>; when the RTU detects a difference in the values of MTPROD <b>716</b> and MTCONS <b>714</b> it signals to the associated TX MAC controller <b>222</b> or <b>232</b> that there is a packet ready to transmit. The region <b>706</b> in the TX Ring <b>406</b> or <b>408</b> contains one or more buffer pointers for the buffers containing packets scheduled for transmission.

0211The TX MAC controller <b>222</b> or <b>232</b> obtains the buffer pointer for the buffer <b>206</b> containing this packet by reading the RTU's MTCONS address for TX Ring <b>406</b> or <b>408</b>, respectively, which causes the RTU to return to the MAC the buffer pointer in memory <b>260</b> referenced by MTCONS <b>714</b>. When the TX MAC <b>218</b> or <b>234</b> has successfully transmitted this packet or has abandoned transmitting this packet due to transmit termination conditions, its controller <b>222</b> or <b>232</b> respectively will optionally write back TX Status <b>806</b> and TX Timestamp <b>808</b> if it has been configured to write status, then retires the buffer by signaling to the RTU <b>264</b> to increment MTCONS <b>714</b>. Upon receiving this signal the RTU <b>264</b> will increment MTCONS <b>714</b> modulo the ring size of 4096 bytes.

0212Index registers MTCONS <b>714</b> and MTRECOV <b>712</b> have a producer-consumer relationship. When the RTU detects a difference in their values, it signals to the PP that the associated TX ring <b>406</b> or <b>408</b> has a retired buffer to recover. That information is visible to the Policy Processor <b>244</b> in a status register in Processor Interface <b>206</b> which the Policy Processor <b>244</b> polls on occasion to see what work it needs to dispatch. Upon testing the RECOVER status for the TX Ring <b>406</b> or <b>408</b> and detecting that there is at least one buffer to recover, the Buffer Recovery code <b>118</b> reads the RTU's <b>264</b> MTRECOV address for that ring to dequeue the buffer pointer from the TX ring <b>406</b> or <b>408</b>. The read causes the RTU to return the buffer pointer referenced by MTRECOV <b>712</b>, and then to increment MTRECOV <b>712</b> modulo the ring size of 4096 bytes. The region <b>704</b> contains the buffer pointers of buffers which have been retired by the TX MAC <b>222</b> or <b>232</b> but have not yet been recovered by the Buffer Recovery code <b>118</b>.

0213The regions <b>702</b> and <b>708</b> are the same region, which in the figure shown are spanning the end and the beginning of the array <b>720</b> in memory <b>260</b> which contains the TX Ring <b>406</b> or <b>408</b>. This region contains entries which are neither a buffer pointer to a buffer ready for transmit, nor a buffer pointer to a buffer which the TX MAC <b>222</b> or <b>232</b> has retired but the recovery code <b>118</b> has not yet dequeued. For the purposes of a TX Ring <b>406</b> or <b>408</b> this region consists of space into which more packets may be scheduled for transmit. One skilled in the art will recognized that region <b>704</b> or region <b>706</b> could just as easily be the region wrapping around the array boundary, depending on the values of MTRECOV <b>712</b>, MTCONS <b>714</b>, and MTPROD <b>716</b>.

0214Embedded in the buffer is the packet length in bytes (including the Ethernet header, but not including the CRC since the TX MAC will generate that) and also the byte offset within the buffer where the Ethernet header begins. The offset is necessary since the start of packet might have been moved back (if adding encapsulation headers) or forward (if decapsulating a packet.) The Ethernet header typically starts at byte offset 0x2 within that word, but the TX MAC supports arbitrary byte alignment. PKT_OFFSET and LENGTH are found in the “RX Status” and “TX Command” word of the buffer as described in Table 1; for transmit purposes those are the only two meaningful fields in that word.

0215The area labeled “TX Status/TX Timestamp” is optionally written with one word of transmit status plus the value of TIMER at the time the field is written, if MCSR[TX_STAT] is set; the content of that word is described in Table 2.

0216<figref idref="DRAWINGS">FIG. 9</figref> illustrates the transmit buffer format according to certain embodiments of the present invention.

0217When a packet is scheduled through TX Ring <b>406</b> or <b>408</b> to be transmitted on a TX MAC <b>218</b> or <b>234</b>, respectively, the TX MAC controller <b>222</b> or <b>232</b>, respectively, interprets the contents of the packet buffer <b>840</b> in accordance with the format shown in <figref idref="DRAWINGS">FIG. 9</figref>. The RX Status Word and TX Command Word <b>802</b> is found at the location pointed to by the 2 KB-aligned buffer pointer obtained from the TX Ring <b>406</b> or <b>408</b>. The RX Status and TX Command Word <b>802</b> is in the format specified by Table 1; when this word is interpreted by the TX MAC controller <b>222</b> or <b>232</b> only the fields LENGTH and PKT_OFFSET have any meaning and the rest of the word is ignored. PKT_OFFSET indicates the byte offset from the start of the 2 KB-aligned buffer at which the first byte of the Ethernet header is to be found, and LENGTH is the number of bytes to be transmitted not including the (4-byte) Ethernet CRC which the TX MAC <b>222</b> or <b>232</b> will generate and append to the packet as it is being transmitted. The RX Timestamp <b>804</b> was used by previous agents processing this buffer, and is not interpreted by the TX MAC controller <b>222</b> or <b>232</b>.

0218The PKT_OFFSET field can legitimately have any value between (16) and (255), allowing the agent that scheduled the transmit to manipulate headers and to relocate the start of the packet header <b>812</b> as needed. <figref idref="DRAWINGS">FIG. 9</figref>. shows a zero-filled two-byte pad <b>830</b> prior to the start of Ether Header <b>812</b>, but that is not a requirement of the preferred embodiment; the TX MAC <b>222</b> or <b>232</b> can transmit a packet which starts at any arbitrary byte alignment in the transmit buffer <b>840</b>. The two-byte pad <b>830</b> shown preceding the header <b>812</b> is shown to illustrate the common case, wherein a received packet was thus aligned and any movement of the ethernet header <b>812</b> for encapsulation or decapsulation of protocols is in units of words (4 bytes.) Pad Space <b>810</b> can vary in size from zero bytes to (240) bytes as defined by the value of PKT_OFFSET in the TX Command Word <b>802</b>.

0219The concatenation of Ether Header <b>812</b> and Payload <b>814</b> comprise the packet that is transmitted, along with the generated Ethernet CRC which the TX MAC <b>222</b> or <b>232</b> appends during transmit. The Ethernet CRC field <b>816</b> is not normally used by the TX MAC <b>218</b> or <b>234</b>, but was written there during receive by the RX MAC <b>220</b> or <b>228</b>. Each TX MAC controller <b>222</b> and <b>232</b> has a configuration setting which can instruct it to not generate CRC as it transmits; in that case the LENGTH field in the TX Command Word <b>802</b> includes the four bytes of Ethernet CRC, and the data in <b>816</b> is sent with the packet for use as the packet's CRC. This configuration which uses software-generated Ethernet CRC is provided primarily as a diagnostic tool for sending bad packets to other devices on the network.

0220Upon completion or abandonment of a transmit, the TX MAC will write back the TX Status Word <b>806</b> and the TX Timestamp <b>808</b> if it is so configured. The TX Status Word <b>806</b> contains the information and format shown in Table 2. The TX Timestamp <b>808</b> is written with the value of the Timestamp Register <b>214</b> at the time the write to TX Timestamp <b>808</b> is initiated.

0221The software data structure <b>820</b> which travels in the packet buffer <b>840</b> along with the packet is the same one <b>614</b> discussed in the description of an RX buffer <b>620</b> as shown in <figref idref="DRAWINGS">FIG. 7</figref>, and may be relocated by software convention as described in the discussion of <figref idref="DRAWINGS">FIG. 7</figref>.

0222The transmit status word <b>806</b> contains a flag indicating if the transmission was successful, and the reason for failure if the transmit was abandoned. This field is written only if MCSR[TX_STAT] is set, otherwise the fields <b>806</b> and <b>808</b> contain uninitialized data. <tables id="TABLE-US-00002" num="2"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="350PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 2</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Ethernet TX Status Word</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="28PT" align="center" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="266PT" align="left" /><tbody valign="top"><row><entry>Bits</entry><entry>Field</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>[31]</entry><entry>TX_OK</entry><entry>Packet was successfully transmitted.</entry></row><row><entry>[30]</entry><entry>LATE_COL</entry><entry>Transmit abandoned due to a late collision. (only if (MCSR[LATE_COL_RTRY] == 0))</entry></row><row><entry>[29]</entry><entry>XS_COL</entry><entry>Transmit abandoned due to excessive collisions (16 collisions)</entry></row><row><entry>[28]</entry><entry>XS_DEFER</entry><entry>Transmit abandoned due to excessive deferrals</entry></row><row><entry>[27]</entry><entry>UNDERFLOW</entry><entry>Transmit abandoned due to slow memory response times.</entry></row><row><entry>[26]</entry><entry>GIANT</entry><entry>Packet length was larger than legal</entry></row><row><entry>[25:22]</entry><entry>COL_CNT[3:0]</entry><entry>Number of collisions experienced (never shows more than 15; if XS_COL this value is ‘x’)</entry></row><row><entry>[21:11]</entry><entry>reserved</entry><entry>MAC writes 0x0 to this field.</entry></row><row><entry>[10:0] </entry><entry>TX_SIZE[10:0]</entry><entry>Number of bytes transmitted (includes the 4-byte Ethernet CRC)</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> There are 5 possible transmit packet sources sharing the TX MAC; these are <ul id="ul0006" list-style="none"><li id="ul0006-0001" num="0000"><ul id="ul0007" list-style="none"><li id="ul0007-0001" num="0223"> The RISC processor (Policy Processor) generating or forwarding a packet </li><li id="ul0007-0002" num="0224"> Crypto generating a modified packet </li><li id="ul0007-0003" num="0225"> The AP either creating, forwarding, or modifying a packet </li><li id="ul0007-0004" num="0226"> A device in a PCI expansion slot creating, forwarding, or modifying a packet </li><li id="ul0007-0005" num="0227"> A peer PE forwarding a packet to a different network segment (e.g. for routing or switching) </li></ul></li></ul>

0228Atomic enqueueing by multiple sources is supported via writes to RTU[MTPROD] associated with that MAC's Transmit Ring. The RTU can detect high-water-mark conditions and signal the situation to the PP and the AP. The MTCONS index pointer is incremented by the MAC whenever a buffer is retired; that is chased by another consume pointer incremented by reads of RTU[MTRECOV] which is used by the PP for recover of retired packet buffers to the buffer pool and (optionally) checking TX status.

00004. Reclassify Rings

0229The Classification Engine receives packets to classify from both the RX MAC (via the RX Ring), and from other sources (PP, AP, Crypto, and potentially other network cards on the PCIbus). A second input ring (Reclassify Ring) is provided for each CE for these other sources to schedule a packet for classification on that CE; each comprises a ring in memory with enqueue and dequeue operations supported through the RTU. The 32-bit entries in the ring are buffer pointers.

0230<figref idref="DRAWINGS">FIG. 10</figref> shows the reclassify ring structure.

0231The Reclassify Rings <b>410</b>, <b>412</b>, <b>414</b>, and <b>416</b> serve a very similar purpose to the RX Rings <b>402</b> and <b>404</b>, and have substantially the same structure. The substantive differences are that there is one less interim consumer-producer in the Reclassify Rings, and that packets get scheduled through the Reclassify Rings via a different path. Reclassify Rings <b>410</b>, <b>412</b>, <b>414</b>, and <b>416</b> are used to schedule packets for processing on CE <b>238</b>, <b>208</b>, <b>242</b>, and <b>212</b> respectively.

0232In the case of the RX Ring <b>402</b> or <b>404</b>, buffer pointers are enqueued by the Buffer Allocation process <b>102</b> running on the Policy Processor <b>244</b> using MPROD <b>518</b>, which allocates the referenced buffers as free and empty for the RX MAC <b>220</b> or <b>228</b>, respectively, to consume using MFILL <b>516</b> when receiving a packet and to produce a full, unclassified buffer to the CE <b>238</b> or <b>242</b>, respectively. Packets scheduled for classification via the Reclassify Rings <b>410</b>, <b>412</b>, <b>414</b>, and <b>416</b> come from a source other than the RX MAC's <b>220</b> or <b>228</b>, as illustrated in <figref idref="DRAWINGS">FIG. 2</figref>. Full, unclassified buffers get scheduled onto one of the Reclassify Rings when an agent enqueues the buffer pointer onto the ring by writing the buffer pointer to the RTU's <b>264</b> enqueue address, which causes the RTU <b>264</b> to write the buffer pointer to the location in memory <b>260</b> referenced by RPROD <b>916</b> and then to increment RPROD <b>916</b> modulo the ring size of 4096 bytes.

0233From that point onward the description is substantially the same as the description of the RX Ring <b>402</b> and <b>404</b>, except that RCCONS <b>914</b> is used in place of MCCONS <b>514</b>, RPCONS <b>912</b> is used in place of MPCONS <b>512</b>, the invalid region <b>902</b> and <b>908</b> substitutes for <b>500</b> and <b>508</b>, Full and Classified <b>904</b> substitutes for <b>502</b>, and Full Unclassified <b>906</b> replaces <b>504</b>. Since this flow has no allocation of empty buffers there is no equivalent to MFILL <b>516</b> nor to Valid Empty <b>506</b>.

0234Note that the “Outbound” classifiers <b>208</b> and <b>212</b> each have only a Reclassify Ring <b>412</b> and <b>416</b>, respectively, but no RX Ring since they are not associated with an RX MAC.

00005. Crypto Command Queue and General Purpose Communications Rings

0235In order to schedule buffers for processing by the external (and optional) encryption engine another memory-based ring containing buffer pointers is implemented, with enqueue and dequeue operations supported through the RTU for the Crypto unit to get the next buffer to process, plus a status bit indicating to Crypto that there is at least one packet buffer pointer in the ring to process. The information about what operations to perform, keys, etc. are embedded in a Crypto Command Descriptor in the software area of the buffer.

0236<figref idref="DRAWINGS">FIG. 11</figref> shows the Crypto Ring and COM[<b>4</b>:<b>0</b>] Rings Structures.

0237The Crypto Ring <b>420</b>, COM<b>0</b> Ring <b>422</b>, COM<b>1</b> Ring <b>424</b>, COM<b>2</b> Ring <b>426</b>, COM<b>3</b> Ring <b>428</b>, and COM<b>4</b> Ring <b>430</b> are identical in structure. Any agent can enqueue a buffer pointer or, in the case of the COM Rings, any 32-bit datum, by writing to the RTU's <b>264</b> enqueue address associated with the particular ring. This causes the RTU to store the buffer pointer or 32-bit datum to the location in memory <b>260</b> referenced by the specified PRODUCE Pointer <b>1010</b> and then to increment PRODUCE <b>1010</b> modulo the ring size of 4096 bytes. There is a producer-consumer relationship between a particular ring's PRODUCE pointer <b>1010</b> and that ring's CONSUME pointer <b>1008</b>. When the RTU detects a difference between the values of PRODUCE <b>1010</b> and CONSUME <b>1008</b> it signals to the consuming unit that there is at least one entry to be consumed.

0238The consumer dequeues a 32-bit entry from one of these rings by reading from the RTU's dequeue address associated with that particular ring; this causes the RTU to return the data at the address in memory <b>260</b> referenced by that CONSUME pointer <b>1008</b> and then to increment CONSUME <b>1008</b> modulo the ring size of 4096 bytes. As is illustrated here, the degenerate case of the multiple-producer, multiple-consumer ring structure described in <figref idref="DRAWINGS">FIGS. 6, 8</figref>, and <b>10</b> is a single-producer, single-consumer FIFO with fifo-not-empty status presented to the consumer. The COM rings <b>422</b>, <b>424</b>, <b>426</b>, and <b>428</b> all report ring-not-empty status and (programmably per ring) either near-full or near-empty threshold status to the Policy Processor <b>244</b> through status registers in the processor interface <b>206</b>. These rings can be assigned for any purpose; anticipated uses include a message-in ring for the Policy Processor <b>244</b>, a ring for allocating buffers for use by remote agents, and a ring for allocating DMA descriptors for use by remote agents scheduling this Policy Engine's DMA Unit <b>210</b>.

0239The Crypto Ring <b>420</b> reports ring-not-empty status to the Crypto Processor <b>246</b> through a status register in Crypto Interface <b>202</b>. COM<b>4</b><b>430</b> also reports ring-not-empty status through a similar location, so that COM<b>4</b><b>430</b> can optionally be used to support scheduling packets for processing by a second Crypto Processor <b>246</b>. The Crypto Processor Interface <b>202</b> has additional support for a second Crypto Processor <b>246</b>, which might be added to provide either more bandwidth for encryption processing or additional functionality such as compression. Packets would be scheduled for processing on this second processor <b>246</b> by enqueueing their buffer pointers onto COM<b>4</b><b>430</b>. Alternatively, both the Crypto Ring <b>420</b> and COM<b>4</b><b>430</b> can be used to schedule buffers for processing on the one Crypto processor <b>246</b>.

0240The general purpose communication rings COM[<b>4</b>:<b>0</b>] <b>422</b>, <b>424</b>, <b>426</b>, <b>428</b>, and <b>430</b> are identical in structure to the Crypto Ring <b>420</b>.

00006. DMA Command Queue and Descriptors

0241The DMA engine also uses a ring unit with an Enqueue register for any agent to schedule DMA transfers (DMA_PROD), a Consume register for the DMA engine to get entries from the ring (DMA_CONS), and a Dequeue register for recovering retired descriptors (and the associated buffers) from the ring (DMA_RECOV).

0242The DMA engine is used to move data between the memory and the PCIbus; the source/target on PCI can be host (AP) memory or another PCI device. DMA operations are scheduled by creating a 16-byte descriptor in memory and then enqueueing the address of that descriptor in the DMA engine's command ring by writing it to DMA_PROD. The PP, the host, a PCI bus peer, and Crypto can atomically schedule use of this engine.

0243DMA is notified by the RTU when the Produce pointer is not equal to the Consume pointer and processes the next descriptor. When that descriptor is retired, DMA increments the Consume pointer; a delta between that and the Recover pointer causes the RTU to signal to the PP that there are DMA descriptors (and the associated buffer pointers) to recover. <tables id="TABLE-US-00003" num="3"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 3</entry></row><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>DMA Descriptor Format</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>PCI_Address [31:00]</entry></row><row><entry>Flags [31:0]</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="center" /><colspec colname="2" colwidth="105PT" align="center" /><colspec colname="3" colwidth="70PT" align="center" /><tbody valign="top"><row><entry>S1[31:27]</entry><entry>Buf_Address [26:11]</entry><entry>S2[10:0](pointer tag</entry></row><row><entry /><entry /><entry>field)</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="1" colwidth="42PT" align="center" /><colspec colname="2" colwidth="77PT" align="center" /><colspec colname="3" colwidth="21PT" align="center" /><colspec colname="4" colwidth="77PT" align="center" /><tbody valign="top"><row><entry>S3[15:11]</entry><entry>Buf_Start_Index [10:2]</entry><entry>0b00</entry><entry>Word_Count[15:0]</entry></row><row><entry namest="1" nameend="4" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> The areas labeled “S<b>2</b>” and “S<b>3</b>” are available for software use. “S<b>1</b>” is reserved for future expansion of PE memory size.

0244Upon completion of a transfer, the DMA engine can optionally set a completion status bit in either the Host Interrupt Register or Processor Interrupt Status Register in case the initiating agent wants completion status of a transfer or group of transfers. 8 bits are provided in each so that transfers can be tagged as desired. This allows both AP and PP software to have up to 8 DMA completion events scheduled at one time for tracking when particular groups of transfers have completed, or for the PP to signal to the AP that information has been pushed up to a mailbox or communication ring in AP memory, or for similar signals from the AP to the PP.

0245The Packet Buffer Address field contains the packet buffer pointer in the same format that is used by all other agents in the Policy Engine; this means that bits [<b>10</b>:<b>0</b>] are ignored by hardware and might contain tag information. The actual memory word address is the concatenation of the 2 KB-aligned Packet_Buffer_Address[<b>31</b>:<b>11</b> ] with Start_Index[<b>10</b>:<b>2</b>], with 00 in the lower two bits. Note that the Word_Count allows for a maximum DMA transfer of (64K-1 Words, or 256K-4 Bytes), in case there are transfers larger than normal packet buffer movement (e.g. moving down PP code or CE microcode).

0246The Flags word contains the following fields: <tables id="TABLE-US-00004" num="4"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="350PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 3a</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>DMA Descriptor “Flags” Word</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="28PT" align="center" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="266PT" align="left" /><tbody valign="top"><row><entry>Bits</entry><entry>Field</entry><entry>Descriptions</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>[31:21]</entry><entry>SOFT[10:0]</entry><entry>Available for software use.</entry></row><row><entry>[20]</entry><entry>TO_MEM</entry><entry>Direction: 1 == To Memory (From PCI), 0 == From Memory (To PCI)</entry></row><row><entry>[19:16]</entry><entry>PCI_CMD[3:0]</entry><entry>This is the PCI command code which is used on the PCI bus for these transactions; the most</entry></row><row><entry /><entry /><entry>common codes will be 0x7 (Memory Write) and 0x6 (Memory Read) with some probability</entry></row><row><entry /><entry /><entry>of also using 0xC (Memory Read Multiple) and 0xE (Memory Read Line) if the attached</entry></row><row><entry /><entry /><entry>host uses them for prefetch directives.</entry></row><row><entry>[15:08]</entry><entry>SET_HISR[7:0]</entry><entry>Any bit that is set will set the corresponding status bit in the HISR upon retirement of this</entry></row><row><entry /><entry /><entry>descriptor. If no bit is set, no status is sent to HISR.</entry></row><row><entry>[07:00]</entry><entry>SET_PISR[7:0]</entry><entry>Any bit that is set will set the corresponding status bit in the PISR upon retirement of this</entry></row><row><entry /><entry /><entry>descriptor. If no bit is set, no status is sent to PISR.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Since DMA descriptors are read from memory by the DMA engine, software must ensure either that the descriptors were non-cacheable by the processor, or that they are flushed from the PP cache prior to writing the descriptor's address to the DMA ring. For descriptors that are generated by the AP or by a PCI peer see “Endianness” in section 8 for details about descriptor endianness.

0247<figref idref="DRAWINGS">FIG. 12</figref> shows the DMA Ring Structure.

0248The DMA Ring <b>418</b> is substantially the same as the TX Rings <b>406</b> and <b>408</b> as described in <figref idref="DRAWINGS">FIG. 8</figref>. There is a single enqueue index DMA_PROD <b>1116</b> used to schedule pointers on the ring <b>418</b> by any agent, and interim consumer-producer index DMA_CONS <b>1114</b> used by the DMA Unit <b>120</b> to consume newly scheduled descriptor pointers and to produce retired descriptor pointers, and a dequeue index DMA_RECOV <b>1112</b> used by the Policy Processor <b>244</b> to recover retired descriptors as well as the buffers associated with them using the buffer pointer embedded in the DMA descriptor being recovered. Differences between DMA_PROD <b>1116</b> and DMA_CONS <b>1114</b> are detected by the RTU <b>264</b> and reported to the DMA Unit <b>120</b>. Differences between DMA_CONS <b>1114</b> and DMA_RECOV <b>1112</b> are reported by the RTU <b>264</b> to the Policy Processor <b>244</b> through a status bit in the Processor Interface <b>206</b>. Region <b>1106</b> contains one or more descriptor pointers which point to DMA descriptors as described in Table 3. Region <b>1104</b> contains the descriptor pointers of descriptors which have been retired by DMA <b>120</b> but have not yet been recovered by Buffer Recovery <b>118</b>. Invalid <b>1102</b> and <b>1108</b> are the unused space into which more pointers can be scheduled.

00007. Buffer Allocation/Flow

0249At initialization time the software allocates a pool of size-aligned 2 KB buffers in memory. Enough of these are allocated to each of the RX rings (that is, the buffer pointers are enqueued on those rings by writing them to the associated RTU[MPROD]) to provide the desired elasticity for the RX MAC, and the rest are placed on a freelist (e.g. on a software-managed linked list.) Each time the PP dequeues a buffer from the RX ring it can allocate a new empty buffer from the freelist, thus keeping the pool size constant. Buffers that go through Crypto may be enqueued by any agent and are dequeued by the Crypto Processor which will then enqueue them on the specified destination ring after processing. Buffers that are scheduled for DMA are recovered at the same time the associated DMA descriptor is recovered from the ring. Buffers may be temporarily absorbed by an application if it is queueing packets for delay. A reference count can be maintained in buffers which go to multiple readers so that they retire only when all readers have retired them.

0250The goal is that the PP can handle buffer allocation and recovery through the read of status bits in the PISR, reads of RTU recover or dequeue addresses to recover retired buffers when the RTU indicates through the PISR that the particular rings have buffers to recover, and writes to ring RTU enqueue addresses to allocate new buffers. It is a primary goal that copying of buffers is avoided except when absolutely necessary.

0251Rings report threshold warnings to the PP/AP through the CRISIS register when there is danger of under/overflowing (within ¼ ring-size of a problem situation) and also report full/empty status of rings through bits in the CRISIS Register as appropriate.

00007.1 The Life of an RX Packet Buffer

0252Ideally, a packet arrives into a buffer, gets processed, and then gets transmitted out the other port or gets dropped. Processing may include a decision by the application to enqueue the buffer for temporary delay (and possible later dropping), to feed a packet through the local optional Crypto for encryption work, or to pass a packet to the AP or external coprocessor (see <figref idref="DRAWINGS">FIG. 4</figref>). The key concept is to think of a packet as being “owned” by some agent, and that agent taking responsibility for the final disposition of the packet.

00007.2 Flow of a Buffer which Remains Local

0253At the beginning of time the system allocates a number of buffers to an RX MAC by writing their pointers into that RX Ring's RTU[MPROD] enqueue register, which presents these buffers to that MAC as empty/allocated. These buffers are now owned by that RX MAC, and cannot be touched by others until the MAC has so indicated. When the RX MAC has filled a buffer with a newly received packet it passes ownership to the associated Classification Engine by moving the MFILL pointer to the next entry (buffer pointer) in the ring. The CE will detect this, then process that packet; when it is done it passes ownership to the PP by incrementing the MCCONS index modulo ring size, and then the application(s) running on the PP will determine what action(s) to take. Ownership of a buffer is always explicitly relinquished by the current owner.

0254The PP can perform any conventional actions with a buffer. Examples of actions for a buffer which remains entirely local are DROP, FORWARD, MODIFY or temporarily ENQUEUE then later FORWARD.

0255DROP: The code running on the PP determines that there are no further uses for the contents of this buffer, so it retires/recovers the buffer. Typically this occurs when the Action portion of the application(s) running on the PP decide that a packet does not meet the criteria for passing it forward.

0256FORWARD: The PP enqueues the pointer onto the appropriate TX ring; TX is fire-and-forget (with optional completion status from the MAC), with the hardware responsible for either completing or abandoning the transmit (that is, the TX MAC owns that buffer). Some time later in the buffer reclaimation code, the PP will recognize that the TX MAC has retired this packet (is done with it) since the RTU indicates that there is a delta between MTCONS and MTRECOV, thus ownership of that buffer has transferred back to the PP. The PP then checks TX completion status (if the application(s) care) and recovers the buffer or reschedules the transmit as appropriate.

0257MODIFY: The application may choose to send the packet through Crypto for processing, may encapsulate/decapsulate the packet, could do address translation, or can do any other modification of the packet that the application directs.

0258ENQUEUE: The application running on the PP determines that it wants to hold on to the packet for some period of time, after which it will either forward or drop it. Ownership of that buffer stays with the application until it relinquishes it by enqueuing the buffer's pointer on the appropriate TX or Reclassify ring, or by deciding to DROP it, in which case the same path as DROP (above) is followed. In the Enqueue case the average residency of a packet in a memory buffer is much longer than in the simple DROP or FORWARD cases, so if applications are enqueueing packets then care must be taken to allocate a large enough buffer pool.

00007.3 Buffer Handling for Packets Sent to the PCI Bus

0259The applications(s) on the PP may decide that a packet should be forwarded to the AP either for further processing or because the packet is actually targeted at the AP as the final destination. In either case it is necessary to migrate the packet to buffers in the AP's memory (e.g. into mbufs in the stack running there or into application-specific storage.) The buffer itself is not migrated, some or all of its contents are copied to a different buffer in host memory; this is done using the DMA engine.

0260Alternatively the application could choose to store the packet locally (that is, maintain ownership of the buffer) and simply pass a pointer and other information up to the AP. In this case the PP cannot reclaim the buffer until the AP has informed the PP that ownership of the buffer has been released back to the PP.

0261Other reasons for sending packets up to the PCI bus include a push-model peer-to-peer copy to a different Policy Engine or external coprocessor, and logging of selected packets at the AP. The latter is interesting because it may involve a fork where a packet takes two paths; one to a MAC transmit queue, and a second to the PCI bus; reclaimation of that buffer would require a convergence of completion, that is, a “join” function before the buffer can be reclaimed (if copying is to be avoided.) Software can maintain a reference count in the buffer for this purpose.

0262Forwarding a packet to the AP can be in the guise of NIC-like behavior or for application-specific communication. In either case the packet's buffer pointer is written to a DMA descriptor as the MEM_ADDR, and after the rest of the DMA descriptor is created the pointer to that descriptor is enqueued on the DMA engine's command queue. As with all other queues described so far, the PP has a trailing recover pointer DMA_RECOV and receives status in the PISR from the RTU when there are retired descriptors to recover.

0263The “NIC” interface as seen in host memory can be arbitrarily complex, but can be as simple as a memory image consisting of a buffer pool and pointer ring with a produce and a consume pointer, all in host memory; the “RX NIC interface” can mean reading a pointer to a free buffer, DMA'ing the entire packet buffer to that location, following that with a DMA of a new value to the “Produce” pointer associated with it, and an interrupt to the host (using one of the bits HISR[DMA_DONE[<b>7</b>:<b>0</b>]]) upon completion of that DMA. More efficient host structures can be implemented without much more complexity. Communication down from the AP can also use the DMA engine and can involve a similar software ring structure in either host or PE memory; messages and/or ring indexes are written by the AP into one of the 16 Mailbox locations provided, which write data to PE memory and set a per-mailbox status bit which signals mailbox status through the PISR to the PP.

0264A peer-to-peer routing operation with a push model might require a buffer pool in PE memory to be allocated for each peer that will be doing this; then sending a packet to another Policy Engine for transmit is as simple as scheduling a DMA to copy the data from the local buffer to a buffer in this PE's buffer pool on the remote PE, followed by a DMA of the pointer to that buffer (in the “local” pointer format) into RTU[MTPROD] to schedule it for transmit. Later the remote PP will reclaim the buffer some time after the transmit is done, and will send back the pointer (or a “credit” message) by DMA'ing it to this PP's “freelist” ring for that particular peer.

0265Another more general method of allocating buffers and DMA descriptors to remote masters is to assign one of the general-purpose COM rings to contain a freelist of buffer pointers, and a second to contain a freelist of DMA descriptor pointers; any remote master desiring to push data could then simply read the two rings to obtain both a target buffer and a DMA descriptor for scheduling a fill of that buffer.

0266A “pull” model of communication would have the remote master send only a (PCI) pointer or a descriptor down through either a mailbox or a COM ring allocated for this function, and require the PP to select a buffer from its own pool of buffers allocated for this purpose, using DMA to copy the buffer from the remote memory into local memory, then taking whatever actions are specified for that packet. Ownership of the actual buffer in this case always belongs to the PP.

00007.4 Placement of the Software Structure in the Buffer

0267While the hardware defines the location of the receive and transmit control and status words and the location of the packet in the packet buffer, it is only by convention that the software structure resides forward from the 2 KB-aligned buffer pointer. A different convention can be used where the software structure of N bytes actually begins N bytes before the 2 KB-aligned buffer pointer; in this case the buffers managed and allocated by software are actually (2 KB-N)-byte aligned, and the RX status word is placed N bytes into the buffer, which lands it precisely on the 2 KB-aligned word where it already goes; hardware doesn't know the difference, but software can take advantage of such a structure to allow for arbitrary-sized packets from any media, which start forward from the RX status word just like the ethernet packet but may occupy contiguous memory far bigger than an ethernet packet would. By placing the software structure before the RX status word, the structure does not have to be moved to accommodate larger packets.

00008. Endianness

00008.1 Overview

0268Internal to the Policy Engine ASIC, all agents are big-endian. This includes the MACs, memory, the CEs, the Policy Processor, the Crypto port, and the DMA engine descriptor format. This choice is most convenient for dealing with protocol headers, which are typically big-endian native. The CE itself has no endianness since it works only in units of 32 bits throughout; however, it does deal with multibyte data in the way those words are formatted in memory, thus it sees the big-endian layout of the packet buffer contents and also writes its status words and hash pointers in big-endian format, which is what the PP expects to see.

0269All PIO accesses from PCI to registers (PCI address range recognized by BAR<b>1</b>) are required to be 32-bit access only. The registers connect to the PCI bus so that bit<<b>0</b>> of the host CPU register is bit<<b>0</b>> of the PE register, and bit<<b>31</b>> corresponds to bit<<b>31</b>>. This implies that bit<<b>0</b>> of a register access travels on bit<<b>0</b>> of the PCIbus. Registers are placed on doubleword boundaries but are accessed as words, and the data travels on bits<<b>31</b>:<b>0</b>> of the PCI bus even if the bus is connecting 64-bit agents. As word-only entities the registers have no byte order issue. The same is true of PCI Configuration Register accesses.

0270All transfers between memory and the PCIbus move data by byte lane; this means that byte<<b>0</b>> in memory travels on byte<<b>0</b>> on the PCIbus, byte<<b>1</b>> on byte<<b>1</b>>, etc. This is endian-neutral for byte streams. This applies to all DMA activity, to PIO accesses from the PCIbus to/from memory, and also reads and writes from PCI through the Ring Translation Unit; the rings are simply memory with fancy address translation. <tables id="TABLE-US-00005" num="5"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="322PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 4</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Byte Lane Steering, PCI64-to-Memory</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="8"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="42PT" align="left" /><colspec colname="4" colwidth="42PT" align="left" /><colspec colname="5" colwidth="42PT" align="left" /><colspec colname="6" colwidth="42PT" align="left" /><colspec colname="7" colwidth="35PT" align="left" /><colspec colname="8" colwidth="35PT" align="left" /><tbody valign="top"><row><entry>(byte 7)</entry><entry>(byte 6)</entry><entry>(byte 5)</entry><entry>(byte 4)</entry><entry>(byte 3)</entry><entry>(byte 2)</entry><entry>(byte 1)</entry><entry>(byte 0)</entry></row><row><entry namest="1" nameend="8" align="center" rowsep="1" /></row><row><entry>PCI[63:56]</entry><entry>PCI[55:48]</entry><entry>PCI[47:40]</entry><entry>PCI[39:32]</entry><entry>PCI[31:24]</entry><entry>PCI[23:16]</entry><entry>PCI[15:8]</entry><entry>PCI[7:0]</entry></row><row><entry>M[7:0]</entry><entry>M[15:8]</entry><entry>M[23:16]</entry><entry>M[31:24]</entry><entry>M[39:32]</entry><entry>M[47:40]</entry><entry>M[55:48]</entry><entry>M[63:56]</entry></row><row><entry namest="1" nameend="8" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0271<tables id="TABLE-US-00006" num="6"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 5</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Byte Lane Steering, PCI32-to-Mem</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="5"><colspec colname="OFFSET" colwidth="63PT" align="left" /><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="35PT" align="left" /><colspec colname="4" colwidth="35PT" align="left" /><tbody valign="top"><row><entry /><entry>(byte 3)</entry><entry>(byte 2)</entry><entry>(byte 1)</entry><entry>(byte 0)</entry></row><row><entry /><entry>PCI[31:24]</entry><entry>PCI[23:16]</entry><entry>PCI[15:8]</entry><entry>PCI[7:0]</entry></row><row><entry /><entry namest="OFFSET" nameend="4" align="center" rowsep="1" /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="5"><colspec colname="1" colwidth="63PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="42PT" align="left" /><colspec colname="4" colwidth="35PT" align="left" /><colspec colname="5" colwidth="35PT" align="left" /><tbody valign="top"><row><entry>First data phase</entry><entry>M[39:32]</entry><entry>M[47:40]</entry><entry>M[55:48]</entry><entry>M[63:56]</entry></row><row><entry>(or word at 0x0)</entry></row><row><entry>Second data phase</entry><entry>M[7:0]</entry><entry>M[15:8]</entry><entry>M[23:16]</entry><entry>M[31:24]</entry></row><row><entry>(or word at 0x4)</entry></row><row><entry namest="1" nameend="5" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> This byte-lane steering has some interesting implications that need to be understood so that it is clear when software will have to twist data. Four interesting cases will be examined: (a) the host writing a DMA descriptor into memory for the DMA engine to consume, (b) the host writing a message to the PP in memory, (c) the PP writing a message in memory that is DMA'd to host memory, and (d) issues surrounding loading of CMEM in the four CE's. <br /> 8.2 Host Writing a DMA Descriptor in Memory

0272The DMA descriptor is not a byte stream, therefore the endian-neutral PIO from the host to memory is not sufficient. The DMA engine sees the descriptor as a 16-byte, 16-byte-aligned big-endian data structure as shown in Table 3 on page 22. For this example the fields are simplified into a 32-bit PCI address PA, a 32-bit Buffer Address BA, a 16-bit offset OF, a 16-bit Word Count WC, and a 32-bit Flag word F.

0273Here is the big-endian view of that descriptor as it appears in memory and as the DMA engine interprets it: <tables id="TABLE-US-00007" num="7"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 6</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>DMA Descriptor Byte Order, big endian memory</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="8"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="35PT" align="left" /><colspec colname="3" colwidth="35PT" align="left" /><colspec colname="4" colwidth="35PT" align="left" /><colspec colname="5" colwidth="35PT" align="left" /><colspec colname="6" colwidth="35PT" align="left" /><colspec colname="7" colwidth="42PT" align="left" /><colspec colname="8" colwidth="35PT" align="left" /><tbody valign="top"><row><entry>(byte 0)</entry><entry>(byte 1)</entry><entry>(byte 2)</entry><entry>(byte 3)</entry><entry>(byte 4)</entry><entry>(byte 5)</entry><entry>(byte 6)</entry><entry>(byte 7)</entry></row><row><entry namest="1" nameend="8" align="center" rowsep="1" /></row><row><entry>PA[31:24]</entry><entry>PA[23:16]</entry><entry>PA[15:08]</entry><entry>PA[07:00]</entry><entry>F[31:24]</entry><entry>F[23:16]</entry><entry>F[15:08]</entry><entry>F[07:00]</entry></row><row><entry>BA[31:24]</entry><entry>BA[23:16]</entry><entry>BA[15:8]</entry><entry>BA[7:0]</entry><entry>OF[15:08]</entry><entry>OF[7:0]</entry><entry>WC[15:08]</entry><entry>WC[7:0]</entry></row><row><entry namest="1" nameend="8" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0274Assuming that the host (AP) will write to this data structure in PE memory using word PIO's over PCI (for the example shown), the host must pre-scramble those words so that the data will arrive in the correct byte lanes: <tables id="TABLE-US-00008" num="8"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 7</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>DMA Descriptor Byte Order, little endian register</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="5"><colspec colname="OFFSET" colwidth="63PT" align="left" /><colspec colname="1" colwidth="42PT" align="center" /><colspec colname="2" colwidth="42PT" align="center" /><colspec colname="3" colwidth="35PT" align="center" /><colspec colname="4" colwidth="35PT" align="center" /><tbody valign="top"><row><entry /><entry>(byte 3)</entry><entry>(byte 2)</entry><entry>(byte 1)</entry><entry>(byte 0)</entry></row><row><entry /><entry namest="OFFSET" nameend="4" align="center" rowsep="1" /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="5"><colspec colname="1" colwidth="63PT" align="left" /><colspec colname="2" colwidth="42PT" align="center" /><colspec colname="3" colwidth="42PT" align="center" /><colspec colname="4" colwidth="35PT" align="center" /><colspec colname="5" colwidth="35PT" align="center" /><tbody valign="top"><row><entry>First data phase</entry><entry>PA[07:00]</entry><entry>PA[15:08]</entry><entry>PA[23:16]</entry><entry>PA[31:24]</entry></row><row><entry>(word at 0x0)</entry></row><row><entry>Second data phase</entry><entry>F[07:00]</entry><entry>F[15:08]</entry><entry>F[23:16]</entry><entry>F[31:24]</entry></row><row><entry>(word at 0x4)</entry></row><row><entry>Third data phase</entry><entry>BA[7:0]</entry><entry>BA[15:8]</entry><entry>BA[23:16]</entry><entry>BA[31:24]</entry></row><row><entry>(word at 0x8)</entry></row><row><entry>Fourth data phase</entry><entry>WC[07:00]</entry><entry>WC[15:08]</entry><entry>OF[7:0]</entry><entry>OF[15:8]</entry></row><row><entry>(word at 0xC)</entry></row><row><entry namest="1" nameend="5" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0275and then when the host writes the address of the descriptor into the DMA ring (which is “byte-lane” memory), that descriptor pointer is written as a word with the following content: <tables id="TABLE-US-00009" num="9"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="259PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 8</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Descriptor Pointer Byte Order, little endian register</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="1" colwidth="63PT" align="center" /><colspec colname="2" colwidth="63PT" align="center" /><colspec colname="3" colwidth="56PT" align="center" /><colspec colname="4" colwidth="77PT" align="center" /><tbody valign="top"><row><entry>(byte 3)</entry><entry>(byte2)</entry><entry>(byte 1)</entry><entry>(byte 0)</entry></row><row><entry namest="1" nameend="4" align="center" rowsep="1" /></row><row><entry>DESC_A[07:00]</entry><entry>DESC_A[15:08]</entry><entry>DESC_A[23:16]</entry><entry>DESC_A[31:24]</entry></row><row><entry namest="1" nameend="4" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Note that reads and writes through the ring unit are accesses to memory, not to registers, which is why the address_shuffle (where “the address” is data, as above) is required when the host is writing to the ring-enqueue address. <br /> 8.3 Host Writing a Message to the PP in Memory

0276The PP views the memory as big-endian in the same manner as the DMA engine, so the example in 7.8.2 describes this path as well. Messages are either a byte stream, or require the host to manually byte swap larger data. The contents of a mailbox and the contents of any ring entry or other item in memory will follow the same format as shown in Table 8.

00008.4 PP Writing a Message in Memory that is DMA'ed to the Host

0277If messages sent up to the host are simply a byte stream then there is no issue, since byte streams travel in an endian-neutral way. If on the other hand the message includes data that are larger than a byte (e.g. a buffer pointer), byte swapping occurs and both ends of the communication must be aware of this.

0278For example, if the PP wants to send a 32-bit address to the host, it must byte swap within that word before sending it. That is, if the PP wants to send the 32-bit word OXDEADBEEF up to the host as a message, then the PP must put it into memory as OXEFBEADDE (see Table 5.)

00008.5 Classification Engine CMEM Fills

0279Writing instructions into CMEM in the Classification Engines takes one of two paths; the data is either DMA'ed or PIO'ed into PE memory from the host and then copied from memory to CMEM by the CE (using the CE's FILL_DMA unit), or the host can PIO data directly into CMEM over the Register interface (CMEM_DIAG access).

0280The CMEM_DIAG path is word-oriented and no twisting occurs, since it is all via the register path. The 32-bit data and addresses seen in the host processor is the same 32-bit data that is seen in the AP's registers. Diagnostic PIO's of data are sent to CMEM in the order [Least Significant Word, then Most Significant Word] to construct the 64-bit instruction.

0281The FILL_DMA path takes 64-bit words from PE memory and writes them into the 64-bit CMEM. The compiler and host software always handle 64-bit instructions in their native (that is, readable) form. CMEM instructions are laid out as native 64-bit units in host memory; the host/compiler does not need to twist them to help the (other-endian) recipient. When the data arrives in PE memory, each 64-bit instruction will arrive byte-swapped due to byte-lane steering; that is, the instruction <br />0XAABBCCDD_EEFF0123<br /> in host memory will land in PE memory as <br />0X2301FFEE_DDCCBBAA<br /> and the CE CMEM Fill data path is wired as shown in Table 4, so that the bytes land in the correct place. Thus the MSB from PE memory will go to the LSB in CMEM, and vice versa. This works whether the data arrived in PE memory via a PIO from the AP or via a DMA from host memory prior to the FILL_DMA transfer into CMEM.

0282The upshot of all of this is that the CMEM_FILL DMA unit views PE memory as little-endian; and it doesn't matter to anyone using normal paths that CMEM microcode images are byte-swapped while they reside in the staging area in PE memory. This is all hidden from software.

IV. Classification Engine

0283The Classification Engine (CE) is a microprogrammed processor designed to accelerate predicate analysis in network infrastructure applications. The primary functions commonly used in predicate analysis include parsing layers of successively encapsulated headers, table lookups, and checksum verification.

0284Header parsing consists of extracting arbitrary single- or multiple-bit fields from those headers, comparing those fields to one or more constants, then taking the results of these comparisons and doing boolean reductions on multiple extraction results to reduce them finally to a single “matches/doesn't-match” status for each complex predicate statement; this single boolean value can then be used to quickly dispatch the appropriate actions at the PP. The size of each header is also determined so that the next level of protocol can be found and parsed in sequence. Applications can also choose to examine packet contents in addition to the headers if desired; the CE does not treat the header portion of a packet any differently from the payload portion.

0285Table lookups can consist of comparing an extracted value against a table of constants, or can involve generating a hash key from extracted values and then doing a lookup in a hash table (content-addressable table) to identify a record associated with packets matching that key; the record can contain arbitrary application-specific information such as permissions, counters, encryption context, etc.

0286Checksum verification involves arithmetic functions across protocol headers and/or packet payloads to determine if the packet contents are valid and thus comprise a valid packet. A special adder parallel to the mask-rotate unit called split-add adds the upper and lower half of a 32-bit operand together and produces a 17-bit result for use as an operand by the ALU; this is used in TCP, UDP, and IP checksum computation.

0287Since one purpose of the CE is to help the PP to avoid needing to touch packet contents and thus fault portions of the packet into the PP's data cache, the CE can also be programmed to extract arbitrary data fields and optionally do computations on them, then pass the results to the applications running on the PP via the packet buffer's software data structure.

0288A software structure is carried in the packet buffer along with the packet and the associated MAC status. This structure is written with predicate analysis results, hash table pointers to records found, hash insertion pointers in the case of a failed search, checksum results, a pointer to the base of each protocol found, extracted and computed fields, etc. for use by the application(s) running on the PP.

0289In order to accelerate these functions, the Classification Engine loads some or all of the packet from the PE's SDRAM-based memory (PE Memory) into a packet memory (PMEM) which it can then access randomly or sequentially to extract fields from the packet. A mask-and-rotate unit allows arbitrary bit fields to be extracted from words of the packet which can then be used as operands in computation or as comparison values for bulk table comparisons. Table comparisons or individual arithmetic and logic operations can set one or more bits in the result vector which is a large, 1-bit wide register file. These RESVEC bits can then be accessed randomly and arbitrary boolean operations can be done on pairs of bits to produce more RESVEC bits, at a rate of up to two boolean bit operations per cycle, eventually reducing sets of bits to single-bit predicate results. Gang operations (GANGOPs) help optimize boolean reduction by doing a logical operation (OR, AND, NOR, or NAND) on any number of selected bits within a 32-bit group of RESVEC bits in a single clock, producing a single RESVEC bit as a result. After boolean reduction is complete, some or all of the result vector can then be spilled to the software structure in the packet buffer in PE Memory for use by the Policy Processor.

0290A 32-bit Arithmetic and Logic Unit (ALU) and a set of general-purpose 32-bit registers (GPREG) allow for general computation as well.

0291Program flow control in the branch unit allows the microcode to decide if the next instruction in the microcode control store (CMEM) comes from a sequential location, from a relative-branch value which can be an immediate value in the microword or the contents of a GPREG, or (in the case of a RETURN) from the top of the hardware microstack; microstack values are enqueued when a CALL style of branch is executed, and the microstack is accessed in LIFO (last-in, first-out) fashion to support nested subroutines in the microcode. Branch, Call, and Return operations are all conditional based on any of the rich set of condition codes provided. When the microcode bit “BRANCH_EN” is set then a Branch, Call, or Return is executed if the selected condition code is true; calls and returns are done if the associated bit CALL or RET is set in the control word when BRANCH_EN is set. Due to pipelining of the microsequencer all program-flow changes have a 1-cycle delay before taking effect, so the instruction following any of program flow control instructions (the “branch delay slot”) is always executed regardless of the success or failure of the conditional flow control instruction; as a result of this the address stored in the microstack upon a successful CALL is the address of the first instruction following the delay slot.

0292The CE also contains several special purpose registers and also supports execution of many special operations. Special-purpose registers include the interface to PE memory, the condition code register, a memory base pointer register used for base-index access to packet buffers in PE memory, a chip-wide timestamp timer, and instrumentation and diagnostic registers including a counter which monitors execution time and a counter which tracks stall cycles due to various memory interface delays.

0293The memory interface appears to the microcode as 3 FIFO's; DFIFO_W receives one or more words of data to be packed into a memory burst access for stores, DFIFO_R unpacks requested bursts of data that have been read from memory, and MEM_ADDR receives PE memory addresses along with size and direction information. Reads (or “loads”) are non-blocking; microcode schedules a load and then can take the data from DFIFO_R at any time later; if the data has not yet arrived then the pipeline will stall until it does. The pipeline will also stall if there is an attempt to write data to DFIFO_W and there is no room or if there is an attempt to schedule another address in MEM_ADDR and there is no room. Both of these conditions are self-clearing as the fifos drain to the chip's memory controller. Extensive error-checking logic uses counters to track the state of various parts of the memory interface and will not allow microcode to oversubscribe DFIFO_R nor to issue a write (“store”) to memory unless precisely the right number of words of data have already been scheduled in DFIFO_W. Memory accesses sizes are 1, 2, 4, or 8 32-bit words.

0294Using the memory interface for a store consists of writing the desired number of words of data to DFIFO_W, then committing the store by scheduling the address into MEM_ADDR along with the appropriate size code and the direction flag for a store. Using it for a load consists of scheduling the address, size, and direction flag for a load into MEM_ADDR, then consuming precisely that many words in order from DFIFO_R at some later time. DFIFO_R holds up to 4 maximum-sized bursts or up to 32 words of data scheduled as smaller reads, so properly written microcode can often hide the latency of reading PE Memory by scheduling several loads before consuming the result of the first. Bulk data movement such as filling PMEM with a packet can keep several reads outstanding in a pipelined fashion to move data at the maximum memory bandwidth available.

0295These non-blocking loads help to accelerate hash table searches and linked-list searches; once the header of a record has been fetched, the forward pointer can be used to speculatively fetch the next record before doing any key comparisons with the current one, hiding much of the memory latency and generally overlapping computation and memory access so that hash searches can be done as fast as the records can be fetched from the SDRAM (PE Memory).

0296Special Operations include various administrative functions that the CE uses; these include functions such as incrementing MCCONS and RCCONS in the RTU, flash-clearing the general purpose registers and the result vector, selecting immediate or index-register addressing for PMEM, loading the PMEM index pointer and setting or clearing its sequential access mode, managing a sequential index counter for RESVEC used for table comparisons and result spills, halting the sequencer or putting it into a power-saving sleep mode, managing certain special condition codes, etc.

0297Bulk Table Comparisons (using the cmprn instruction) implement the CE's only multi-cycle instruction; prior to executing cmprn, one or two 32-bit comparison values are loaded into general purpose registers. In the first cycle of a cmprn instruction one or two general-purpose registers are identified as the A-side and B-side comparison values (both can be the same register if desired), a starting index into RESVEC is set, four special condition codes associated with bulk table comparisons are cleared, an instruction-length counter is initialized to the instruction length “N”, and the entire processor is set for cmprn mode. The next “N” 64-bit microcode words are interpreted as pairs of 32-bit values for comparison rather than as microcode; one 32-bit value is compared to the A-side register and the other is compared to the B-side register, and if either matches the associated bit in the (even,odd) bit pair pointed to by the RESVEC_INDEX is set; then the RESVEC_INDEX in incremented to point at the next bit pair, the length counter is decremented, and the next comparison value pair is fetched from CMEM. The process is repeated until the length counter reaches 0.

0298Associated with this process are the four condition-code bits MATCH_A, MATCH_B, MATCH_A_OR_B. and MATCH A_AND_B, which indicate that at least one table value matched on the A-side, on the B-side, on either side, or on A and B-side together (as a 64-bit match), respectively.

0299Given this facility it is possible to compare one extracted value to (2*N) constants or to compare two values to N constants each, in a total of (N+1) cycles. These bulk table lookups are useful for rapidly searching small tables as part of predicate analysis; hash-table lookups are used for larger tables when it becomes more time-efficient to do so.

0300Another special condition-code is “Sticky-zero” or “SZ”. It is used to cumulatively check status on a chain of equality comparisons of the form “if (A==X) and (B==Y) and (C==Z) and (D==W) then . . . ” by first setting the SZ bit in the Condition Code Register using a special operation, then doing a series of equality comparisons or other arithmetic functions, then doing a conditional test of SZ; the bit stays set as long as the result of all intervening operations that set conditions codes have the “data equals zero” status. Any “data not equal to zero status” result in the series will cause SZ to clear and to stay clear.

0301A messaging facility between the CE and the PP is provided; the CE can set any of 4 status bits which cause status to become visible to the PP (Message-Out bits) and the PP can set any of 4 status bits (Message-In bits) which the CE can test as condition codes. These bits can be used for any messaging purpose as assigned by software.

0302Two other condition code bits are “RX_RING_RDY” and “RECLASS_RING_RDY”, which are used by the RTU to indicate to the CE that there is a least one buffer pointer for it to process in the two buffer pointer rings on which it is a consumer; one ring is the “RX Ring” and always carries packets from the associated RX MAC to this CE, and the other is called the “Reclassification Ring” through which any party can schedule a packet to be processed on this CE.

0303In summary, the Classification Engine tests the two ring status bits and the 4 message bits in a dispatch loop, and calls the appropriate service routine when a condition is found to be active. (When no conditions are active the dispatch loop sets the CE into “sleep mode” to reduce power consumption.) The ring service routines fetch a packet buffer pointer from the associated ring, fetch some or all of the packet (only as much as the microcode will need to examine, or all of the packet if checksums are to be validated on the payload), then starts with the first protocol header and executes a series of application-specific operations to extract fields from the packet, identify and process arbitrary protocol headers, do table lookups via bulk comparisons or hash table searches as directed by the application, do checksum verifications as programmed, do boolean reduction on interim results, extract and optionally compute on arbitrary fields in the packet, and finally to write all results to a data structure in the per-packet result area that travels with the packet in the packet buffer in SDRAM. The results written include the set of single-bit predicate analysis results, hash search results (a pointer to the record that matches the key extracted from this packet or a pointer to where a hash record should be inserted if one does not exist and the application wants to create one, for any number of different tables with different keys), plus any extracted or computed values (such as index pointers to the start of each layer of protocol header) desired by the application. Microcode can be loaded into CMEM by the AP or PP, or by the CE itself once it has been loaded with its initial microcode.

0304The following pages include a block diagram of the CE, a table identifying the various microcode control bits, formats for the microcode, and tables of relevant values.

00001. CE Block Diagram

0305<figref idref="DRAWINGS">FIG. 13</figref> shows a block diagram of the Classification engine.

00001.1 Overview of the Classification Engine in <figref idref="DRAWINGS">FIG. 13</figref>.

0306The Classification Engine is a pipelined microsequencer. A 64-bit microword is fetched from Control Store CMEM <b>1202</b> using an address supplied by register PC <b>1234</b>, and is stored in the instruction register I-REG <b>1216</b>. This cycle is referred to as the Fetch cycle <b>1302</b>.

0307The 64-bit microword in I-Reg <b>1216</b> has 7 bits each dedicated to enabling the retirement of a result by causing registers to be loaded. One of these bits is reserved for future enhancements, while 6 of them have specified functions as described in Table 16. This group of signals are known as the write enables WE[<b>6</b>:<b>0</b>]. The WE bits also have function-specific names as shown in Table 1; BRANCH_EN, REG_WE, CC_WE, RESVEC_WE, PMEM_WE, and SPECOP_EN.

0308BRANCH_EN enables conditional program flow changes if a condition test is met. It controls units in the Address Generation Unit <b>1230</b>.

0309REG_WE enables retirement of 32-bit results in the word-oriented half of the machine to all of the general-purpose registers and special registers listed in Table 17. It also has side effects of incrementing the pmem <b>1204</b> index counter PCNT <b>1222</b> or dequeuing a word of data from DFIFO_R <b>1250</b> under certain circumstances.

0310CC_WE enables the writing of the arithmetic result bits in the condition code register.

0311PMEM_WE enables writes into packet memory PMEM <b>1204</b>.

0312RESVEC_WE enables stores in the bit-oriented result vector RESVEC <b>1208</b>.

0313SPECOP_EN enables special operations including writing to PCNT <b>1222</b>, NCNT <b>1224</b>, BDST_CNT <b>1226</b>, and other functions listed in Table 22.

0314The pipeline is 3 stages deep as shown in <figref idref="DRAWINGS">FIG. 14</figref>. The Fetch stage <b>1302</b> has been described above. The Decode stage <b>1304</b> takes place from the output of I-REG <b>1216</b> to the inputs of D-REG <b>1212</b>, PC <b>1234</b>. and RESVEC <b>1208</b>. The Execute stage <b>1306</b> takes place from the output of D-REG <b>1212</b> to the inputs of all general purpose registers and special purpose registers listed in table 17; ALUOUT can be written to GPREG <b>1206</b>, MEM_ADDR <b>1254</b>, DFIFO_W <b>1252</b>, the CTRL_FILL registers <b>1210</b>, and the special registers in block <b>1270</b>. <figref idref="DRAWINGS">FIG. 14</figref> shows in detail what occurs in each stage of the pipeline, and at what stage various types of results are retired. Pipeline stall conditions suppress all of the WE bits so that the same condition holds from once cycle to the next, until the stall condition clears. Since this stall condition affects all microcode-controlled changes of state in the CE, it is implicit in all subsequent discussion of operation of the pipeline and the effect of stalls needs no further discussion. The causes of pipeline stalls are described in subsequent sections.

00001.2 Program Flow Control

0315The address generation unit <b>1230</b> determines what address will be used to fetch the next microword from CMEM. The Program Counter (PC) <b>1234</b> contains the address of the current instruction being fetched. If BRANCH_EN is a ‘0’ then the next value of PC is an increment of the current value; with no branches the microsequencer fetches microwords sequentially from CMEM. When BRANCH_EN is asserted a test of condition codes listed in Table 21 is done as selected by bits CCSEL[<b>4</b>:<b>0</b>] and inverted by FALSE, both fields described in Table 16. If the condition test returns a “1” then the conditional branch will be taken, otherwise PC <b>1234</b> will be loaded with the increment of its current value. The bit REG is tested; if it is ‘0’ then the address PC is added to the value of the bits BRANCH_ADDR[<b>9</b>:<b>0</b>] to generate the branch value of PC; if it is ‘1’ then the address PC is added to the value on bus REGB[<b>9</b>:<b>0</b>] to generate the branch value. The bus REGB carries the output of GPREG <b>1206</b> port DO<b>1</b>, which carries the value of the general purpose register selected with bits RSRCB[<b>2</b>:<b>0</b>].

0316Next bit RET is tested. If it is a ‘1’ then PC is loaded with the output of the microstack <b>1232</b>, and the microstack's stack pointer is decremented by 1. The microstack <b>1232</b> is a Last-in, First-out LIFO structure used to support micro-subroutines, nested up to 8 deep. If RET was a ‘0’ then PC is loaded with the calculated branch value described above instead, and CALL is examined. If CALL is a ‘1’ then the microstack <b>1232</b> has its stack pointer incremented, and the incremented value of the previous PC is written into the microstack using the new value of the stack pointer. In this way the address stored in the microstack <b>1232</b> when a CALL is executed is the address of the next instruction that would have been executed sequentially if the branch had not succeeded; thus when calling a subroutine it is the address of the next instruction to return to after executing a RET to terminate the subroutine.

0317Since all program flow control decisions are made in the Decode stage <b>1304</b>, the sequential instruction which follows is already in the fetch stage and is always executed. This means that there is always a 1-cycle delay between fetching a successful BRANCH_EN instruction and its effect on PC. The instruction which follows a branch instruction, and is always executed regardless of the success or failure of the branch, is called a delay-slot instruction. A delay-slot instruction may not have BRANCH_EN set. The return value stored in the microstack <b>1232</b> after a successful CALL is the address of the instruction following the delay slot instruction of the CALL.

0318The microstack <b>1232</b> in the preferred embodiment of the invention consists of 8 registers with a multiplexer (mux) selecting one of them as the microstack output. A single 3-bit counter is used as the stack pointer; it is decoded in such a way that the read address N is the write address (N+1) so that a read-and-decrement or write-and-increment can be executed in a single cycle. Attempting to execute a CALL when the microstack already has 8 valid entries in it, or attempting to execute a RET when the microstack has no valid entries in it, causes the pipeline to halt and signal STACK_ERROR status to the Policy Processor <b>244</b>.

0319CCSEL, FALSE, BRANCH_ADDR, RSRCB, REG, CALL, and RET are all defined in Table 16.

00001.3 32-Bit Operations

0320The Classification Engine has two distinct data domains; one is oriented around 32-bit data, and the other is oriented around 1-bit boolean data in RESVEC <b>1208</b> and the Bit ALU <b>1260</b>. There are a few places where data is communicated between these two domains. This section describes the 32-bit domain.

0321The 32-bit domain centers around selecting the A-side and B-side operands which are then fed into AIN and BIN of the ALU <b>1214</b>. The output ALUOUT from ALU <b>1214</b> is then written back to one of the 32-bit destinations, and optionally the arithmetic condition codes are set if CC_WE is ‘1’. The ALU <b>1214</b> is a 32-bit Arithmetic and Logic Unit which performs any of the arithmetic functions listed in Table 19 or any of the logic functions listed in Table 20 under control of the bits ALUOP[<b>5</b>:<b>0</b>] defined in Table 16.

0322GPREG <b>1206</b> is a 32-bit general-purpose register file comprising 8 32-bit registers. It has two read ports and one write port. Read port DO<b>0</b> has the contents of the register selected by RSRCA[<b>2</b>:<b>0</b>], and read port DO<b>1</b> has the contents of the register selected by RSRCB[<b>2</b>:<b>0</b>]. The register selected by RDST[<b>2</b>:<b>0</b>] is written to with the value of ALU_OUT if RDST[<b>3</b>] is ‘0’ and REG_WE is ‘1’. In order to make newly-generated register values available in the subsequent instruction, the pipeline delay of writing into GPREG and reading out the new value is squashed through use of Bypass Multiplexers <b>1221</b> and <b>1223</b>, which are used to forward ALU_OUT to busses REGA and REGB if RDST of the instruction in the execute stage matches RSRCA or RSRCB, respectively, in the instruction in the decode stage, thus hiding the pipeline delay. The A-side operand is selected among the A-side sources listed in Table 17 by multiplexer <b>1225</b>. The selected data is then sent into the split-add-mask-and-rotate unit <b>1240</b>. Bits[<b>31</b>:<b>16</b>] of the data are added to bits[<b>15</b>:<b>0</b>] of the data in the adder <b>1248</b>, and the 17-bit result is concanated with zeros in bits [<b>31</b>:<b>17</b>] to create the split-add result. The selected data is also sent to the Mask Unit <b>1242</b> where it is bitwised AND'ed with MASK[<b>31</b>:<b>0</b>] if MSK[<b>1</b>] is a ‘1’, or is passed through unmodified if MSK[<b>1</b>] is a ‘0’; the result from MASK <b>1242</b> is sent through the ROTATE barrel-shifter <b>1244</b> where the data is rotated right by the number of bits specified in ROT[<b>4</b>:<b>0</b>] in the microword. Finally, MSK[<b>0</b>] is used to select between the split-add result and the mask-rotate result in multiplexer <b>1246</b>, and the result is presented to D-REG <b>1212</b> as the A-side operand for the execute stage <b>1306</b>. The B-side operand is selected among the B-side sources listed in Table 18 using multiplexer <b>1228</b>, and is presented to the D-REG <b>1212</b> as the B-side operand for the execute stage <b>1306</b>.

0323RSRCA, RSRCB, ALUOP[<b>5</b>:<b>0</b>], RDST[<b>3</b>:<b>0</b>], MASK[<b>31</b>:<b>0</b>], MSK[<b>1</b>], MSK[<b>0</b>], ROT[<b>4</b>:<b>0</b>] are all described in Table 16.

1.4 PMEM

0324Packet Memory (PMEM) <b>1204</b> is a (32-bit by 512-entry) RAM with one read port and one write port used to hold some or all of the packet being processed, and also to hold arbitrary data generated by the program. PMEM <b>1204</b> can be written from two sources; DFIFO_R <b>1250</b>, or the REGA bus from the general-purpose registers GPREG <b>1206</b>, where the register is selected by RSRCA[<b>2</b>:<b>0</b>]; such writes occur when PMEM_WE is a ‘1’ in the microword. PMEM is read as one of the A-side sources selectable as one of the “special register” sources.

0325PMEM <b>1204</b> addressing depends on the state bit USE_PCNT. When USE_PCNT is ‘0’, then PMEM <b>1204</b> is addressed by PINDEX[<b>10</b>:<b>2</b>] from the microword. When USE_PCNT is ‘1’ then the address to PMEM <b>1204</b> is provided by the counter/register PCNT <b>1222</b>. USE_PCNT is set and cleared via special operations. When SPECOP_EN is ‘1’ and LD_PCNT is ‘1’, then PCNT_REG is examined. If it is a “1” then PCNT is loaded with the value of bits [<b>10</b>:<b>2</b>] of the general-purpose register in GPREG <b>1206</b> selected by RSRCB[<b>2</b>:<b>0</b>]; alternatively if PCNT_REG is a “0” then PCNT is loaded with the value of PINDEX[<b>10</b>:<b>2</b>] in the microword. In either case the state bit USE_PCNT is set. Additionally, bit PCNT_INC is examined, if it is a “1” then PCNT_INC_MODE is set, or if it is a “0” then PCNT_INC_MODE is cleared. The state bit PCNT_INC_MODE determines if PCNT <b>1222</b> holds a static value during the PCNT_MODE period, or if increments by one each time PMEM is written to or is used as a register source. USE_PCNT clears when an instruction has SPECOP_EN equal to “1” and UNLOCK_PCNT also equal to “1”.

0326DFIFO_R, RSRCA[<b>3</b>:<b>0</b>], RSRCB[<b>3</b>:<b>0</b>], PINDEX[<b>10</b>:<b>2</b>] are all defined in Table 16, LD_PCNT, PCNT_REG, PCNT_INC, UNLOCK_PCNT are all defined in Table 22.

00001.5 Interface to Memory <b>260</b>

0327SDRAM Memory <b>260</b> can be read and written by the microcode. The memory interface visible to the microcode consists of the MEM_ADDR FIFO <b>1254</b>, the write data FIFO DFIFO_W <b>1252</b>, and the read data FIFO DFIFO_R <b>1250</b>. Writes to memory <b>260</b> are called stores, and reads from memory <b>260</b> are called loads. Loads and stores can be of size 1, 2, 4, or 8 words of 32-bits each. The address of a memory access must be size-aligned for the specified burst; that is, the address for a 2-word memory access must be on an 8-byte boundary, the address of an 8-word access must be on a 32-byte boundary, etc.

0328To schedule a store, precisely the number of words for the specified size of transfer are written to the special register destination DFIFO_W <b>1252</b>, then the address (along with control information MEM_SIZE[<b>1</b>:<b>0</b>] and MEM_DIR=STORE) are written into the address fifo MEM_ADDR <b>1254</b>, which triggers the memory interface to issue the store. The microsequencer is decoupled from the memory system by the FIFOs <b>1252</b> and <b>1254</b>, and thus can continue operation while the memory interface processes the store operation. The FIFOs <b>1254</b> and <b>1252</b> can hold up to 8 addresses and 16 words of data, respectively, so that in general more than one store operation can be outstanding without stalling the pipeline. The entire pipeline stalls when the execute stage <b>1306</b> operation is a write to either MEM_ADDR <b>1254</b> or to DFIFO_W <b>1252</b> and the target FIFO does not have room for another word. The situation will clear as the FIFO drains its current operation to memory <b>260</b> so the stall condition is transient.

0329To schedule a load, the address (along with control information MEM_SIZE[<b>1</b>:<b>0</b>] and MEM_DIR=LD) is written to special register destination MEM_ADDR, and some time later the microcode can obtain the requested data from the read data FIFO DFIFO_R <b>1250</b>. Between the time that the microsequencer scheduled the load operation and the time the data is consumed, there is latency to access the memory system <b>260</b>. The microcode can choose to execute any number of instructions between the time the load is scheduled in MEM_ADDR <b>1254</b> and the data is consumed from DFIFO_R <b>1250</b>, since the loads are non-blocking. However, if the microcode attempts to read data from DFIFO_R <b>1250</b> and there is no data available, the pipeline will stall until such time as requested data has returned from memory <b>260</b>. More than one load can be scheduled before any data is consumed; DFIFO_R <b>1250</b> has room for up to 16 doublewords (128 bytes) of data.

0330The microcode is responsible for ensuring that it never attempts to read data from DFIFO_R <b>1250</b> when no more words of read data have been scheduled, nor to issue a store address to MEM_ADDR <b>1254</b> when DFIFO_W <b>1252</b> has not been written with precisely the number of words specified in the size of the store. The microcode is also responsible for never oversubscribing DFIFO_R <b>1254</b>, that is, scheduling more outstanding words of read data than DFIFO_R <b>1254</b> has room for. Any of these conditions is detected by error-checking logic in the CE which will halt the CE and report violations to the Policy Processor <b>244</b> if the memory system is used incorrectly.

00001.6 Bit-Oriented Operations

0331RESVEC <b>1208</b> is a 1-bit by 512-entry register file with special characteristics. It has one write port and 3 read ports; this means that in any one instruction 3 bits can be read and one write can be issued. The write can be to one bit, or to an adjacent pair of bits whose address differs only in the least significant bit, referred to here as an even-odd bit pair. For certain operations RESVEC <b>1208</b> can also be accessed as a 32-bit by 16-entry register file.

0332When RESVEC_WE is a ‘1’ and the microcode bit 2 BIT is a ‘0’ then a single bit in RESVEC <b>1208</b> is written with the data presented on the DIN<b>0</b> data input port; that data is selected from among 4 different sources under control of the RES<b>0</b>_SEL[<b>1</b>:<b>0</b>] bits in the microword. Alternatively if 2 BIT is a ‘1’ then the DIN<b>0</b> data is written to the even-numbered bit in the destination, and DIN<b>1</b> selected from among two sources by RES<b>1</b>_SEL is written to the odd-numbered bit of the pair.

0333The destination address in RESVEC <b>1208</b> comes either from RES_BIT_DST[<b>9</b>:<b>0</b>] if state bit USE_WCNT is ‘0’, or from BDST_CNT <b>1226</b> if USE_WCNT is a ‘1’. USE_WCNT is set when SPECOP_EN is ‘1’ and LD_BDST_CNT is a ‘1’. In that case BDST_CNT <b>1226</b> is written with the value RES_BIT_DST[<b>9</b>:<b>1</b>]. At the same time BDST_CNT <b>1226</b> is loaded, the bit BDST_CNT_MODE in the microword is examined. If it is ‘0’ then BDST_CNT <b>1226</b> is set to increment by 2, if it is ‘1’ then BDST_CNT <b>1226</b> is configured to increment by 32. The former is used in the special instruction CMPRN to sweep across sequential bit pairs in each cycle of the instruction and to write to them, while the latter is used for the RESVEC <b>1208</b> read address port RA<b>0</b> to sequentially read 32-bit groups of RESVEC <b>1208</b> bits as the B-side special register RES_VEC.

0334The bit-oriented ALU <b>1260</b> contains two boolean logic units <b>1264</b> and <b>1268</b> and one gang operation unit <b>1262</b>. Boolean logic unit <b>1264</b> takes the two bits selected by RES_BIT_SRC_A[<b>9</b>:<b>0</b>] and RES_BIT_SRC_B[<b>9</b>:<b>0</b>] and applies the boolean operation BITOPAB[<b>3</b>:<b>0</b>] as specified in table 20. The 1-bit result RES_BIT<b>0</b> is one of the potential sources for write data port DIN<b>0</b> on RESVEC <b>1208</b>. Boolean logic unit <b>1268</b> similarly takes the operands selected by RES_BIT_SRC_A[<b>9</b>:<b>0</b>] and RES_BIT_SRC_C[<b>9</b>:<b>0</b>] and applies BITOPAC[<b>3</b>:<b>0</b>] in a substantially similar manner, generating the 1-bit result RES_BIT<b>1</b> which may be selected as the DIN<b>1</b> write data source if 2 BIT is ‘1’. Thus in one cycle up to two bitwise boolean operations can be executed if the two operations have one common operand. The GANGOP unit <b>1262</b> takes the 32 adjacent bits from RESVEC <b>1208</b> selected by RES_BIT_SRC_A[<b>9</b>:<b>5</b>] and treats them as a word operand. MASK[<b>31</b>:<b>0</b>] is used to select which bits of that word will contribute to the gang results, then an AND, OR, NAND, or NOR operation is performed on all of the selected bits as instructed in GANGOP[<b>1</b>:<b>0</b>], and the result bit RES_GANG is presented as one of the possible sources for DIN<b>0</b> on RESVEC <b>1208</b>.

0335The condition code selected by CCSEL[<b>4</b>:<b>0</b>] and optionally inverted with FALSE can also be selected as the data source for port DIN<b>0</b>.

0336The remaining sources for DIN<b>0</b> and DIN<b>1</b> on RESVEC <b>1208</b> are the CMPR_A, CMPR_B result bits from one cycle of a bulk comparison instruction CMPRN, described below.

0337RESVEC <b>1208</b> address fields for sources and destination are specified as 10 bits, even though only 9 bits are used in the preferred embodiment; the extra bit allows for a doubling of the size of RESVEC <b>1208</b> in future generations of the device.

0338Writes to RESVEC <b>1208</b> are retired at the end of the Decode stage <b>1304</b> and can thus be used immediately as an operand in the subsequent instruction, without need for bypassing as is done with GPREG <b>1206</b>.

03392 BIT, RES<b>0</b>_SEL[<b>1</b>:<b>0</b>], RES<b>1</b>_SEL, BITOPAB, BITOPAC, GANGOP[<b>1</b>:<b>0</b>], RES_BIT_DST[<b>9</b>:<b>0</b>], RES_BIT_SRC_A[<b>9</b>:<b>0</b>], RES_BIT_SRC_B[<b>9</b>:<b>0</b>], RES_BIT_SRC_C[<b>9</b>:<b>0</b>], MASK[<b>31</b>:<b>0</b>], CCSEL[<b>4</b>:<b>0</b>], FALSE are all defined in Table 16.

0340LD_BDST_CNT, BDST_CNT_MODE are specified in Table 22.

00001.7 Bulk Comparisons

0341When SPECOP_EN is ‘1’ and LD_NCNT is also ‘1’, the instruction cycle counter N_CNT <b>1224</b> is loaded with the value NCNT[<b>6</b>:<b>0</b>] (bits[<b>22</b>:<b>16</b>] of the microword) and the state bit CMPRN is set. LD_BDST_CNT is required to also be a ‘1’ for this instruction, and BDST_CNT_MODE must be a ‘0’. BDST_CNT <b>1226</b> is loaded with the value RES_BIT_DST[<b>9</b>:<b>1</b>]. GPREG <b>1206</b> is locked with the A-side select RSRCA[<b>2</b>:<b>0</b>] and the B-side select RSRCB[<b>2</b>:<b>0</b>]. The bit CLEAR_HIT is required to be a ‘1’ also in this instruction, which has the effect of setting the condition code register bits MTCH_A, MTCH_B, MTCH_AORB, MTCH_AANDB all to zero.

0342For the next N cycles, until N_CNT <b>1224</b> has decremented to zero, interpretation of the 64-bit microword is suppressed and all 64 bits are treated as data instead. In each of these cycles the microword bits [<b>63</b>:<b>32</b>] are compared to the selected A-side register value REGA using comparator <b>1220</b> to produce the result CMPR_A if they are equal; and microword bits [<b>31</b>:<b>0</b>] are compared to the selected B-side register value REGB using comparator <b>1227</b> to produce result CMPR_B if they are equal. During CMPRN the RESVEC unit <b>1208</b> is locked into a mode where 2 BIT is true and RES<b>0</b>_SEL and RES<b>1</b>_SEL select CMPR_A, CMPR_B respectively. The results CMPR_A and CMPR_B are stored to the even-odd pair of bits in RESVEC <b>1208</b> selected by BDST_CNT <b>1226</b>, then BDST_CNT <b>1226</b> is incremented, NCNT <b>1224</b> is decremented, and the process repeats until NCNT <b>1224</b> equals zero. At that point the state bits USE_BDST_CNT and CMPRN clear and the pipeline goes back to normal operation where every microword is interpreted.

0343During every comparison cycle of the CMPRN instruction, if CMPR_A is a ‘1’ then the condition code bit MTCH_A will set and will stay set. Similarly if CMPR_B is a ‘1’ during any of those cycles then bit MTCH_B will set and will stay set. If either CMPR_A or CMPR_B is true during any of these cycles then condition code bit MTCH_AORB will set and will stay set. Finally, if CMPR_A and CMPR_B are both ‘1’ during a CMPRN compare cycle, then MTCH_AANDB will set and will stay set to indicate that a 64-bit match was encountered.

0344By loading one or two registers in GPREG <b>1206</b> with comparison values prior to executing the CMPRN instruction, a single value can be compared to (2*N) values in a table, or two different values can each be compared to (N) values, in ((2*N)+1) execution cycles.

0345RES_BIT_DST[<b>9</b>:<b>0</b>], RSRCA[<b>3</b>:<b>0</b>], RSRCB[<b>3</b>:<b>0</b>], 2BIT, RES<b>0</b>_SEL, RES<b>1</b>_SEL are specified in Table 16.

0346LD_NCNT, LD_BDST_CNT, CLEAR_HIT are specified in Table 22.

00001.8 Special Operations

0347In addition to the special operations mentioned so far, there are other administrative functions which are enabled with SPECOP_EN and decoded from the bits specified in Table 22. Decode of these functions and any decode necessary for implementing the instruction set specified take place in the decoder block DCD <b>1272</b>.

00001.9 CMEM Fills

0348The microstore CMEM <b>1202</b> is filled either via a series of PIO write accesses from the Policy Processor <b>244</b> or Application Processor <b>302</b>, or can be loaded by use of the CTRL_FILL unit <b>1210</b>. The registers in CTRL_FILL <b>1210</b> are loaded with an address in memory <b>260</b>, an address in CMEM <b>1202</b>, and a count of the number of instructions to be loaded. With the CE pipeline halted, the CTRL_FILL unit will execute this transfer.

0349The transfer may be initiated by the Policy Processor <b>244</b>, the Application Processor <b>302</b>, or can be initiated by microcode running on the CE, in which case the CTRL_FILL <b>1210</b> registers appear as special register destinations as shown in Table 17, and the operation is triggered with an instruction which has SPECOP_EN equal to ‘1’, and HALT and DO_CMEM_FILL asserted. After the transfer completes, microcode can then continue execution, including the newly downloaded code. The CE can only load and launch itself if microcode to do so is already resident in CMEM <b>1202</b> and if the host has configured the CE to allow it to do so.

0350HALT and DO_CMEM_FILL are specified in Table 22.

00002. CE Programming Languages

0351CE programs can be written directly in binary; however for programmer convenience a microassembly language uasm has been developed which allows a microword to be constructed by declaring fields and their values in a symbolic form. The set of common microwords for the intended use of the CE have also been described in a higher-level CE Assembly Language called masm which allows the programmer to describe operations in a register-transfer format and to describe concurrent operations without having to worry about the details of microcode control of the underlying hardware. Both of these languages can be used by a programmer or can be generated automatically from a compiler which translates CE programs from a higher-level language such as NetBoost Classification Language (NCL).

V. Microprogramming Guide

0352The 64-bit CE instruction word is raw microcode; some bits enable retirement of operations by writing to one or more units, and the rest are used to steer different data paths and to provide control codes to various units in parallel. Depending on which results are retired, the fields in the microword have different meaning. There are 7 different ways that the microword is interpreted; even though all steering is really done in parallel, these 7 instruction formats show which sets of fields can be used without conflict.

0353There are 7 bits that are constant in all formats; these are the bits that enable stores into various units. These bits are {REG_W, RESVEC_W, CC_WE, reserved, PMEM_WE, BRANCH_EN, and SPECOP_EN}, which are assigned in that order to bits [<b>63</b>:<b>57</b>] of the microword and are described in Table 16. The remaining bits are assigned to control points as shown in <figref idref="DRAWINGS">FIG. 13</figref> and are defined in the following sections.

0354As shown in <figref idref="DRAWINGS">FIG. 14</figref>, the CE is implemented as a 3-stage pipeline; each instruction passes through the three stages Fetch <b>1302</b>, Decode <b>1304</b>, and Execute <b>1306</b>; at any time there are three different instructions being processed. The figure shows what processes occur in each stage of the pipeline, and helps illustrate behavior of the pipeline shown in <figref idref="DRAWINGS">FIG. 13</figref>. When the pipeline stalls all three stages stall together in lockstep.

0355Most word-oriented operations pass one operand through either the mask/shift unit or the split-add unit and then all word-oriented operations pass through the Execute-stage ALU before being retired. Any consumer of a newly-produced GPREG value actually receives a forwarded copy of the current ALU output via some bypass logic so that there is no delay between creation of a result and use of it in a subsequent operation. Similarly, use of condition codes for BRANCH (conditional flow control) or BSET (setting a selected RESVEC bit to the result of a condition code test), or reads of CC_REG (Condition Code Register) when the bits are being updated requires bypassing.

0356Other registers (e.g. BASE_REG) do not have forwarding so the software must delay one clock after writing them before using the result.

00001. Microword Format Definitions

00001.1 MOV, ALU, and LDST Operations

0357REG_WE is set.

0358These instructions select 1 or 2 sources among GPREG and SPREG, do a mask/shift or split-add of the A-side operand, then pass them through the ALU and store the result to an SPREG or GPREG. Condition codes Z, N, V, SZ, and CY are optionally set by this operation if CC_WE is set. <tables id="TABLE-US-00010" num="10"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="371PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 9</entry></row><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>MOV and ALU formats</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row><row><entry><chemistry id="CHEM-US-00001" num="1"><img file="US2007169179A1_D0001.tif" /></chemistry></entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0359<tables id="TABLE-US-00011" num="11"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="336PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 10</entry></row><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>MOV and ALU formats with PMEM src</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row><row><entry><chemistry id="CHEM-US-00002" num="2"><img file="US2007169179A1_D0002.tif" /></chemistry></entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0360Note that with PMEM[immediate_index] as a source the ALU is bypassed (except for sign and zero-detect); however mask/rotate or split-add are still available. <tables id="TABLE-US-00012" num="12"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="371PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 11</entry></row><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>LDST format</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row><row><entry><chemistry id="CHEM-US-00003" num="3"><img file="US2007169179A1_D0003.tif" /></chemistry></entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry namest="1" nameend="1" align="left" id="FOO-00001"><br />(a) SIZE[1:0]<br /></entry></row><row><entry namest="1" nameend="1" align="left" id="FOO-00002"><br />(b) DIR <br /></entry></row></tbody></tgroup></table></tables><br /> 1.2 BIT_OP

0361Bitops and gangops have RESVEC_WE set. These instructions select a bit RES_BIT_DST in RESVEC as a destination to which the RESO result is written; and if (optionally) 2 BIT is set, then RES_BIT_DST is treated as the pointer to an adjacent pair of bits where the first has an even address and the second has the next (odd) address. With 2 BIT the odd bit is written with the RES<b>1</b> result.

0362Depending on the value of the field RES<b>0</b>_SEL, the RES<b>0</b> result may come from a boolean operation BITOPAB performed on the operands selected by RES_BIT_SRC_A and RES_BIT_SRC_B, or the result of a GANG operation performed on bits in the group of 32 RESVEC bits selected by RES_BIT_SRC_A[<b>9</b>:<b>5</b>] and further selected by the “1” bits in the 32-bit immediate MASK field, or the selected and optionally inverted condition code bit selected by CCSEL and FALSE, or the A-side result of a bulk table comparison CMPR_A.

0363If RES<b>1</b> is being written to the odd bit of a pair, the RES<b>1</b> result is selected by RES<b>1</b>_SEL to be either the result of the arbitrary boolean operation BITOPAC performed on the operands selected by RES_BIT_SRC_A and RES_BIT_SRC_C, or the B-side result of a bulk table comparison CMPR_B. <tables id="TABLE-US-00013" num="13"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="441PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 12</entry></row><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>BIT_OP Format</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row><row><entry><chemistry id="CHEM-US-00004" num="4"><img file="US2007169179A1_D0004.tif" /></chemistry></entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry namest="1" nameend="1" align="left" id="FOO-00003"><br />(a) RES0_SEL[1:0]<br /></entry></row><row><entry namest="1" nameend="1" align="left" id="FOO-00004"><br />(b) 2BIT <br /></entry></row><row><entry namest="1" nameend="1" align="left" id="FOO-00005"><br />(c) RESI_SEL <br /></entry></row><row><entry namest="1" nameend="1" align="left" id="FOO-00006"><br />(d) FALSE (selects gender of CCMUX output; 0 '2 as is, I = inverted) <br /></entry></row></tbody></tgroup></table></tables>

03641.3 GANG_OP <tables id="TABLE-US-00014" num="14"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="441PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 13</entry></row><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>GANG_OP Format</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row><row><entry><chemistry id="CHEM-US-00005" num="5"><img file="US2007169179A1_D0005.tif" /></chemistry></entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry namest="1" nameend="1" align="left" id="FOO-00007"><br />(a) GANG_OP[1:0]<br /></entry></row></tbody></tgroup></table></tables><br /> 1.4 Branch

0365BRANCH_EN is always set in this format. Note that a register-to-register aluop can be folded into the same instruction as long as there are no other field conflicts. <tables id="TABLE-US-00015" num="15"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="441PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 14</entry></row><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Branch Format</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row><row><entry><chemistry id="CHEM-US-00006" num="6"><img file="US2007169179A1_D0006.tif" /></chemistry></entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry namest="1" nameend="1" align="left" id="FOO-00008"><br />(a) FALSE (selects gender of CCMUX output; 0 = as is, 1 = inverted) <br /></entry></row><row><entry namest="1" nameend="1" align="left" id="FOO-00009"><br />(b) CALL <br /></entry></row><row><entry namest="1" nameend="1" align="left" id="FOO-00010"><br />(c) RET <br /></entry></row><row><entry namest="1" nameend="1" align="left" id="FOO-00011"><br />(d) REG (selects GPREG (‘1’) or immediate value (‘0’) for branch <br /></entry></row></tbody></tgroup></table></tables><br /> 1.5 SPECOP

0366Special Operation bits (which are all qualified with SPECOP_EN) are defined in Section Table 22 on page 91. The instructions cmprn, setpcnt[i], and set_resvec_index also use some specop fields. <tables id="TABLE-US-00016" num="16"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="441PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 15</entry></row><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>SPECOP Format</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row><row><entry><chemistry id="CHEM-US-00007" num="7"><img file="US2007169179A1_D0007.tif" /></chemistry></entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry namest="1" nameend="1" align="left" id="FOO-00012"><br />(a) RES0_SEL[1:0] (for CMPRN) <br /></entry></row><row><entry namest="1" nameend="1" align="left" id="FOO-00013"><br />(b) 2BIT (for CMPRN) <br /></entry></row><row><entry namest="1" nameend="1" align="left" id="FOO-00014"><br />(c) RES 1_SEL (for CMPRN) <br /></entry></row><row><entry namest="1" nameend="1" align="left" id="FOO-00015"><br />(*) The interpretation of these bits is defined in Table 22 of page 91. <br /></entry></row><row><entry namest="1" nameend="1" align="left" id="FOO-00016"><br />(?) Undefined but reserved for future special operations <br /></entry></row></tbody></tgroup></table></tables>

03671.6 Control Field Definitions <tables id="TABLE-US-00017" num="17"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="343PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 16</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Control Fields</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="63PT" align="left" /><colspec colname="2" colwidth="252PT" align="left" /><colspec colname="3" colwidth="28PT" align="center" /><tbody valign="top"><row><entry>Signals</entry><entry>Function</entry><entry>Bits</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>WE[6:0]</entry><entry>These are the fixed-format signals which retire results (unless the pipeline is</entry><entry>[63:57]</entry></row><row><entry /><entry>stalled); they are:</entry></row><row><entry /><entry>[0] SPECOP_EN: enables special ops as defined in 9.2.5.</entry></row><row><entry /><entry>[1] BRANCH_EN: Enables a conditional program flow control operation</entry></row><row><entry /><entry>[2] PMEM_WE: Enables stores into PMEM</entry></row><row><entry /><entry>[3] reserved</entry></row><row><entry /><entry>[4] CC_WE: Enables store to CC_Z, CC_CY, CC_SZ, CC_V, CC_N</entry></row><row><entry /><entry>[5] RESVEC_WE: Enables stores to the result bit vector</entry></row><row><entry /><entry>[6] REG_WE: Enables stores of ALU_OUT into the GPREG file if (RDST[3] = 0),</entry></row><row><entry /><entry>or into SPREG's if (RDST[3] = 1).</entry></row><row><entry>RSRCA[3:0]</entry><entry>Selects a GPREG to drive out on DOUT0 (using [2:0]) and selects between</entry><entry>[35:32]</entry></row><row><entry /><entry>GPREG and SPREG sources on the mux to SPLIT-ADD and MASK using [3]</entry></row><row><entry>RSRCB[3:0]</entry><entry>Selects a GPREG to drive out on DOUT1 (using [2:0]) and selects between that</entry><entry>[39 36]</entry></row><row><entry /><entry>and SPREG sources on the ALUB input mux</entry></row><row><entry>RDST[3:0]</entry><entry>Selects which GPREG to enable the WE onto with [2:0] if [3] == 0; and if [3] == 1,</entry><entry>[56:53]</entry></row><row><entry /><entry>[2:0] is decoded to select which SPREG to write to.</entry></row><row><entry>ROT[4:0]</entry><entry>Steers the 32-bit barrel shifter</entry><entry>[50:46]</entry></row><row><entry>MSK[1]</entry><entry>If [1] then masking is enabled; if [0] then pass-thru</entry><entry>[52]</entry></row><row><entry>MSK[0]</entry><entry>If [1] selects MASK/ROTATE output, if [0] selects SPLIT_ADD output, on ALUA</entry><entry>[51]</entry></row><row><entry /><entry>input mux.</entry></row><row><entry>ALUOP[5:4]</entry><entry>[1x] selects ALUA input as ALU_OUT The reason for this is to enable a MOV</entry><entry>[45:44]</entry></row><row><entry /><entry>from PMEM[index] with mask and rot; but we lose ALUOP due to bit overlays, so</entry></row><row><entry /><entry>we can't use the ALU in the same instruction.</entry></row><row><entry /><entry>[00] selects ADDER output</entry></row><row><entry /><entry>[01] selects LOGIC output</entry></row><row><entry>ALUOP[3:0]</entry><entry>On LOGIC unit, these 4 bits are the mux inputs steered by the bit pairs.</entry><entry>[43:40]</entry></row><row><entry>ALUOP[1:0]</entry><entry>Selects CY_IN to ADDER:</entry><entry>[41:40]</entry></row><row><entry /><entry>[00] selects “0”</entry></row><row><entry /><entry>[01] selects “1” (for subtracts)</entry></row><row><entry /><entry>[1x] selects CC_REG_CY</entry></row><row><entry>ALUOP[2]</entry><entry>If ‘1’, inverts ADDER input on the A port.</entry><entry>[42]</entry></row><row><entry>ALUOP[3]</entry><entry>If ‘1’, inverts ADDER input on the B port.</entry><entry>[43]</entry></row><row><entry>IMMEDIATE</entry><entry>32-bit immediate value used on ALUB input path; if (RDST == MEM_ADDR)</entry><entry>[31:0]</entry></row><row><entry /><entry>then only bits [27:0] are used</entry></row><row><entry>MASK</entry><entry>32-bit immediate value used in MASK and GANG_OP units for bit masking;</entry><entry>[31:0]</entry></row><row><entry /><entry>AND'ed with the input value</entry></row><row><entry>PINDEX[10:2]</entry><entry>Used to address words in PMEM for MOV operations and for loading PCNT for</entry><entry>[44:36]</entry></row><row><entry /><entry>sequential pmem operations. a.k.a. INDEX[8:0]</entry></row><row><entry>MEM_SIZE[1:0]</entry><entry>In LDST format, indicates the size to MEM_ADDR:</entry><entry>[31:30]</entry></row><row><entry /><entry>[00]: 1 word</entry></row><row><entry /><entry>[01]: 2 words (only aligned double-word allowed)</entry></row><row><entry /><entry>[10]: 4 words (aligned on a 16-byte boundary)</entry></row><row><entry /><entry>[11]: 8-word burst (aligned on an 8-word (32-byte) boundary)</entry></row><row><entry /><entry>Note that hardware masks the lower address bits to force size-alignment</entry></row><row><entry>MEM_DIR</entry><entry>In LDST format, [1] is a store, [0] is a load from memory</entry><entry>[29]</entry></row><row><entry>RES_BIT_SRC_A</entry><entry>Selects a bit of the 512-bit result vector; bit [9] is not connected, leaves room for</entry><entry>[41:32]</entry></row><row><entry>[9:0]</entry><entry>future growth. Bits[8:5] select the word to port W0[31:0] on the file. Bits[4:0]</entry></row><row><entry /><entry>select the bit within the word to port B0</entry></row><row><entry>RES_BIT_SRC_B</entry><entry>Same as above, but to word W1 and bit B1.</entry><entry>[31:22]</entry></row><row><entry>[9.0]</entry></row><row><entry>RES_BIT_SRC_C</entry><entry>Same as above, but to word W2 and bit B2.</entry><entry>[21:12]</entry></row><row><entry>[9:0]</entry></row><row><entry>RES_BIT_DST</entry><entry>[9] is reserved for future growth. [8:5] are decoded to a row select, and [4:0] are</entry><entry>[56:47]</entry></row><row><entry>[9:0]</entry><entry>decoded to a column select for enabling the bit write.</entry></row><row><entry>RES0_SEL[1:0]</entry><entry>Mux select for the DIN0 bit to RESVEC;</entry><entry>[46:45]</entry></row><row><entry /><entry>[00]: CMPR_A</entry></row><row><entry /><entry>[01]: RES_BIT0</entry></row><row><entry /><entry>[10]: RES_GANG</entry></row><row><entry /><entry>[11]: COND_CODE as selected by {FALSE, CC_SEL[4:0]}</entry></row><row><entry>RESI_SEL</entry><entry>Mux select for the DIN1 bit to RESVEC, used if 2BIT is set;</entry><entry>[43]</entry></row><row><entry /><entry>[0]: CMPR_B</entry></row><row><entry /><entry>[1]: RES_BIT1</entry></row><row><entry>2BIT</entry><entry>Enables next-neighbor write to odd-numbered bits in RESVEC, for operations with</entry><entry>[44]</entry></row><row><entry /><entry>two results (dbitop, cmprn)</entry></row><row><entry>BITOP_AB[3:0]</entry><entry>These bits are selected by {BIT1, BIT0} to provide arbitrary boolean functions on</entry><entry>[7:4]</entry></row><row><entry /><entry>the bits: {00}->[01], {01}->[1], {10}->[2], {11}->[3]</entry></row><row><entry>GANG_OP[1]</entry><entry>Mux steering. ‘1’==AND, ‘0’==OR</entry><entry>[43]</entry></row><row><entry>GANG_OP[0]</entry><entry>Inverts result if ‘1’ to create NAND or NOR</entry><entry>[42]</entry></row><row><entry>BRANCH[9:0]</entry><entry>If BRANCH condition passes, this is the signed relative branch offset in CMEM</entry><entry>[9:0]</entry></row><row><entry>CALL</entry><entry>Loads a copy of (PC + 1) into the microstack; timed so that the address saved is one</entry><entry>[31]</entry></row><row><entry /><entry>past the branch delay slot, and bumps microstack pointer</entry></row><row><entry>RET</entry><entry>Forces the contents of the microstack register into the PC reg and decrements the</entry><entry>[30]</entry></row><row><entry /><entry>microstack pointer</entry></row><row><entry>BRANCH_REG</entry><entry>If ‘1’, branch to REG_B output on a branch/call; if ‘0’ branch to the immediate</entry><entry>[29]</entry></row><row><entry /><entry>value</entry></row><row><entry>FALSE</entry><entry>If ‘1’, invert the output of the CC_MUX</entry><entry>[27]</entry></row><row><entry>CC_SEL[4:0]</entry><entry>Selects a condition code bit for a branch decision</entry><entry>[26:22]</entry></row><row><entry>Special ops</entry><entry>Defined in “SPECOP bit assignments” on page 46</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> 2. Register Select Codes

03682.1 A-side Operands and Destination Registers <tables id="TABLE-US-00018" num="18"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 17</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Register Select Codes for Destinations and for A-side Sources</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="56PT" align="left" /><colspec colname="4" colwidth="63PT" align="left" /><tbody valign="top"><row><entry /><entry>REG[3] =</entry><entry /><entry /></row><row><entry>REG[2:0]</entry><entry>0, Src. or Dst.</entry><entry>REG[3] = 1, Dst.</entry><entry>REG[3] = 1, Src.</entry></row><row><entry namest="1" nameend="4" align="center" rowsep="1" /></row><row><entry>0b000</entry><entry>GPREG0 (g0)</entry><entry>NULL (discard)</entry><entry>CC_REG</entry></row><row><entry>0b001</entry><entry>GPREG1 (g1)</entry><entry>BASE_REG</entry><entry>BASE_REG</entry></row><row><entry>0b010</entry><entry>GPREG2 (g2)</entry><entry>DFIFO_W</entry><entry>DFIFO_R</entry></row><row><entry>0b011</entry><entry>GPREG3 (g3)</entry><entry>MEM_ADDR</entry><entry>BASE_REG_MSK</entry></row><row><entry>0b100</entry><entry>GPREG4 (g4)</entry><entry /><entry>PMEM</entry></row><row><entry>0b101</entry><entry>GPREG5 (gS)</entry><entry>CEFADR</entry></row><row><entry>0b110</entry><entry>GPREG6 (g6)</entry><entry>CESTART</entry></row><row><entry>0b111</entry><entry>GPREG7 (g7)</entry><entry>CECNT</entry></row><row><entry namest="1" nameend="4" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

03692.2 B-Side Operands <tables id="TABLE-US-00019" num="19"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 18</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Register Select Codes for B-side Sources</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="126PT" align="left" /><tbody valign="top"><row><entry>REG[2:0]</entry><entry>REG[3] = 0</entry><entry>REG[3] = 1</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>0b000</entry><entry>GPREG0 (g0)</entry><entry>IMMEDIATE</entry></row><row><entry>0b001</entry><entry>GPREG1 (g1)</entry><entry>IMMED_ADDR[27:0] ([31:28] are 0x0)</entry></row><row><entry>0b010</entry><entry>GPREG2 (g2)</entry><entry>DURATION</entry></row><row><entry>0b011</entry><entry>GPREG3 (g3)</entry><entry>MEM_WAIT</entry></row><row><entry>0b100</entry><entry>GPREG4 (g4)</entry><entry>TIMER</entry></row><row><entry>0b101</entry><entry>GPREG5 (g5)</entry><entry>DIAG_REG</entry></row><row><entry>0b110</entry><entry>GPREG6 (g6)</entry></row><row><entry>0b111</entry><entry>GPREG7 (g7)</entry><entry>RESVEC[1]</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry namest="1" nameend="3" align="left" id="FOO-00017"><br />[1]Indirect addressing of RESVEC: RESVEC accesses a word of the result vector pointed to by WCNT (which was loaded via a specop) and then autoincrements the index. After the RESVEC store to dfifo is completed a resvec_index_unlock must be executed to enable random access to RESVEC. <br /></entry></row></tbody></tgroup></table></tables><br /> 3. ALU and Logic Operations

03703.1 Adder Op Codes <tables id="TABLE-US-00020" num="20"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 19</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>ALUOP Bit Specifications for ADDER (ALUOP[4] = 0)</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="105PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="63PT" align="left" /><tbody valign="top"><row><entry>OPERATION</entry><entry>ALUOP[3:0]</entry><entry><ALUop> Name</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>A + B</entry><entry>0b0000</entry><entry>ADD</entry></row><row><entry>A + B + CY</entry><entry>0b0010</entry><entry>ADC</entry></row><row><entry>A + B + 1</entry><entry>0b0001</entry><entry>ADINC</entry></row><row><entry>A − B</entry><entry>0b1001</entry><entry>SUB</entry></row><row><entry>A − B − <o ostyle="single">CY</o> (A + <o ostyle="single">B</o> + CY)</entry><entry>0b1010</entry><entry>SUBB</entry></row><row><entry>A − B − 1</entry><entry>0b1000</entry><entry>SBDEC</entry></row><row><entry>B − A</entry><entry>0b0101</entry><entry>SBR (Reverse)</entry></row><row><entry>B − A − 1</entry><entry>0b0100</entry><entry>SBRDEC</entry></row><row><entry>B − A − <o ostyle="single">CY</o> ( <o ostyle="single">A</o> + B + CY)</entry><entry>0b0110</entry><entry>SBRB</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

03713.2 Logic Op and BITOP Codes <tables id="TABLE-US-00021" num="21"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 20</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>ALUOP Bit Specifications for LOGIC (ALUOP[4] = 1)</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="77PT" align="left" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="70PT" align="left" /><tbody valign="top"><row><entry /><entry>OPERATION</entry><entry>ALUOP[3:0]</entry><entry><ALUop> Name</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>AND</entry><entry>0b1000</entry><entry>AND</entry></row><row><entry /><entry>OR</entry><entry>0b1110</entry><entry>OR</entry></row><row><entry /><entry>XOR</entry><entry>0b0110</entry><entry>XOR</entry></row><row><entry /><entry>NAND</entry><entry>0b0111</entry><entry>NAND</entry></row><row><entry /><entry>NOR</entry><entry>0b0001</entry><entry>NOR</entry></row><row><entry /><entry>XNOR</entry><entry>0b1001</entry><entry>XNOR</entry></row><row><entry /><entry>INVERT_A</entry><entry>0b0011</entry><entry>INVA</entry></row><row><entry /><entry>INVERT_B</entry><entry>0b0101</entry><entry>INVB</entry></row><row><entry /><entry>PASS_A</entry><entry>0b1100</entry><entry>PASSA</entry></row><row><entry /><entry>PASS_B</entry><entry>0b1010</entry><entry>PASSB</entry></row><row><entry /><entry>ZERO</entry><entry>0b0000</entry><entry>ZERO</entry></row><row><entry /><entry>ONES</entry><entry>0b1111</entry><entry>ONES</entry></row><row><entry /><entry>A_AND_NOT_B</entry><entry>0b0100</entry><entry>AANDNB</entry></row><row><entry /><entry>B_AND_NOT_A</entry><entry>0b0010</entry><entry>BANDNA</entry></row><row><entry /><entry>B_OR_NOT_A</entry><entry>0b1011</entry><entry>BORNA</entry></row><row><entry /><entry>A_OR_NOT_B</entry><entry>0b1101</entry><entry>AORNB</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0372BITOP's and 32-bit Logic operations use the two operand bits as selects into a MUX which select among 4 bits provided in the instruction. The encoding for logic operations uses the value of each pair of operand bits {A,B} to select which bit of ALUOP[<b>3</b>:<b>0</b>] provides the result. When the logic operation is performed on bit operands from RESVEC the bits {bsrcb, bsrca} provide the same selection of bits from the BITOP field (that is, for bitopab we use {b<b>1</b>,b<b>0</b>} and for bitopac we use {b<b>2</b>,b<b>0</b>} as operands: <tables id="TABLE-US-00022" num="22"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="5"><colspec colname="1" colwidth="161PT" align="left" /><colspec colname="2" colwidth="42PT" align="center" /><colspec colname="3" colwidth="42PT" align="center" /><colspec colname="4" colwidth="42PT" align="center" /><colspec colname="5" colwidth="42PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="5" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>Operand {b1, b0} or {b2, b0} (or bits of {opA, opB})</entry><entry>{1, 1}</entry><entry>{1, 0}</entry><entry>{0, 1}</entry><entry>{0, 0}</entry></row><row><entry>BITOP (or ALUOP) bit selected as the result</entry><entry>BITOPAx[3]</entry><entry>BITOPAx[2]</entry><entry>BITOPAx[1]</entry><entry>BITOPAx[0]</entry></row><row><entry namest="1" nameend="5" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> 4. Condition Code Selects

0373Each of these values can be tested true or inverted based on bit “F” in the instruction. <tables id="TABLE-US-00023" num="23"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="336PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 21</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Condition Code MUX values</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="63PT" align="left" /><colspec colname="3" colwidth="238PT" align="left" /><tbody valign="top"><row><entry>CC_SEL</entry><entry>Bit</entry><entry>Notes</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>0b00000</entry><entry>TRUE</entry><entry>For unconditional branch</entry></row><row><entry>0b00001</entry><entry>CY</entry><entry>Last saved Carry (or a bypass of it if the preceeding instruction had CC_WE</entry></row><row><entry /><entry /><entry>set)</entry></row><row><entry>0b00010</entry><entry>Z</entry><entry>Last saved Zero (or a bypass of it)</entry></row><row><entry>0b00011</entry><entry>N</entry><entry>Sign bit of last result (or a bypass of it)</entry></row><row><entry>0b00100</entry><entry>V</entry><entry>Signed overflow (CY{circumflex over ( )}N) of last result (or a bypass of it)</entry></row><row><entry>0b00101</entry><entry>GT</entry><entry>CY &amp;&amp; Z (unsigned Greater Than)</entry></row><row><entry>0b00110</entry><entry>LT</entry><entry>CY (unsigned Less Than)</entry></row><row><entry>0b00111</entry><entry>GE</entry><entry>CY || Z (unsigned Greater Than or Equal)</entry></row><row><entry>0b01000</entry><entry>LE</entry><entry>CY || Z (unsigned Less Than or Equal)</entry></row><row><entry>0b01001</entry><entry>SZ</entry><entry>STICKY_Z, set via a SPECOP. Each time CC_Z is written, this bit will clear if</entry></row><row><entry /><entry /><entry>CC_Z_I is ‘0’, otherwise it holds its previous value.</entry></row><row><entry>0b01010</entry><entry>RX_RING</entry><entry>RX Ring has at least one buffer for this CE</entry></row><row><entry>0b01011</entry><entry>RECLASS_RING</entry><entry>Reclassify Ring has at least one buffer for this CE</entry></row><row><entry>0b01100</entry><entry>PEND_RD_WAIT</entry><entry>There is a read pending for which some data has not yet arrived in DFIFO_R</entry></row><row><entry>0b01101</entry><entry>PEND_WR</entry><entry>DFIFO_W has at least one word in it</entry></row><row><entry>0b01110</entry><entry>PEND_ADDR</entry><entry>MEM_ADDR has at least one address in it</entry></row><row><entry>0b01111</entry><entry>RES_BIT</entry><entry>Selected bit of Result Vector (using bit2 (port C))</entry></row><row><entry>0b10000</entry><entry>MSG_IN_A</entry><entry>These are the message bits from the PP or AP to the microcode indicating that</entry></row><row><entry>0b10001</entry><entry>MSG_IN_B</entry><entry>an action is to be taken (CTRL fill, hash insert or delete, etc). These are</entry></row><row><entry>0b10010</entry><entry>MSG_IN_C</entry><entry>assigned by software convention. Note that when a BRANCH_cc is made on</entry></row><row><entry>0b10011</entry><entry>MSG_IN_D</entry><entry>any of these bits the associated CCREG bit will clear when the branch is taken.</entry></row><row><entry>0b10100</entry><entry>SGT</entry><entry>Z &amp;&amp; N (Signed greater-than)</entry></row><row><entry>0b10101</entry><entry>SLT</entry><entry>Z &amp;&amp; N (Signed less-than)</entry></row><row><entry>0b10110</entry><entry>SGE</entry><entry>Z || N (Signed greater-than-or-equal)</entry></row><row><entry>0b10111</entry><entry>SLE</entry><entry>Z || N (Signed less-than-or-equal)</entry></row><row><entry>0b11000</entry><entry>PEND_RD_DATA</entry><entry>At least one word is available in DFIFO_R</entry></row><row><entry>0b11001</entry><entry>MTCH_AORB</entry><entry>Any A- or B-side operand matched during a cmprn instruction</entry></row><row><entry>0b11010</entry><entry>MTCH_A</entry><entry>Any A-side operand matched during a cmprn instruction</entry></row><row><entry>0b11011</entry><entry>MTCH_B</entry><entry>Any B-side operand matched during a cmprn instruction</entry></row><row><entry>0b11100</entry><entry>MTCH_AANDB</entry><entry>Any 64-bit A-B pair operand matched during a cmprn instruction</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> 5. Special Operation Fields

0374These bits are enabled by SPECOP_EN. <tables id="TABLE-US-00024" num="24"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="350PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 22</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>SPECOP bit assignments</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="28PT" align="center" /><colspec colname="2" colwidth="70PT" align="left" /><colspec colname="3" colwidth="252PT" align="left" /><tbody valign="top"><row><entry>Bit</entry><entry>Name</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>[0]</entry><entry>unlock_pcnt</entry><entry>Puts PCNT counter back into normal immediate-P-index mode</entry></row><row><entry>[1]</entry><entry>unlock_resvec_index</entry><entry>Puts RESVEC index counter back into normal immediate mode</entry></row><row><entry>[2]</entry><entry>inc_rx_index</entry><entry>Increments CE_CONS pointer in this CE's RX ring</entry></row><row><entry>[3]</entry><entry>inc_reclassify_index</entry><entry>Increments CE_CONS pointer in this CE's RECLASS ring</entry></row><row><entry>[4]</entry><entry>clear_hit</entry><entry>Clears CCREG[MTCH_A, MTCH_B, MTCH_AORB, MTCH_AANDB]</entry></row><row><entry>[5]</entry><entry>clear_duration</entry><entry>Sets the DURATION counter to 0x0</entry></row><row><entry>[6]</entry><entry>reset_gpreg</entry><entry>Flash clear of GPREG[7:0]</entry></row><row><entry>[7]</entry><entry>reset_resvec0</entry><entry>Flash clear of RESVEC[31:0]. Allows preservation of up to 32 global bit variables</entry></row><row><entry /><entry /><entry>while clearing the rest</entry></row><row><entry>[8]</entry><entry>reset_resvec_15_1</entry><entry>Flash clear of RESVEC[511:32]</entry></row><row><entry>[9]</entry><entry>setsz</entry><entry>Sets CC_REG[SZ] to ‘1’ to start a chained-equality compare</entry></row><row><entry>[10] </entry><entry>do_cmem_fill</entry><entry>Triggers a CMEM fill sequence</entry></row><row><entry>[11] </entry><entry>halt</entry><entry>Sets CSR[HALT] and freezes the CE pipeline</entry></row><row><entry>[15:12]</entry><entry>set_msg[3:0]</entry><entry>Each bit sets one of the 4 MSG_OUT bits in CE_CSR</entry></row><row><entry>[24]</entry><entry>ld_ncnt</entry><entry>loads N-counter for CMPRN instruction</entry></row><row><entry>[25]</entry><entry>ld_bdst_cnt</entry><entry>loads BDST counter, sets RESVEC sequential mode (for CMPRN &amp; resvec spills)</entry></row><row><entry>[26]</entry><entry>bdst_cnt_mode</entry><entry>‘0’ = count-by-2 for CMPRN, ‘1’ = count-by-32 for resvec spill</entry></row><row><entry>[27]</entry><entry>ld_pcnt</entry><entry>Writes either PINDEX[10:2] or REGB[10:2] into PCNT and sets PCNT</entry></row><row><entry /><entry /><entry>autoincrement mode per PCNT_INC</entry></row><row><entry>[28]</entry><entry>pcnt_reg</entry><entry>With ld_pcnt, ‘0’ = load with immediate, ‘1’ = load from gpreg on B-side</entry></row><row><entry>[29]</entry><entry>pcnt_inc</entry><entry>With ld_pcnt, ‘1’ = pcnt autoincrements, ‘0’ = no increments</entry></row><row><entry>[30]</entry><entry>sleep</entry><entry>Freezes pipeline, sets CECSR[SLEEP], puts CMEM in power-down mode. Sleep</entry></row><row><entry /><entry /><entry>mode persists until any of CECSR[RX_RING, RECLASS, MSG_IN[D:A]] causes a</entry></row><row><entry /><entry /><entry>wakeup.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> 6. Miscellany <br /> 6.1 Memory Scheduling Rules

0375A memory access is scheduled by writing the address/size/direction to the MEM_ADDR special register. The following rules apply to scheduling of memory accesses; violation of any of these rules will cause the pipeline to HALT with status of the cause of the error in the CE Control and Status Register (CECSR).

03761) There must be at least one intervening instruction between a LD and use of the resulting data if no other read data is outstanding. A load followed by immediate consumption when the outstanding schedule is ‘0’ will result in a deadlock.

03772) A maximum of 16 slots of read data can be scheduled. A slot is a 2-word entry in DFIFO_R. A LD or LD<b>2</b> consumes 1 slot, a LD<b>4</b> consumes 2 slots, and a LD<b>8</b> consumes 4 slots in DFIFO_R. The appropriate number of slots must be available before another {LD, LD<b>2</b>, LD<b>4</b>, LD<b>8</b>} is scheduled.

03783) A maximum of 32 outstanding words of read data can be scheduled; data must be consumed to make room in DFIFO_R before more can be scheduled.

03794) Precisely the correct number of words of write data must be written to DFIFO_W prior to scheduling the store of that size.

00006.2 Register Write-Use Rules

0380GPREG and RESVEC results can safely be accessed in the instruction after the data is written to them.

0381PCNT, WCNT, and NCNT are all loaded via use of a specop. They can safely be used immediately in the next instruction.

0382The specop unlock_pcnt takes effect immediately, so PMEM immediate index can safely be used in the next instruction. Likewise, specop unlock_resvec_index takes effect immediately, and random access to RESVEC can be used in the next instruction.

0383BASE_REG has a one-cycle write-use delay rule; if it is written to in instruction A, it cannot be used as a source operand in instruction A+1.

0384PMEM has a one cycle write-use delay rule for any particular address. If address addr is written to in instruction A, then addr may not be read in instruction A+1; however it is perfectly safe to read any other location in PMEM in cycle A+1.

0385Data written to special register NULL may not be read back because, well, it's gone, man.

00006.3 PMEM Addressing

0386Packet Memory PMEM can be addressed by an immediate index provided in the microword, indirectly from the PCNT register, or indirectly with auto-increment of PCNT. Immediate indexing is the standard mode; use of PCNT is initiated with the Id_pcnt special operation, which also carries the mode bit pcnt_inc that can optionally be asserted. This special operation sets the state bits USE_PCNT and (optionally) PCNT_INC_MODE. USE_PCNT is cleared by the special operation unlock_pcnt.

0387PCNT can be loaded from an immediate value PINDEX provided in the ld_pcnt special operation, or from bits [<b>10</b>:<b>2</b>] of any GPREG specified in RSRCB if the specop bit pcnt_reg is set during the Id_pcnt.

00006.4 Microstack

0388The microstack is written and the stack pointer is incremented every time a conditional CALL instruction succeeds. It is read and the stack pointer is decremented every time a conditional RET instruction succeeds. The address written is the address of the instruction following the delay slot of the call, since the delay slot is always executed. The microstack holds up to 8 entries. Calling to a depth greater than 8, or returning past the valid number of entries, causes a halt with a report of STACK_ERROR in the CECSR.

VI. Programming Model

0389This section describes the programming model and set of abstractions employed when creating an application for the NetBoost platform (i.e., the platform described in this patent application). An application on the NetBoost platform is to be considered a service, provided within the network, that may require direct knowledge or manipulation of network packets or frames. The programming model provides for direct access to low-level frame data, plus a set of library functions capable of reassembling low-level frame data into higher-layer messages or packets. In addition, the library contains functions capable of performing protocol operations on network or transport-layer messages.

0390An application developed for the NetBoost platform receives link-layer frames from an attached network interface, matches the frames against some set of selection criteria, and determines their disposition. Frame processing takes place as a sequence of serialized processing steps. Each step includes a classification and action phase. During the classification phase, frame data is compared against application-specified matching criteria called rules. When a rule's matching criteria evaluates true, its action portion specifies the disposition of the frame. Execution of the action portion constitutes the action Phase. Only the actions of rules with true matching criteria are executed.

0391Implementing an application for the NetBoost platform involves partitioning the application into two modules. Modules are a grouping of application code destined to execute in a particular portion of the NetBoost platform. There are two modules required: the application processor (AP) module, and the policy engine (PE) module. Application code in the AP module runs on the host processor, and is most appropriate for processing not requiring wire-speed access to network frames. Application code for the PE module comprises the set of classification rules written in the NetBoost Classification Language (NCL), and an accompanying set of compiled actions (C or C++ functions/objects). PE actions are able to manipulate network frames with minimal overhead, and are thus the appropriate mechanism for implementing fast and simple manipulation of frame data. The execution environment for PE action code is more restricted than that of AP code (no virtual memory or threads), but includes a library providing efficient implementation for common frame manipulation tasks (see Section VIII). A message passing facility allows for communication between PE action code and the AP module.

00001. Application Structure

0392<figref idref="DRAWINGS">FIG. 15</figref> illustrates the NetBoost application structure.

0393Applications <b>1402</b> written for the NetBoost platform must be partitioned into the following modules and sub-modules, as illustrated in <figref idref="DRAWINGS">FIG. 15</figref>. <ul id="ul0008" list-style="none"><li id="ul0008-0001" num="0000"><ul id="ul0009" list-style="none"><li id="ul0009-0001" num="0394"> AP Module (—application processor (host) module) <b>1406</b></li><li id="ul0009-0002" num="0395"> PE Module (—policy engine module) <b>1408</b></li><li id="ul0009-0003" num="0396"> Classification rules—specified in NCL </li><li id="ul0009-0004" num="0397"> Action implementation—object code provided by app developer </li></ul></li></ul>

0398The AP module <b>1406</b> executes in the programming environment of a standard operating system and has access to all PEs <b>1408</b> available on the system, plus the conventional APIs implemented in the host operating system. Thus, the AP module <b>1406</b> has the capability of performing both frame-level processing (in conjunction with the PE), or traditional network processing using a standard API.

0399The PE <b>1408</b> module is subdivided into a set of classification rules and actions. Classification rules are specified in the NetBoost Classification Language (NCL) and are compiled on-the-fly by a fast incremental compiler provided by NetBoost. Actions are implemented as relocatable object code provided by the application developer. A dynamic linker/loader included with the NetBoost platform is capable of linking and loading the classification rules with the action implementations and loading these either into the host (software implementation) or hardware PE (hardware implementation) for execution.

0400The specific division of functionality between AP and PE modules <b>1406</b> and <b>1408</b> in an application is left entirely up to the application designer. Preferably, the AP module <b>1406</b> should be used to implement initialization and control, user interaction, exception handling, and infrequent processing of frames requiring special attention. The PE module <b>1408</b> preferably should implement simple processing on frames (possibly including the reconstruction of higher-layer messages) requiring extremely fast execution. PE action code runs in a run-to-completion real-time environment without memory protection, similar to an interrupt handler in most conventional operating systems. Thus, functions requiring lengthy processing times should be avoided, or executed in the AP module <b>1406</b>. In addition, other functions may be loaded into the PE to support actions, asynchronous execution, timing, or other processing (such as upcalls/downcalls, below). All code loaded into the PE has access to the PE runtime environment, provided by the ASL.

0401The upcall/downcall facility provides for communication between PE actions and AP functions. An application may use upcalls/downcalls for sharing information or signaling between the two modules. The programmer may use the facility to pass memory blocks, frame contents, or other messages constructed by applications in a manner similar to asynchronous remote procedure calls.

00002. Basic Building Blocks

0402This section describes the C++ classes needed to develop an application for the NetBoost platform. Two fundamental classes are used to abstract the classification and handling of network frames: <ul id="ul0010" list-style="none"><li id="ul0010-0001" num="0000"><ul id="ul0011" list-style="none"><li id="ul0011-0001" num="0403"> ACE, representing classification and action steps </li><li id="ul0011-0002" num="0404"> Target, representing possible frame destinations <br /> 2.1 ACEs </li></ul></li></ul>

0405The ACE class (short for Action-Classification-Engine) abstracts a set of frame classification criteria and associated actions, upcall/downcall entrypoints, and targets. They are simplex: frame processing is uni-directional. An application may make use of cascaded ACEs to achieve serialization of frame processing. ACEs are local to an application.

0406ACEs provide an abstraction of the execution of classification rules, plus a container for holding the rules and actions. ACEs are instantiated on particular hardware resources either by direct control of the application or by the plumber application.

0407An ACE <b>1500</b> is illustrated in <figref idref="DRAWINGS">FIG. 16</figref>:

0408The ACE is the abstraction of frame classification rules <b>1506</b> and associated actions <b>1508</b>, destinations for processed frames, and downcall/upcall entrypoints. An application may employ several ACEs, which are executed in a serial fashion, possibly on different hardware processors.

0409<figref idref="DRAWINGS">FIG. 16</figref> illustrates an ACE with two targets <b>1502</b> and <b>1504</b>. The targets represent possible destinations for frames and are described in the following section.

0410Frames arrive at an ACE from either a network interface or from an ACE. The ACE classifies the frame according its rules. A rule is a combination of a predicate and action. A rule is said to be “true” or to “evaluate true” or to be a “matching rule” if its predicate portion evaluates true in the Boolean sense for the current frame being processed. The action portion of each matching rule indicates what processing should take place.

0411The application programmer specifies rule predicates within an ACE using Boolean operators, packet header fields, constants, set membership queries, and other operations defined in the NetBoost Classification Language (NCL), a declarative language described in Section VII. A set of rules (an NCL program) may be loaded or unloaded from an ACE dynamically under application control. In certain embodiments, the application developer implements actions in a conventional high level language. Special external declaration statements in NCL indicate the names of actions supplied by the application developer to be called as the action portion for matching rules.

0412Actions are function entry-points implemented according to the calling conventions of the C programming language (static member functions in C++ classes are also supported). The execution environment for actions includes a C and C++ runtime environment with restricted standard libraries appropriate to the PE execution environment. In addition to the C environment, the ASL library provides added functionality for developing network applications. The ASL provides support for handling many TCP/IP functions such as IP fragmentation and re-assembly, Network Address Translation (NAT), and TCP connection monitoring (including stream reconstruction). The ASL also provides support for encryption and basic system services (e.g. timers, memory management).

0413During classification, rules are evaluated first-to-last. When a matching rule is encountered, its action executes and returns a value indicating whether it disposed of the frame. Disposing of a frame corresponds to taking the final desired action on the frame for a single classification step (e.g. dropping it, queueing it, or delivering it to a target). If an action executes but does not dispose of the current frame, it returns a code indicating the frame should undergo further rule evaluations in the current classification step. If any action disposes of the frame, the classification phase terminates. If all rules are evaluated without a disposing action, the frame is delivered to the default target of the ACE.

00002.2 Targets

0414Targets specify possible destinations for frames (an ACE or network interface). A target is said to be bound to either an ACE or network interface (in the outgoing direction), otherwise it is unbound. Frames delivered to unbound targets are dropped. Target bindings are manipulated by a plumbing application in accordance with the present invention.

0415<figref idref="DRAWINGS">FIG. 17</figref> shows a cascade of ACEs. ACEs use targets as frame destinations. Targets <b>1</b> and <b>2</b> (illustrated at <b>1602</b> and <b>1604</b>) are bound to ACEs <b>1</b> and <b>2</b> (illustrated at <b>1610</b> and <b>1612</b>), respectively. Target <b>3</b> (at <b>1606</b>) is bound to a network interface (<b>1620</b>) in the outgoing direction. Processing occurs serially from left to right. Ovals indicate ACEs, hexagons indicate network interfaces. Outgoing arcs indicate bound targets. An ACE with multiple outgoing arcs indicates an ACE that performs a demultiplexing function: the set of outgoing arcs represent the set off all frame destinations in the ACE, across all actions. In this example, each ACE has a single destination (the default target). When several hardware resources are available for executing ACEs (e.g. in the case of the NetBoost hardware platform), ACEs may execute more efficiently (using pipelining). Note, however, that when one ACE has finished processing a frame, it is given to another ACE that may execute on the same hardware resource.

00003. Complex Configurations

0416As described above, a single application may employ more than one ACE. Generally, processing bidirectional network data will require a minimum of two ACEs. Four ACEs may be a common configuration for a system providing two network interfaces and an application wishing to install ACEs at the input and output for each interface (e.g. in the NetBoost hardware environment with one PE).

0417<figref idref="DRAWINGS">FIG. 18</figref> illustrates an application employing six ACEs <b>1802</b>, <b>1804</b>, <b>1806</b>, <b>1808</b>, <b>1810</b> and <b>1812</b>. Shaded circles represent targets. Two directions of processing are depicted, as well as an ACE with more than one output arc and an ACE with more than one input arc. The arcs represent possible destinations for frames.

0418An ACE depicted with more than one outgoing arc may represent the processing of a single frame, or in certain circumstances, the replication (copying) of a frame to be sent to more than one downstream ACE simultaneously. Frame replication is used in implementing broadcast and multicast forwarding (e.g. in layer <b>2</b> bridging and IP multicast forwarding). The interconnection of targets to downstream objects is typically performed by the plumber application described in the next section.

00004. Software Architecture

0419This section describes the major components comprising the NetBoost software implementation. The software architecture provides for the execution of several applications performing frame-layer processing of network data, and includes user-level, kernel-level, and embedded processor-level components (for the hardware platform). The software architecture is illustrated <figref idref="DRAWINGS">FIG. 19</figref>.

0420The layers of software comprising the overall architecture are described bottom-up. The first layer is the NetBoost Policy Engine <b>2000</b> (PE). Each host system may be equipped with one or more PEs. In systems equipped with NetBoost hardware PEs, each PE will be equipped with several frame classifiers and a processor responsible for executing action code. For systems lacking the hardware PE, all PE functionality is implemented in software. The PE includes a set of C++ library functions comprising the Action Services Library (ASL) which may be used by action code in ACE rules to perform messaging, timer-driven event dispatch, network packet reassembly or other processing.

0421The PE interacts with the host system via a device driver <b>2010</b> and ASL <b>2012</b> supplied by NetBoost. The device driver is responsible for supporting maintenance operations to NetBoost PE cards. In addition, this driver is responsible for making the network interfaces supplied on NetBoost PE cards available to the host system as standard network interfaces. Also, specialized kernel code is inserted into the host's protocol stack to intercept frames prior to receipt by the host protocol stack (incoming) or transmission by conventional network interface cards (outgoing).

0422The Resolver <b>2008</b> is a user-level process started at boot time responsible for managing the status of all applications using the NetBoost facilities. In addition, it includes the NCL compiler and PE linker/loader. The process responds to requests from applications to set up ACEs, bind targets, and perform other maintenance operations on the NetBoost hardware or software-emulated PE.

0423The Application Library <b>2002</b> (having application <b>1</b>, <b>2</b> &amp; <b>3</b> shown at <b>2020</b>, <b>2040</b>, <b>2042</b>) is a set of C++ classes providing the API to the NetBoost system. It allows for the creation and configuration of ACEs, binding of targets, passing of messages to/from the PE, and the maintenance of the name-to-object bindings for objects which exist in both the AP and PE modules.

0424The plumber <b>2014</b> is a management application used to set up or modify the bindings of every ACE in the system (across all applications). It provides a network administrator the ability to specify the serial order of frame processing by binding ACE targets to subsequent ACEs. The plumber is built using a client/server architecture, allowing for both local and remote access to specify configuration control. All remote access is authenticated and encrypted.

VII. Classification Language

0425The NetBoost Classification Language (NCL) is a declarative high level language for defining packet filters. The language has six primary constructs: protocol definitions, predicates, sets, set searches, rules and external actions. Protocol definitions are organized in an object-oriented fashion and describe the position of protocol header fields in packets. Predicates are Boolean functions on protocol header fields and other predicates. Rules consist of a predicate/action pair having a predicate portion and an action portion where an action is invoked if its corresponding predicate is true. Actions refer to procedure entrypoints implemented external to the language.

0426Individual packets are classified according to the predicate portions of the NCL rules. More than one rule may be true for any single packet classification. The action portion of rules with true predicates are invoked in the order the rules have been specified. Any of these actions invoked may indicate that no further actions are to be invoked. NCL provides a number of operators to access packet fields and execute comparisons of those fields. In addition, it provides a set abstraction, which can be used to determine containment relationships between packets and groups of defined objects (e.g. determining if a particular packet belongs to some TCP/IP flow or set of flows), providing the ability to keep persistent state in the classification process between packets.

0427Standard arithmetic, logical and bit-wise operators are supported and follow their equivalents in the C programming language. These operators provide operations on the fields of the protocols headers and result in scalar or Boolean values. An include directive allows for splitting NCL programs into several files.

00001. Names and Data Types

0428The following definitions in NCL constants have names: protocols, predicates, fields, sets, searches on sets, and rules (defined later subsequent sections). A name is formed using any combination of alphanumeric characters and underscores except the first character must be an alphabetic character. Names are case sensitive. For example, <tables id="TABLE-US-00025" num="25"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="84PT" align="left" /><colspec colname="1" colwidth="133PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>set_tcp_udp</entry></row><row><entry /><entry>IsIP</entry></row><row><entry /><entry>isIPv6</entry></row><row><entry /><entry>set_udp_ports</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0429The above examples are all legal names. The following examples are all illegal names: <tables id="TABLE-US-00026" num="26"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="84PT" align="left" /><colspec colname="1" colwidth="133PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>6_byte_ip</entry></row><row><entry /><entry>set_tcp+udp</entry></row><row><entry /><entry>ip_src&amp;dst</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> The first is illegal because it starts with a numeric character; the other two are illegal because they contain operators.

0430Protocol fields (see Section 6) are declared in byte-oriented units, and used in constructing protocols definitions. All values are big-endian. Fields specify the location and size of portions of a packet header. All offsets are relative to a particular protocol. In this way it is possible to specify a particular header field without knowing the absolute offset of the any particular protocol header. Mask and shift operations support the accessing of non-byte-sized header fields. For example, <tables id="TABLE-US-00027" num="27"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="56PT" align="left" /><colspec colname="1" colwidth="161PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>dst  { ip[16:4] }</entry></row><row><entry /><entry>ver  { (ip[0:1] & 0xf0) >> 4 }</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> In the first line, the 4-byte field dst is specified as being at byte offset 16 from the beginning of the IP protocol header. In the second example, the field ver is a half-byte sized field at the beginning of the IP header. <br /> 2. Operators

0431Arithmetic, logical and bit-wise binary operators are supported. Table 23 lists the arithmetic operators and grouping operator supported: <tables id="TABLE-US-00028" num="28"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 23</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Arithmetic operators</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="119PT" align="center" /><colspec colname="2" colwidth="98PT" align="left" /><tbody valign="top"><row><entry>Operator</entry><entry>Description</entry></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row><row><entry>( )</entry><entry>Grouping operator</entry></row><row><entry>+</entry><entry>Addition</entry></row><row><entry>−</entry><entry>Subtraction</entry></row><row><entry><<</entry><entry>Logical left shift</entry></row><row><entry>>></entry><entry>Logical right shift</entry></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> The arithmetic operators result in scalar quantities, which are typically used for comparison. These operators may be used in field and predicate definitions. The shift operations do not support arithmetic shifts. The shift amount is a compile time constant. Multiplication, division and modulo operators are not supported. The addition and subtraction operations are not supported for fields greater than 4 bytes.

0432Logical operators are supported that result in Boolean values. Table 24 provides the logical operators that are supported by the language. <tables id="TABLE-US-00029" num="29"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 24</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Logical operators</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="105PT" align="center" /><colspec colname="2" colwidth="112PT" align="left" /><tbody valign="top"><row><entry>Operator</entry><entry>Description</entry></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row><row><entry>&&</entry><entry>Logical AND</entry></row><row><entry>||</entry><entry>Logical OR</entry></row><row><entry>!</entry><entry>Not</entry></row><row><entry>></entry><entry>Greater Than</entry></row><row><entry>>=</entry><entry>Greater Than or Equal To</entry></row><row><entry><</entry><entry>Less Than</entry></row><row><entry><=</entry><entry>Less Than or Equal To</entry></row><row><entry>==</entry><entry>Equal To</entry></row><row><entry>!=</entry><entry>Not Equal</entry></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0433Bit-wise operators are provided for masking and setting of bits. The operators supported are as follows: <tables id="TABLE-US-00030" num="30"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 25</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Bit-wise operators</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="105PT" align="center" /><colspec colname="2" colwidth="112PT" align="left" /><tbody valign="top"><row><entry>Operators</entry><entry>Description</entry></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row><row><entry>&amp;</entry><entry>Bit-wise AND</entry></row><row><entry>|</entry><entry>Bit-wise OR</entry></row><row><entry>{circumflex over ( )}</entry><entry>Bit-wise Exclusive OR</entry></row><row><entry>˜</entry><entry>Bit-wise One's Compliment</entry></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0434The precedence and the associativity of all the operators listed above are shown in Table 26. The precedence is listed in decreasing order. <tables id="TABLE-US-00031" num="31"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 26</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Operator precedence</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="98PT" align="center" /><colspec colname="2" colwidth="35PT" align="center" /><colspec colname="3" colwidth="84PT" align="center" /><tbody valign="top"><row><entry>Precedence</entry><entry>Operators</entry><entry>Associativity</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>High</entry><entry>( ) [ ]</entry><entry>Left to right</entry></row><row><entry>.</entry><entry>! ˜</entry><entry>Right to left</entry></row><row><entry>.</entry><entry>+ −</entry><entry>Left to right</entry></row><row><entry>.</entry><entry><< >></entry><entry>Left to right</entry></row><row><entry>.</entry><entry>< <= > >=</entry><entry>Left to right</entry></row><row><entry>.</entry><entry>== !=</entry><entry>Left to right</entry></row><row><entry>.</entry><entry>&</entry><entry>Left to right</entry></row><row><entry>.</entry><entry>{circumflex over ( )}</entry><entry>Left to right</entry></row><row><entry>.</entry><entry>|</entry><entry>Left to right</entry></row><row><entry>.</entry><entry>&&</entry><entry>Left to right</entry></row><row><entry>Low</entry><entry>||</entry><entry>Left to right</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> 3. Field Formats

0435The language supports several standard formats, and also domain specific formats, for constants, including the dotted-quad form for IP version 4 addresses and colon-separated hexadecimal for Ethernet and IP version 6 addresses, in addition to conventional decimal and hexadecimal constants. Standard hexadecimal constants are defined as they are in the C language, with a leading 0x prefix.

0436For data smaller than 4 bytes in length, unsigned extension to 4 bytes is performed automatically. A few examples are as shown below: <tables id="TABLE-US-00032" num="32"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 27</entry></row><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Constant formats</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="OFFSET" colwidth="21PT" align="left" /><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="126PT" align="left" /><tbody valign="top"><row><entry /><entry>0x11223344</entry><entry>Hexadecimal form</entry></row><row><entry /><entry>101.230.135.45</entry><entry>Dot separated IP address form</entry></row><row><entry /><entry>ff:12:34:56:78:9a</entry><entry>Colon separated MAC address form</entry></row><row><entry /><entry namest="OFFSET" nameend="2" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> 4. Comments

0437C and C++ style comments are supported. One syntax supports multiple lines, the other supports comments terminating with a newline. The syntax for the first form follows the C language comment syntax using /* and */ to demark the start and end of a comment, respectively. The syntax for the second form follows the C++ comment syntax, using // to indicate the start of the comment. Such comments end at the end of the line. Nesting of comments is not allowed in the case of the first form. In the second case, everything is discarded to the end of the line, so nesting of the second form is allowed. Comments can occur anywhere in the program. A few examples of comments are shown below, <tables id="TABLE-US-00033" num="33"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 1: Legal comments</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="left" /><tbody valign="top"><row><entry>/* Comment in a single line */</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="189PT" align="left" /><tbody valign="top"><row><entry /><entry>// Second form of the comment: compiler ignores to end-of-line</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="left" /><tbody valign="top"><row><entry>/* Comments across multiple line</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="203PT" align="left" /><tbody valign="top"><row><entry /><entry>second line</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="left" /><tbody valign="top"><row><entry>third line */</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="42PT" align="left" /><colspec colname="1" colwidth="175PT" align="left" /><tbody valign="top"><row><entry /><entry>// Legal comment // still ignored to end-of-line</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="left" /><tbody valign="top"><row><entry>/*   First form   //Second form, but OK</entry></row><row><entry>*/</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0438The examples above are all legal. The examples shown in Diagram 11 (below) are illegal. <tables id="TABLE-US-00034" num="34"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 2: Illegal comments</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="49PT" align="left" /><colspec colname="1" colwidth="168PT" align="left" /><tbody valign="top"><row><entry /><entry>/ *     space */</entry></row><row><entry /><entry>/     new-line</entry></row><row><entry /><entry>* Testing */</entry></row><row><entry /><entry>/*   Nesting  /*  Second level */</entry></row><row><entry /><entry>*/</entry></row><row><entry /><entry>/ /  space</entry></row><row><entry /><entry>/   new-line</entry></row><row><entry /><entry>/</entry></row><row><entry /><entry>//   /* Nesting</entry></row><row><entry /><entry>*/</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> The first comment is illegal because of the space between / and *, and the second one because of the new-line. The third is illegal because of nesting. The fourth is illegal because of the space between the ‘/’ chars ant the next one because of the new-line. The last one is illegal because the /* is ignored, causing the */ to be in error of nesting of the first form of the comment in the second form. <br /> 5. Constant Definitions and Include Directives

0439The language provides user-definable symbolic constants. The syntax for the definition is the keyword #define, then the name followed by the constant. No spaces are allowed between # and define. The constant can be in any of the forms described in the next subsection of this patent application. The definition can start at the beginning of a line or any other location on a line as long as the preceding characters are either spaces or tabs. For example, <tables id="TABLE-US-00035" num="35"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 3: Sample of constant definition usage</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="119PT" align="left" /><colspec colname="2" colwidth="98PT" align="left" /><tbody valign="top"><row><entry>#define   TELNET_PORT_NUM</entry><entry>23  // Port number for telnet</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="105PT" align="left" /><colspec colname="2" colwidth="98PT" align="left" /><tbody valign="top"><row><entry /><entry>#define   IP_ADDR</entry><entry>10.4.7.18</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="119PT" align="left" /><colspec colname="2" colwidth="98PT" align="left" /><tbody valign="top"><row><entry>#define    MAC_ADDR</entry><entry>cd.ee.f0.34.74.93</entry></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0440The language provides the ability to include files within the compilation unit so that pre-existing code can be reused. The keyword #include is used, followed by the filename enclosed in double quotes. The # must start on a new-line, but may have spaces immediately preceding the keyword. No space are allowed between # and the include. The filename is any legal filename supported by the host. For example, <tables id="TABLE-US-00036" num="36"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 4: Sample include directives</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="112PT" align="left" /><colspec colname="2" colwidth="105PT" align="left" /><tbody valign="top"><row><entry>#include  “myproto.def”</entry><entry>// Could be protocol definitions</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="98PT" align="left" /><colspec colname="2" colwidth="105PT" align="left" /><tbody valign="top"><row><entry /><entry>#include  “stdrules.rul”</entry><entry>// Some standard rules</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="112PT" align="left" /><colspec colname="2" colwidth="105PT" align="left" /><tbody valign="top"><row><entry>#include    “newproto.def”</entry><entry>/* New protocol definitions */</entry></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> 6. Protocol Definitions

0441NCL provides a convenient method for describing the relationship between multiple protocols and the header fields they contain. A protocol defines fields within a protocol header, intrinsics (built-in functions helpful in processing headers and fields), predicates (Boolean functions on fields and other predicates), and the demultiplexing method to high-layer protocols. The keyword protocol identifies a protocol definition and its name. The name may later be referenced as a Boolean value which evaluates true if the protocol is activated (see 6.2). The declarations for fields, intrinsics and demultiplexing are contained in a protocol definition as illustrated below.

00006.1 Fields

0442Fields within the protocol are declared by specifying a field name followed by the offset and field length in bytes. Offsets are always defined relative to a protocol. The base offset is specified by the protocol name, followed by colon separated offset and size enclosed in square brackets. This syntax is as shown below: <tables id="TABLE-US-00037" num="37"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="49PT" align="left" /><colspec colname="1" colwidth="168PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>field_name( protocol_name[offset:size] )</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0443Fields may be defined using a combination of byte ranges within the protocol header and shift/mask or grouping operations. The field definitions act as access methods to the areas within in the protocol header or payload. For example, fields within a protocol named MyProto might be specified as follows: <tables id="TABLE-US-00038" num="38"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="42PT" align="left" /><colspec colname="1" colwidth="175PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>dest_addr [ MyProto[6:4] ]</entry></row><row><entry /><entry>bit_flags [ (MyProto[10:2] & 0×0ff0) >> 8]</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> In the first example, field dest_addr is declared as a field at offset 6 bytes from the start of the protocol MyProto and 4 bytes in size. In the second example, the field bit_flags is a bit field because it crosses a byte boundary, two bytes are used in conjunction with a mask and right shift operation to get the field value. <br /> 6.2 Intrinsics

0444Intrinsics are functions listed in a protocol statement, but implemented internally. Compiler-provided intrinsics are declared in the protocol definition (for consistency) using the keyword intrinsic followed by the intrinsic name. Intrinsics provide convenient or highly optimized functions that are not easily expressed using the standard language constructs. One such intrinsic is the IP checksum. Intrinsics may be declared within the scope of a protocol definition or outside, as in the following examples: <tables id="TABLE-US-00039" num="39"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 5: Sample intrinsic declarations</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="63PT" align="left" /><colspec colname="1" colwidth="154PT" align="left" /><tbody valign="top"><row><entry /><entry>protocol foo {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="77PT" align="left" /><colspec colname="1" colwidth="140PT" align="left" /><tbody valign="top"><row><entry /><entry>_field defs...</entry></row><row><entry /><entry>intrinsic chksumvalid { }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="63PT" align="left" /><colspec colname="1" colwidth="154PT" align="left" /><tbody valign="top"><row><entry /><entry>}</entry></row><row><entry /><entry>intrinsic now</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> The first example indicates chksumvalid intrinsic is associated with the protocol foo. Thus, the expression foo.chksumvalid could be used in the creation of predicates or expressions defined later. The second example indicates a global intrinsic called now that may be used anywhere within the program. Intrinsics can return Boolean and scalar values.

0445In a protocol definition, predicates are used to define frequently used Boolean results from the fields within the protocol being defined. They are identified by the keyword predicate. Predicates are described in section 7.

00006.3 Demux

0446The keyword demux in each protocol statement indicates how demultiplexing should be performed to higher-layer protocols. In effect, it indicates which subsequent protocol is “activated”, as a function of fields and predicates defined within the current set of activated protocols.

0447Evaluation of the Boolean expressions within a protocol demux statement determines which protocol is activated next. Within a demux statement, the first expression which evaluates to true indicates that the associated protocol is to be activated at a specified offset relative to the first byte of the present protocol. The starting offset of the protocol to be activated is specified using the keyword at. A default protocol may be specified using the keyword default. The first case of the demux to evaluate true indicates which protocol is activated next. All others are ignored. The syntax for the demux is as follows: <tables id="TABLE-US-00040" num="40"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 6: Demux syntax sample</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="35PT" align="left" /><colspec colname="1" colwidth="182PT" align="left" /><tbody valign="top"><row><entry /><entry>demux {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="49PT" align="left" /><colspec colname="1" colwidth="168PT" align="left" /><tbody valign="top"><row><entry /><entry>boolean_exp { protocol_name at offset }</entry></row><row><entry /><entry>default { protocol_name at offset }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="35PT" align="left" /><colspec colname="1" colwidth="182PT" align="left" /><tbody valign="top"><row><entry /><entry>}</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0448Diagram 7 shows an example of the demux declaration. <tables id="TABLE-US-00041" num="41"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 7: Sample protocol demux</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="left" /><tbody valign="top"><row><entry>demux {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="91PT" align="left" /><colspec colname="2" colwidth="112PT" align="left" /><tbody valign="top"><row><entry /><entry>(length == 10</entry><entry>{ proto_a at offset_a }</entry></row><row><entry /><entry>(flags &amp;&amp; predicate_x)</entry><entry>{ proto_b at offset_b }</entry></row><row><entry /><entry>default</entry><entry>{ proto_default at offset_default }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="left" /><tbody valign="top"><row><entry>}</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0449In the above example, protocol proto_a is “activated” at offset offset_a if the expression length equals ten. Protocol proto_b is activated at offset offset_b if flags is true, predicate_x is true and length is not equal to 10. predicate_x is a pre-defined Boolean expression. The default protocol is proto_default, which is defined here so that packets not matching the predefined criteria can be processed. The fields and predicates in a protocol are accessed by specifying the protocol and the field or predicate separated by the dot operator. This hierarchical naming model facilitates easy extension to new protocols. Consider the IP protocol example shown below. <tables id="TABLE-US-00042" num="42"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 8: Protocol Sample: IP</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="left" /><tbody valign="top"><row><entry>protocol ip {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="84PT" align="left" /><colspec colname="2" colwidth="119PT" align="left" /><tbody valign="top"><row><entry /><entry>vers</entry><entry>{ (ip[0:1] & 0×f0) >> 4 }</entry></row><row><entry /><entry>hlenqth</entry><entry>{ ip[0:1] & 0×0f }</entry></row><row><entry /><entry>hlength_b</entry><entry>{ hlength << 2 }</entry></row><row><entry /><entry>tos</entry><entry>{ ip[1:1] }</entry></row><row><entry /><entry>length</entry><entry>{ ip[2:2] }</entry></row><row><entry /><entry>id</entry><entry>{ ip[4:2] }</entry></row><row><entry /><entry>flaqs</entry><entry>{ (ip[6:1] & 0×e0) >> 5 }</entry></row><row><entry /><entry>fragoffset</entry><entry>{ ip[6:2]& 0×1fff }</entry></row><row><entry /><entry>ttl</entry><entry>{ ip[8:1] }</entry></row><row><entry /><entry>proto</entry><entry>{ ip[9:1] }</entry></row><row><entry /><entry>chksum</entry><entry>{ ip[10:2] }</entry></row><row><entry /><entry>src</entry><entry>{ ip[12:4] }</entry></row><row><entry /><entry>dst</entry><entry>{ ip[16:4] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="203PT" align="left" /><tbody valign="top"><row><entry /><entry>intrinsic chksumvalid { }</entry></row><row><entry /><entry>intrinsic genchksum { }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="84PT" align="left" /><colspec colname="2" colwidth="119PT" align="left" /><tbody valign="top"><row><entry /><entry>predicate bcast</entry><entry>{dst == 255.255.255.255 }</entry></row><row><entry /><entry>predicate mcast</entry><entry>{ (dst & 0×f0000000) == 0×e0000000 }</entry></row><row><entry /><entry>predicate frag</entry><entry>{ fragoffset != 0 | (flags & 2) != 0 }</entry></row><row><entry /><entry>demux {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="119PT" align="left" /><tbody valign="top"><row><entry /><entry>( proto == 6 )</entry><entry>{ tcp at hlength_b }</entry></row><row><entry /><entry>( proto == 17 )</entry><entry>{ udp at hlength_b }</entry></row><row><entry /><entry>( proto == 1 )</entry><entry>{ icmp at hlength_b }</entry></row><row><entry /><entry>( proto == 2 )</entry><entry>{ igmp at hlength_b }</entry></row><row><entry /><entry>default</entry><entry>{ unknownIP at hlength_b }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="203PT" align="left" /><tbody valign="top"><row><entry /><entry>}</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="left" /><tbody valign="top"><row><entry>}</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0450Here, ip is the protocol name being defined. The protocol definition includes a number of fields which correspond to portions of the IP header comprising one or more bytes. The fields vers, hlength, flags and fragoffset have special operations that extract certain bits from the IP header. hlength_b holds the length of the header in bytes computed using the hlength field (which is in units of 32-bit words).

0451bcast, mcast, and frag are predicates which may be useful in defining other rules or predicates. Predicates are defined in Section 7.

0452This protocol demuxes into four other protocols, excluding the default, under different conditions. In this example, the demultiplexing key is the protocol type specified by the value of the IP pro to fields All the protocols are activated at offset hlength_b relative to the start of the IP header.

0453When a protocol is activated due to the processing of a lower-layer demux statement, the activated protocol's name becomes a Boolean that evaluates true (it is otherwise false). Thus, if the IP protocol is activated, the expression ip will evaluate to a true Boolean expression. The fields and predicates in a protocol are accessed by specifying the protocol and the field, predicate or intrinsic separated by the dot operator. For example: <tables id="TABLE-US-00043" num="43"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 9: Sample references</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="84PT" align="left" /><colspec colname="1" colwidth="133PT" align="left" /><tbody valign="top"><row><entry /><entry>ip.length</entry></row><row><entry /><entry>ip.bcast</entry></row><row><entry /><entry>ip.chsumvalid</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0454Users can provide additional declarations for new fields, predicates and demux cases by extending previously-defined protocol elements. Any name conflicts will be resolved by using the newest definitions. This allows user-provided definitions to override system-supplied definitions updates and migration. The syntax for extensions is the protocol name followed by the new element separated by the dot (.) operator. Following the name is the definition enclosed in delimiters as illustrated below: <tables id="TABLE-US-00044" num="44"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 10: Sample protocol extension</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="49PT" align="left" /><colspec colname="1" colwidth="168PT" align="left" /><tbody valign="top"><row><entry /><entry>xx.newfield { xx[10:4] }</entry></row><row><entry /><entry>predicate xx.newpred { xx[8:2] !=10 }</entry></row><row><entry /><entry>xx.demux }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="63PT" align="left" /><colspec colname="1" colwidth="154PT" align="left" /><tbody valign="top"><row><entry /><entry>(xx[6:2] == 5 ) } newproto at 20 }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="49PT" align="left" /><colspec colname="1" colwidth="168PT" align="left" /><tbody valign="top"><row><entry /><entry>}</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0455In the first example, a new field called newfield is declared for the protocol xx. In the second, a new predicate called newpred is defined for the protocol xx. In the third example, a new higher-layer protocol newproto is declared as a demultiplexing for the protocol xx. The root of the protocol hierarchy is the reserved protocol frame, which refers to the received data from the link-layer. The redefinition of the protocol frame is not allowed for any protocol definitions, but new protocol demux opertions can be added to it.

0456The intrinsics provided are listed in Table 28: <tables id="TABLE-US-00045" num="45"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry namest="1" nameend="1" align="center">TABLE 28</entry></row></thead><tbody valign="top"><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>List of intrinsics</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="56PT" align="left" /><colspec colname="2" colwidth="161PT" align="left" /><tbody valign="top"><row><entry>Intrinsic Name</entry><entry>Functionality</entry></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row><row><entry>ip.chksumvalid</entry><entry>Check the validity of the ip header checksum, return</entry></row><row><entry /><entry>boolean value</entry></row><row><entry>tcp.chksumvalid</entry><entry>Check the validity of the tcp pseudo checksum, return</entry></row><row><entry /><entry>boolean value</entry></row><row><entry>udp.chksumvalid</entry><entry>Check the validity of udp pseudo checksum, return</entry></row><row><entry /><entry>boolean value</entry></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> 7. Predicates

0457Predicates are named Boolean expressions that use protocol header fields, other Boolean expressions, and previously-defined predicates as operands. The syntax for predicates is as follows: <br />predicate predicate_name{boolean_expression}

0458For example, <tables id="TABLE-US-00046" num="46"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="21PT" align="left" /><colspec colname="1" colwidth="196PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>predicate isTcpSyn { tcp &amp;&amp; (tcp.flags &amp; 0x02) != 0 }</entry></row><row><entry /><entry>predicate isNewTelnet { isTcpSyn &amp;&amp; (tcp.dport == 23) }</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> In the second example, the predicate isTcpSyn is used in the expression to evaluate the predicate isNewTelnet. <br /> 8. Sets

0459The language supports the notion of sets and named searches on sets, which can be used to efficiently check whether a packet should be considered a member of some application-defined equivalence class. Using sets, classification rules requiring persistent state may be constructed. The classification language only supports the evaluation of set membership; modification to the contents of the sets are handled exclusively by actions in conjunction with the ASL. A named search defines a particular search on a set and its name may be used as a Boolean variable in subsequent Boolean expressions. Named searches are used to tie precomputed lookup results calculated in the classification phase to actions executing in the action phase.

0460A set is defined using the keyword set followed by an identifier specifying the name of the set. The number of keys for any search on the set is specified following the name, between < and >. A set definition may optionally include a hint as to the expected number of members of the set, specified using the keyword size_hint. The syntax is as follows: <tables id="TABLE-US-00047" num="47"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 11: Declaring a set</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="49PT" align="left" /><colspec colname="1" colwidth="168PT" align="left" /><tbody valign="top"><row><entry /><entry>set set_name < nkeys > }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="63PT" align="left" /><colspec colname="1" colwidth="154PT" align="left" /><tbody valign="top"><row><entry /><entry>size_hint { expected_population }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="49PT" align="left" /><colspec colname="1" colwidth="168PT" align="left" /><tbody valign="top"><row><entry /><entry>}</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> The size_hint does not place a strict limit on the population of the set, but as the set size grows beyond the hint value, the search time may slowly increase.

0461Predicates and rules may perform named searches (see the following section for a discussion of rules). Named searches are specified using the keyword search followed by the search name and search keys. The search name consists of two parts: the name of the set to search, and the name of the search being defined. The keys may refer to arbitrary expressions, but typically refer to fields in protocols. The number of keys defined in the named search must match the number of keys defined for the set. The named search may be used in subsequent predicates as a Boolean value, where “true” indicates a record is present in the associated set with the specified keys. An optional Boolean expression may be included in a named search using the requires keyword. If the Boolean expression fails to evaluate true, the search result is always “false”. The syntax for named searches is as follows: <tables id="TABLE-US-00048" num="48"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 12: Named search</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="42PT" align="left" /><colspec colname="1" colwidth="175PT" align="left" /><tbody valign="top"><row><entry /><entry>search set_name.search_name (key1, key2) {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="56PT" align="left" /><colspec colname="1" colwidth="161PT" align="left" /><tbody valign="top"><row><entry /><entry>requires { boolean_expression }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="42PT" align="left" /><colspec colname="1" colwidth="175PT" align="left" /><tbody valign="top"><row><entry /><entry>}</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0462Consider the following example defining a set of transport-layer protocol ports (tcp or udp): <tables id="TABLE-US-00049" num="49"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 13: Sharing a set definition</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="21PT" align="left" /><colspec colname="1" colwidth="196PT" align="left" /><tbody valign="top"><row><entry /><entry>#define MAX_TCP_UDP_PORTS_SET_SZ    200</entry></row><row><entry /><entry>/* TUPORTS: a set of TCP or UDP ports */</entry></row><row><entry /><entry>set tuports<1> {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="35PT" align="left" /><colspec colname="1" colwidth="182PT" align="left" /><tbody valign="top"><row><entry /><entry>size_hint { MAX_TCP_UDP_PORTS_SET_SZ }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="21PT" align="left" /><colspec colname="1" colwidth="196PT" align="left" /><tbody valign="top"><row><entry /><entry>}</entry></row><row><entry /><entry>search tuports.tcp_sport (tcp.sport)</entry></row><row><entry /><entry>search tuports.tcp_dport (tcp.dport)</entry></row><row><entry /><entry>search tuports.udp_sport (udp.sport)</entry></row><row><entry /><entry>search tuports.udp_dport (udp.dport)</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0463This example illustrates how one set may be used by multiple searches. The set tuports might contain a collection of port numbers of interest for either protocol, TCP/IP or UDP/IP. The four named searches provide checks as to whether different TCP or UDP source or destination port numbers are present in the set. The results of named searches may be used as Boolean values in expressions, as illustrated below: <tables id="TABLE-US-00050" num="50"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 14: Using shared sets</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="203PT" align="left" /><tbody valign="top"><row><entry /><entry>predicate tcp_sport_in {tuports.tcp_sport}</entry></row><row><entry /><entry>predicate tcp_port_in {tuport.tcp_sport &amp;&amp; tuports.tcp_dport }</entry></row><row><entry /><entry>predicate udp_sdport_in {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="189PT" align="left" /><tbody valign="top"><row><entry /><entry>tuports.udp_sport ||tuports.udp_dport</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="203PT" align="left" /><tbody valign="top"><row><entry /><entry>}</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0464In the first example, a predicate tcp_sport_in is defined to be the Boolean result of the named search tuports.tcp_sport, which determines whether or not the tcp.sport field (source port) of a TCP segment is in the set tuports. In the second example, both the source and destination ports of the TCP protocol header are searched using named searches. In the third case, membership of either the source or destination ports of a UDP datagram in the set is determined.

00009. Rules and Actions

0465Rules are a named combination of a predicate and action. They are defined using the keyword rule. The predicate portion is a Boolean expression consisting of any combination of individual Boolean sub expressions or other predicate names. The Boo lean value of a predicate name corresponds to the Boolean value of its associated predicate portion. The action portion specifies the name of the action which is to be invoked when the predicate portion evaluates “true” for the current frames Actions are implemented external to the classifier and supplied by application developers. Arguments can be specified for the action function and may include predicates, named searches on sets, or results of intrinsic functions. The following illustrates the syntax: <tables id="TABLE-US-00051" num="51"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 15 Rule syntax</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="42PT" align="left" /><colspec colname="1" colwidth="175PT" align="left" /><tbody valign="top"><row><entry /><entry>rule rule_name   { predicate } {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="56PT" align="left" /><colspec colname="1" colwidth="161PT" align="left" /><tbody valign="top"><row><entry /><entry>external_action_func (arg 1, arg2, ...)</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="42PT" align="left" /><colspec colname="1" colwidth="175PT" align="left" /><tbody valign="top"><row><entry /><entry>}</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0466The argument list defines the values passed to the action code executed externally to NCL. An arbitrary number of arguments are supported. <tables id="TABLE-US-00052" num="52"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="259PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 16: Telnet/FTP example</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="259PT" align="left" /><tbody valign="top"><row><entry>set set_ip_tcp_0ports <3> |</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="231PT" align="left" /><tbody valign="top"><row><entry /><entry>size_hint { 100 }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="259PT" align="left" /><tbody valign="top"><row><entry>}</entry></row><row><entry>set set_ip_udp_ports <3> |</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="231PT" align="left" /><tbody valign="top"><row><entry /><entry>size_hint { 100 }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="259PT" align="left" /><tbody valign="top"><row><entry>}</entry></row><row><entry>search set_ip_tcp_ports.tcp_dport (ip.src, ip.dst, tcp.dport ) {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="245PT" align="left" /><tbody valign="top"><row><entry /><entry>requires {ip && tcp}</entry></row><row><entry /><entry>}</entry></row><row><entry /><entry>search set_ip_udp_ports.udp_dport { ip.src, ip.dst, udp.dport } {</entry></row><row><entry /><entry>requires {ip && udp}</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="259PT" align="left" /><tbody valign="top"><row><entry>{</entry></row><row><entry>predicate ipValid { ip && ip.chksumvalid && (ip.hlen > 5) &&</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="42PT" align="left" /><colspec colname="1" colwidth="217PT" align="left" /><tbody valign="top"><row><entry /><entry>{ip.ver == 4) }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="259PT" align="left" /><tbody valign="top"><row><entry>predicate newtelnet { (tcp.flags & 0×02) && (tcp.dport == 23) }</entry></row><row><entry>predicate tftp { (udp.dport == 21) && set_ip_udp_ports.udp_porst }</entry></row><row><entry>rule telnetNewCon { ipValid && newtelnet &&   set_ip_tcp_ports.tcp_dports }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="231PT" align="left" /><tbody valign="top"><row><entry /><entry>{ start_telnet( set_ip_tcp_ports.tcp_dports) }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="259PT" align="left" /><tbody valign="top"><row><entry>rule tftppkt {ipValid && tftp }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="231PT" align="left" /><tbody valign="top"><row><entry /><entry>{ is_tftp_pkt ( udp.dport ) }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="259PT" align="left" /><tbody valign="top"><row><entry>rule addnewtelnet { newtelnet }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="231PT" align="left" /><tbody valign="top"><row><entry /><entry>{ add_to_tcp_pkt_count( ) }</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0467In the above example, two sets are defined. One contains source and destination IP addresses, plus TCP ports. The other set contains IP addresses and UDP ports. Two named searches are defined. The first search uses the IP source and destination addresses and the TCP destination port number as keys. The second search uses the IP source and destination addresses and UDP destination port as keys. The predicate ipValid checks to make sure the packet is an IP packet with valid checksum, has a header of acceptable size, and is IP version 4. The predicate newtelnet determines if the current TCP segment is a SYN packet destined for a telnet port. The predicate tftp determines if the UDP destination port corresponds to the TFTP port number and the combination of IP source and destination addresses and destination UDP port number is in the set ip_udp_ports. The rule telnetNewCon determines if the current segment is a new telnet connection, and specifies that the associated external function start_telnet will be invoked when this rule is true. The function takes the search result as argument. The rule tftppkt checks whether the packet belongs to a TFTP association. If so, the associated action is_tftp_pkt will be invoked with udp.dport as the argument. The third checks if the current segment is a new telnet connection and defines the associated action function add_to_tcp_pkt_count.

000010. With Clauses

0468A with clause is a special directive providing for conditional execution of a group of rules or predicates. The syntax is as follows: <tables id="TABLE-US-00053" num="53"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 17: With clause syntax sample</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="203PT" align="left" /><tbody valign="top"><row><entry /><entry>with boolean_expression {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="189PT" align="left" /><tbody valign="top"><row><entry /><entry>predicate pred_name { any_boolean_exp }</entry></row><row><entry /><entry>rule rule_name {any_boolean_exp } { action_reference }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="203PT" align="left" /><tbody valign="top"><row><entry /><entry>}</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0469If the Boolean expression in the with clause evaluates false, all the enclosed predicates and rules evaluate false. For example, if we want to evaluate the validity of an IP datagram and use it in a set of predicates and rules, these can be encapsulated using the with clause and a conditional, which could be the checksum of the IP header. Nested with clauses are allowed, as illustrated in the following example: <tables id="TABLE-US-00054" num="54"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="266PT" align="center" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row><row><entry>Diagram 18: Nested with clauses</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="266PT" align="left" /><tbody valign="top"><row><entry>predicate tcpValid { tcp &amp;&amp; tcp.chksumalid }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="140PT" align="left" /><colspec colname="2" colwidth="126PT" align="left" /><tbody valign="top"><row><entry>#define TELNET</entry><entry>23   // port number for telnet</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="266PT" align="left" /><tbody valign="top"><row><entry>with ipValid {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="126PT" align="left" /><colspec colname="2" colwidth="126PT" align="left" /><tbody valign="top"><row><entry /><entry>predicate tftp</entry><entry>{ (udp.dport == 21) &amp;&amp;</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="154PT" align="left" /><colspec colname="2" colwidth="112PT" align="left" /><tbody valign="top"><row><entry /><entry>ip_udp_ports.udp_dport }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="252PT" align="left" /><tbody valign="top"><row><entry /><entry>with tcpValid {   /* Nested with */</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="140PT" align="left" /><colspec colname="2" colwidth="98PT" align="left" /><tbody valign="top"><row><entry /><entry>predicate newtelnet</entry><entry>{ (tcp.flags &amp; 0×02) &amp;&amp;</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="182PT" align="left" /><colspec colname="2" colwidth="84PT" align="left" /><tbody valign="top"><row><entry /><entry>tcp.dport == TELNET }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="238PT" align="left" /><tbody valign="top"><row><entry /><entry>rule telnetNewCon { newtelnet &amp;&amp; ip_tcp_ports.tcp_dport }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="56PT" align="left" /><colspec colname="1" colwidth="210PT" align="left" /><tbody valign="top"><row><entry /><entry>{ start_telnet ( ip_tcp_sport.tcp_dport) }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="252PT" align="left" /><tbody valign="top"><row><entry /><entry>}</entry></row><row><entry /><entry>rule tftppkt { tftp &amp;&amp; ip_udp_ports.udp_dport }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="42PT" align="left" /><colspec colname="1" colwidth="224PT" align="left" /><tbody valign="top"><row><entry /><entry>{ is_tftp_pkt ( udp.dport ) }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="266PT" align="left" /><tbody valign="top"><row><entry>}</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> 11. Protocol Definitions for TCP/IP

0470The following NCL definitions are used for processing of TCP/IP and related protocols. <tables id="TABLE-US-00055" num="55"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>/***************************** FRAME (base unit) *****************************/</entry></row><row><entry>protocol frame {</entry></row><row><entry>// status words written by NetBoost Ethernet MACs</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> rxstatus</entry><entry>{ frame[0x180:4] } // receive status</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="98PT" align="left" /><colspec colname="2" colwidth="189PT" align="left" /><tbody valign="top"><row><entry> rxstamp</entry><entry>{ frame[0x184:4] } // receive time stamp</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> txstatus</entry><entry>{ frame[0x188:4] } // xmit status (if sent out)</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="98PT" align="left" /><colspec colname="2" colwidth="189PT" align="left" /><tbody valign="top"><row><entry> txstamp</entry><entry>{ frame[0x18C:4] } // xmit time stamp (if sent)</entry></row><row><entry> predicate rxerror</entry><entry>{ (rxstatus & 0x80000000) }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="OFFSET" colwidth="42PT" align="left" /><colspec colname="1" colwidth="56PT" align="left" /><colspec colname="2" colwidth="189PT" align="left" /><tbody valign="top"><row><entry /><entry>length</entry><entry>{ (rxstatus & 0x07FF0000) >> 16 } // frame len</entry></row><row><entry /><entry>source</entry><entry>{ (rxstatus & 0x00000F00) >> 8 } // hardware origin</entry></row><row><entry /><entry>offset</entry><entry>{ (rxstatus & 0x000000FF) }  // start of frame</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="189PT" align="left" /><tbody valign="top"><row><entry> predicate</entry><entry>txok</entry><entry>{ (txstatus & 0x80000000) != 0 } // tx success</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="left" /><tbody valign="top"><row><entry> demux {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="98PT" align="left" /><colspec colname="2" colwidth="189PT" align="left" /><tbody valign="top"><row><entry>   rxerror</entry><entry>{ frame_bad at 0 }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="left" /><tbody valign="top"><row><entry>   // source 0: NetBoost onboard MAC A ethernet packet</entry></row><row><entry>   // source 1: NetBoost onboard MAC B ethernet packet</entry></row><row><entry>   // source 2: Other rxstatus-encodable ethernet packet</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="98PT" align="left" /><colspec colname="2" colwidth="189PT" align="left" /><tbody valign="top"><row><entry>   (source < 3)</entry><entry>{ ether at 0x180 + offset }</entry></row><row><entry>   default</entry><entry>{ frame_bad at 0 }</entry></row><row><entry> }</entry></row><row><entry>}</entry></row><row><entry>protocol frame_bad {</entry></row><row><entry>}</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="left" /><tbody valign="top"><row><entry>/**************************** ETHERNET **********************************/</entry></row><row><entry>#define ETHER_IPTYPE0x0800</entry></row><row><entry>#define ETHER_ARPTYPE   0x0806</entry></row><row><entry>#define ETHER_RARPTYPE   0x8035</entry></row><row><entry>protocol ether {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="168PT" align="left" /><tbody valign="top"><row><entry> dst</entry><entry>{ ether[0:6] }</entry><entry>// source ethernet address</entry></row><row><entry> src</entry><entry>{ ether[6:6] }</entry><entry>// destination ethernet address</entry></row><row><entry> typelen</entry><entry>{ ether[12:2] }</entry><entry>   // length or type, depends on encap</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="77PT" align="left" /><colspec colname="3" colwidth="168PT" align="left" /><tbody valign="top"><row><entry> snap</entry><entry>{ ether[14:6] }</entry><entry>// SNAP code if present</entry></row><row><entry> type</entry><entry>{ ether[20:2] }</entry><entry>// type for 8023 encaps</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="left" /><tbody valign="top"><row><entry> // We are only interested in a specific subset of the possible</entry></row><row><entry> // 802.3 encapsulations; specifically, those where the 802.2 LLC area</entry></row><row><entry> // contains DSAP=0xAA, SSAP=0xAA, and CNTL=0x03; followed by</entry></row><row><entry> // the 802.2 SNAP ar3ea contains the ORG code 0x000000. In this</entry></row><row><entry> // case, the 7802.2 SNAP “type” field contains one of our ETHER</entry></row><row><entry> // type values defined above.</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="28PT" align="left" /><colspec colname="3" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> predicate</entry><entry>issnap</entry><entry>{ (typelen <= 1500) && (snap == 0xAAAA03000000) }</entry></row><row><entry /><entry>offset</entry><entry>{ 14 + (issnap << 3) }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="154PT" align="left" /><colspec colname="2" colwidth="133PT" align="left" /><tbody valign="top"><row><entry> demux {</entry><entry /></row><row><entry>   typelen == ETHER_ARPTYPE</entry><entry>{ arp at offset }</entry></row><row><entry>   typelen == ETHER_RARPTYPE</entry><entry>{ arp at offset }</entry></row><row><entry>   typelen == ETHER_IPTYPE</entry><entry>   { ip at offset }</entry></row><row><entry>   issnap && (type == ETHER_ARPTYPE)</entry><entry>{ arp at offset }</entry></row><row><entry>   issnap && (type == ETHER_RARPTYPE)</entry><entry>{ arp at offset }</entry></row><row><entry>   issnap && (type == ETHER_IPTYPE)</entry><entry>{ ip at offset }</entry></row><row><entry>   default</entry><entry>{ ether_bad at 0 }</entry></row><row><entry> }</entry></row><row><entry>}</entry></row><row><entry>protocol ether_bad {</entry></row><row><entry>}</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="left" /><tbody valign="top"><row><entry>/****************** ARP PROTOCOL ************************/</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="112PT" align="left" /><colspec colname="2" colwidth="14PT" align="left" /><colspec colname="3" colwidth="161PT" align="left" /><tbody valign="top"><row><entry>#define ARPHRD_ETHER</entry><entry>1</entry><entry>/* ethernet hardware format */</entry></row><row><entry>#define ARPHRD_FRELAY</entry><entry>15</entry><entry>/* frame relay hardware format */</entry></row><row><entry>#define ARPOP_REQUEST</entry><entry>1</entry><entry>/* request to resolve address */</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="112PT" align="left" /><colspec colname="2" colwidth="175PT" align="left" /><tbody valign="top"><row><entry>#define ARPOP_REPLY  2</entry><entry>/* response to previous request */</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="112PT" align="left" /><colspec colname="2" colwidth="14PT" align="left" /><colspec colname="3" colwidth="161PT" align="left" /><tbody valign="top"><row><entry>#define ARPOP_REVREQUEST 3</entry><entry /><entry>/* request protocol address given hardware */</entry></row><row><entry>#define ARPOP_REVREPLY</entry><entry>4</entry><entry>/* response giving protocol address */</entry></row><row><entry>#define ARPOP_INVREQUEST 8</entry><entry /><entry>/* request to identify peer */</entry></row><row><entry>#define ARPOP_INVREPLY</entry><entry>9</entry><entry>/* response identifying peer */</entry></row><row><entry>protocol arp {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="245PT" align="left" /><tbody valign="top"><row><entry> htype</entry><entry>{ arp[0:2] }</entry></row><row><entry> ptype</entry><entry>{ arp[2:2] }</entry></row><row><entry> hsize</entry><entry>{ arp[4:1] }</entry></row><row><entry> psize</entry><entry>{ arp[5:1] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="28PT" align="left" /><colspec colname="3" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> op</entry><entry /><entry>{ arp[6:2] }</entry></row><row><entry> varhdr</entry><entry /><entry>{ 8 }</entry></row><row><entry> predicate</entry><entry>ethip4</entry><entry>{ (op <= ARPOP_REVREPLY) && (htype == ARPHRD_ETHER) &&</entry></row><row><entry /><entry /><entry> (ptype == ETHER_IPTYPE) && (hsize == 6) && (psize == 4) }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> demux {</entry><entry /></row><row><entry>   ethip4</entry><entry>{ ether_ip4_arp at varhdr }</entry></row><row><entry>   default</entry><entry>{ unimpl_arp at 0 }</entry></row><row><entry> }</entry></row><row><entry>}</entry></row><row><entry>protocol unimpl_arp {</entry></row><row><entry>}</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="left" /><tbody valign="top"><row><entry>protocol ether_ip4_arp {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> shaddr</entry><entry>{ ether_ip4_arp[0:6] }</entry></row><row><entry> spaddr</entry><entry>{ ether_ip4_arp[6:4] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="245PT" align="left" /><tbody valign="top"><row><entry> thaddr</entry><entry>{ ether_ip4_arp[10:6] }</entry></row><row><entry> tpaddr</entry><entry>{ ether_ip4_arp[16:4] }</entry></row><row><entry>}</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="left" /><tbody valign="top"><row><entry>/************************ IP v4 ************************/</entry></row><row><entry>protocol ip {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="245PT" align="left" /><tbody valign="top"><row><entry> verhl</entry><entry>{ ip[0:1] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="OFFSET" colwidth="42PT" align="left" /><colspec colname="1" colwidth="28PT" align="left" /><colspec colname="2" colwidth="217PT" align="left" /><tbody valign="top"><row><entry /><entry>ver</entry><entry>{ (verhl & 0xf0) >> 4 }</entry></row><row><entry /><entry>hl</entry><entry>{ (verhl & 0x0f) }</entry></row><row><entry /><entry>hlen</entry><entry>{ hl << 2}</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> tos</entry><entry>{ ip[1:1] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="245PT" align="left" /><tbody valign="top"><row><entry> length</entry><entry>{ ip[2:2] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> id</entry><entry>{ ip[4:2] }</entry></row><row><entry> ffo</entry><entry>{ ip[6:2] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="28PT" align="left" /><colspec colname="3" colwidth="217PT" align="left" /><tbody valign="top"><row><entry /><entry>flags</entry><entry>{ (ffo & 0xe000) >> 13 }</entry></row><row><entry /><entry>fragoff</entry><entry>{ (ffo & 0x1fff) }</entry></row><row><entry> ttl</entry><entry /><entry>{ ip[8:1] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="245PT" align="left" /><tbody valign="top"><row><entry> proto</entry><entry>{ ip[9:1] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> cksum</entry><entry>{ ip[10:2] }</entry></row><row><entry> src</entry><entry>{ ip[12:4] }</entry></row><row><entry> dst</entry><entry>{ ip[16:4] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="left" /><tbody valign="top"><row><entry> // varible length options start at offset 20</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="28PT" align="left" /><colspec colname="3" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> predicate</entry><entry>dbcast</entry><entry>{ dst == 255.255.255.255 }</entry></row><row><entry> predicate</entry><entry>sbcast</entry><entry>{ src == 255.255.255.255 }</entry></row><row><entry> predicate</entry><entry>smcast</entry><entry>{ (src & 0xF0000000) == 0xE0000000 }</entry></row><row><entry> predicate</entry><entry>dmcast</entry><entry>{ (dst & 0xF0000000) == 0xE0000000 }</entry></row><row><entry> predicate</entry><entry>dontfr</entry><entry>{ (flags & 2) != 0 }   // “do not fragment this packet”</entry></row><row><entry> predicate</entry><entry>morefr</entry><entry>{ (flags & 1) != 0 }    // “not last frag in datagram”</entry></row><row><entry> predicate</entry><entry>isfrag</entry><entry>{ morefr || fragoff }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="245PT" align="left" /><tbody valign="top"><row><entry> predicate</entry><entry>options { hlen > 20 }</entry></row><row><entry> intrinsic</entry><entry>chksumvalid  { }</entry></row><row><entry> predicate</entry><entry>okhwlen { (frame.length − ether.offset) >= length }</entry></row><row><entry> predicate</entry><entry>invalid { (ver != 4) || (hlen < 20) ||</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="28PT" align="left" /><colspec colname="3" colwidth="217PT" align="left" /><tbody valign="top"><row><entry /><entry /><entry>((frame.length − ether.offset) < length) ||</entry></row><row><entry /><entry /><entry>(length < hlen) || !chksumvalid }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="245PT" align="left" /><tbody valign="top"><row><entry> predicate</entry><entry>badsrc { sbcast || smcast }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="left" /><tbody valign="top"><row><entry> demux {</entry></row><row><entry>   // Demux expressions are evaluated in order, and the</entry></row><row><entry>   // first one that matches causes a demux to the protocol;</entry></row><row><entry>   // once one matches, no further checks are made, so the</entry></row><row><entry>   // cases do not have to be precisely mutually exclusive.</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="217PT" align="left" /><tbody valign="top"><row><entry>   invalid</entry><entry>{ ip_bad at 0 }</entry></row><row><entry>   badsrc</entry><entry>{ ip_badsrc at 0 }</entry></row><row><entry>   (proto == 1)</entry><entry>{ icmp at hlen }</entry></row><row><entry>   (proto == 2)</entry><entry>{ igmp at hlen }</entry></row><row><entry>   (proto == 6)</entry><entry>{ tcp at hlen }</entry></row><row><entry>   (proto == 17)</entry><entry>{ udp at hlen }</entry></row><row><entry>   default</entry><entry>{ ip_unknown_transport at hlen }</entry></row><row><entry> }</entry></row><row><entry>}</entry></row><row><entry>protocol ip_bad {</entry></row><row><entry>}</entry></row><row><entry>protocol ip_badsrc {</entry></row><row><entry>}</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="left" /><tbody valign="top"><row><entry>protocol ip_unknown_transport {</entry></row><row><entry>}</entry></row><row><entry>/*************************** UDP ********************************/</entry></row><row><entry>protocol udp {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="245PT" align="left" /><tbody valign="top"><row><entry> sport</entry><entry>{ udp[0:2] }</entry></row><row><entry> dport</entry><entry>{ udp[2:2] }</entry></row><row><entry> length</entry><entry>{ udp[4:2] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> cksum</entry><entry>{ udp[6:2] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="189PT" align="left" /><tbody valign="top"><row><entry> intrinsic</entry><entry>chksumvalid</entry><entry>{ } /* undefined if a frag */</entry></row><row><entry> predicate</entry><entry>valid</entry><entry>{ ip.isfrag || chksumvalid }</entry></row><row><entry>}</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="left" /><tbody valign="top"><row><entry>/************************** TCP *******************************/</entry></row><row><entry>protocol tcp {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="245PT" align="left" /><tbody valign="top"><row><entry> sport</entry><entry>{ tcp[0:2] }</entry></row><row><entry> dport</entry><entry>{ tcp[2:2] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> seq</entry><entry>{ tcp[4:4] }</entry></row><row><entry> ack</entry><entry>{ tcp[8:4] }</entry></row><row><entry> hlf</entry><entry>{ tcp[12:2] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="28PT" align="left" /><colspec colname="3" colwidth="217PT" align="left" /><tbody valign="top"><row><entry /><entry>hl</entry><entry>{ (hlf & 0xf000) >> 12 }</entry></row><row><entry /><entry>hlen</entry><entry>{ hl << 2 }</entry></row><row><entry /><entry>flags</entry><entry>{ (hlf & 0x003f) }</entry></row><row><entry> win</entry><entry /><entry>{ tcp[14:2] }</entry></row><row><entry> cksum</entry><entry /><entry>{ tcp[16:2] }</entry></row><row><entry> urp</entry><entry /><entry>{ tcp[18:2] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="189PT" align="left" /><tbody valign="top"><row><entry> intrinsic</entry><entry>chksumvalid</entry><entry>{ } /* undefined if IP Fragment */</entry></row><row><entry> predicate</entry><entry>valid</entry><entry>{ ip.isfrag || ((hlen >= 20) && chksumvalid) }</entry></row><row><entry> predicate</entry><entry>opt_present</entry><entry>{ hlen > 20 }</entry></row><row><entry>}</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="left" /><tbody valign="top"><row><entry>/************************** ICMP ***********************************/</entry></row><row><entry>protocol icmp {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="245PT" align="left" /><tbody valign="top"><row><entry> type</entry><entry>{ icmp[0:1] }</entry></row><row><entry> code</entry><entry>{ icmp[1:1] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> cksum</entry><entry>{ icmp[2:2] }</entry></row><row><entry>}</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="287PT" align="left" /><tbody valign="top"><row><entry>/************************* IGMP ***********************************/</entry></row><row><entry>protocol igmp {</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="28PT" align="left" /><colspec colname="3" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> vertype</entry><entry /><entry>{ igmp[0:1] }</entry></row><row><entry /><entry>ver</entry><entry>{ (vertype & 0xf0) >> 4 }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="42PT" align="left" /><colspec colname="1" colwidth="245PT" align="left" /><tbody valign="top"><row><entry /><entry>type { (vertype & 0x0f) }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="28PT" align="left" /><colspec colname="3" colwidth="217PT" align="left" /><tbody valign="top"><row><entry> reserved</entry><entry /><entry>{ igmp[1:1] }</entry></row><row><entry> cksum</entry><entry /><entry>{ igmp[2:2] }</entry></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="245PT" align="left" /><tbody valign="top"><row><entry> group</entry><entry>{ igmp[4:4] }</entry></row><row><entry>}</entry></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

VIII. ASL

0471The Application Services Library (ASL) provides a set of library functions available to action code that are useful for packet processing. The complete environment available to action code includes: the ASL; a restricted C/C++ library and runtime environment; one or more domain specific extensions such as TCP/IP.

0000The Restricted C/C++ Libraries and Runtime Environment

0472Action code may be implemented in either the ANSI C or C++ programming languages. A library supporting most of the functions defined in the ANSI C and C++ libraries is provided. These libraries are customized for the NetBoost PE hardware environment, and as such differ slightly from their equivalents in a standard host operating system. Most notably, file operations are restricted to the standard error and output streams (which are mapped into upcalls).

0473In addition to the C and C++ libraries available to action code, NetBoost supplies a specialized C and C++ runtime initialization object module which sets up the C and C++ run-time environments by initializing the set of environment variables and, in the case of C++, executing constructors for static objects.

00001. ASL Functions

0474The ASL contains class definitions of potential use to any action code executing in the PE. It includes memory allocation, management of API objects (ACEs, targets), upcall/downcall support, set manipulation, timers, and a namespace support facility. The components comprising the ASL library are as follows:

0000Basic Scalar Types

0475The library contains basic type definitions that include the number of bits represented. These include int8 (8 bit integers), int16 (16 bit integers), int32 (32 bit integers), and int64 (64 bit integers). In addition, unsigned values (uint8, uint16, uint32, uint64) are also supported.

0000Special Endian-Sensitive Scalar Types

0476The ASL is commonly used for manipulating the contents of packets which are generally in network byte order. The ASL provides type definitions similar to the basic scalar types, but which represent data in network byte order. Types in network byte order as declared in the same fashion as the basic scalar types but with a leading n prefix (e.g. nuint16 refers to an unsigned 16 bit quantity in network byte order). The following functions are used to convert between the basic types (host order) and the network order types: <tables id="TABLE-US-00056" num="56"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="77PT" align="left" /><colspec colname="2" colwidth="112PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="2" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>uint32 ntohl(nuint32 n);</entry><entry>// network to host (32 bit)</entry></row><row><entry /><entry>uint16 ntohs(nuint16 n);</entry><entry>// network to host (16 bit)</entry></row><row><entry /><entry>nuint32 htonl(uint32 h);</entry><entry>// host to network (32 bit)</entry></row><row><entry /><entry>nuint16 htons(uint16 h);</entry><entry>// host to network (16 bit)</entry></row><row><entry /><entry namest="OFFSET" nameend="2" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Macros and Classes for Handling Errors and Exceptions in the ASL

0477The ASL contains a number of C/C++ macro definitions used to aid in debugging and code development (and mark fatal error conditions). These are listed below:

0478ASSERT Macros (asserts boolean expression, halts on failure)

0479CHECK Macros (asserts boolean, returns from current real-time loop on failure)

0480STUB Macros (gives message, c++ file name and line number)

0481SHO Macros (used to monitor value of a variable/expression during execution)

0000Exceptions

0482The ASL contains a number of functions available for use as exception handlers. Exceptions are a programming construct used to delivery error information up the call stack. The following functions are provided for handling exceptions:

0483NBaction_err and NBaction_warn functions to be invoked when exceptions are thrown.

0484OnError class, used to invoke functions during exception handling, mostly for debugger breakpoints.

0000ACE Support

0485Ace objects in the ASL contain the per-Ace state information. To facilitate common operations, the base Ace class' pass and drop targets are provided by the base class and built when an Ace instance is constructed. If no write action is taken on a buffer that arrives at the Ace (i.e. none of the actions of matching rules indicates it took ownership), the buffer is sent to the pass target. The pass and drop functions (i.e. target take functions, below) may be used directly as actions within the NCL application description, or they may be called by other actions. Member functions of the Ace class include: pass( ), drop( ), enaRule( )—enable a rule, disRule( )—disable a rule.

0000Action Support:

0486The init_actions( ) call is the primary entry point into the application's Action code. It is used by the ASL startup code to initialize the PE portion of the Network Application. It is responsible for constructing an Ace object of the proper class, and typically does nothing else.

0487Example Syntax: <tables id="TABLE-US-00057" num="57"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="189PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>INITF init_actions(void* id, char* name, Image* obj)</entry></row><row><entry /><entry>{</entry></row><row><entry /><entry>  return new ExampleAce(id, name, obj);</entry></row><row><entry /><entry>}</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> The function should return a pointer to an object subclassed from the Ace class, or a NULL pointer if an Ace could not be constructed. Throwing an NBaction_err or NBaction_warn exception may also be appropriate and will be caught by the initialization code. Error conditions will be reported back to the Resolver as a failure to create the Ace. <br /> Return Values from Action Code/Handlers

0488When a rule's action portion is invoked because the rule predication portion evaluated true, the action function must return a code indicating how processing should proceed. The action may return a code indicating it has disposed of the frame (ending the classification phase), or it may indicate it did not dispose of the frame, and further classification (rule evaluations) should continue. A final option available is for the action to return a defer code, indicating that it wishes to modify a frame, but that the frame is in use elsewhere. The return values are defined as C/C++ pre-processor definitions: <ul id="ul0012" list-style="none"><li id="ul0012-0001" num="0489"> #define RULE_DONE . . . <ul id="ul0013" list-style="none"><li id="ul0013-0001" num="0490"> Actions should return RULE_DONE to terminate processing of rules and actions within the context of the current Ace; for instance, when a buffer has been sent to a target, or stored for later processing. </li></ul></li><li id="ul0012-0002" num="0491"> #define RULE_CONT . . . <ul id="ul0014" list-style="none"><li id="ul0014-0001" num="0492"> Actions should return RULE_CONT if they have merely observed the buffer and wish for additional rules and actions within the context of the current ace to be processed. </li><li id="ul0014-0002" num="0493"> #define RULE_DEFER . . . </li><li id="ul0014-0003" num="0494"> Actions should return RULE_DEFER if they wish to modify a packet within a buffer but the buffer notes that the packet is currently busy elsewhere. <br /> Predefined Actions </li></ul></li></ul>

0495The common cases of disposing of a frame by either dropping it or sending it on to the next classification entity for processing is supported by two helper functions available to NCL code and result in calling the functions Ace::pass( ) or Ace::drop( ) within the ASL: action_pass (predefined action), passes frame to ‘pass target’, always returns RULE_DONE action_drop (predefined action), passes frame to ‘drop target’, always returns RULE_DONE

0000User-Defined Actions

0496Most often, user-defined actions are used in an Ace. Such actions are implemented with the following calling structure.

0497The ACTNF return type is used to set up linkage. Action handlers take two arguments: pointer to the current buffer being processed, and the Ace associated with this action. Example: <tables id="TABLE-US-00058" num="58"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="203PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>ACTNF do_mcast(Buffer *buf, ExAce *ace) {</entry></row><row><entry /><entry>  ace->mcast_ct ++;</entry></row><row><entry /><entry>  cout << ace->name( ) << “: ” << ace->mcast_ct << endl;</entry></row><row><entry /><entry>  return ace->drop(buf);</entry></row><row><entry /><entry>}</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0498Thus, the Buffer* and ExAce* types are passed to the handler. In this case, ExAce is derived from the base Ace class: <tables id="TABLE-US-00059" num="59"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="21PT" align="left" /><colspec colname="1" colwidth="196PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>#include “NBaction/NBaction.h”</entry></row><row><entry /><entry>class ExAce : public Ace {</entry></row><row><entry /><entry>public:</entry></row><row><entry /><entry>  ExAce(ModuleId id, char *name, Image *obj)</entry></row><row><entry /><entry> : Ace(id, name, obj), mcast_ct(0) { }</entry></row><row><entry /><entry>  int mcast_ct;</entry></row><row><entry /><entry>};</entry></row><row><entry /><entry>INITF init_actions(void *id, char *name, Image *obj) {</entry></row><row><entry /><entry>  return new ExAce(id, name, obj);</entry></row><row><entry /><entry>}</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Buffer Management (Buffer Class)

0499The basic unit of processing in the ASL is the Buffer. All data received from the network is received in buffers, and all data to be transmitted must be properly formatted into buffers. Buffers are reference-counted. Contents are typed (more specifically, the type of the first header has a certain type [an integer/enumerated type]). Member functions of the Buffer class support common trimming operations (trim head, trim tail) plus additions (prepend and append date). Buffers are assigned a time stamp upon arrival and departure (if they are transmitted). The member function erxTime( ) returns receipt time stamp of the frame contained in the buffer. The txTime( ) gives transmission complete time stamp of the buffer if the frame it contains has been transmitted. Several additional member functions and operators are supported: new( )—allocates buffer from pool structure (see below), headerBase( )—location of first network header, headerOffset( )—reference to byte offset from start of storage to first network header, packetSize( )—number of bytes in frame, headerType( )—type of first header, packetPadHeadSize( )—free space before net packet, packetPadTailSize( )—free space after net packet, prepend( )—add data to beginning, append( )—add data to end, trim_head( )—remove data from head, trim_tail( )—remove data from end, {rx, tx }Time( )—see above, next( )—reference to next buffer on chain, incref( )—bump reference count, decref( )—decrement reference count, busy( )—indicates buffer being processed, log( )—allows for adding info the ‘transaction log’ of a buffer which can indicate what has processed it.

0000Targets

0500Target objects within an Ace indicate the next hardware or software resource that will classify a buffer along a selected path. Targets are bound to another Ace within the same application, an Ace within a different application, or a built in resource such as decryption. Bindings for Targets are set up by the plumber (see above). The class includes the member function take( ) which sends a buffer to the next downstream entity for classification.

0501Targets have an associated module and Ace (specified by a “ModuleId” object and an Ace*). They also have a name in the name space contained in the resolver, which associates Aces to applications.

0000Upcall

0502An upcall is a form of procedure call initiated in the PE module and handled in the AP module. Upcalls provide communication between the “inline” portion of an application and its “slower path” executing in the host environment. Within the ASL, the upcall facility sends messages to the AP. Messages are defined below. The upcall class contains the member function call( )—which takes objects of type Message* and sends them asynchronously to AP module.

0000DowncallHandler

0503A downcall is a form of procedure call initiated in the AP module and handled in the PE module. Downcalls provide the opposite direction of communication than upcalls. The class contains the member function direct( ) which provides a pointer to the member function of the Ace class that is to be invoked when the associated downcall is requested in the AP. The Ace member function pointed to takes a Message * type as argument.

0000Message

0504Messages contain zero, one, or two blocks of message data, which are independently constructed using the MessageBlock constructors (below). Uninitialized blocks will appear at the Upcall handler in the AP module as zero length messages. Member functions of the Message class include: msg<b>1</b>( ), msg<b>2</b>( ), len<b>1</b>( ), len<b>2</b>( )—returns addresses and lengths of the messages [if present]. Other member functions: clr<b>1</b>( ), clr<b>2</b>( ), done( )—acknowledge receipt of a message and free resources.

0000MessageBlock

0505The MessageBlock class is used to encapsulate a region of storage within the Policy Engine memory that will be used in a future Upcall Message. It also includes a method to be called when the service software has copied the data out of that storage and no longer needs it to be stable (and can allow it to be recycled). Constructor syntax is as follows: <tables id="TABLE-US-00060" num="60"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="189PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>MessageBlock(char *msg, int len=0, DoneFp done=0);</entry></row><row><entry /><entry>MessageBlock(Buffer *buf);</entry></row><row><entry /><entry>MessageBlock(int len, int off=0);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> The first form specifies an existing data area to be used as the data source. If the completion callback function (DoneFp) is specified, it will be called when the data has been copied out of the source area. Otherwise, no callback is made and no special actions are taken after the data is copied out of the message block. If no length is specified, then the base pointer is assumed to point to a zero-terminated string; the length is calculated to include the null termination. The second form specifies a Buffer object; the data transferred is the data contained within the buffer, and the relative alignment of the data within the 32-bit word is retained. The reference count on the buffer is incremented when the MessageBlock is created, and the callback function is set to decrement the reference count when the copy out is complete. This will have the effect of marking the packet as “busy” for any actions that check for busy buffers, as well as preventing the buffer from being recycled before the copy out is complete. The third form requests that MessageBlock handle dynamic allocation of a region of memory large enough to hold a message of a specified size. Optionally, a second parameter can be specified that gives the offset from the 32-bit word alignment boundary where the data should start. The data block will retain this relative byte offset throughout its transfer to the Application Processor. This allows, for instance, allocating a 1514-byte data area with 2-byte offset, building an Ethernet frame within it, and having any IP headers included in the packet land properly aligned on 32-bit alignment boundaries. <br /> Sets

0506Sets are an efficient way to track a large number of equivalence classes of packets, so that state can be kept for all packets that have the same values in specific fields. For instance, the programmer might wish to count the number of packets that flow between any two specific IP address pairs, or keep state for each TCP stream. Sets represent collections of individual members, each one of which matches buffers with a specific combination of field values. If the programmer instead wishes to form sets of the form “the set of all packets with IP header lengths greater than twenty bytes,” then the present form of sets are not appropriate; instead, a Classification Predicate should be used.

0507In NCL, the only information available regarding a set is whether or not a set contained a record corresponding to a vector of search keys. Within the ASL, all other set operations are supported: searches, insertions, and removals. For searches conducted in the CE, the ASL provides access to additional information obtained during the search operation: specifically, a pointer to the actual element located (for successful searches), and other helpful information such as an insertion pointer (on failure). The actual elements stored in each set are of a class constructed by the compiler, or are of a class that the software vendor has subclassed from that class. The hardware environment places strict requirements on the alignment modulus and alignment offset for each set element.

0508As shown in the NCL specification, a single set may be searched by several vectors of keys, resulting in multiple search results that share the same target element records. Each of these directives results in the construction of a function that fills the key fields of the suitable Element subclass from a buffer.

0509Within the ASL, the class set is used to abstract a set. It serves as a base class for compiler generated classes specific to the sets specified in the NCL program (see below).

0000Search

0510The Search class is the data type returned by all set searching operations, whether provided directly by the ASL or executed within the classification engine. Member functions: ran( )—true if the CE executed this search on a set, hit( )—true if the CE found a match using this search, miss( )—inverse of hit( ) but can return a cookie making inserts faster, toElement( )—converts successful search result to underlying object, insert ( )—insert an object at the place the miss( ) function indicates we should.

0000Element

0511Contents of sets are called elements, and the NCL compiler generates a collection of specialized classes derived from the Element base class to contain user-specified data within set elements. Set elements may have an associated timeout value, indicating the maximum amount of time the set element should be maintained. After the time out is reached, the set element is automatically removed from the set. The time out facility is useful for monitoring network activity such as packet flows that should eventually be cleared due to inactivity.

0000Compiler-Generated Elt_<Setname> Classes

0512For each set directive in the NCL program, the NCL compiler produces an adjusted subclass of the Element class called Elt_<setname>, substituting the name of the set for <setname>. This class is used to define the type of elements of the specified set. Because each set declaration contains the number of keys needed to search the set, this compiler-generated class is specialized from the element base class for the number of words of search key being used.

0000Compiler-Generated Set_<Setname> Classes

0513For each set directive in the NCL program, the NCL compiler produces an adjusted subclass of the Element class called Set_<setname>, substituting the name of the set for <set name>. This class is used to define the lookup functions of the specified set. The NCL compiler uses the number of words of key information to customize the parameter list for the lookup function; the NCL size_hint is used to adjust a protected field within the class. Aces that needing to manipulate sets should include an object of the customized Set class as a member of their Ace.

0000Events

0514The Event class provides for execution of functions at arbitrary times in the future, with efficient rescheduling of the event and the ability to cancel an event without destroying the event marker itself. A calendar queue is used to implement the event mechanism. When constructing objects of the Event class, two optional parameters may be specified: the function to be called (which must be a member function of a class based on Event), and an initial scheduled time (how long in the future, expressed as a Time object). When both parameters are specified, the event's service function is set and the event is scheduled. If the Time parameter is not specified, the Event's service function is still set but the event is not scheduled. If the service function is not set, it is assumed that the event will be directed to a service function before it is scheduled in the future. Member functions of this class include: direct( )—specifies what function to be executed at expiry, schedule( )—indicates how far in the future for event to trigger, cancel( )—unschedule event, curr( )—get time of currently running event.

0000Rate

0515The Rate class provides a simple way to track event rates and bandwidths in order to watch for rates exceeding desired values. The Rate constructor allows the application to specify arbitrary sampling periods. The application can (optionally) specify how finely to divide the sampling period. Larger divisors result in more precise rate measurement but require more overhead, since the Rate object schedules Events for each of the shorter periods while there are events within the longer period. Member functions of this class include: clear( )—reset internal state, add( )—bumps event count, count( )—gives best estimate of current trailing rate of events over last/longer period

0000Time

0516The Time class provides a common format for carrying around a time value. Absolute, relative, and elapsed times are all handled identically. As conversions to and from int64 (a sixty-four bit unsigned integer value) are provided, all scalar operators are available for use; in addition, the assignment operators are explicitly provided. Various other classes use Time objects to specify absolute times and time intervals. For maximum future flexibility in selection of storage formats, the actual units of the scalar time value are not specified; instead, they are stored as a class variable. Extraction of meaningful data should be done via the appropriate access methods rather than by direct arithmetic on the Time object.

0517Class methods are available to construct Time objects for specified numbers of standard time units (microseconds, milliseconds, seconds, minutes, hours, days and weeks); also, methods are provided for extraction of those standard time periods from any Time object. Member functions include: curr( )—returns current real time, operators: +=, −=, *=, /=, %=, <<=, >>=, |=, ˆ=, &=, accessors+builders: usec( ), msec( ), secs( ), mins( ), hour( ), days( ), week( ), which access or build Time objects using the specified number of microseconds, milliseconds, seconds, minutes, hours, days, and weeks, respectively.

0000Memory Pool

0518The Pool class provides a mechanism for fast allocation of objects of fixed sizes at specified offsets from specified power-of-two alignments, restocking the raw memory resources from the PE module memory pool as required. The constructor creates an object that describes the contents of the memory pool and contains the configuration control information for how future allocations will be handled.

0519Special ‘offset’ and ‘restock’ parameters are used. The offset parameter allows allocation of classes where a specific member needs to be strongly aligned; for example, objects from the Buffer class contain an element called hard that must start at the beginning of a 2048-byte-aligned region. The restock parameter controls how much memory is allocated from the surrounding environment when the pool is empty. Enough memory is allocated to contain at least the requested number of objects, of the specified size, at the specified offset from the alignment modulus. Member function include: take( )—allocate a chunk, free( )—return a chunk to the pool.

0000Tagged Memory Pool

0520Objects that carry with them a reference back to the pool from which they were taken are called tagged. This is most useful for cases when the code that frees the object will not necessarily know what pool it came from. This class is similar to normal Memory Pools, except for internal details and the calling sequence for freeing objects back into the pool. The tagged class trades some additional space overhead for the flexibility of being able to free objects without knowing which Tagged pool they came from; this is similar to the overhead required by most C library malloc implementations. If the object has strong alignment requirements, the single added word of overhead could cause much space to be wasted between the objects. For instance, if the objects were 32 bytes long and were required to start on 32-byte boundaries, the additional word would cause another 28 bytes of padding to be wasted between adjacent objects.

0521The Tagged class adds a second (static) version of the take method, which is passed the size of the object to be allocated. The Tagged class manages an appropriate set of pools based on possible object sizes, grouping objects of similar size together to limit the number of pools and allow sharing of real memory between objects of slightly different sizes. Member functions include: take( )—allocate a chunk, free( )—return a chunk to the pool.

0000Dynamic

0522This class takes care of overloading the new and delete operators, redirecting the memory allocation to use a number of Tagged Pools managed by the NBACTION DLL. All classes derived from Dynamic share the same set of Tagged Pools; each pool handles a specific range of object sizes, and objects of similar sizes will share the same Tagged Pool. The dynamic class has no storage requirements and no virtual functions. Thus, declaring objects derived from Dynamic will not change the size or layout of your objects (just how they are allocated). Operators defined include: new( )—allocate object from underlying pool, delete( )—return to underlying pool.

0000Name Dictionary

0523The Name class keeps a database of named objects (that are arbitrary pointers in the memory address space of the ASL. It provides mechanisms for adding objects to the dictionary, finding objects by name, and removing them from the dictionary. It is implemented with a Patricia Tree (a structure often used in longest prefix match in routing table lookups). Member functions include: find( )—look up string, name( )—return name of dictionary.

00002. ASL Extensions for TCP/IP

0524The TCP/IP Extensions to the Action Services Library (ASL) provides a set of class definitions designed to make several tasks common to TCP/IP-based network-oriented applications easier. With functions spanning several protocol layers, it includes operations such as IP fragment reassembly and TCP stream reconstruction. Note that many of the functions that handle Internet data make use of 16 and 32-bit data types beginning with ‘n’ (such as nuint16 and nuint32). These data types refer to data in network byte order (i.e. big endian). Functions used to convert between host and network byte such as htonl( ) (which converts a 32-bit word from host to network byte order), are also defined.

00003. The Internet Class

0525Functions of potential use to any Internet application are grouped together as methods of the Internet class. These functions are declared static within the class, so that they may be used easily without requiring an instantiation of the Internet class.

0000Internet Checksum Support

0526The Internet Checksum is used extensively within the TCP/IP protocols to provide reasonably high assurance that data has been delivered correctly. In particular, it is used in IP (for headers), TCP and UDP (for headers and data), ICMP (for headers and data), and IGMP (for headers).

0527The Internet checksum is defined to be the 1's complement of the sum of a region of data, where the sum is computed using 16-bit words and 1's complement addition.

0528Computation of this checksum is documented in a number of RFCs (available from ftp://ds.internic.net/rfc):RFC <b>1936</b> describes ahardware implementation, RFC <b>1624</b> and RFC <b>1141</b> describe incremental updates, RFC <b>1071</b> describes a number of mathematical properties of the checksum and how to compute it quickly. RFC <b>1071</b> also includes a copy of IEN <b>45</b> (from 1978), which describes motivations for the design of the checksum.

0529The ASL provides the following functions to calculate Internet Checksums: <ul id="ul0015" list-style="none"><li id="ul0015-0001" num="0530"> cksum <br /> Description </li></ul>

0531Computes the Internet Checksum of the data specified. This function works properly for data aligned to any byte boundary, but may perform (significantly) better for 32-bit aligned data.

0000Syntax

0000<ul id="ul0016" list-style="none"><li id="ul0016-0001" num="0532"> static nuint16 Internet::cksum(u_char* base, int len); </li></ul>

0533Parameters <tables id="TABLE-US-00061" num="61"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="112PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>base</entry><entry>unsigned</entry><entry>The starting address of the data.</entry></row><row><entry /><entry /><entry>char *</entry></row><row><entry /><entry>len</entry><entry>int</entry><entry>The number of bytes of data.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0534Returns the Internet Checksum in the same byte order as the underlying data, which is assumed to be in network byte order (big endian). <ul id="ul0017" list-style="none"><li id="ul0017-0001" num="0535"> psum <br /> Description </li></ul>

0536Computes the 2's-complement sum of a region of data taken as 16-bit words. The Internet Checksum for the specified data region may be generated by folding any carry bits above the low-order 16 bits and taking the 1's complement of the resulting value.

0000Syntax

0000<ul id="ul0018" list-style="none"><li id="ul0018-0001" num="0537"> static uint32 Internet::psum(u-char* base, int len); </li></ul>

0538Parameters <tables id="TABLE-US-00062" num="62"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="112PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>base</entry><entry>unsigned</entry><entry>The starting address of the data.</entry></row><row><entry /><entry /><entry>char *</entry></row><row><entry /><entry>len</entry><entry>int</entry><entry>The number of bytes of data.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0539Returns the 2's-complement 32-bit sum of the data treated as an array of 16-bit words. <ul id="ul0019" list-style="none"><li id="ul0019-0001" num="0540"> incrcksum <br /> Description </li></ul>

0541Computes a new Internet Checksum incrementally. That is, a new checksum is computed given the original checksum for a region of data, a checksum for a block of data to be replaced, and a checksum of the new data replacing the old data. This function is especially useful when small regions of packets are modified and checksums must be updated appropriately (e.g. for decrementing IP ttl fields or rewriting address fields for NAT).

0542Syntax <tables id="TABLE-US-00063" num="63"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="203PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>static uint16</entry></row><row><entry /><entry>  Internet::incrcksum(nuint16 ocksum, nuint16 odsum, nuint16</entry></row><row><entry /><entry>ndsum);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0543Parameters <tables id="TABLE-US-00064" num="64"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="119PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>ocksum</entry><entry>nuint16</entry><entry>The original checksum.</entry></row><row><entry /><entry>odsum</entry><entry>nuint16</entry><entry>The checksum of the old data.</entry></row><row><entry /><entry>ndsum</entry><entry>nuint16</entry><entry>The checksum of the new (replacing)</entry></row><row><entry /><entry /><entry /><entry>data.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0544Returns the computed checksum. <ul id="ul0020" list-style="none"><li id="ul0020-0001" num="0545"> asum <br /> Description </li></ul>

0546The function asum computes the checksum over only the IP source and destination addresses.

0000Syntax

0000<ul id="ul0021" list-style="none"><li id="ul0021-0001" num="0547"> static uint16 asum(IP4Header* hdr); </li></ul>

0548Parameters <tables id="TABLE-US-00065" num="65"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="49PT" align="left" /><colspec colname="2" colwidth="63PT" align="left" /><colspec colname="3" colwidth="91PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>hdr</entry><entry>IP4Header *</entry><entry>Pointer to the header.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0549Returns the checksum. <ul id="ul0022" list-style="none"><li id="ul0022-0001" num="0550"> apsum <br /> Description </li></ul>

0551The function apsum behaves like asum but includes the address plus the two 16-bit words immediately following the IP header (which are the port numbers for TCP and UDP).

0000Syntax

0000<ul id="ul0023" list-style="none"><li id="ul0023-0001" num="0552"> static uint16 apsum(IP4Header* hdr); </li></ul>

0553Parameters <tables id="TABLE-US-00066" num="66"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="49PT" align="left" /><colspec colname="2" colwidth="63PT" align="left" /><colspec colname="3" colwidth="91PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>hdr</entry><entry>IP4Header *</entry><entry>Pointer to the header.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0554Returns the checksum. <ul id="ul0024" list-style="none"><li id="ul0024-0001" num="0555"> apssum <br /> Description </li></ul>

0556The function apssum behaves like apsum, but covers the IP addresses, ports, plus TCP sequence number.

0000Syntax

0000<ul id="ul0025" list-style="none"><li id="ul0025-0001" num="0557"> static uint16 apssum(IP4Header* hdr); </li></ul>

0558Parameters <tables id="TABLE-US-00067" num="67"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="49PT" align="left" /><colspec colname="2" colwidth="63PT" align="left" /><colspec colname="3" colwidth="91PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>hdr</entry><entry>IP4Header *</entry><entry>Pointer to the header.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0559Returns the checksum. <ul id="ul0026" list-style="none"><li id="ul0026-0001" num="0560"> apasum <br /> Description </li></ul>

0561The function apasum is behaves like apssum, but covers the TCP ACK field instead of the sequence number field.

0000Syntax

0000<ul id="ul0027" list-style="none"><li id="ul0027-0001" num="0562"> static uint16 apasum(IP4Header* hdr); </li></ul>

0563Parameters <tables id="TABLE-US-00068" num="68"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="49PT" align="left" /><colspec colname="2" colwidth="63PT" align="left" /><colspec colname="3" colwidth="91PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>hdr</entry><entry>IP4Header *</entry><entry>Pointer to the header.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0564Returns the checksum. <ul id="ul0028" list-style="none"><li id="ul0028-0001" num="0565"> apsasum <br /> Description </li></ul>

0566The function apsasum behaves like apasum but covers the IP addresses, ports, plus the TCP ACK and sequence numbers.

0000Syntax

0000<ul id="ul0029" list-style="none"><li id="ul0029-0001" num="0567"> static uint16 apsasum(IP4Header* hdr); </li></ul>

0568Parameters <tables id="TABLE-US-00069" num="69"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="49PT" align="left" /><colspec colname="2" colwidth="63PT" align="left" /><colspec colname="3" colwidth="91PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>hdr</entry><entry>IP4Header *</entry><entry>Pointer to the header.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0569Returns the checksum.

05704. IP Support

0571This section describes the class definitions and constants used in processing IP-layer data. Generally, all data is stored in network byte order (big endian). Thus, care should be taken by the caller to ensure computations result in proper values when processing network byte ordered data on little endian machines (e.g. in the NetBoost software-only environment on pc-compatible architectures).

0572<b>5</b>. IP Addresses <ul id="ul0030" list-style="none"><li id="ul0030-0001" num="0000"><ul id="ul0031" list-style="none"><li id="ul0031-0001" num="0573"> The IP4Addr class defines 32-bit IP version 4 addresses. </li></ul></li><li id="ul0030-0002" num="0574"> Constructors <br /> Description </li></ul>

0575The class IP4Addr is the abstraction of an IP (version 4) address within the ASL. It has two constructors, allowing for the creation of the IPv4 addresses given an unsigned 32-bit word in either host or network byte order. In addition, the class is derived from nuint32, so IP addresses may generally be treated as 32-bit integers in network byte order.

0576Syntax <tables id="TABLE-US-00070" num="70"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="70PT" align="left" /><colspec colname="1" colwidth="147PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>IP4Addr(nuint32 an);</entry></row><row><entry /><entry>IP4Addr(uint32 ah);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0577Parameters <tables id="TABLE-US-00071" num="71"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="35PT" align="left" /><colspec colname="3" colwidth="140PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>an</entry><entry>nuint32</entry><entry>Unsigned 32-bit word in network byte order.</entry></row><row><entry>ah</entry><entry>uint32</entry><entry>Unsigned 32-bit word in host byte order.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0578None.

0000Example

0579The following simple example illustrates the creation of addresses: <tables id="TABLE-US-00072" num="72"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="203PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>#include “NBip.h”</entry></row><row><entry /><entry>uint32 myhaddr = (128 &lt;&lt; 24)|(32 &lt;&lt; 16)|(12 &lt;&lt; 8)|4;</entry></row><row><entry /><entry>nuint32 mynaddr = htonl((128 &lt;&lt; 24)|(32 &lt;&lt; 16)|(12 &lt;&lt; 8)|4);</entry></row><row><entry /><entry>IP4Addr ip1(myhaddr);</entry></row><row><entry /><entry>IP4Addr ip2(mynaddr);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> This example creates two IP4Addr objects, each of which refer to the IP address 128.32.12.4. Note the use of the htonl( ) ASL function to convert the host 32-bit word into network byte order. <br /> 6. IP Masks

0580Masks are often applied to IP addresses in order to determine network or subnet numbers, CIDR blocks, etc. The class IP4Mask is the ASL abstraction for a 32-bit mask, available to be applied to an IPv4 address (or for any other use). <ul id="ul0032" list-style="none"><li id="ul0032-0001" num="0581"> Constructor <br /> Description </li></ul>

0582Instantiates the IP4Mask object with the mask specified.

0583Syntax <tables id="TABLE-US-00073" num="73"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="70PT" align="left" /><colspec colname="1" colwidth="147PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>IP4Mask(nuint32 mn);</entry></row><row><entry /><entry>IP4Mask(uint32 mh);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0584Parameters <tables id="TABLE-US-00074" num="74"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="119PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>mh</entry><entry>uint32</entry><entry>32-bit mask in host byte order</entry></row><row><entry /><entry>mn</entry><entry>nuint32</entry><entry>32-bit mask in network byte order</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0033" list-style="none"><li id="ul0033-0001" num="0585"> None. </li><li id="ul0033-0002" num="0586"> leftcontig <br /> Description </li></ul>

0587Returns true if all of the 1-bits in the mask are left-contiguous, and returns false otherwise.

0000Syntax

0000<ul id="ul0034" list-style="none"><li id="ul0034-0001" num="0588"> bool leftcontig( ); <br /> Parameters </li></ul>

0589None.

0000Return Value

0590Returns true if all the 1-bits in the mask are left-contiguous. <ul id="ul0035" list-style="none"><li id="ul0035-0001" num="0591"> bits <br /> Description </li></ul>

0592The function bits returns the number of left-contiguous 1-bits in the mask (a form of “population count”).

0000Syntax

0000<ul id="ul0036" list-style="none"><li id="ul0036-0001" num="0593"> int bits( ); <br /> Parameters </li></ul>

0594None.

0000Return Value

0595Returns the number of left-contiguous bits in the mask. Returns −1 if the 1-bits in the mask are not left-contiguous.

0596Example <tables id="TABLE-US-00075" num="75"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="21PT" align="left" /><colspec colname="1" colwidth="196PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>#inlude NBip.h</entry></row><row><entry /><entry>uint32 mymask = 0xffffff80; // 255.255.255.128 or /25</entry></row><row><entry /><entry>IP4Mask ipm(mymask);</entry></row><row><entry /><entry>int nbits = ipm.bits( );</entry></row><row><entry /><entry>if (nbits >= 0) {</entry></row><row><entry /><entry>    sprintf(msgbuf, “Mask is of the form /%d”, nbits);</entry></row><row><entry /><entry>} else {</entry></row><row><entry /><entry>    sprintf(msgbuf, “Mask is not left-contiguous!”);</entry></row><row><entry /><entry>}</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> This example creates a subnet mask with 25 bits, and sets up a message buffer containing a string which describes the form of the mask (using the common “slash notation” for subnet masks). <br /> 7. IP Header

0597The IP4Header class defines the standard IP header, where sub-byte sized fields have been merged in order to reduce byte-order dependencies. In addition to the standard IP header, the class includes a number of methods for convenience. The class contains no virtual functions, and therefore pointers to the IP4Header class may be used to point to IP headers received in live network packets.

0598The class contains a number of member functions, some of which provide direct access to the header fields and others which provide computed values based on header fields. Members which return computed values are described individually; those functions which provide only simple access to fields are as follows: <tables id="TABLE-US-00076" num="76"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="140PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Function</entry><entry>Return Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>vhl( )</entry><entry>nuint8&amp;</entry><entry>Returns a reference to the byte containing the</entry></row><row><entry /><entry /><entry>IP version and header length</entry></row><row><entry>tos( )</entry><entry>nuint8&amp;</entry><entry>Returns a reference to the IP type of service</entry></row><row><entry /><entry /><entry>byte</entry></row><row><entry>len( )</entry><entry>nuint16&amp;</entry><entry>Returns a reference to the IP datagram</entry></row><row><entry /><entry /><entry>(fragment) length in bytes</entry></row><row><entry>id( )</entry><entry>nuint16&amp;</entry><entry>Returns a reference to the IP identification field</entry></row><row><entry /><entry /><entry>(used for fragmentation)</entry></row><row><entry>offset( )</entry><entry>nuint16&amp;</entry><entry>Returns a reference to the word containing</entry></row><row><entry /><entry /><entry>fragmentation flags and fragment offset</entry></row><row><entry>ttl( )</entry><entry>nuint8&amp;</entry><entry>Returns a reference to the IP time-to-live byte</entry></row><row><entry>proto( )</entry><entry>nuint8&amp;</entry><entry>Returns a reference to the IP protocol byte</entry></row><row><entry>cksum( )</entry><entry>nuint16&amp;</entry><entry>Returns a reference to the IP checksum</entry></row><row><entry>src( )</entry><entry>IP4Addr&amp;</entry><entry>Returns a reference to the IP source address</entry></row><row><entry>dst( )</entry><entry>IP4Addr&amp;</entry><entry>Returns a reference to the IP destination</entry></row><row><entry /><entry /><entry>address</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> The following member functions of the IP4Header class provide convenient methods for accessing various information about an IP header. <ul id="ul0037" list-style="none"><li id="ul0037-0001" num="0599"> optbase <br /> Description </li></ul>

0600Returns the location of the first IP option in the IP header (if present).

0000Syntax

0000<ul id="ul0038" list-style="none"><li id="ul0038-0001" num="0601"> unsigned char* optbase( ); <br /> Parameters </li><li id="ul0038-0002" num="0602"> None. <br /> Return Value </li></ul>

0603Returns the address of the first option present in the header. If no options are present, it returns the address of the first byte of the payload. <ul id="ul0039" list-style="none"><li id="ul0039-0001" num="0604"> hl <br /> Description </li></ul>

0605The first form of this function returns the number of 32-bit words in the IP header. The second form modifies the header length field to be equal to the specified length.

0606Syntax <tables id="TABLE-US-00077" num="77"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="84PT" align="left" /><colspec colname="1" colwidth="133PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>int hl( );</entry></row><row><entry /><entry>void hl(int h);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0607Parameters <tables id="TABLE-US-00078" num="78"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="21PT" align="left" /><colspec colname="3" colwidth="161PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>h</entry><entry>int</entry><entry>Specifies the header length (in 32-bit words) to assign</entry></row><row><entry /><entry /><entry>to the IP header</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0608The first form of this function returns the number of 32-bit words in the IP header. <ul id="ul0040" list-style="none"><li id="ul0040-0001" num="0609"> hlen <br /> Description </li></ul>

0610The function hlen returns the number of bytes in the IP header (including options).

0000Syntax

0000<ul id="ul0041" list-style="none"><li id="ul0041-0001" num="0611"> int hlen( ); <br /> Parameters </li></ul>

0612None.

0000Return Value

0613Returns the number of bytes in the IP header including options. <ul id="ul0042" list-style="none"><li id="ul0042-0001" num="0614"> ver <br /> Description </li></ul>

0615The first form of this function ver returns the version field of the IP header (should be 4).

0616The second form assigns the version number to the IP header.

0617Syntax <tables id="TABLE-US-00079" num="79"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="84PT" align="left" /><colspec colname="1" colwidth="133PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>int ver( );</entry></row><row><entry /><entry>void ver(int v);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0618Parameters <tables id="TABLE-US-00080" num="80"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="49PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="112PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>v</entry><entry>int</entry><entry>Specifies the version number.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0619The first form returns the version field of the IP header. <ul id="ul0043" list-style="none"><li id="ul0043-0001" num="0620"> payload <br /> Description </li></ul>

0621The function payload returns the address of the first byte of data (beyond any options present).

0000Syntax

0000<ul id="ul0044" list-style="none"><li id="ul0044-0001" num="0622"> unsigned char* payload( ); <br /> Parameters </li></ul>

0623None.

0000Return Value

0624Returns the address of the first byte of payload data in the IP packet. <ul id="ul0045" list-style="none"><li id="ul0045-0001" num="0625"> psum <br /> Description </li></ul>

0626The function psum is used internally by the ASL library, but may be useful to some applications. It returns the 16-bit one's complement sum of the source and destination IP addresses plus 8-bit protocol field [in the low-order byte]. It is useful in computing pseudo-header checksums for UDP and TCP.

0000Syntax

0000<ul id="ul0046" list-style="none"><li id="ul0046-0001" num="0627"> uint32 psum( ); <br /> Parameters </li></ul>

0628None.

0000Return Value

0629Returns the 16-bit one's complement sum of the source and destination IP addresses plus the 8-bit protocol field.

0000Definitions

0630In addition to the IP header itself, a number of definitions are provided for manipulating fields of the IP header with specific semantic meanings.

0631Fragmentation <tables id="TABLE-US-00081" num="81"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="49PT" align="left" /><colspec colname="2" colwidth="28PT" align="left" /><colspec colname="3" colwidth="140PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Define</entry><entry>Value</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>IP_DF</entry><entry>0x4000</entry><entry>Don't fragment flag, RFC 791, p. 13.</entry></row><row><entry>IP_MF</entry><entry>0x2000</entry><entry>More fragments flag, RFC 791, p. 13.</entry></row><row><entry>IP_OFFMASK</entry><entry>0x1FFF</entry><entry>Mask for determining the fragment offset from</entry></row><row><entry /><entry /><entry>the IP header offset( ) function.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0632Limitations <tables id="TABLE-US-00082" num="82"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="35PT" align="left" /><colspec colname="3" colwidth="98PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>IP_MAXPACKET</entry><entry>65535</entry><entry>Maximum IP datagram size.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> IP Service Type

0633The following table contains the definitions for IP type of service byte (not commonly used): <tables id="TABLE-US-00083" num="83"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="77PT" align="left" /><colspec colname="2" colwidth="49PT" align="center" /><colspec colname="3" colwidth="77PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Define</entry><entry>Value</entry><entry>Reference</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>IPTOS_LOWDELAY</entry><entry>0x10</entry><entry>RFC 791, p. 12.</entry></row><row><entry /><entry>IPTOS_THROUGHPUT</entry><entry>0x08</entry><entry>RFC 791, p. 12.</entry></row><row><entry /><entry>IPTOS_RELIABILITY</entry><entry>0x04</entry><entry>RFC 791, p. 12.</entry></row><row><entry /><entry>IPTOS_MINCOST</entry><entry>0X02</entry><entry>RFC 1349.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> IP Precedence

0634The following table contains the definitions for IP precedence. All are from RFC 791, p. 12 (not widely used). <tables id="TABLE-US-00084" num="84"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="126PT" align="left" /><colspec colname="2" colwidth="63PT" align="center" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="2" align="center" rowsep="1" /></row><row><entry /><entry>Define</entry><entry>Value</entry></row><row><entry /><entry namest="OFFSET" nameend="2" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>IPTOS_PREC_NETCONTROL</entry><entry>0xE0</entry></row><row><entry /><entry>IPTOS_PREC_INTERNETCONTROL</entry><entry>0xC0</entry></row><row><entry /><entry>IPTOS_PREC_CRITIC_ECP</entry><entry>0xA0</entry></row><row><entry /><entry>IPTOS_PREC_FLASHOVERRIDE</entry><entry>0x80</entry></row><row><entry /><entry>IPTOS_PREC_FLASH</entry><entry>0x60</entry></row><row><entry /><entry>IPTOS_PREC_IMMEDIATE</entry><entry>0x40</entry></row><row><entry /><entry>IPTOS_PREC_PRIORITY</entry><entry>0x20</entry></row><row><entry /><entry>IPTOS_PREC_ROUTINE</entry><entry>0x00</entry></row><row><entry /><entry namest="OFFSET" nameend="2" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Option Definitions

0635The following table contains the definitions for supporting IP options. All definitions are from RFC 791, pp. 15-23. <tables id="TABLE-US-00085" num="85"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="70PT" align="left" /><colspec colname="2" colwidth="42PT" align="center" /><colspec colname="3" colwidth="105PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Define</entry><entry>Value</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>IPOPT_COPIED(o)</entry><entry>((o)&amp;0x80)</entry><entry>A macro which returns true if the</entry></row><row><entry /><entry /><entry>option ‘o’ is to be copied upon</entry></row><row><entry /><entry /><entry>fragmentation.</entry></row><row><entry>IPOPT_CLASS(o)</entry><entry>((o)&amp;0x60)</entry><entry>A macro giving the option class</entry></row><row><entry /><entry /><entry>for the option ‘o’</entry></row><row><entry>IPOPT_NUMBER(o)</entry><entry>((o)&amp;0x1F)</entry><entry>A macro giving the option number</entry></row><row><entry /><entry /><entry>for the option ‘o’</entry></row><row><entry>IPOPT_CONTROL</entry><entry>0x00</entry><entry>Control class</entry></row><row><entry>IPOPT_RESERVED1</entry><entry>0x20</entry><entry>Reserved</entry></row><row><entry>IPOPT_DEBMEAS</entry><entry>0x40</entry><entry>Debugging and/or measurement</entry></row><row><entry /><entry /><entry>class</entry></row><row><entry>IPOPT_RESERVED2</entry><entry>0x60</entry><entry>Reserved</entry></row><row><entry>IPOPT_EOL</entry><entry>0</entry><entry>End of option list.</entry></row><row><entry>IPOPT_NOP</entry><entry>1</entry><entry>No operation.</entry></row><row><entry>IPOPT_RR</entry><entry>7</entry><entry>Record packet route.</entry></row><row><entry>IPOPT_TS</entry><entry>68</entry><entry>Time stamp.</entry></row><row><entry>IPOPT_SECURITY</entry><entry>130</entry><entry>Provide s, c, h, tcc.</entry></row><row><entry>IPOPT_LSRR</entry><entry>131</entry><entry>Loose source route.</entry></row><row><entry>IPOPT_SATID</entry><entry>136</entry><entry>Satnet ID.</entry></row><row><entry>IPOPT_SSRR</entry><entry>137</entry><entry>Strict source route.</entry></row><row><entry>IPOPT_RA</entry><entry>148</entry><entry>Router alert.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Options Field Offsets

0636The following table contains the offsets to fields in options other than EOL and NOP. <tables id="TABLE-US-00086" num="86"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="63PT" align="left" /><colspec colname="2" colwidth="49PT" align="center" /><colspec colname="3" colwidth="91PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Define</entry><entry>Value</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>IPOPT_OPTVAL</entry><entry>0</entry><entry>Option ID.</entry></row><row><entry /><entry>IPOPT_OLEN</entry><entry>1</entry><entry>Option length.</entry></row><row><entry /><entry>IPOPT_OFFSET</entry><entry>2</entry><entry>Offset within option.</entry></row><row><entry /><entry>IPOPT_MINOFF</entry><entry>4</entry><entry>Minimum value of offset.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> 7. Fragments and Datagrams

0637The IP protocol performs adaptation of its datagram size by an operation known as fragmentation. Fragmentation allows for an initial (large) IP datagram to be broken into a sequence of IP fragments, each of which is treated as an independent packet until they are received and reassembled at the original datagram's ultimate destination. Conventional IP routers never reassemble fragments but instead route them independently, leaving the destination host to reassemble them. In some circumstances, however, applications running on the NetBoost platform may wish to reassemble fragments themselves (e.g. to simulate the operation of the destination host).

00008. IP Fragment Class

0638Within the ASL, a fragment represents a single IP packet (containing an IP header), which may or not be a complete IP layer datagram. In addition, a datagram within the ASL represents a collection of fragments. A datagram (or fragment) is said to be complete if it represents or contains all the fragments necessary to represent an entire IP-layer datagram.

0639The IP4Fragment class is defined as follows. <ul id="ul0047" list-style="none"><li id="ul0047-0001" num="0640"> Constructors <br /> Description </li></ul>

0641The IP4Fragment class provides the abstraction of a single IP packet placed in an ASL buffer (see the description of the Buffer elsewhere in this chapter). It has two constructors intended for use by applications. <ul id="ul0048" list-style="none"><li id="ul0048-0001" num="0000"><ul id="ul0049" list-style="none"><li id="ul0049-0001" num="0642"> The first of these allows for specifying the buffer containing an IP fragment as the parameter bp. The location of the of the IP header within the buffer is the second argument. This is the most commonly-used constructor when processing IP fragments in ACE action code. </li><li id="ul0049-0002" num="0643"> The second form of the constructor performs the same steps as the first form, but also allocates a new Buffer object and copies the IP header pointed to by iph into the new buffer (if specified). This form of the constructor is primarily intended for creation of IP fragments during IP datagram fragmentation. If the specified header contains IP options, only those options which are copied during fragmentation are copied. </li></ul></li></ul>

0644Syntax <tables id="TABLE-US-00087" num="87"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="189PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>IP4Fragment(Buffer* bp, IP4Header* iph);</entry></row><row><entry /><entry>IP4Fragment(int maxiplen, IP4Header* protohdr = 0);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0645Parameters <tables id="TABLE-US-00088" num="88"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="133PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>bp</entry><entry>Buffer *</entry><entry>The starting address of the buffer containing</entry></row><row><entry /><entry /><entry>the IP fragment</entry></row><row><entry>maxiplen</entry><entry>int</entry><entry>The maximum size of the fragment being</entry></row><row><entry /><entry /><entry>created; used to size the allocated Buffer.</entry></row><row><entry>protohdr</entry><entry>IP4Header *</entry><entry>The IP4 header to copy into the buffer, if</entry></row><row><entry /><entry /><entry>provided. If the header contains IP options,</entry></row><row><entry /><entry /><entry>only those options normally copied during</entry></row><row><entry /><entry /><entry>fragmentation are copied.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0646None. <ul id="ul0050" list-style="none"><li id="ul0050-0001" num="0647"> Destructor <br /> Description </li></ul>

0648Frees the fragment.

0000Syntax

0000<ul id="ul0051" list-style="none"><li id="ul0051-0001" num="0649"> ˜IP4Fragment( ); <br /> Parameters </li><li id="ul0051-0002" num="0650"> None. <br /> Return Value </li><li id="ul0051-0003" num="0651"> None. </li><li id="ul0051-0004" num="0652"> hdr <br /> Description </li></ul>

0653The function hdr returns the address of the IP header of the fragment.

0000Syntax

0000<ul id="ul0052" list-style="none"><li id="ul0052-0001" num="0654"> IP4Header* hdr( ); <br /> Parameters </li></ul>

0655None.

0000Return Value

0656Returns the address of the IP4Header class at the beginning of the fragment. <ul id="ul0053" list-style="none"><li id="ul0053-0001" num="0657"> payload <br /> Description </li></ul>

0658The function payload returns the address of the first byte of data in the IP fragment (after the basic header and options).

0000Syntax

0000<ul id="ul0054" list-style="none"><li id="ul0054-0001" num="0659"> u_char* payload( ); <br /> Parameters </li></ul>

0660None.

0000Return Value

0661Returns the address of the first byte of data in the IP fragment. <ul id="ul0055" list-style="none"><li id="ul0055-0001" num="0662"> buf <br /> Description </li></ul>

0663The function buf returns the address of the Buffer structure containing the IP fragment.

0000Syntax

0000<ul id="ul0056" list-style="none"><li id="ul0056-0001" num="0664"> Buffer* buf( ); <br /> Parameters </li></ul>

0665None.

0000Return Value

0666Returns the address of the Buffer structure containing the IP fragment. This may return NULL if there is no buffer associated with the fragment. <ul id="ul0057" list-style="none"><li id="ul0057-0001" num="0667"> next <br /> Description </li></ul>

0668Returns a reference to the pointer pointing to the next fragment of a doubly-linked list of fragments. This is used to link together fragments when they are reassembled (in Datagrams), or queued, etc. Typically, fragments are linked together in a doubly-linked list fashion with NULL pointers indicating the list endpoints.

0000Syntax

0000<ul id="ul0058" list-style="none"><li id="ul0058-0001" num="0669"> IP4Fragment*&amp; next( ); <br /> Parameters </li></ul>

0670None.

0000Return Value

0671Returns a reference to the internal linked-list pointer. <ul id="ul0059" list-style="none"><li id="ul0059-0001" num="0672"> prev <br /> Description </li></ul>

0673Like next, but returns a reference to pointer to the previous fragment on the list.

0000Syntax

0000<ul id="ul0060" list-style="none"><li id="ul0060-0001" num="0674"> IP4Fragment*&amp; prev( ); <br /> Parameters </li></ul>

0675None.

0000Return Value

0676Returns a reference to the internal linked-list pointer. <ul id="ul0061" list-style="none"><li id="ul0061-0001" num="0677"> first <br /> Description </li></ul>

0678The function first returns true when the fragment represents the first fragment of a datagram.

0000Syntax

0000<ul id="ul0062" list-style="none"><li id="ul0062-0001" num="0679"> bool first( ); <br /> Parameters </li></ul>

0680None.

0000Return Value

0681Returns true when the fragment represents the first fragment of a datagram. <ul id="ul0063" list-style="none"><li id="ul0063-0001" num="0682"> fragment <br /> Description </li></ul>

0683Fragments an IP datagram comprising a single fragment. The fragment( ) function allocates Buffer structures to hold the newly-formed IP fragments and links them together. It returns the head of the doubly-linked list of fragments. Each fragment in the list will be limited in size to at most the specified MTU size. The original fragment is unaffected.

0000Syntax

0000<ul id="ul0064" list-style="none"><li id="ul0064-0001" num="0684"> IP4Datagram* fragment(int mtu); </li></ul>

0685Parameters <tables id="TABLE-US-00089" num="89"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="21PT" align="left" /><colspec colname="3" colwidth="161PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>mtu</entry><entry>int</entry><entry>The maximum transmission unit MTU size limiting the</entry></row><row><entry /><entry /><entry>maximum fragment size</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0686Returns a pointer to an IP4Datagram object containing a doubly-linked list of IP4Fragment objects. Each fragment object is contained within a Buffer class allocated by the ASL library. The original fragment object (the one fragmented) is not freed by this function. The caller must free the original fragment when it is no longer needed. <ul id="ul0065" list-style="none"><li id="ul0065-0001" num="0687"> complete <br /> Description </li></ul>

0688The function complete returns true when the fragment represents a complete IP datagram.

0000Syntax

0000<ul id="ul0066" list-style="none"><li id="ul0066-0001" num="0689"> bool complete( ); <br /> Parameters </li></ul>

0690None.

0000Return Value

0691Returns true when the fragment represents a complete IP datagram (that is, when the fragment offset field is zero and there are no additional fragments). <ul id="ul0067" list-style="none"><li id="ul0067-0001" num="0692"> optcopy <br /> Description </li></ul>

0693The static method optcopy is used to copy options from one header to another during IP fragmentation. The function will only copy those options that are supposed to be copied during fragmentation (i.e. for those options x where the macro IPOPT_COPIED(x) is non zero (true)).

0000Syntax

0000<ul id="ul0068" list-style="none"><li id="ul0068-0001" num="0694"> static int optcopy(IP4Header* src, IP4Header* dst); </li></ul>

0695Parameters <tables id="TABLE-US-00090" num="90"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="133PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>src</entry><entry>IP4Header *</entry><entry>Pointer to the source IP header containing</entry></row><row><entry /><entry /><entry>options</entry></row><row><entry>dst</entry><entry>IP4Header *</entry><entry>Pointer to the destination, where the source</entry></row><row><entry /><entry /><entry>header should be copied to</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0696Returns the number of bytes of options present in the destination IP header.

00009. IP Datagram Class

0697The class IP4Datagram represents a collection of IP fragments, which may (or may not) represent a complete IP4datagram. Note that objects of the class IP4Datagram include a doubly-linked list of IP4Fragment objects in sorted order (sorted by IP offset). When IP fragments are inserted into a datagram (in order to perform reassembly), coalescing of data between fragments is not performed automatically. Thus, although the IP4Datagram object may easily determine whether it contains a complete set of fragments, it does not automatically reconstruct a contiguous buffer of the original datagram's contents for the caller.

0698This class supports the fragmentation, reassembly, and grouping of IP fragments. The IP4Datagram class is defined as follows: <ul id="ul0069" list-style="none"><li id="ul0069-0001" num="0699"> Constructors <br /> Description </li></ul>

0700The class has two constructors. <ul id="ul0070" list-style="none"><li id="ul0070-0001" num="0000"><ul id="ul0071" list-style="none"><li id="ul0071-0001" num="0701"> The first form of the constructor is used when creating a fresh datagram (typically for starting the process of reassembly). </li><li id="ul0071-0002" num="0702"> The second form is useful when an existing list of fragments are to be placed into the datagram immediately at its creation. </li></ul></li></ul>

0703Syntax <tables id="TABLE-US-00091" num="91"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="56PT" align="left" /><colspec colname="1" colwidth="161PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>IP4Datagram( );</entry></row><row><entry /><entry>IP4Datagram(IP4Fragment* frag);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0704Parameters <tables id="TABLE-US-00092" num="92"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="126PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>frag</entry><entry>IP4Fragment *</entry><entry>Pointer to a doubly linked list of fragments</entry></row><row><entry /><entry /><entry>used to create the datagram object</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0705None. <ul id="ul0072" list-style="none"><li id="ul0072-0001" num="0706"> Destructor <br /> Description </li></ul>

0707The destructor calls the destructors for each of the fragments comprising the datagram and frees the datagram object. <ul id="ul0073" list-style="none"><li id="ul0073-0001" num="0708"> len <br /> Description </li></ul>

0709The len function returns the entire length (in bytes) of the datagram, including all of its comprising fragments. Its value is only meaningful if the datagram is complete.

0000Syntax

0000<ul id="ul0074" list-style="none"><li id="ul0074-0001" num="0710"> int len( ); <br /> Parameters </li></ul>

0711None.

0000Return Value

0712Returns the length of the entire datagram (in bytes). If the datagram contains multiple fragments, only the size of the first fragment header is included in this value. <ul id="ul0075" list-style="none"><li id="ul0075-0001" num="0713"> fragment <br /> Description </li></ul>

0714The fragment function breaks an IP datagram into a series of IP fragments, each of which will fit in the packet size specified by mtu. Its behavior is equivalent to the <ul id="ul0076" list-style="none"><li id="ul0076-0001" num="0715"> IP4Fragment::fragment (int mtu) function described previously. <br /> Syntax </li><li id="ul0076-0002" num="0716"> IP4Datagram* fragment(int mtu); <br /> Parameters </li><li id="ul0076-0003" num="0717"> See IP4Fragment::fragment (int mtu) above. <br /> Return Value </li></ul>

0718See IP4Fragment::fragment (int mtu) above. <ul id="ul0077" list-style="none"><li id="ul0077-0001" num="0719"> insert <br /> Description </li></ul>

0720The function insert inserts a fragment into the datagram. The function attempts to reassemble the overall datagram by checking the IP offset and ID fields.

0000Syntax

0000<ul id="ul0078" list-style="none"><li id="ul0078-0001" num="0721"> int insert(IP4Fragment* frag); </li></ul>

0722Parameters <tables id="TABLE-US-00093" num="93"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="119PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>frag</entry><entry>IP4Fragment *</entry><entry>Pointer to the fragment being inserted.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0723Because this function can fail/act in a large number of ways, the following definitions are provided to indicate the results of insertions that were attempted by the caller. The return value is a 32-bit word where each bit indicates a different error or unusual condition. The first definition below, IPD_INSERT_ERROR is set whenever any of the other conditions are encountered. This is an extensible list which may evolve to indicate new error conditions in future releases: <tables id="TABLE-US-00094" num="94"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="98PT" align="left" /><colspec colname="2" colwidth="119PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row><row><entry>Define</entry><entry>Description</entry></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>IPD_INSERT_ERROR</entry><entry>‘Or’ of all other error bits.</entry></row><row><entry>IPD_INSERT_OH</entry><entry>Head overlapped.</entry></row><row><entry>IPD_INSERT_OT</entry><entry>Tail overlapped.</entry></row><row><entry>IPD_INSERT_MISMATCH</entry><entry>Payload mismatch.</entry></row><row><entry>IPD_INSERT_CKFAIL</entry><entry>IP header checksum failed (if enabled)</entry></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><ul id="ul0079" list-style="none"><li id="ul0079-0001" num="0724"> nfrags <br /> Description </li></ul>

0725The function nfrags returns the number of fragments currently present in the datagram.

0726Syntax <tables id="TABLE-US-00095" num="95"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="84PT" align="left" /><colspec colname="1" colwidth="133PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>int nfrags( );</entry></row><row><entry /><entry>complete</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Description

0727The function complete returns true when all fragments comprising the original datagram are present.

0000Syntax

0000<ul id="ul0080" list-style="none"><li id="ul0080-0001" num="0728"> bool complete( ); <br /> Parameters </li></ul>

0729None.

0000Return Value

0730Returns a boolean value indicating when all fragments comprising the original datagram are present. <ul id="ul0081" list-style="none"><li id="ul0081-0001" num="0731"> head <br /> Description </li></ul>

0732The function head returns the address of the first IP fragment in the datagram's linked list of fragments.

0000Syntax

0000<ul id="ul0082" list-style="none"><li id="ul0082-0001" num="0733"> IP4Fragment* head( ); <br /> Parameters </li></ul>

0734None.

0000Return Value

0735Returns the address of the first IP fragment in the datagram's linked list of fragments.

000010. UDP Support

0736The UDP protocol provides a best-effort datagram service. Due to its limited complexity, only the simple UDP header definitions are included here. Additional functions operating on several protocols (eg. UDP and TCP NAT) are defined in subsequent sections.

000011. UDP Header

0737The UDPHeader class defines the standard UDP header. It is defined in NBudp.h. In addition to the standard UDP header, the class includes a single method for convenience in accessing the payload portion of the UDP datagram. The class contains no virtual functions, and therefore pointers to the UDPHeader class may be used to point to UDP headers received in live network packets.

0738The class contains a number of member functions, most of which provide direct access to the header fields. A special payload function may be used to obtain a pointer immediately beyond the UDP header. The following table lists the functions providing direct access to the header fields: <tables id="TABLE-US-00096" num="96"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="140PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Function</entry><entry>Return Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>sport( )</entry><entry>nuint16&amp;</entry><entry>Returns a reference to the source UDP port</entry></row><row><entry /><entry /><entry>number</entry></row><row><entry>dport( )</entry><entry>nuint16&amp;</entry><entry>Returns a reference to the destination UDP port</entry></row><row><entry /><entry /><entry>number</entry></row><row><entry>len( )</entry><entry>nuint16&amp;</entry><entry>Returns a reference to the UDP length field</entry></row><row><entry>cksum( )</entry><entry>nuint16&amp;</entry><entry>Returns a reference to the UDP pseudoheader</entry></row><row><entry /><entry /><entry>checksum. UDP checksums are optional; a</entry></row><row><entry /><entry /><entry>value of all zero bits indicate no checksum is</entry></row><row><entry /><entry /><entry>was computed.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> The following function provides convenient access to the payload portion of the datagram, and maintains consistency with other protocol headers (ie. IP and TCP). <ul id="ul0083" list-style="none"><li id="ul0083-0001" num="0739"> payload <br /> Description </li></ul>

0740The function payload returns the address of the first byte of data (beyond the UDP header).

0000Syntax

0000<ul id="ul0084" list-style="none"><li id="ul0084-0001" num="0741"> unsigned char* payload( ); <br /> Parameters </li><li id="ul0084-0002" num="0742"> None. <br /> Return Value </li></ul>

0743Returns the address of the first byte of payload data in the UDP packet.

000012. TCP Support

0744The TCP protocol provides a stateful connection-oriented stream service. The ASL provides the TCP-specific definitions, including the TCP header, plus a facility to monitor the content and progress of an active TCP flow as a third party (i.e. without having to be an endpoint). For address and port number translation of TCP, see the section on NAT in subsequent sections of this document.

000013. TCP Sequence Numbers

0745TCP uses sequence numbers to keep track of an active data transfer. Each unit of data transfer is called a segment, and each segment contains a range of sequence numbers. In TCP, sequence numbers are in byte units. If a TCP connection is open and data transfer is progressing from computer A to B, TCP segments will be flowing from A to B and acknowledgements will be flowing from B toward A. The acknowledgements indicate to the sender the amount of data the receiver has received. TCP is a bidirectional protocol, so that data may be flowing simultaneously from A to B and from B to A. In such cases, each segment (in both directions) contains data for one direction of the connection and acknowledgements for the other direction of the connection. Both sequence numbers (sending direction) and acknowledgement numbers (reverse direction) use TCP sequence numbers as the data type in the TCP header. TCP sequence numbers are 32-bit unsigned numbers that are allowed to wrap beyond 2ˆ32-1. Within the ASL, a special class called TCPSeq defines this class and associated operators, so that objects of this type may be treated like ordinary scalar types (e.g. unsigned integers).

000014. TCP Header

0746The TCPHeader class defines the standard TCP header. In addition to the standard TCP header, the class includes a set of methods for convenience in accessing the payload portion of the TCP stream. The class contains no virtual functions, and therefore pointers to the TCPHeader class may be used to point to TCP headers received in live network packets.

0747The class contains a number of member functions, most of which provide direct access to the header fields. A special payload function may be used to obtain a pointer immediately beyond the TCP header. The following table lists the functions providing direct access to the header fields: <tables id="TABLE-US-00097" num="97"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="140PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Function</entry><entry>Return Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>sport( )</entry><entry>nuint16&amp;</entry><entry>Returns a reference to the source TCP port</entry></row><row><entry /><entry /><entry>number</entry></row><row><entry>dport( )</entry><entry>nuint16&amp;</entry><entry>Returns a reference to the destination TCP port</entry></row><row><entry /><entry /><entry>number</entry></row><row><entry>seq( )</entry><entry>TCPSeq&amp;</entry><entry>Returns a reference to the TCP sequence</entry></row><row><entry /><entry /><entry>number</entry></row><row><entry>ack( )</entry><entry>TCPSeq&amp;</entry><entry>Returns a reference to the TCP</entry></row><row><entry /><entry /><entry>acknowledgement number</entry></row><row><entry>off( )</entry><entry>nuint8</entry><entry>Returns the number of 32-bit words in the TCP</entry></row><row><entry /><entry /><entry>header (includes TCP options)</entry></row><row><entry>flags( )</entry><entry>nuint8&amp;</entry><entry>Returns a reference to the byte containing the</entry></row><row><entry /><entry /><entry>6 flags bits (and 2 reserved bits)</entry></row><row><entry>win( )</entry><entry>nuint16&amp;</entry><entry>Returns a reference to the window</entry></row><row><entry /><entry /><entry>advertisement field (unscaled)</entry></row><row><entry>cksum( )</entry><entry>nuint16&amp;</entry><entry>Returns a reference to the TCP pseudoheader</entry></row><row><entry /><entry /><entry>checksum. TCP checksums are not optional.</entry></row><row><entry>udp( )</entry><entry>nuint16&amp;</entry><entry>Returns a reference to the TCP urgent pointer</entry></row><row><entry /><entry /><entry>field</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> The following functions provides convenient access to other characteristics of the segment: <ul id="ul0085" list-style="none"><li id="ul0085-0001" num="0748"> payload <br /> Description </li></ul>

0749The function payload returns the address of the first byte of data (beyond the TCP header).

0000Syntax

0000<ul id="ul0086" list-style="none"><li id="ul0086-0001" num="0750"> unsigned char* payload( ); <br /> Parameters </li><li id="ul0086-0002" num="0751"> None. <br /> Return Value </li></ul>

0752Returns the address of the first byte of payload data in the TCP packet. <ul id="ul0087" list-style="none"><li id="ul0087-0001" num="0753"> window <br /> Description </li></ul>

0754The function window returns the window advertisement contained in the segment, taking into account the use of TCP large windows (see RFC 1323).

0000Syntax

0000<ul id="ul0088" list-style="none"><li id="ul0088-0001" num="0755"> uint32 window(int wshift) </li></ul>

0756Parameters <tables id="TABLE-US-00098" num="98"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="28PT" align="left" /><colspec colname="3" colwidth="133PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>wshift</entry><entry>int</entry><entry>The “window shift value” (number of left-</entry></row><row><entry /><entry /><entry /><entry>shift bit positions to scale window field)</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0757Returns the receiver's advertised window in the segment (in bytes). This function is to be used when RFC1323-style window scaling is in use. <ul id="ul0089" list-style="none"><li id="ul0089-0001" num="0758"> optbase <br /> Description </li></ul>

0759The function optbase returns the address of the first option in the TCP header, if any are present. If no options are present, it returns the address of the first payload byte (which may be urgent data if the URG bit is set in the flags field).

0000Syntax

0000<ul id="ul0090" list-style="none"><li id="ul0090-0001" num="0760"> u_char* optbase( ) <br /> Parameters </li><li id="ul0090-0002" num="0761"> None. <br /> Return Value </li></ul>

0762Returns the address of the first byte of data beyond the urgent pointer field of the TCP header. <ul id="ul0091" list-style="none"><li id="ul0091-0001" num="0763"> hlen <br /> Description </li></ul>

0764The first form of this function ver returns the TCP header length in bytes. The second form assigns the TCP header length to the number of bytes specified.

0765Syntax <tables id="TABLE-US-00099" num="99"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="77PT" align="left" /><colspec colname="1" colwidth="140PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>int hlen( );</entry></row><row><entry /><entry>void hlen(int bytes);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0766Parameters <tables id="TABLE-US-00100" num="100"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="56PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="105PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>bytes</entry><entry>int</entry><entry>Specifies the number of bytes</entry></row><row><entry /><entry /><entry /><entry>present in the TCP header</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0767The first form returns the number of bytes in the TCP header.

0000Definitions

0768In addition to the TCP header itself, a number of definitions are provided for manipulating options in TCP headers:

0769TCP Options <tables id="TABLE-US-00101" num="101"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="105PT" align="left" /><colspec colname="2" colwidth="21PT" align="center" /><colspec colname="3" colwidth="91PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Define</entry><entry>Value</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="105PT" align="left" /><colspec colname="2" colwidth="21PT" align="char" char="." /><colspec colname="3" colwidth="91PT" align="left" /><tbody valign="top"><row><entry>TCPOPT_EOL</entry><entry>0</entry><entry>End of Option List</entry></row><row><entry>TCPOPT_NOP</entry><entry>1</entry><entry>No operation (used for</entry></row><row><entry /><entry /><entry>padding</entry></row><row><entry>TCPOPT_MAXSEG</entry><entry>2</entry><entry>Maximum segment size</entry></row><row><entry>TCPOPT_SACK_PERMITTED</entry><entry>4</entry><entry>Selective Acknowledgements</entry></row><row><entry /><entry /><entry>available</entry></row><row><entry>TCPOPT_SACK</entry><entry>5</entry><entry>Selective Acknowledgements</entry></row><row><entry /><entry /><entry>in this segment</entry></row><row><entry>TCPOPT_TIMESTAMP</entry><entry>8</entry><entry>Time stamps</entry></row><row><entry>TCPOPT_CC</entry><entry>11</entry><entry>for T/TCP (see RFC 1644)</entry></row><row><entry>TCPOPT_CCNEW</entry><entry>12</entry><entry>for T/TCP</entry></row><row><entry>TCPOPT_CCECHO</entry><entry>13</entry><entry>for T/TCP</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> 15. TCP Following

0770TCP operates as an 11-state finite state machine. Most of the states are related to connection establishment and tear-down. By following certain control bits in the TCP headers of segments passed along a connection, it is possible to infer the TCP state at each endpoint, and to monitor the data exchanged between the two endpoints.

0000Defines

0771The following definitions are for TCP state monitoring, and indicate states in the TCP finite state machine: <tables id="TABLE-US-00102" num="102"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="105PT" align="left" /><colspec colname="2" colwidth="105PT" align="center" /><colspec colname="3" colwidth="105PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Define</entry><entry>Value</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /></row></tbody></tgroup><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="105PT" align="left" /><colspec colname="2" colwidth="105PT" align="char" char="." /><colspec colname="3" colwidth="105PT" align="left" /><tbody valign="top"><row><entry>TCPS_CLOSED</entry><entry>0</entry><entry>Closed</entry></row><row><entry>TCPS_LISTEN</entry><entry>1</entry><entry>Listening for connection.</entry></row><row><entry>TCPS_SYN_SENT</entry><entry>2</entry><entry>Active open, have sent SYN.</entry></row><row><entry>TCPS_SYN_RECEIVED</entry><entry>3</entry><entry>Have sent and received SYN.</entry></row><row><entry>TCPS_ESTABLISHED</entry><entry>4</entry><entry>Established.</entry></row><row><entry>TCPS_CLOSE_WAIT</entry><entry>5</entry><entry>Received FIN, waiting for closed.</entry></row><row><entry>TCPS_FIN_WAIT_1</entry><entry>6</entry><entry>Have closed, sent FIN.</entry></row><row><entry>TCPS_CLOSING</entry><entry>7</entry><entry>Closed exchanged FIN; awaiting</entry></row><row><entry /><entry /><entry>FIN ACK.</entry></row><row><entry>TCPS_LAST_ACK</entry><entry>8</entry><entry>Had FIN and close; await FIN</entry></row><row><entry /><entry /><entry>ACK.</entry></row><row><entry>TCPS_FIN_WAIT_2</entry><entry>9</entry><entry>Have closed, FIN is acked.</entry></row><row><entry>TCPS_TIME_WAIT</entry><entry>10</entry><entry>In 2*MSL quiet wait after close.</entry></row><row><entry>TCPS_HAVERCVDSYN(s)</entry><entry>((s) >= TCPS_SYN_RECEIVED)</entry><entry>True if state s indicates a SYN has</entry></row><row><entry /><entry /><entry>been received</entry></row><row><entry>TCPS_HAVEESTABLISHED(s)</entry><entry>((s) >= TCPS_ESTABLISHED)</entry><entry>True if state s indicates have</entry></row><row><entry /><entry /><entry>established ever</entry></row><row><entry>TCPS_HAVERCVDFIN(s)</entry><entry>((s) >= TCPS_TIME_WAIT)</entry><entry>True if state s indicates a FIN ever</entry></row><row><entry /><entry /><entry>received</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry namest="1" nameend="3" align="left" id="FOO-00018"><br />Note 1: <br /></entry></row><row><entry namest="1" nameend="3" align="left" id="FOO-00019"><br />States less than TCPS_ESTABLISHED indicate connections not yet established. <br /></entry></row><row><entry namest="1" nameend="3" align="left" id="FOO-00020"><br />Note 2: <br /></entry></row><row><entry namest="1" nameend="3" align="left" id="FOO-00021"><br />States greater than TCPS_CLOSE_WAIT are those where the user has closed. <br /></entry></row><row><entry namest="1" nameend="3" align="left" id="FOO-00022"><br />Note 3: <br /></entry></row><row><entry namest="1" nameend="3" align="left" id="FOO-00023"><br />States greater than TCPS_CLOSE_WAIT and less than TCPS_FIN_WAIT_2 await ACK of FIN. <br /></entry></row></tbody></tgroup></table></tables><br /> The TCPSegInfo Class

0772The TCPSegInfo class is a container class for TCP segments that have been queued during TCP stream reconstruction and may be read by applications (using the ReassemblyQueue::read function, defined below). When segments are queued, they are maintained in a doubly-linked list sorted by sequence number order. Note that the list may contain “holes”. That is, it may contain segments that are not adjacent in the space of sequence numbers because some data is missing in between. In addition, because retransmitted TCP segments can potentially overlap one another's data areas, the starting and ending sequence number fields (startseq_ and endseq_) may not correspond to the starting sequence number

0773The class contains the following fields, all of which are declared public: <tables id="TABLE-US-00103" num="103"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="133PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Field</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>prev_—</entry><entry>TCPSegInfo*</entry><entry>Pointer to the next TCPSegInfo object of the</entry></row><row><entry /><entry /><entry>forward linked list; NULL if no more</entry></row><row><entry>next_—</entry><entry>TCPSegInfo*</entry><entry>Pointer to the previous TCPSegInfo object of</entry></row><row><entry /><entry /><entry>the reverse linked list; NULL if no previous</entry></row><row><entry /><entry /><entry>segment exists</entry></row><row><entry>segment_—</entry><entry>IP4Datagram*</entry><entry>Pointer to the datagram containing the TCP</entry></row><row><entry /><entry /><entry>segment</entry></row><row><entry>startseq_—</entry><entry>TCPSeq</entry><entry>The starting sequence number for the</entry></row><row><entry /><entry /><entry>segment</entry></row><row><entry>endseq_—</entry><entry>TCPSeq</entry><entry>The ending sequence number for the segment</entry></row><row><entry>startbuf_—</entry><entry>u_char*</entry><entry>Pointer to the byte whose sequence number</entry></row><row><entry /><entry /><entry>is specified by the startseq_field</entry></row><row><entry>endbuf_—</entry><entry>u_char*</entry><entry>Pointer to the byte whose sequence number</entry></row><row><entry /><entry /><entry>is specified by the endseq_field</entry></row><row><entry>flags_—</entry><entry>uint32</entry><entry>Flags field for the segment (reserved as of</entry></row><row><entry /><entry /><entry>the EA2 release)</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> The ReassemblyQueue Class

0774The ReassemblyQueue class is a container class used in reconstructing TCP streams from TCP segments that have been “snooped” on a TCP connection. This class contains a list of TCPSegInfo objects, each of which corresponds to a single TCP segment. The purpose of this class is not only to contain the segments, but to reassemble received segments as they arrive and present them in proper sequence number order for applications to read. Applications are generally able to read data on the connection in order, or to skip past some fixed amount of enqued data. <ul id="ul0092" list-style="none"><li id="ul0092-0001" num="0775"> Constructor <br /> Description </li></ul>

0776A ReassemblyQueue object is used internally by the TCP stream reconstruction facility, but may be useful to applications in generaly under some circumstances. It provides for reassembly of TCP streams based on sequence numbers contained in TCP segments. The constructor takes an argument specifying the next sequence number to expect. It is updated as additional segments are inserted into the object. If a segment is inserted which is not contiguous in sequence number space, it is considered “out of order” and is queued in the object until the “hole” (data between it and the previous in-sequence data) is filled.

0000Syntax

0000<ul id="ul0093" list-style="none"><li id="ul0093-0001" num="0777"> ReassemblyQueue(TCPSeq&amp; rcvnxt) </li></ul>

0778Parameters <tables id="TABLE-US-00104" num="104"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="35PT" align="left" /><colspec colname="3" colwidth="147PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>rcvnxt</entry><entry>TCPSeq&amp;</entry><entry>A reference to the next TCP sequence number to</entry></row><row><entry /><entry /><entry>expect. The sequence number referred to by</entry></row><row><entry /><entry /><entry>rcvnxt is updated by the add function (see</entry></row><row><entry /><entry /><entry>below) to always indicate the next in-order TCP</entry></row><row><entry /><entry /><entry>sequence number expected</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0779None.

0000Defines

0780The following definitions are provided for insertion of TCP segments into a ReassemblyQueue object, and are used as return values for the add function defined below. Generally, acceptable conditions are indicated by bits in the low-order half-word, and suspicious or error conditions are indicated in the upper half-word. <tables id="TABLE-US-00105" num="105"><table frame="none" colsep="0" rowsep="0" pgwide="1"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="77PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="154PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Define</entry><entry>Value</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>RQ_OK</entry><entry>0x00000000</entry><entry>Segment was non-overlapping and in-order</entry></row><row><entry>RQ_OUTORDER</entry><entry>0x00000001</entry><entry>Segment was out of order (didn't match next</entry></row><row><entry /><entry /><entry>expected sequence number)</entry></row><row><entry>RQ_LOW_OLAP</entry><entry>0x00000002</entry><entry>Segment's sequence number was below next</entry></row><row><entry /><entry /><entry>expected but segment extended past next expected</entry></row><row><entry>RQ_HIGH_OLAP</entry><entry>0x00000004</entry><entry>Segment's data overlapped another queued</entry></row><row><entry /><entry /><entry>segment's data</entry></row><row><entry>RQ_DUP</entry><entry>0x00000008</entry><entry>Completely duplicate segment</entry></row><row><entry>RQ_BAD_HLEN</entry><entry>0x00010000</entry><entry>Bad header length (e.g. less than 5)</entry></row><row><entry>RQ_BAD_RSVD</entry><entry>0x00020000</entry><entry>Bad reserved field (reserved bits are non-zero)</entry></row><row><entry>RQ_FLAGS_ALERT</entry><entry>0x00040000</entry><entry>Suspicious combination of flags (e.g. RST on or all</entry></row><row><entry /><entry /><entry>on, etc)</entry></row><row><entry>RQ_FLAGS_BADURP</entry><entry>0x00080000</entry><entry>Bad urgent pointer</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><ul id="ul0094" list-style="none"><li id="ul0094-0001" num="0781"> add <br /> Description </li></ul>

0782The add function inserts an IP datagram or complete IP fragment containing a TCP segment into the reassembly queue. The TCP sequence number referenced by rcvnxt in the constructor is updated to reflect the next in-sequence sequence number expected.

0783Syntax <tables id="TABLE-US-00106" num="106"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="189PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>int add(IP4Datagram* dp, TCPSeq seq, uint32 dlen);</entry></row><row><entry /><entry>int add(IP4Fragment* fp, TCPSeq seq, uint32 dlen);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0784Parameters <tables id="TABLE-US-00107" num="107"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="133PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>fp</entry><entry>IP4Fragment*</entry><entry>Pointer to an unfragmented IP fragment</entry></row><row><entry /><entry /><entry>containing a TCP segment</entry></row><row><entry>dp</entry><entry>IP4Datagram*</entry><entry>A pointer to a complete IP datagram</entry></row><row><entry /><entry /><entry>containing a TCP segment</entry></row><row><entry>seq</entry><entry>TCPSeq</entry><entry>Initial sequence number for the TCP segment</entry></row><row><entry>dlen</entry><entry>uint32</entry><entry>Usable length of the TCP segment</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0785Returns a 32-bit integer with the possible values indicated above (definitions beginning with RQ_). <ul id="ul0095" list-style="none"><li id="ul0095-0001" num="0786"> empty <br /> Description </li></ul>

0787The empty function returns true if the reassembly queue contains no segments.

0000Syntax

0000<ul id="ul0096" list-style="none"><li id="ul0096-0001" num="0788"> bool empty( ) <br /> Parameters </li></ul>

0789None.

0000Return Value

0790Returns true if the reassembly queue contains no segments. <ul id="ul0097" list-style="none"><li id="ul0097-0001" num="0791"> clear <br /> Description </li></ul>

0792The clear function removes all queued segments from the reassembly queue and frees their storage.

0000Syntax

0000<ul id="ul0098" list-style="none"><li id="ul0098-0001" num="0793"> void clear( ) <br /> Parameters </li></ul>

0794None.

0000Return Value

0795None. <ul id="ul0099" list-style="none"><li id="ul0099-0001" num="0796"> read <br /> Description </li></ul>

0797The read function provides application access to the contiguous data currently queued in the reassembly queue. The function returns a linked list of TCPSegInfo objects. The list is in order sorted by sequence number beginning with the first in-order sequence number and continues no further than the number of bytes specified by the caller. Note that the caller must inspect the value filled in by the call to determine how many byte worth of sequence number space is consumed by the linked list. This call removes the segments returned to the caller from the reassembly queue.

0000Syntax

0000<ul id="ul0100" list-style="none"><li id="ul0100-0001" num="0798"> TCPSegInfo* read(int&amp; len); </li></ul>

0799Parameters <tables id="TABLE-US-00108" num="108"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="21PT" align="left" /><colspec colname="3" colwidth="161PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>len</entry><entry>int&amp;</entry><entry>Contains the number of bytes worth of in-sequence</entry></row><row><entry /><entry /><entry>data the application is interested in reading from the</entry></row><row><entry /><entry /><entry>reassembly queue. The underlying integer is modified</entry></row><row><entry /><entry /><entry>by this call to indicate the number of bytes actually </entry></row><row><entry /><entry /><entry>covered by the list of segments returned. The call is</entry></row><row><entry /><entry /><entry>guaranteed to never return a larger number of bytes</entry></row><row><entry /><entry /><entry>than requested.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0800Returns a pointer to the first TCPSegInfo object in a doubly-linked list of objects each of which point to TCP segments that are numerically adjacent in TCP sequence number space. <ul id="ul0101" list-style="none"><li id="ul0101-0001" num="0801"> The TCPEndpoint Class </li></ul>

0802The TCPEndpoint class is the abstraction of a single endpoint of a TCP connection. In TCP, a connection is identified by a 4-tuple of two IP addresses and a two port numbers. Each endpoint is identified by a single IP address and port number. Thus, a TCP connection (or “session”—see below) actually comprises two endpoint objects. Each endpoint contains the TCP finite state machine state as well as a ReassemblyQueue object, used to contain queued data. The TCPEndpoint class is used internally by the TCPSession class below, but may be useful to applications in certain circumstances. <ul id="ul0102" list-style="none"><li id="ul0102-0001" num="0803"> Constructor <br /> Description </li></ul>

0804The TCPEndpoint class is created in an empty state and is unable to determine which endpoint of a connection it represents. The user should call the init function described below after object instantiation to begin use of the object.

0000Syntax

0000<ul id="ul0103" list-style="none"><li id="ul0103-0001" num="0805"> TCPEndpoint( ) <br /> Parameters </li></ul>

0806None.

0000Return Value

0807None. <ul id="ul0104" list-style="none"><li id="ul0104-0001" num="0808"> Destructor <br /> Description </li></ul>

0809Deletes all queued TCP segments and frees the object's memory.

0000Syntax

0000<ul id="ul0105" list-style="none"><li id="ul0105-0001" num="0810"> ˜TCPEndpoint( ) <br /> Parameters </li></ul>

0811None.

0000Return Value

0812None. <ul id="ul0106" list-style="none"><li id="ul0106-0001" num="0813"> reset <br /> Description </li></ul>

0814Resets the endpoint internal state to closed and clears any queued data.

0000Syntax

0000<ul id="ul0107" list-style="none"><li id="ul0107-0001" num="0815"> ˜TCPEndpoint( ) <br /> Parameters </li></ul>

0816None.

0000Return Value

0817None. <ul id="ul0108" list-style="none"><li id="ul0108-0001" num="0818"> state <br /> Description </li></ul>

0819Returns the current state in the TCP finite state machine associated with the TCP endpoint.

0000Syntax

0000<ul id="ul0109" list-style="none"><li id="ul0109-0001" num="0820"> int state( ) <br /> Parameters </li></ul>

0821None.

0000Return Value

0822Returns an integer indicating the internal state according to the definitions given above (defines beginning with TCPS_) <ul id="ul0110" list-style="none"><li id="ul0110-0001" num="0823"> init <br /> Description </li></ul>

0824The init function provides initialization of a TCP endpoint object by specifying the IP address and port number the endpoint is acting as. After this call has been made, subsequent processing of IP datagrams and fragments containing TCP segments (and ACKs) is accomplished by the process calls described below.

0000Syntax

0000<ul id="ul0111" list-style="none"><li id="ul0111-0001" num="0825"> void init(IP4Addr* myaddr, uint16 myport); </li></ul>

0826Parameters <tables id="TABLE-US-00109" num="109"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="35PT" align="left" /><colspec colname="3" colwidth="147PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>myaddr</entry><entry>IP4Addr*</entry><entry>A pointer to the IP address identifying this</entry></row><row><entry /><entry /><entry>TCP endpoint</entry></row><row><entry>myport</entry><entry>nuint16</entry><entry>The port number (in network byte order) of port</entry></row><row><entry /><entry /><entry>number identifying this TCP endpoint</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0827None. <ul id="ul0112" list-style="none"><li id="ul0112-0001" num="0828"> process <br /> Description </li></ul>

0829The process function processes an incoming or outgoing TCP segment relative to the TCP endpoint object. The first form of the function operates on a datagram which must be complete; the second form operates on a fragment which must also be complete. Given that the TCPEndpoint object is not actually the literal endpoint of the TCP connection itself, it must infer state transitions at the literal endpoints based upon observed traffic. Thus, it must monitor both directions of the TCP connection to properly follow the state at each literal endpoint.

0830Syntax <tables id="TABLE-US-00110" num="110"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="63PT" align="left" /><colspec colname="1" colwidth="154PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>int process(IP4Datagram* pd);</entry></row><row><entry /><entry>int process(IP4Fragment* pf);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0831Parameters <tables id="TABLE-US-00111" num="111"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="119PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>pd</entry><entry>IP4Datagram*</entry><entry>A pointer to a complete IP datagram</entry></row><row><entry /><entry /><entry>containing a TCP segment</entry></row><row><entry>pf</entry><entry>IP4Fragment*</entry><entry>Pointer to an unfragmented IP fragment</entry></row><row><entry /><entry /><entry>containing a TCP segment</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0832Returns a 32-bit integer with the same semantics defined for <ul id="ul0113" list-style="none"><li id="ul0113-0001" num="0833"> ReassemblyQueue::add (see above). </li><li id="ul0113-0002" num="0834"> The TCPSession Class </li></ul>

0835The TCPSession class is the abstraction of a complete, bidirectional TCP connection. It includes two TCP endpoint objects, which each include a reassembly queue. Thus, provided the TCPSess ion object is able to process all data sent on the connection in either direction it will have a reasonably complete picture of the progress and data exchanged across the connection. <ul id="ul0114" list-style="none"><li id="ul0114-0001" num="0836"> Constructor <br /> Description </li></ul>

0837The TCPSession object is created by the caller when a TCP segment arrives on a new connection. The session object will infer from the contents of the segment which endpoint will be considered the client (the active opener—generally the sender of the first SYN), and which will be considered the server (the passive opener—generally the sender of the first SYN+ACK). In circumstances of simultaneous active opens (a rare case when both endpoints send SYN packets), the notion of client and server is not well defined, but the session object will behave as though the sender of the first SYN received by the session object is the client. In any case, the terms client and server are only loosely defined and do not affect the proper operation of the object.

0838Syntax <tables id="TABLE-US-00112" num="112"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="56PT" align="left" /><colspec colname="1" colwidth="161PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>TCPSession(IP4Datagram* dp);</entry></row><row><entry /><entry>TCPSession(IP4Fragment* fp);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0839Parameters <tables id="TABLE-US-00113" num="113"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="133PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>pd</entry><entry>IP4Datagram*</entry><entry>A pointer to a complete IP datagram</entry></row><row><entry /><entry /><entry>containing the first TCP segment on the</entry></row><row><entry /><entry /><entry>connection</entry></row><row><entry>pf</entry><entry>IP4Fragment*</entry><entry>Pointer to a complete IP fragment containing</entry></row><row><entry /><entry /><entry>a the first TCP segment on the connection</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0840None. <ul id="ul0115" list-style="none"><li id="ul0115-0001" num="0841"> Destructor <br /> Description </li></ul>

0842Deletes all TCP segments queued and frees the object's memory.

0000Syntax

0000<ul id="ul0116" list-style="none"><li id="ul0116-0001" num="0843"> ˜TCPSession( ) <br /> Parameters </li><li id="ul0116-0002" num="0844"> None. <br /> Return value </li><li id="ul0116-0003" num="0845"> None. </li><li id="ul0116-0004" num="0846"> process <br /> Description </li></ul>

0847The process function processes a TCP segment on the connection. The first form of the function operates on a datagram which must be complete; the second form operates on a fragment which must also be complete. This function operates by passing the datagram or fragment to each endpoint's process function.

0848Syntax <tables id="TABLE-US-00114" num="114"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="63PT" align="left" /><colspec colname="1" colwidth="154PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>int process(IP4Datagram* pd);</entry></row><row><entry /><entry>int process(IP4Fragment* pf);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0849Parameters <tables id="TABLE-US-00115" num="115"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="119PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>pd</entry><entry>IP4Datagram *</entry><entry>A pointer to a complete IP datagram</entry></row><row><entry /><entry /><entry>containing a TCP segment</entry></row><row><entry>pf</entry><entry>IP4Fragment *</entry><entry>Pointer to an unfragmented IP fragment</entry></row><row><entry /><entry /><entry>containing a TCP segment</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0850Returns a 32-bit integer with the same semantics defined for ReassemblyQueue::add (see above). The value returned will be the result of calling the add function of the reassembly queue object embedded in the endpoint object corresponding to the destination address and port of the received segment.

000016. Network Address Translation (NAT)

0851Network Address Translation (NAT) refers to the general ability to modify various fields of different protocols so that the effective source, destination, or source and destination entities are replaced by an alternative. The definitions to perform NAT for the IP, UDP, and TCP protocols are defined within the ASL. The NAT implementation uses incremental checksum computation, so performance should not degrade in proportion to packet size.

17. IP NAT

0852IP address translation refers to the mapping of an IP datagram (fragment) with source and destination IP address (s<b>1</b>,d<b>1</b>) to the same datagram (fragment) with new address pair (s<b>2</b>, d<b>2</b>). A source-rewrite only modifies the source address (d<b>1</b> is left equal to d<b>2</b>). A destination rewrite implies only the destination address is rewritten (s<b>1</b> is left equal to s<b>2</b>). A source and destination rewrite refers to a change in both the source and destination IP addresses. Note that for IP NAT, only the IP source and/or destination addresses are rewritten (in addition to rewriting the IP header checksum). For traffic such as TCP or UDP, NAT functionality must include modification of the TCP or UDP pseudoheader checksum (which covers the IP header source and destination addresses plus protocol field). Properly performing NAT on TCP or UDP traffic, requires attention to these details.

000018. IP NAT Base Class

0853The class IPNat provides a base class for other IP NAT classes. Because of the pure virtual function rewrite, applications will not create objects of type IP4Nat directly, but rather use the objects of typeIP4SNat, IP4DNat, and IP4SDNat defined below. <ul id="ul0117" list-style="none"><li id="ul0117-0001" num="0854"> rewrite <br /> Description </li></ul>

0855This pure-virtual function is defined in derived classes. It performs address rewriting in a specific fashion implemented by the specific derived classes (i.e. source, destination, or source/destination combination). The rewrite call, as applied to a fragment, only affects the given fragment. When applied to a datagram, each of the fragment headers comprising the datagram are re-written.

0856Syntax <tables id="TABLE-US-00116" num="116"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="42PT" align="left" /><colspec colname="1" colwidth="175PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>virtual void rewrite(IP4Datagram*fp) = 0;</entry></row><row><entry /><entry>virtual void rewrite(IP4Fragment*fp) = 0;</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0857Parameters <tables id="TABLE-US-00117" num="117"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="119PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>dp</entry><entry>IP4Datagram *</entry><entry>Pointer to the datagram to rewrite</entry></row><row><entry>fp</entry><entry>IP4Fragment *</entry><entry>Pointer to the single fragment to rewrite</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0118" list-style="none"><li id="ul0118-0001" num="0858"> None. </li></ul>

0859There are three classes available for implementing IP NAT, all of which are derived from the base class IP4Nat. The classes IP4SNat, IPDNat, and IPSDNat define the structure of objects implementing source, destination, and source/destination rewriting for IP datagrams and fragments.

000019. IP4SNat class

0860The IP4SNat class is derived from the IP4Nat class. It defines the class of objects implementing source rewriting for IP datagrams and fragments. <ul id="ul0119" list-style="none"><li id="ul0119-0001" num="0861"> Constructor <br /> Description </li></ul>

0862Instantiates the IP4SNat object.

0000Syntax

0000<ul id="ul0120" list-style="none"><li id="ul0120-0001" num="0863"> IP4SNat(IP4Addr* newsrc); </li></ul>

0864Parameters <tables id="TABLE-US-00118" num="118"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="35PT" align="left" /><colspec colname="3" colwidth="140PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>newsrc</entry><entry>IP4Addr *</entry><entry>Pointer to the new source address for IP NAT.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0121" list-style="none"><li id="ul0121-0001" num="0865"> None. </li><li id="ul0121-0002" num="0866"> rewrite <br /> Description </li></ul>

0867Defines the pure virtual rewrite functions in the parent class.

0868Syntax <tables id="TABLE-US-00119" num="119"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="56PT" align="left" /><colspec colname="1" colwidth="161PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>void rewrite(IP4Datagram* dp);</entry></row><row><entry /><entry>void rewrite(IP4Fragment* fp);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0869Parameters <tables id="TABLE-US-00120" num="120"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="119PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>dp</entry><entry>IP4Datagram *</entry><entry>Pointer to the datagram to be rewritten</entry></row><row><entry /><entry /><entry>(all fragment headers are modified)</entry></row><row><entry>fp</entry><entry>IP4Fragment *</entry><entry>Pointer to the fragment to rewrite (only</entry></row><row><entry /><entry /><entry>the single fragment header is modified)</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0122" list-style="none"><li id="ul0122-0001" num="0870"> None. <br /> 20. IP4DNat Class </li></ul>

0871The IP4DNat class is derived from the IP4Nat class. It defines the class of objects implementing destination rewriting for IP datagrams and fragments. <ul id="ul0123" list-style="none"><li id="ul0123-0001" num="0872"> Constructor <br /> Description </li></ul>

0873Instantiates the IP4DNat object.

0000Syntax

0000<ul id="ul0124" list-style="none"><li id="ul0124-0001" num="0874"> IP4DNat(IP4Addr* newdst); </li></ul>

0875Parameters <tables id="TABLE-US-00121" num="121"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="49PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="105PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>newdst</entry><entry>IP4Addr *</entry><entry>Pointer to the new destination</entry></row><row><entry /><entry /><entry /><entry>address for IP NAT.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0125" list-style="none"><li id="ul0125-0001" num="0876"> None. </li><li id="ul0125-0002" num="0877"> rewrite <br /> Description </li></ul>

0878Defines the pure virtual rewrite functions in the parent class.

0879Syntax <tables id="TABLE-US-00122" num="122"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="56PT" align="left" /><colspec colname="1" colwidth="161PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>void rewrite(IP4Datagram* dp);</entry></row><row><entry /><entry>void rewrite(IP4Fragment* fp);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0880Parameters <tables id="TABLE-US-00123" num="123"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="119PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>dp</entry><entry>IP4Datagram *</entry><entry>Pointer to the datagram to be rewritten</entry></row><row><entry /><entry /><entry>(all fragment headers are modified)</entry></row><row><entry>fp</entry><entry>IP4Fragment *</entry><entry>Pointer to the fragment to rewrite (only</entry></row><row><entry /><entry /><entry>the single fragment header is modified)</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0126" list-style="none"><li id="ul0126-0001" num="0881"> None. <br /> 21. IP4SDNat class </li></ul>

0882The IP4SDNat class is derived from the IP4Nat class. It defines the class of objects implementing source and destination rewriting for IP datagrams and fragments. <ul id="ul0127" list-style="none"><li id="ul0127-0001" num="0883"> Constructor <br /> Description </li></ul>

0884Instantiates the IP4SDNat object.

0000Syntax

0000<ul id="ul0128" list-style="none"><li id="ul0128-0001" num="0885"> IP4SDNat(IP4Addr* newsrc, IP4Addr* newdst); </li></ul>

0886Parameters <tables id="TABLE-US-00124" num="124"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="119PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>nesrc</entry><entry>IP4Addr *</entry><entry>Pointer to the new source address</entry></row><row><entry /><entry /><entry /><entry>for IP NAT.</entry></row><row><entry /><entry>newdst</entry><entry>IP4Addr *</entry><entry>Pointer to the new destination address</entry></row><row><entry /><entry /><entry /><entry>for IP NAT.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0129" list-style="none"><li id="ul0129-0001" num="0887"> None. </li><li id="ul0129-0002" num="0888"> rewrite <br /> Description </li></ul>

0889Defines the pure virtual rewrite functions in the parent class.

0890Syntax <tables id="TABLE-US-00125" num="125"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="56PT" align="left" /><colspec colname="1" colwidth="161PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>void rewrite(IP4Datagram* dp);</entry></row><row><entry /><entry>void rewrite(IP4Fragment* fp);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0891Parameters <tables id="TABLE-US-00126" num="126"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="126PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>dp</entry><entry>IP4Datagram *</entry><entry>Pointer to the datagram to be rewritten</entry></row><row><entry /><entry /><entry>(all fragment headers are modified)</entry></row><row><entry>fp</entry><entry>IP4Fragment *</entry><entry>Pointer to the fragment to rewrite (only the</entry></row><row><entry /><entry /><entry>single fragment header is modified)</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0892None.

0000Example

0893For fragments, only the single fragment is modified. For datagrams, all comprising fragments are updated. The following simple example illustrates the use of one of these objects:

0894Assuming ipa<b>1</b> is an address we wish to place in the IP packet's destination address field,buf points to the ASL buffer containing an IP packet we wish to rewrite, and iph points the IP header of the packet contained in the buffer: <tables id="TABLE-US-00127" num="127"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="1" colwidth="119PT" align="left" /><colspec colname="2" colwidth="98PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>IPDNat *ipd = new IPDNat(&ipa1);</entry><entry>// create IP DNat object</entry></row><row><entry>IP4Fragment ipf(buf, iph);</entry><entry> // create IP fragment object</entry></row><row><entry>ipd->rewrite(&ipf);</entry><entry>// rewrite fragment's header</entry></row><row><entry namest="1" nameend="2" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0895The use of other IP NAT objects follows a similar pattern.

22. UDP NAT

0896The organization of the UDP NAT classes follows the IP NAT classes very closely. The primary difference is in the handling of UDP ports. For UDP NAT, the optional rewriting of port numbers (in addition to IP layer addresses) is specified in the constructor.

000023. UDPNat Base Class

0897The class UDPNat provides a base class for other UDP NAT classes. The constructor is given a value indicating whether port number rewriting is enabled. Because of the pure virtual function rewrite, applications will not create objects of type UDPNat directly, but rather use the objects of type UDPSNat, UDPDNat, and UDPSDNat defined below. <ul id="ul0130" list-style="none"><li id="ul0130-0001" num="0898"> Constructor <br /> Description </li></ul>

0899The constructor is given a value indicating whether port number rewriting is enabled.

0000Syntax

0000<ul id="ul0131" list-style="none"><li id="ul0131-0001" num="0900"> UDPNat(bool deports); </li></ul>

0901Parameters <tables id="TABLE-US-00128" num="128"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="28PT" align="left" /><colspec colname="3" colwidth="133PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>doports</entry><entry>bool</entry><entry>Boolean value indicating whether the port</entry></row><row><entry /><entry /><entry /><entry>number rewriting is enabled. A true value</entry></row><row><entry /><entry /><entry /><entry>indicates port number rewriting</entry></row><row><entry /><entry /><entry /><entry>is enabled.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0132" list-style="none"><li id="ul0132-0001" num="0902"> None. </li><li id="ul0132-0002" num="0903"> rewrite <br /> Description </li></ul>

0904This pure-virtual function is defined in derived classes. It performs address rewriting in a specific fashion implemented by the specific derived classes (i.e. source, destination, or source/destination combination). The rewrite call, as applied to a fragment, only affects the given fragment. When applied to a datagram, each of the fragment headers comprising the datagram are re-written.

0905Syntax <tables id="TABLE-US-00129" num="129"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="42PT" align="left" /><colspec colname="1" colwidth="175PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>virtual void rewrite(IP4Datagram*fp) = 0;</entry></row><row><entry /><entry>virtual void rewrite(IP4Fragment*fp) = 0;</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0906Parameters <tables id="TABLE-US-00130" num="130"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="119PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>dp</entry><entry>IP4Datagram *</entry><entry>Pointer to the datagram to rewrite</entry></row><row><entry>fp</entry><entry>IP4Fragment *</entry><entry>Pointer to the single fragment to rewrite</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0907None. <ul id="ul0133" list-style="none"><li id="ul0133-0001" num="0908"> ports <br /> Description </li></ul>

0909The first form of this function returns true if the NAT object is configured to rewrite port numbers. The second form of this function configures the object to enable or disable port number rewriting using the values true and false, respectively.

0910Syntax <tables id="TABLE-US-00131" num="131"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="77PT" align="left" /><colspec colname="1" colwidth="140PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>bool ports( );</entry></row><row><entry /><entry>void ports(bool p);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0911Parameters <tables id="TABLE-US-00132" num="132"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="21PT" align="left" /><colspec colname="3" colwidth="161PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>p</entry><entry>bool</entry><entry>Boolean containing whether port rewriting is enabled.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0912The first form of this function returns true if the NAT object is configured to rewrite UDP port numbers.

000024. UDPSNat Class

0913The UDPSNat class is derived from the UDPNat class. It defines the class of objects implementing source address and (optionally) port number rewriting for complete and fragmented UDP datagrams. <ul id="ul0134" list-style="none"><li id="ul0134-0001" num="0914"> Constructors <br /> Description </li></ul>

0915The single-argument constructor is used to create UDP NAT objects that rewrite only the addresses in the IP header (and update the IP header checksum and UDP pseudo-header checksum appropriately). The two-argument constructor is used to create NAT objects that also rewrite the source port number in the UDP header. For fragmented UDP datagrams, the port numbers will generally be present in only the first fragment.

0916Syntax <tables id="TABLE-US-00133" num="133"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="189PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>UDPSNat(IP4Addr* newsaddr, nuint16 newsport);</entry></row><row><entry /><entry>UDPSNat(IP4Addr* newsaddr);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0917Parameters <tables id="TABLE-US-00134" num="134"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="42PT" align="left" /><colspec colname="3" colwidth="133PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>newsaddr</entry><entry>IP4Addr *</entry><entry>Pointer the new source address to be used</entry></row><row><entry>newsport</entry><entry>nuint16</entry><entry>The new source port number to be used</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0135" list-style="none"><li id="ul0135-0001" num="0918"> None. </li><li id="ul0135-0002" num="0919"> rewrite <br /> Description </li></ul>

0920Defines the pure virtual rewrite functions in the parent class.

0921Syntax <tables id="TABLE-US-00135" num="135"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="56PT" align="left" /><colspec colname="1" colwidth="161PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>void rewrite(IP4Datagram* dp);</entry></row><row><entry /><entry>void rewrite(IP4Fragment* fp);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0922Parameters <tables id="TABLE-US-00136" num="136"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="133PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>dp</entry><entry>IP4Datagram *</entry><entry>Pointer to the datagram to be rewritten</entry></row><row><entry /><entry /><entry>(all fragment headers are modified)</entry></row><row><entry>fp</entry><entry>IP4Fragment *</entry><entry>Pointer to the fragment to rewrite (only the</entry></row><row><entry /><entry /><entry>single fragment header is modified). Should</entry></row><row><entry /><entry /><entry>only be called when the fragment represents</entry></row><row><entry /><entry /><entry>a complete UDP/IP datagram.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0136" list-style="none"><li id="ul0136-0001" num="0923"> None. <br /> 25. UDPDNat Class </li></ul>

0924The UDPDNat class is derived from the UDPNat class. It defines the class of objects implementing destination address and (optionally) port number rewriting for complete and fragmented UDP datagrams. <ul id="ul0137" list-style="none"><li id="ul0137-0001" num="0925"> Constructors <br /> Description </li></ul>

0926The single-argument constructor is used to create UDP NAT objects that rewrite only the addresses in the IP header (and update the IP header checksum and UDP pseudo-header checksum appropriately). The two-argument constructor is used to create NAT objects that also rewrite the destination port number in the UDP header. For fragmented UDP datagrams, the port numbers will generally be present in only the first fragment.

0927Syntax <tables id="TABLE-US-00137" num="137"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="28PT" align="left" /><colspec colname="1" colwidth="189PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>UDPSNat(IP4Addr* newdaddr, nuint16 newdport);</entry></row><row><entry /><entry>UDPSNat(IP4Addr* newdaddr);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0928Parameters <tables id="TABLE-US-00138" num="138"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="35PT" align="left" /><colspec colname="3" colwidth="140PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>newdaddr</entry><entry>IP4Addr *</entry><entry>Pointer the new destination address to be used</entry></row><row><entry>newdport</entry><entry>nuint16</entry><entry>The new destination port number to be used</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0138" list-style="none"><li id="ul0138-0001" num="0929"> None. </li><li id="ul0138-0002" num="0930"> rewrite <br /> Description </li></ul>

0931Defines the pure virtual rewrite functions in the parent class.

0932Syntax <tables id="TABLE-US-00139" num="139"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="56PT" align="left" /><colspec colname="1" colwidth="161PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>void rewrite(IP4Datagram* dp);</entry></row><row><entry /><entry>void rewrite(IP4Fragment* fp);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0933Parameters <tables id="TABLE-US-00140" num="140"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="133PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>dp</entry><entry>IP4Datagram *</entry><entry>Pointer to the datagram to be rewritten</entry></row><row><entry /><entry /><entry>(all fragment headers are modified)</entry></row><row><entry>fp</entry><entry>IP4Fragment *</entry><entry>Pointer to the fragment to rewrite (only the</entry></row><row><entry /><entry /><entry>single fragment header is modified). Should</entry></row><row><entry /><entry /><entry>only be called when the fragment</entry></row><row><entry /><entry /><entry>represents a complete UDP/IP</entry></row><row><entry /><entry /><entry>datagram.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0139" list-style="none"><li id="ul0139-0001" num="0934"> None. <br /> 26. UDPSDNat Class </li></ul>

0935The UDPSDNat class is derived from the UDPNat class. It defines the class of objects implementing source and destination address and (optionally) port number rewriting for complete and fragmented UDP datagrams. <ul id="ul0140" list-style="none"><li id="ul0140-0001" num="0936"> Constructors <br /> Description </li></ul>

0937The two-argument constructor is used to create UDP NAT objects that rewrite only the addresses in the IP header (and update the IP header checksum and UDP pseudo-header checksum appropriately). The four-argument constructor is used to create NAT objects that also rewrite the source and destination port number in the UDP header. For fragmented UDP datagrams, the port numbers will generally be present in only the first fragment.

0938Syntax <tables id="TABLE-US-00141" num="141"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="1"><colspec colname="1" colwidth="217PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>UDPSNat(IP4Addr* newsaddr, nuint16 newsport, IP4Addr* newdaddr,</entry></row><row><entry>nuint16 newdport);</entry></row><row><entry>UDPSNat(IP4Addr* newsaddr, IP4Addr* newdaddr);</entry></row><row><entry namest="1" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0939Parameters <tables id="TABLE-US-00142" num="142"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="35PT" align="left" /><colspec colname="3" colwidth="140PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>newsaddr</entry><entry>IP4Addr *</entry><entry>Pointer the new source address to be used</entry></row><row><entry>newsport</entry><entry>nuint16</entry><entry>The new source port number to be used</entry></row><row><entry>newdaddr</entry><entry>IP4Addr *</entry><entry>Pointer the new destination address to be used</entry></row><row><entry>newdport</entry><entry>nuint16</entry><entry>The new destination port number to be used</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0141" list-style="none"><li id="ul0141-0001" num="0940"> None. </li><li id="ul0141-0002" num="0941"> rewrite <br /> Description </li></ul>

0942Defines the pure virtual rewrite functions in the parent class.

0943Syntax <tables id="TABLE-US-00143" num="143"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="56PT" align="left" /><colspec colname="1" colwidth="161PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>void rewrite(IP4Datagram* dp);</entry></row><row><entry /><entry>void rewrite(IP4Fragment* fp);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0944Parameters <tables id="TABLE-US-00144" num="144"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="133PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>dp</entry><entry>IP4Datagram *</entry><entry>Pointer to the datagram to be rewritten (all</entry></row><row><entry /><entry /><entry>fragment headers are modified)</entry></row><row><entry>fp</entry><entry>IP4Fragment *</entry><entry>Pointer to the fragment to rewrite (only the</entry></row><row><entry /><entry /><entry>single fragment header is modified). Should</entry></row><row><entry /><entry /><entry>only be called when the fragment represents</entry></row><row><entry /><entry /><entry>a complete UDP/IP datagram.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0142" list-style="none"><li id="ul0142-0001" num="0945"> None. <br /> 27. TCP NAT </li></ul>

0946The structure of the TCP NAT support classes follow the UDP classes very closely. The primary difference is in the handling of TCP sequence and ACK numbers.

000028. TCPNat Base Class

0947The class TCPNat provides a base class for other TCP NAT classes. The constructor is given a pair of values indicating whether port number, sequence number, and acknowledgement number rewriting is enabled. Sequence number and ACK number rewriting are coupled such that enabling sequence number rewriting for source-rewriting will modify the sequence number field of the TCP segment, but enabling sequence number rewriting for destination-rewriting will instead modify the ACK field. This arrangement makes it possible to perform NAT on TCP streams without unnecessary complexity in the TCP NAT interface. Because of the pure virtual function rewrite, applications will not create objects of type TCPNat directly, but rather use the objects of type TCPSNat, TCPDNat, and TCPSDNat defined below. <ul id="ul0143" list-style="none"><li id="ul0143-0001" num="0948"> Constructor <br /> Description </li></ul>

0949The constructor is given a value indicating whether port number rewriting is enabled.

0000Syntax

0000<ul id="ul0144" list-style="none"><li id="ul0144-0001" num="0950"> TCPNat(bool deports, bool doseqs); </li></ul>

0951Parameters <tables id="TABLE-US-00145" num="145"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="28PT" align="left" /><colspec colname="3" colwidth="154PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>doports</entry><entry>bool</entry><entry>Boolean value indicating whether the port</entry></row><row><entry /><entry /><entry>number rewriting is enabled. A true value indicates</entry></row><row><entry /><entry /><entry>port number rewriting is enabled.</entry></row><row><entry>doseqs</entry><entry>bool</entry><entry>Boolean value indicating whether the sequence/ACK</entry></row><row><entry /><entry /><entry>number rewriting is enabled. A true value indicates</entry></row><row><entry /><entry /><entry>sequence/ACK number rewriting is enabled.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0145" list-style="none"><li id="ul0145-0001" num="0952"> None. </li><li id="ul0145-0002" num="0953"> rewrite <br /> Description </li></ul>

0954This pure-virtual function is defined in derived classes. It performs address rewriting in a specific fashion implemented by the specific derived classes (i.e. source, destination, or source/destination combination). The rewrite call, as applied to a fragment, only affects the given fragment. When applied to a datagram, each of the fragment headers comprising the datagram are re-written.

0955Syntax <tables id="TABLE-US-00146" num="146"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="42PT" align="left" /><colspec colname="1" colwidth="175PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>virtual void rewrite(IP4Datagram* dp) = 0;</entry></row><row><entry /><entry>virtual void rewrite(IP4Fragment* fp) = 0;</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0956Parameters <tables id="TABLE-US-00147" num="147"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="119PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>dp</entry><entry>IP4Datagram *</entry><entry>Pointer to the datagram to rewrite</entry></row><row><entry>fp</entry><entry>IP4Fragment *</entry><entry>Pointer to the single fragment to rewrite</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0146" list-style="none"><li id="ul0146-0001" num="0957"> None. </li><li id="ul0146-0002" num="0958"> ports <br /> Description </li></ul>

0959The first form of this function returns true if the NAT object is configured to rewrite port numbers. The second form of this function configures the object to enable or disable port number rewriting using the values true and false, respectively.

0960Syntax <tables id="TABLE-US-00148" num="148"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="77PT" align="left" /><colspec colname="1" colwidth="140PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>bool ports( );</entry></row><row><entry /><entry>void ports(bool p);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0961Parameters <tables id="TABLE-US-00149" num="149"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="4"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="49PT" align="left" /><colspec colname="2" colwidth="35PT" align="left" /><colspec colname="3" colwidth="119PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row><row><entry /><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>p</entry><entry>bool</entry><entry>Boolean indicating whether port</entry></row><row><entry /><entry /><entry /><entry>number rewriting is enabled.</entry></row><row><entry /><entry namest="OFFSET" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0962The first form of this function returns true if the NAT object is configured to rewrite TCP port numbers. <ul id="ul0147" list-style="none"><li id="ul0147-0001" num="0963"> seqs <br /> Description </li></ul>

0964The first form of this function returns true if the NAT object is configured to rewrite sequence/ACK numbers. The second form of this function configures the object to enable or disable sequence/ACK number rewriting using the values true and false, respectively.

0965Syntax <tables id="TABLE-US-00150" num="150"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="77PT" align="left" /><colspec colname="1" colwidth="140PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>bool seqs( );</entry></row><row><entry /><entry>void seqs(bool s);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0966Parameters <tables id="TABLE-US-00151" num="151"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="28PT" align="left" /><colspec colname="3" colwidth="154PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>s</entry><entry>bool</entry><entry>Boolean indicating whether sequence/ACK number</entry></row><row><entry /><entry /><entry>rewriting is enabled.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value

0967The first form of this function returns true if the NAT object is configured to rewrite TCP port numbers.

000029. TCPSNat Class

0968The TCPSNat class is derived from the TCPNat class. It defines the class of objects implementing source address and (optionally) port number and sequence number rewriting for complete and fragmented TCP segments. <ul id="ul0148" list-style="none"><li id="ul0148-0001" num="0969"> Constructors <br /> Description </li></ul>

0970The single-argument constructor is used to create TCP NAT objects that rewrite only the addresses in the IP header (and update the IP header checksum and TCP pseudo-header checksum appropriately). The two-argument constructor is used to create NAT objects that also rewrite the source port number in the TCP header. The three-argument constructor is used to rewrite the IP address, source port number, and to modify the TCP sequence number by a relative (constant) amount. The sequence offset provided may be positive or negative.

0971Syntax <tables id="TABLE-US-00152" num="152"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="203PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>TCPSNat(IP4Addr* newsaddr);</entry></row><row><entry /><entry>TCPSNat(IP4Addr* newsaddr, nuint16 newsport);</entry></row><row><entry /><entry>TCPSNat(IP4Addr* newsaddr, nuint16 newsport, long seqoff)</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0972Parameters <tables id="TABLE-US-00153" num="153"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="35PT" align="left" /><colspec colname="3" colwidth="147PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>newsaddr</entry><entry>IP4Addr *</entry><entry>Pointer the new source address to be used</entry></row><row><entry>newsport</entry><entry>nuint16</entry><entry>The new source port number to be used</entry></row><row><entry>seqoff</entry><entry>long</entry><entry>Relative change to make to TCP sequence number</entry></row><row><entry /><entry /><entry>fields. A positive value indicates the TCP</entry></row><row><entry /><entry /><entry>sequence number is increased by the</entry></row><row><entry /><entry /><entry>amount specified. A negative value indicates</entry></row><row><entry /><entry /><entry>the sequence number is reduced by the amount</entry></row><row><entry /><entry /><entry>specified.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0149" list-style="none"><li id="ul0149-0001" num="0973"> None. </li><li id="ul0149-0002" num="0974"> rewrite <br /> Description </li></ul>

0975Defines the pure virtual rewrite functions in the parent class.

0976Syntax <tables id="TABLE-US-00154" num="154"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="56PT" align="left" /><colspec colname="1" colwidth="161PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>void rewrite(IP4Datagram* dp);</entry></row><row><entry /><entry>void rewrite(IP4Fragment* fp);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0977Parameters <tables id="TABLE-US-00155" num="155"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="49PT" align="left" /><colspec colname="3" colwidth="133PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>dp</entry><entry>IP4Datagram *</entry><entry>Pointer to the datagram to be</entry></row><row><entry /><entry /><entry>rewritten (all fragment headers are modified)</entry></row><row><entry>fp</entry><entry>IP4Fragment *</entry><entry>Pointer to the fragment to rewrite</entry></row><row><entry /><entry /><entry>(only the single fragment header</entry></row><row><entry /><entry /><entry>is modified). Should only be called</entry></row><row><entry /><entry /><entry>when the fragment represents</entry></row><row><entry /><entry /><entry>a complete TCP/IP segment.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0150" list-style="none"><li id="ul0150-0001" num="0978"> None. <br /> 30. TCPSDNat Class </li></ul>

0979The TCPSDNat class is derived from the TCPNat class. It defines the class of objects implementing source address and (optionally) port number and sequence number/ACK number rewriting for complete and fragmented TCP segments. <ul id="ul0151" list-style="none"><li id="ul0151-0001" num="0980"> Constructors <br /> Description </li></ul>

0981The two-argument constructor is used to create TCP NAT objects that rewrite only the addresses in the IP header (and update the IP header checksum and TCP pseudo-header checksum appropriately). The four-argument constructor is used to create NAT objects that also rewrite the source and destination port numbers in the TCP header. The three-argument constructor is used to rewrite the IP address, source port number, and to modify the TCP ACK number by a relative (constant) amount. The ACK offset provided may be positive or negative.

0982Syntax <tables id="TABLE-US-00156" num="156"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="14PT" align="left" /><colspec colname="1" colwidth="203PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>TCPSDNat(IP4Addr* newsaddr, IP4Addr* newdaddr);</entry></row><row><entry /><entry>TCPSDNat(IP4Addr* newsaddr, nuint16 newsport,</entry></row><row><entry /><entry>IP4Addr* newdaddr, nuint16 newdport);</entry></row><row><entry /><entry>TCPSDNat(IP4Addr* newsaddr, nuint16 newsport, long seqoff,</entry></row><row><entry /><entry>IP4Addr* newdaddr, nuint16 newdport, long ackoff);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0983Parameters <tables id="TABLE-US-00157" num="157"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="35PT" align="left" /><colspec colname="2" colwidth="35PT" align="left" /><colspec colname="3" colwidth="147PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>newsaddr</entry><entry>IP4Addr *</entry><entry>The new source address to be used</entry></row><row><entry>newsport</entry><entry>nuint16</entry><entry>The new source port number to be used</entry></row><row><entry>seqoff</entry><entry>long</entry><entry>Relative change to make to TCP sequence</entry></row><row><entry /><entry /><entry>number fields. A positive value indicates the TCP</entry></row><row><entry /><entry /><entry>sequence number is increased by the amount</entry></row><row><entry /><entry /><entry>specified. A negative value indicates the</entry></row><row><entry /><entry /><entry>sequence number is reduced by the amount</entry></row><row><entry /><entry /><entry>specified.</entry></row><row><entry>newdaddr</entry><entry>IP4Addr *</entry><entry>The new destination address to be used</entry></row><row><entry>newdport</entry><entry>nuint16</entry><entry>The new destination port number to be used</entry></row><row><entry>ackoff</entry><entry>long</entry><entry>Relative change to make to TCP ACK number</entry></row><row><entry /><entry /><entry>fields. A positive value indicates the TCP ACK</entry></row><row><entry /><entry /><entry>number is increased by the amount specified. A</entry></row><row><entry /><entry /><entry>negative value indicates the ACK number is</entry></row><row><entry /><entry /><entry>reduced by the amount specified.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0152" list-style="none"><li id="ul0152-0001" num="0984"> None. </li><li id="ul0152-0002" num="0985"> rewrite <br /> Description </li></ul>

0986Defines the pure virtual rewrite functions in the parent class.

0987Syntax <tables id="TABLE-US-00158" num="158"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="2"><colspec colname="OFFSET" colwidth="56PT" align="left" /><colspec colname="1" colwidth="161PT" align="left" /><thead><row><entry /><entry /></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry /><entry>void rewrite(IP4Datagram* dp);</entry></row><row><entry /><entry>void rewrite(IP4Fragment* fp);</entry></row><row><entry /><entry namest="OFFSET" nameend="1" align="center" rowsep="1" /></row></tbody></tgroup></table></tables>

0988Parameters <tables id="TABLE-US-00159" num="159"><table frame="none" colsep="0" rowsep="0"><tgroup align="left" colsep="0" rowsep="0" cols="3"><colspec colname="1" colwidth="42PT" align="left" /><colspec colname="2" colwidth="56PT" align="left" /><colspec colname="3" colwidth="119PT" align="left" /><thead><row><entry /></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row><row><entry>Parameter</entry><entry>Type</entry><entry>Description</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></thead><tbody valign="top"><row><entry>dp</entry><entry>IP4Datagram *</entry><entry>Pointer to the datagram to</entry></row><row><entry /><entry /><entry>be rewritten (all fragment headers are</entry></row><row><entry /><entry /><entry>modified)</entry></row><row><entry>fp</entry><entry>IP4Fragment *</entry><entry>Pointer to the fragment to rewrite</entry></row><row><entry /><entry /><entry>(only the single fragment header</entry></row><row><entry /><entry /><entry>is modified). Should only be called</entry></row><row><entry /><entry /><entry>when the fragment represents a</entry></row><row><entry /><entry /><entry>complete TCP/IP segment.</entry></row><row><entry namest="1" nameend="3" align="center" rowsep="1" /></row></tbody></tgroup></table></tables><br /> Return Value <ul id="ul0153" list-style="none"><li id="ul0153-0001" num="0989"> None. </li></ul>

0990Those skilled in the art will appreciate variations of the above described embodiments. In addition to these embodiments, other variations will be appreciated by those skilled in the art. As such, the scope of the invention is not limited to the specified embodiments, but is defined by the following claims.